mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-22 07:03:38 +00:00
a57f6b8e2c
They will be removed in libguestfs 1.58 (the next but one version). Currently they don't actually compile. The larger problem is that they don't handle 64 bit quantities properly (using floats instead), meaning that any disk size or offset above a certain size will be improperly passed through the API, usually rounded to the nearest 53 bits.
181 lines
4.5 KiB
Plaintext
181 lines
4.5 KiB
Plaintext
=head1 NAME
|
|
|
|
guestfs-java - How to use libguestfs from Java
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
import com.redhat.et.libguestfs.*;
|
|
|
|
GuestFS g = new GuestFS ();
|
|
g.add_drive ("disk.img",
|
|
new HashMap<String,Object>() {
|
|
{
|
|
put ("readonly", Boolean.TRUE);
|
|
put ("format", "raw");
|
|
}
|
|
});
|
|
g.launch ();
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This manual page documents how to call libguestfs from the Java
|
|
programming language. This page just documents the differences from
|
|
the C API and gives some examples. If you are not familiar with using
|
|
libguestfs, you also need to read L<guestfs(3)>.
|
|
|
|
=head2 CLOSING THE HANDLE
|
|
|
|
The handle is closed when it is reaped by the garbage collector.
|
|
Because libguestfs handles include a lot of state, it is also
|
|
possible to close (and hence free) them explicitly by calling
|
|
the C<close> method.
|
|
|
|
=head2 EXCEPTIONS
|
|
|
|
Errors from libguestfs functions are mapped into the
|
|
C<LibGuestFSException> exception. This has a single parameter which
|
|
is the error message (a C<String>).
|
|
|
|
Calling any method on a closed handle raises the same exception.
|
|
|
|
If L<malloc(3)> or some other allocation fails inside the bindings,
|
|
the C<LibGuestFSOutOfMemory> exception is thrown.
|
|
|
|
=head2 EVENTS
|
|
|
|
The L<libguestfs event API|guestfs(3)/EVENTS> is fully supported from
|
|
Java. Create a class which implements the C<EventCallback> interface,
|
|
create an instance of this class, and then call the C<GuestFS#set_event_callback>
|
|
method to register this instance. The C<event> method of the class is
|
|
called when libguestfs generates an event.
|
|
|
|
For example, this will print all trace events:
|
|
|
|
GuestFS g = new GuestFS ();
|
|
g.set_trace (true);
|
|
g.set_event_callback (
|
|
new EventCallback () {
|
|
public void event (long event, int eh,
|
|
String buffer, long[] array) {
|
|
System.out.println (GuestFS.eventToString (event) +
|
|
": " + buffer);
|
|
}
|
|
},
|
|
GuestFS.EVENT_TRACE);
|
|
g.add_drive_ro ("disk.img");
|
|
// etc.
|
|
|
|
The output looks similar to this:
|
|
|
|
EVENT_TRACE: add_drive_ro "disk.img"
|
|
EVENT_TRACE: add_drive_ro = 0
|
|
// etc.
|
|
|
|
=head2 OPTIONAL ARGUMENTS
|
|
|
|
Some methods take an optional map of optional parameters. An example
|
|
of this is C<g.add_drive> which can be called in one of two ways:
|
|
|
|
g.add_drive ("disk.img");
|
|
|
|
or with optional arguments:
|
|
|
|
Map<String, Object> optargs =
|
|
new HashMap<String, Object>() {
|
|
{
|
|
put ("readonly", Boolean.TRUE);
|
|
put ("format", "raw");
|
|
}
|
|
};
|
|
g.add_drive ("disk.img", optargs);
|
|
|
|
For more information on this topic, see
|
|
L<guestfs(3)/CALLS WITH OPTIONAL ARGUMENTS>.
|
|
|
|
=head3 Optional handle parameters
|
|
|
|
When creating the handle you can also pass a map of optional
|
|
parameters:
|
|
|
|
Map<String, Object> optargs =
|
|
new HashMap<String, Object>() {
|
|
{
|
|
put ("close_on_exit", Boolean.FALSE);
|
|
put ("environment", Boolean.TRUE);
|
|
}
|
|
};
|
|
GuestFS g = new GuestFS (optargs);
|
|
|
|
For more information, see L<guestfs(3)/guestfs_create_flags>.
|
|
|
|
=head1 COMPILING AND RUNNING
|
|
|
|
Libguestfs for Java is a Java Native Interface (JNI) extension,
|
|
supplied in three parts:
|
|
|
|
=over 4
|
|
|
|
=item F<libguestfs.jar>
|
|
|
|
=item F<libguestfs-I<VERSION>.jar>
|
|
|
|
The pure Java JAR file which contains several classes, the primary one
|
|
being C<com.redhat.et.libguestfs.GuestFS>. Upstream, the JAR file
|
|
contains a version number in the filename, but some Linux distros may
|
|
rename it without the version number.
|
|
|
|
=item F<libguestfs_jni.so>
|
|
|
|
The JNI code (written in C). This contains private native functions
|
|
that interface between Java code and the regular libguestfs C library.
|
|
You should B<not> call these directly.
|
|
|
|
=item F<libguestfs.so>
|
|
|
|
The regular libguestfs C library.
|
|
|
|
=back
|
|
|
|
To compile your Java program, you need to locate the JAR file and add
|
|
it to the class path. For example:
|
|
|
|
export CLASSPATH=/usr/share/java/libguestfs.jar
|
|
javac MyProgram.java
|
|
|
|
To run your Java program, you also need to ensure that the JAR file is
|
|
on the class path, as well as the path of your program. For example:
|
|
|
|
export CLASSPATH=.:/usr/share/java/libguestfs.jar
|
|
java MyProgram
|
|
|
|
=head1 EXAMPLE 1: CREATE A DISK IMAGE
|
|
|
|
@EXAMPLE1@
|
|
|
|
=head1 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE
|
|
|
|
@EXAMPLE2@
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<guestfs(3)>,
|
|
L<guestfs-examples(3)>,
|
|
L<guestfs-erlang(3)>,
|
|
L<guestfs-golang(3)>,
|
|
L<guestfs-lua(3)>,
|
|
L<guestfs-ocaml(3)>,
|
|
L<guestfs-perl(3)>,
|
|
L<guestfs-python(3)>,
|
|
L<guestfs-recipes(1)>,
|
|
L<guestfs-ruby(3)>,
|
|
L<http://libguestfs.org/>,
|
|
L<http://caml.inria.fr/>.
|
|
|
|
=head1 AUTHORS
|
|
|
|
Richard W.M. Jones (C<rjones at redhat dot com>)
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (C) 2011-2025 Red Hat Inc.
|