appliance: udev-174 moves udevd to /lib/udev/udevd (instead of /sbin/udevd)

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 93f31e6..013a923 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -99,7 +99,7 @@ this:
   * disk image.
   */
  guestfs_touch (g, "/hello");
   * disk image.
   */
  guestfs_touch (g, "/hello");

-
+ 

  /* This is only needed for libguestfs < 1.5.24.  Since then
   * it is done automatically when you close the handle.  See
   * discussion of autosync in this page.
  /* This is only needed for libguestfs < 1.5.24.  Since then
   * it is done automatically when you close the handle.  See
   * discussion of autosync in this page.


@@ -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
 


@@ -670,9 +675,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 +713,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<Sys::Guestfs(3)>.

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


@@ -723,15 +728,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
 


@@ -907,8 +912,8 @@ architecture for multithreaded programs using libvirt and libguestfs.
 
 =head2 PATH
 
 
 =head2 PATH
 

-Libguestfs needs a kernel and initrd.img, which it finds by looking
-along an internal path.
+Libguestfs needs a supermin appliance, which it finds by looking along
+an internal path.

 
 By default it looks for these in the directory C<$libdir/guestfs>
 (eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
 
 By default it looks for these in the directory C<$libdir/guestfs>
 (eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).


@@ -1387,8 +1392,8 @@ Returns the current error handler callback.
 =head2 guestfs_set_out_of_memory_handler
 
  typedef void (*guestfs_abort_cb) (void);
 =head2 guestfs_set_out_of_memory_handler
 
  typedef void (*guestfs_abort_cb) (void);

- int guestfs_set_out_of_memory_handler (guestfs_h *g,
-                                        guestfs_abort_cb);
+ void guestfs_set_out_of_memory_handler (guestfs_h *g,
+                                         guestfs_abort_cb);

 
 The callback C<cb> will be called if there is an out of memory
 situation.  I<Note this callback must not return>.
 
 The callback C<cb> will be called if there is an out of memory
 situation.  I<Note this callback must not return>.


@@ -1706,7 +1711,8 @@ indicator which shows the ratio of C<position>:C<total>.
 =item *
 
 If any progress notification is sent during a call, then a final
 =item *
 
 If any progress notification is sent during a call, then a final

-progress notification is always sent when C<position> = C<total>.
+progress notification is always sent when C<position> = C<total>
+(I<unless> the call fails with an error).

 
 This is to simplify caller code, so callers can easily set the
 progress indicator to "100%" at the end of the operation, without
 
 This is to simplify caller code, so callers can easily set the
 progress indicator to "100%" at the end of the operation, without


@@ -2335,6 +2341,11 @@ Automated tests of the C API.
 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
 and documentation.
 
 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
 and documentation.
 

+=item C<caution>
+
+Safety and liveness tests of components that libguestfs depends upon
+(not of libguestfs itself).  Mainly this is for qemu and the kernel.
+

 =item C<contrib>
 
 Outside contributions, experimental parts.
 =item C<contrib>
 
 Outside contributions, experimental parts.


@@ -2452,8 +2463,8 @@ example:
 
 =item LIBGUESTFS_PATH
 
 
 =item LIBGUESTFS_PATH
 

-Set the path that libguestfs uses to search for kernel and initrd.img.
-See the discussion of paths in section PATH above.
+Set the path that libguestfs uses to search for a supermin appliance.
+See the discussion of paths in section L</PATH> above.

 
 =item LIBGUESTFS_QEMU
 
 
 =item LIBGUESTFS_QEMU