check the pid is > 0 before calling waitpid()

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 93f31e6..0b3b654 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -162,27 +162,33 @@ NAMING> below.
 
 Before you can read or write files, create directories and so on in a
 disk image that contains filesystems, you have to mount those
 
 Before you can read or write files, create directories and so on in a
 disk image that contains filesystems, you have to mount those

-filesystems using L</guestfs_mount>.  If you already know that a disk
-image contains (for example) one partition with a filesystem on that
-partition, then you can mount it directly:
+filesystems using L</guestfs_mount_options> or L</guestfs_mount_ro>.
+If you already know that a disk image contains (for example) one
+partition with a filesystem on that partition, then you can mount it
+directly:

 
 

- guestfs_mount (g, "/dev/sda1", "/");
+ guestfs_mount_options (g, "", "/dev/sda1", "/");

 
 where C</dev/sda1> means literally the first partition (C<1>) of the
 first disk image that we added (C</dev/sda>).  If the disk contains
 
 where C</dev/sda1> means literally the first partition (C<1>) of the
 first disk image that we added (C</dev/sda>).  If the disk contains

-Linux LVM2 logical volumes you could refer to those instead (eg. C</dev/VG/LV>).
+Linux LVM2 logical volumes you could refer to those instead
+(eg. C</dev/VG/LV>).  Note that these are libguestfs virtual devices,
+and are nothing to do with host devices.

 
 If you are given a disk image and you don't know what it contains then
 you have to find out.  Libguestfs can do that too: use
 L</guestfs_list_partitions> and L</guestfs_lvs> to list possible
 partitions and LVs, and either try mounting each to see what is
 mountable, or else examine them with L</guestfs_vfs_type> or
 
 If you are given a disk image and you don't know what it contains then
 you have to find out.  Libguestfs can do that too: use
 L</guestfs_list_partitions> and L</guestfs_lvs> to list possible
 partitions and LVs, and either try mounting each to see what is
 mountable, or else examine them with L</guestfs_vfs_type> or

-L</guestfs_file>.  Libguestfs also has a set of APIs for inspection of
-disk images (see L</INSPECTION> below).  But you might find it easier
-to look at higher level programs built on top of libguestfs, in
+L</guestfs_file>.  To list just filesystems, use
+L</guestfs_list_filesystems>.
+
+Libguestfs also has a set of APIs for inspection of unknown disk
+images (see L</INSPECTION> below).  But you might find it easier to
+look at higher level programs built on top of libguestfs, in

 particular L<virt-inspector(1)>.
 
 particular L<virt-inspector(1)>.
 

-To mount a disk image read-only, use L</guestfs_mount_ro>.  There are
+To mount a filesystem read-only, use L</guestfs_mount_ro>.  There are

 several other variations of the C<guestfs_mount_*> call.
 
 =head2 FILESYSTEM ACCESS AND MODIFICATION
 several other variations of the C<guestfs_mount_*> call.
 
 =head2 FILESYSTEM ACCESS AND MODIFICATION


@@ -256,10 +262,9 @@ L<http://tldp.org/HOWTO/LVM-HOWTO/>.
 
 =head2 DOWNLOADING
 
 
 =head2 DOWNLOADING
 

-Use L</guestfs_cat> to download small, text only files.  This call
-is limited to files which are less than 2 MB and which cannot contain
-any ASCII NUL (C<\0>) characters.  However it has a very simple
-to use API.
+Use L</guestfs_cat> to download small, text only files.  This call is
+limited to files which are less than 2 MB and which cannot contain any
+ASCII NUL (C<\0>) characters.  However the API is very simple to use.

 
 L</guestfs_read_file> can be used to read files which contain
 arbitrary 8 bit data, since it returns a (pointer, size) pair.
 
 L</guestfs_read_file> can be used to read files which contain
 arbitrary 8 bit data, since it returns a (pointer, size) pair.


@@ -347,13 +352,13 @@ descriptor N.
 For example, L<virt-cat(1)> writes its output to stdout by
 doing:
 
 For example, L<virt-cat(1)> writes its output to stdout by
 doing:
 

- guestfs_download (filename, "/dev/stdout");
+ guestfs_download (g, filename, "/dev/stdout");

 
 and you can write tar output to a pipe C<fd> by doing:
 
  char devfd[64];
  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
 
 and you can write tar output to a pipe C<fd> by doing:
 
  char devfd[64];
  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);

- guestfs_tar_out ("/", devfd);
+ guestfs_tar_out (g, "/", devfd);

 
 =head2 LISTING FILES
 
 
 =head2 LISTING FILES
 


@@ -545,10 +550,11 @@ device (I<not> the underlying encrypted block device).
 =head2 INSPECTION
 
 Libguestfs has APIs for inspecting an unknown disk image to find out
 =head2 INSPECTION
 
 Libguestfs has APIs for inspecting an unknown disk image to find out

-if it contains operating systems.  (These APIs used to be in a
-separate Perl-only library called L<Sys::Guestfs::Lib(3)> but since
-version 1.5.3 the most frequently used part of this library has been
-rewritten in C and moved into the core code).
+if it contains operating systems, an install CD or a live CD.  (These
+APIs used to be in a separate Perl-only library called
+L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most frequently
+used part of this library has been rewritten in C and moved into the
+core code).

 
 Add all disks belonging to the unknown virtual machine and call
 L</guestfs_launch> in the usual way.
 
 Add all disks belonging to the unknown virtual machine and call
 L</guestfs_launch> in the usual way.


@@ -603,6 +609,25 @@ again.  (L</guestfs_inspect_list_applications> works a little
 differently from the other calls and does read the disks.  See
 documentation for that function for details).
 
 differently from the other calls and does read the disks.  See
 documentation for that function for details).
 

+=head3 INSPECTING INSTALL DISKS
+
+Libguestfs (since 1.9.4) can detect some install disks, install
+CDs, live CDs and more.
+
+Call L</guestfs_inspect_get_format> to return the format of the
+operating system, which currently can be C<installed> (a regular
+operating system) or C<installer> (some sort of install disk).
+
+Further information is available about the operating system that can
+be installed using the regular inspection APIs like
+L</guestfs_inspect_get_product_name>,
+L</guestfs_inspect_get_major_version> etc.
+
+Some additional information specific to installer disks is also
+available from the L</guestfs_inspect_is_live>,
+L</guestfs_inspect_is_netinst> and L</guestfs_inspect_is_multipart>
+calls.
+

 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
 
 Libguestfs can mount NTFS partitions.  It does this using the
 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
 
 Libguestfs can mount NTFS partitions.  It does this using the


@@ -670,9 +695,9 @@ Although we don't want to discourage you from using the C API, we will
 mention here that the same API is also available in other languages.
 
 The API is broadly identical in all supported languages.  This means
 mention here that the same API is also available in other languages.
 
 The API is broadly identical in all supported languages.  This means

-that the C call C<guestfs_mount(g,path)> is
-C<$g-E<gt>mount($path)> in Perl, C<g.mount(path)> in Python,
-and C<Guestfs.mount g path> in OCaml.  In other words, a
+that the C call C<guestfs_add_drive_ro(g,file)> is
+C<$g-E<gt>add_drive_ro($file)> in Perl, C<g.add_drive_ro(file)> in Python,
+and C<g#add_drive_ro file> in OCaml.  In other words, a

 straightforward, predictable isomorphism between each language.
 
 Error messages are automatically transformed
 straightforward, predictable isomorphism between each language.
 
 Error messages are automatically transformed


@@ -708,11 +733,11 @@ with libguestfs.
 
 =item B<OCaml>
 
 
 =item B<OCaml>
 

-For documentation see L<guestfs-ocaml(3)>.
+See L<guestfs-ocaml(3)>.

 
 =item B<Perl>
 
 
 =item B<Perl>
 

-For documentation see L<Sys::Guestfs(3)>.
+See L<guestfs-perl(3)> and L<Sys::Guestfs(3)>.

 
 =item B<PHP>
 
 
 =item B<PHP>
 


@@ -723,15 +748,15 @@ The PHP binding only works correctly on 64 bit machines.
 
 =item B<Python>
 
 
 =item B<Python>
 

-For documentation see L<guestfs-python(3)>.
+See L<guestfs-python(3)>.

 
 =item B<Ruby>
 
 
 =item B<Ruby>
 

-For documentation see L<guestfs-ruby(3)>.
+See L<guestfs-ruby(3)>.

 
 =item B<shell scripts>
 
 
 =item B<shell scripts>
 

-For documentation see L<guestfish(1)>.
+See L<guestfish(1)>.

 
 =back
 
 
 =back
 


@@ -947,6 +972,63 @@ For example:
 Note that libguestfs also calls qemu with the -help and -version
 options in order to determine features.
 
 Note that libguestfs also calls qemu with the -help and -version
 options in order to determine features.
 

+=head2 ATTACHING TO RUNNING DAEMONS
+
+I<Note (1):> This is B<highly experimental> and has a tendency to eat
+babies.  Use with caution.
+
+I<Note (2):> This section explains how to attach to a running daemon
+from a low level perspective.  For most users, simply using virt tools
+such as L<guestfish(1)> with the I<--live> option will "just work".
+
+=head3 Using guestfs_set_attach_method
+
+By calling L</guestfs_set_attach_method> you can change how the
+library connects to the C<guestfsd> daemon in L</guestfs_launch>
+(read L</ARCHITECTURE> for some background).
+
+The normal attach method is C<appliance>, where a small appliance is
+created containing the daemon, and then the library connects to this.
+
+Setting attach method to C<unix:I<path>> (where I<path> is the path of
+a Unix domain socket) causes L</guestfs_launch> to connect to an
+existing daemon over the Unix domain socket.
+
+The normal use for this is to connect to a running virtual machine
+that contains a C<guestfsd> daemon, and send commands so you can read
+and write files inside the live virtual machine.
+
+=head3 Using guestfs_add_domain with live flag
+
+L</guestfs_add_domain> provides some help for getting the
+correct attach method.  If you pass the C<live> option to this
+function, then (if the virtual machine is running) it will
+examine the libvirt XML looking for a virtio-serial channel
+to connect to:
+
+ <domain>
+   ...
+   <devices>
+     ...
+     <channel type='unix'>
+       <source mode='bind' path='/path/to/socket'/>
+       <target type='virtio' name='org.libguestfs.channel.0'/>
+     </channel>
+     ...
+   </devices>
+ </domain>
+
+L</guestfs_add_domain> extracts C</path/to/socket> and sets the attach
+method to C<unix:/path/to/socket>.
+
+Some of the libguestfs tools (including guestfish) support a I<--live>
+option which is passed through to L</guestfs_add_domain> thus allowing
+you to attach to and modify live virtual machines.
+
+The virtual machine needs to have been set up beforehand so that it
+has the virtio-serial channel and so that guestfsd is running inside
+it.
+

 =head2 ABI GUARANTEE
 
 We guarantee the libguestfs ABI (binary interface), for public,
 =head2 ABI GUARANTEE
 
 We guarantee the libguestfs ABI (binary interface), for public,


@@ -2354,7 +2436,9 @@ C API example code.
 
 =item C<fish>
 
 
 =item C<fish>
 

-L<guestfish(1)>, the command-line shell.
+L<guestfish(1)>, the command-line shell, and various shell scripts
+built on top such as L<virt-copy-in(1)>, L<virt-copy-out(1)>,
+L<virt-tar-in(1)>, L<virt-tar-out(1)>.

 
 =item C<fuse>
 
 
 =item C<fuse>
 


@@ -2375,6 +2459,10 @@ Some "phony" guest images which we test against.
 
 L<virt-inspector(1)>, the virtual machine image inspector.
 
 
 L<virt-inspector(1)>, the virtual machine image inspector.
 

+=item C<logo>
+
+Logo used on the website.  The fish is called Arthur by the way.
+

 =item C<m4>
 
 M4 macros used by autoconf.
 =item C<m4>
 
 M4 macros used by autoconf.


@@ -2470,12 +2558,13 @@ has the same effect as calling C<guestfs_set_trace (g, 1)>.
 
 =item TMPDIR
 
 
 =item TMPDIR
 

-Location of temporary directory, defaults to C</tmp>.
+Location of temporary directory, defaults to C</tmp> except for the
+cached supermin appliance which defaults to C</var/tmp>.

 
 If libguestfs was compiled to use the supermin appliance then the
 real appliance is cached in this directory, shared between all
 handles belonging to the same EUID.  You can use C<$TMPDIR> to
 
 If libguestfs was compiled to use the supermin appliance then the
 real appliance is cached in this directory, shared between all
 handles belonging to the same EUID.  You can use C<$TMPDIR> to

-configure another directory to use in case C</tmp> is not large
+configure another directory to use in case C</var/tmp> is not large

 enough.
 
 =back
 enough.
 
 =back


@@ -2489,6 +2578,8 @@ L<guestfs-ruby(3)>,
 L<guestfish(1)>,
 L<guestmount(1)>,
 L<virt-cat(1)>,
 L<guestfish(1)>,
 L<guestmount(1)>,
 L<virt-cat(1)>,

+L<virt-copy-in(1)>,
+L<virt-copy-out(1)>,

 L<virt-df(1)>,
 L<virt-edit(1)>,
 L<virt-filesystems(1)>,
 L<virt-df(1)>,
 L<virt-edit(1)>,
 L<virt-filesystems(1)>,


@@ -2499,6 +2590,8 @@ L<virt-ls(1)>,
 L<virt-make-fs(1)>,
 L<virt-rescue(1)>,
 L<virt-tar(1)>,
 L<virt-make-fs(1)>,
 L<virt-rescue(1)>,
 L<virt-tar(1)>,

+L<virt-tar-in(1)>,
+L<virt-tar-out(1)>,

 L<virt-win-reg(1)>,
 L<qemu(1)>,
 L<febootstrap(1)>,
 L<virt-win-reg(1)>,
 L<qemu(1)>,
 L<febootstrap(1)>,