Add caution subdirectory containing safety and liveness tests.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 73657d0..d8156b9 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.


@@ -262,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.


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


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


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


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


@@ -913,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>).


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


@@ -2341,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.


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