win-reg: Add Windows Tips to documentation.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 8370982..9cf66f3 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -14,7 +14,6 @@ guestfs - Library for accessing and modifying virtual machine images
  guestfs_mount (g, "/dev/sda1", "/");
  guestfs_touch (g, "/hello");
  guestfs_umount (g, "/");
  guestfs_mount (g, "/dev/sda1", "/");
  guestfs_touch (g, "/hello");
  guestfs_umount (g, "/");

- guestfs_sync (g);

  guestfs_close (g);
 
  cc prog.c -o prog -lguestfs
  guestfs_close (g);
 
  cc prog.c -o prog -lguestfs


@@ -52,6 +51,9 @@ need enough permissions to access the disk images.
 Libguestfs is a large API because it can do many things.  For a gentle
 introduction, please read the L</API OVERVIEW> section next.
 
 Libguestfs is a large API because it can do many things.  For a gentle
 introduction, please read the L</API OVERVIEW> section next.
 

+There are also some example programs in the L<guestfs-examples(3)>
+manual page.
+

 =head1 API OVERVIEW
 
 This section provides a gentler overview of the libguestfs API.  We
 =head1 API OVERVIEW
 
 This section provides a gentler overview of the libguestfs API.  We


@@ -97,11 +99,10 @@ this:
   * disk image.
   */
  guestfs_touch (g, "/hello");
   * disk image.
   */
  guestfs_touch (g, "/hello");

- 
- /* You only need to call guestfs_sync if you have made
-  * changes to the guest image.  (But if you've made changes
-  * then you *must* sync).  See also: guestfs_umount and
-  * guestfs_umount_all calls.
+
+ /* 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.

   */
  guestfs_sync (g);
  
   */
  guestfs_sync (g);
  


@@ -114,7 +115,8 @@ functions that return integers return C<-1> on error, and all
 functions that return pointers return C<NULL> on error.  See section
 L</ERROR HANDLING> below for how to handle errors, and consult the
 documentation for each function call below to see precisely how they
 functions that return pointers return C<NULL> on error.  See section
 L</ERROR HANDLING> below for how to handle errors, and consult the
 documentation for each function call below to see precisely how they

-return error indications.
+return error indications.  See L<guestfs-examples(3)> for fully worked
+examples.

 
 =head2 DISK IMAGES
 
 
 =head2 DISK IMAGES
 


@@ -654,7 +656,7 @@ with libguestfs.
 
 =item B<OCaml>
 
 
 =item B<OCaml>
 

-For documentation see the file C<guestfs.mli>.
+For documentation see L<guestfs-ocaml(3)>.

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


@@ -669,16 +671,11 @@ The PHP binding only works correctly on 64 bit machines.
 
 =item B<Python>
 
 
 =item B<Python>
 

-For documentation do:
-
- $ python
- >>> import guestfs
- >>> help (guestfs)
+For documentation see L<guestfs-python(3)>.

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

-Use the Guestfs module.  There is no Ruby-specific documentation, but
-you can find examples written in Ruby in the libguestfs source.
+For documentation see L<guestfs-ruby(3)>.

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


@@ -1095,6 +1092,14 @@ data.  Callers should be careful to escape these before printing them
 to a structured file (for example, use HTML escaping if creating a web
 page).
 
 to a structured file (for example, use HTML escaping if creating a web
 page).
 

+Guest configuration may be altered in unusual ways by the
+administrator of the virtual machine, and may not reflect reality
+(particularly for untrusted or actively malicious guests).  For
+example we parse the hostname from configuration files like
+C</etc/sysconfig/network> that we find in the guest, but the guest
+administrator can easily manipulate these files to provide the wrong
+hostname.
+

 The inspection API parses guest configuration using two external
 libraries: Augeas (Linux configuration) and hivex (Windows Registry).
 Both are designed to be robust in the face of malicious data, although
 The inspection API parses guest configuration using two external
 libraries: Augeas (Linux configuration) and hivex (Windows Registry).
 Both are designed to be robust in the face of malicious data, although


@@ -1849,6 +1854,14 @@ The header contains the procedure number (C<guestfs_proc>) which is
 how the receiver knows what type of args structure to expect, or none
 at all.
 
 how the receiver knows what type of args structure to expect, or none
 at all.
 

+For functions that take optional arguments, the optional arguments are
+encoded in the C<guestfs_I<foo>_args> structure in the same way as
+ordinary arguments.  A bitmask in the header indicates which optional
+arguments are meaningful.  The bitmask is also checked to see if it
+contains bits set which the daemon does not know about (eg. if more
+optional arguments were added in a later version of the library), and
+this causes the call to be rejected.
+

 The reply message for ordinary functions is:
 
  total length (header + ret,
 The reply message for ordinary functions is:
 
  total length (header + ret,


@@ -2075,11 +2088,16 @@ enough.
 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO
 

+L<guestfs-examples(3)>,
+L<guestfs-ocaml(3)>,
+L<guestfs-python(3)>,
+L<guestfs-ruby(3)>,

 L<guestfish(1)>,
 L<guestmount(1)>,
 L<virt-cat(1)>,
 L<virt-df(1)>,
 L<virt-edit(1)>,
 L<guestfish(1)>,
 L<guestmount(1)>,
 L<virt-cat(1)>,
 L<virt-df(1)>,
 L<virt-edit(1)>,

+L<virt-filesystems(1)>,

 L<virt-inspector(1)>,
 L<virt-list-filesystems(1)>,
 L<virt-list-partitions(1)>,
 L<virt-inspector(1)>,
 L<virt-list-filesystems(1)>,
 L<virt-list-partitions(1)>,