From: Richard W.M. Jones Date: Tue, 19 Jul 2011 16:54:35 +0000 (+0100) Subject: java: Add guestfs-java(3) man page. X-Git-Tag: 1.11.20~2 X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=commitdiff_plain;h=d025e91f6751505c70b7b5f492ee72c67e274ecf java: Add guestfs-java(3) man page. --- diff --git a/.gitignore b/.gitignore index 19d971b..4777a4f 100644 --- a/.gitignore +++ b/.gitignore @@ -118,6 +118,7 @@ haskell/Guestfs.hs html/guestfish.1.html html/guestfs.3.html html/guestfs-examples.3.html +html/guestfs-java.3.html html/guestfs-ocaml.3.html html/guestfs-perl.3.html html/guestfs-python.3.html @@ -182,6 +183,8 @@ java/com/redhat/et/libguestfs/Version.java java/com/redhat/et/libguestfs/VG.java java/com/redhat/et/libguestfs/XAttr.java java/doc-stamp +java/examples/guestfs-java.3 +java/examples/stamp-guestfs-java.pod *.la libguestfs.pc libguestfs.spec diff --git a/Makefile.am b/Makefile.am index baa6f60..e1ddf0d 100644 --- a/Makefile.am +++ b/Makefile.am @@ -52,7 +52,7 @@ if HAVE_RUBY SUBDIRS += ruby ruby/examples endif if HAVE_JAVA -SUBDIRS += java +SUBDIRS += java java/examples endif if HAVE_HASKELL SUBDIRS += haskell @@ -131,6 +131,7 @@ EXTRA_DIST = \ HTMLFILES = \ html/guestfs.3.html \ html/guestfs-examples.3.html \ + html/guestfs-java.3.html \ html/guestfs-ocaml.3.html \ html/guestfs-perl.3.html \ html/guestfs-python.3.html \ diff --git a/configure.ac b/configure.ac index fc94224..57ae0a9 100644 --- a/configure.ac +++ b/configure.ac @@ -819,6 +819,7 @@ AC_CONFIG_FILES([Makefile images/Makefile inspector/Makefile java/Makefile + java/examples/Makefile libguestfs.pc ocaml/META ocaml/Makefile diff --git a/examples/guestfs-examples.pod b/examples/guestfs-examples.pod index 775675e..39259e1 100644 --- a/examples/guestfs-examples.pod +++ b/examples/guestfs-examples.pod @@ -33,6 +33,7 @@ libguestfs, you also need to read L. =head1 SEE ALSO L, +L, L, L, L, diff --git a/examples/guestfs-recipes.pod b/examples/guestfs-recipes.pod index 595c2c4..97a8053 100644 --- a/examples/guestfs-recipes.pod +++ b/examples/guestfs-recipes.pod @@ -386,6 +386,7 @@ https://rwmj.wordpress.com/2011/05/10/tip-use-libguestfs-on-vmware-esx-guests/#c L, L, L, +L, L, L, L, diff --git a/java/examples/CreateDisk.java b/java/examples/CreateDisk.java new file mode 100644 index 0000000..4742b5a --- /dev/null +++ b/java/examples/CreateDisk.java @@ -0,0 +1,87 @@ +// Example showing how to create a disk image. + +import java.io.*; +import java.util.Map; +import java.util.HashMap; +import com.redhat.et.libguestfs.*; + +public class CreateDisk +{ + static String output = "disk.img"; + + public static void main (String[] argv) + { + try { + GuestFS g = new GuestFS (); + + // Create a raw-format sparse disk image, 512 MB in size. + RandomAccessFile f = new RandomAccessFile (output, "rw"); + f.setLength (512 * 1024 * 1024); + f.close (); + + // Set the trace flag so that we can see each libguestfs call. + g.set_trace (true); + + // Set the autosync flag so that the disk will be synchronized + // automatically when the libguestfs handle is closed. + g.set_autosync (true); + + // Attach the disk image to libguestfs. + Map optargs = new HashMap() { + { + put ("format", "raw"); + put ("readonly", Boolean.FALSE); + } + }; + g.add_drive_opts (output, optargs); + + // Run the libguestfs back-end. + g.launch (); + + // Get the list of devices. Because we only added one drive + // above, we expect that this list should contain a single + // element. + String[] devices = g.list_devices (); + if (devices.length != 1) + throw new Error ("expected a single device from list-devices"); + + // Partition the disk as one single MBR partition. + g.part_disk (devices[0], "mbr"); + + // Get the list of partitions. We expect a single element, which + // is the partition we have just created. + String[] partitions = g.list_partitions (); + if (partitions.length != 1) + throw new Error ("expected a single partition from list-partitions"); + + // Create a filesystem on the partition. + g.mkfs ("ext4", partitions[0]); + + // Now mount the filesystem so that we can add files. + g.mount_options ("", partitions[0], "/"); + + // Create some files and directories. + g.touch ("/empty"); + String message = "Hello, world\n"; + g.write ("/hello", message.getBytes()); + g.mkdir ("/foo"); + + // This one uploads the local file /etc/resolv.conf into + // the disk image. + g.upload ("/etc/resolv.conf", "/foo/resolv.conf"); + + // Because 'autosync' was set (above) we can just close the handle + // and the disk contents will be synchronized. You can also do + // this manually by calling g#umount_all and g#sync. + // + // Note also that handles are automatically closed if they are + // reaped by the garbage collector. You only need to call close + // if you want to close the handle right away. + g.close (); + } + catch (Exception exn) { + System.err.println (exn); + System.exit (1); + } + } +} diff --git a/java/examples/InspectVM.java b/java/examples/InspectVM.java new file mode 100644 index 0000000..d92aa70 --- /dev/null +++ b/java/examples/InspectVM.java @@ -0,0 +1,99 @@ +// Example showing how to inspect a virtual machine disk. + +import java.util.ArrayList; +import java.util.Collections; +import java.util.Comparator; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import com.redhat.et.libguestfs.*; + +public class InspectVM +{ + static final Comparator COMPARE_KEYS_LEN = + new Comparator() { + public int compare (String k1, String k2) { + return k1.length() - k2.length(); + } + }; + + public static void main (String[] argv) + { + try { + if (argv.length != 1) + throw new Error ("usage: InspectVM disk.img"); + + String disk = argv[0]; + + GuestFS g = new GuestFS (); + + // Attach the disk image read-only to libguestfs. + Map optargs = new HashMap() { + { + //put ("format", "raw"); + put ("readonly", Boolean.TRUE); + } + }; + + g.add_drive_opts (disk, optargs); + + // Run the libguestfs back-end. + g.launch (); + + // Ask libguestfs to inspect for operating systems. + String roots[] = g.inspect_os (); + if (roots.length == 0) + throw new Error ("inspect_vm: no operating systems found"); + + for (String root : roots) { + System.out.println ("Root device: " + root); + + // Print basic information about the operating system. + System.out.println (" Product name: " + + g.inspect_get_product_name (root)); + System.out.println (" Version: " + + g.inspect_get_major_version (root) + + "." + + g.inspect_get_minor_version (root)); + System.out.println (" Type: " + + g.inspect_get_type (root)); + System.out.println (" Distro: " + + g.inspect_get_distro (root)); + + // Mount up the disks, like guestfish -i. + // + // Sort keys by length, shortest first, so that we end up + // mounting the filesystems in the correct order. + Map mps = g.inspect_get_mountpoints (root); + List mps_keys = new ArrayList (mps.keySet ()); + Collections.sort (mps_keys, COMPARE_KEYS_LEN); + + for (String mp : mps_keys) { + String dev = mps.get (mp); + try { + g.mount_ro (dev, mp); + } + catch (Exception exn) { + System.err.println (exn + " (ignored)"); + } + } + + // If /etc/issue.net file exists, print up to 3 lines. + String filename = "/etc/issue.net"; + if (g.is_file (filename)) { + System.out.println ("--- " + filename + " ---"); + String[] lines = g.head_n (3, filename); + for (String line : lines) + System.out.println (line); + } + + // Unmount everything. + g.umount_all (); + } + } + catch (Exception exn) { + System.err.println (exn); + System.exit (1); + } + } +} diff --git a/java/examples/LICENSE b/java/examples/LICENSE new file mode 100644 index 0000000..f8106cd --- /dev/null +++ b/java/examples/LICENSE @@ -0,0 +1,2 @@ +All the examples in the 'java/examples' subdirectory may be freely +copied, modified and distributed without any restrictions. diff --git a/java/examples/Makefile.am b/java/examples/Makefile.am new file mode 100644 index 0000000..503b55d --- /dev/null +++ b/java/examples/Makefile.am @@ -0,0 +1,50 @@ +# libguestfs Java examples +# Copyright (C) 2011 Red Hat Inc. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +EXTRA_DIST = \ + LICENSE \ + CreateDisk.java \ + InspectVM.java \ + guestfs-java.pod + +CLEANFILES = \ + *.class \ + stamp-guestfs-java.pod + +man_MANS = guestfs-java.3 +noinst_DATA = $(top_builddir)/html/guestfs-java.3.html + +guestfs-java.3 $(top_builddir)/html/guestfs-java.3.html: stamp-guestfs-java.pod + +stamp-guestfs-java.pod: guestfs-java.pod CreateDisk.java InspectVM.java + $(top_srcdir)/podwrapper.sh \ + --section 3 \ + --man guestfs-java.3 \ + --html $(top_builddir)/html/guestfs-java.3.html \ + --verbatim CreateDisk.java:@EXAMPLE1@ \ + --verbatim InspectVM.java:@EXAMPLE2@ \ + $< + touch $@ + +if HAVE_JAVA + +noinst_SCRIPTS = CreateDisk.class InspectVM.class + +%.class: %.java + $(JAVAC) $(JAVAC_FLAGS) -classpath ../libguestfs-$(VERSION).jar $< + +endif diff --git a/java/examples/guestfs-java.pod b/java/examples/guestfs-java.pod new file mode 100644 index 0000000..abf62db --- /dev/null +++ b/java/examples/guestfs-java.pod @@ -0,0 +1,80 @@ +=encoding utf8 + +=head1 NAME + +guestfs-java - How to use libguestfs from Java + +=head1 SYNOPSIS + + import com.redhat.et.libguestfs.*; + + GuestFS g = new GuestFS (); + g.add_drive_opts ("disk.img", null); + 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. + +=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 method. + +=head2 EXCEPTIONS + +Errors from libguestfs functions are mapped into the +C exception. This has a single parameter which +is the error message (a C). + +Calling any method on a closed handle raises the same exception. + +=head1 EXAMPLE 1: CREATE A DISK IMAGE + +@EXAMPLE1@ + +=head1 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE + +@EXAMPLE2@ + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2011 Red Hat Inc. L + +The examples in this manual page may be freely copied, modified and +distributed without any restrictions. + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA diff --git a/ocaml/examples/guestfs-ocaml.pod b/ocaml/examples/guestfs-ocaml.pod index f0cffe9..0978650 100644 --- a/ocaml/examples/guestfs-ocaml.pod +++ b/ocaml/examples/guestfs-ocaml.pod @@ -79,6 +79,7 @@ function that you called. L, L, +L, L, L, L, diff --git a/perl/examples/guestfs-perl.pod b/perl/examples/guestfs-perl.pod index cf3011a..0973382 100644 --- a/perl/examples/guestfs-perl.pod +++ b/perl/examples/guestfs-perl.pod @@ -41,6 +41,7 @@ C (see L). L, L, L, +L, L, L, L, diff --git a/python/examples/guestfs-python.pod b/python/examples/guestfs-python.pod index 7b9e03b..cab7e9b 100644 --- a/python/examples/guestfs-python.pod +++ b/python/examples/guestfs-python.pod @@ -43,6 +43,7 @@ Type: L, L, +L, L, L, L, diff --git a/ruby/examples/guestfs-ruby.pod b/ruby/examples/guestfs-ruby.pod index 2966031..9197f9b 100644 --- a/ruby/examples/guestfs-ruby.pod +++ b/ruby/examples/guestfs-ruby.pod @@ -37,6 +37,7 @@ string). L, L, +L, L, L, L, diff --git a/src/guestfs.pod b/src/guestfs.pod index f480cce..db9d8f0 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -728,7 +728,7 @@ and we are looking for help to complete this binding. =item B Full documentation is contained in the Javadoc which is distributed -with libguestfs. +with libguestfs. For examples, see L. =item B @@ -3011,6 +3011,7 @@ enough. =head1 SEE ALSO L, +L, L, L, L,