Remove checks for Test::Pod and Test::Pod::Coverage.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index d005257..68fca7d 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -8,13 +8,18 @@ guestfs - Library for accessing and modifying virtual machine images
 
  #include <guestfs.h>
  
 
  #include <guestfs.h>
  

- guestfs_h *handle = guestfs_create ();
- guestfs_add_drive (handle, "guest.img");
- guestfs_launch (handle);
- guestfs_mount (handle, "/dev/sda1", "/");
- guestfs_touch (handle, "/hello");
- guestfs_sync (handle);
- guestfs_close (handle);
+ guestfs_h *g = guestfs_create ();
+ guestfs_add_drive (g, "guest.img");
+ guestfs_launch (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
+or:
+ cc prog.c -o prog `pkg-config libguestfs --cflags --libs`

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -58,43 +63,48 @@ from reading about the individual calls below.
 Before you can use libguestfs calls, you have to create a handle.
 Then you must add at least one disk image to the handle, followed by
 launching the handle, then performing whatever operations you want,
 Before you can use libguestfs calls, you have to create a handle.
 Then you must add at least one disk image to the handle, followed by
 launching the handle, then performing whatever operations you want,

-and finally closing the handle.  So the general structure of all
-libguestfs-using programs looks like this:
+and finally closing the handle.  By convention we use the single
+letter C<g> for the name of the handle variable, although of course
+you can use any name you want.

 
 

- guestfs_h *handle = guestfs_create ();
+The general structure of all libguestfs-using programs looks like
+this:
+
+ guestfs_h *g = guestfs_create ();

  
  /* Call guestfs_add_drive additional times if there are
   * multiple disk images.
   */
  
  /* Call guestfs_add_drive additional times if there are
   * multiple disk images.
   */

- guestfs_add_drive (handle, "guest.img");
+ guestfs_add_drive (g, "guest.img");

  
  /* Most manipulation calls won't work until you've launched
  
  /* Most manipulation calls won't work until you've launched

-  * the handle.  You have to do this _after_ adding drives
+  * the handle 'g'.  You have to do this _after_ adding drives

   * and _before_ other commands.
   */
   * and _before_ other commands.
   */

- guestfs_launch (handle);
+ guestfs_launch (g);

  
  /* Now you can examine what partitions, LVs etc are available.
   */
  
  /* Now you can examine what partitions, LVs etc are available.
   */

- char **partitions = guestfs_list_partitions (handle);
- char **logvols = guestfs_lvs (handle);
+ char **partitions = guestfs_list_partitions (g);
+ char **logvols = guestfs_lvs (g);

  
  /* To access a filesystem in the image, you must mount it.
   */
  
  /* To access a filesystem in the image, you must mount it.
   */

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

  
  /* Now you can perform filesystem actions on the guest
   * disk image.
   */
  
  /* Now you can perform filesystem actions on the guest
   * disk image.
   */

- guestfs_touch (handle, "/hello");
+ guestfs_touch (g, "/hello");

  
  /* You only need to call guestfs_sync if you have made
  
  /* You only need to call guestfs_sync if you have made

-  * changes to the guest image.
+  * changes to the guest image.  (But if you've made changes
+  * then you *must* sync).

   */
   */

- guestfs_sync (handle);
+ guestfs_sync (g);

  
  

- /* Close the handle. */
- guestfs_close (handle);
+ /* Close the handle 'g'. */
+ guestfs_close (g);

 
 The code above doesn't include any error checking.  In real code you
 should check return values carefully for errors.  In general all
 
 The code above doesn't include any error checking.  In real code you
 should check return values carefully for errors.  In general all


@@ -137,7 +147,7 @@ filesystems using C<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:
 
 image contains (for example) one partition with a filesystem on that
 partition, then you can mount it directly:
 

- guestfs_mount (handle, "/dev/sda1", "/");
+ guestfs_mount (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


@@ -167,7 +177,7 @@ Specify filenames as full paths including the mount point.
 For example, if you mounted a filesystem at C<"/"> and you want to
 read the file called C<"etc/passwd"> then you could do:
 
 For example, if you mounted a filesystem at C<"/"> and you want to
 read the file called C<"etc/passwd"> then you could do:
 

- char *data = guestfs_cat (handle, "/etc/passwd");
+ char *data = guestfs_cat (g, "/etc/passwd");

 
 This would return C<data> as a newly allocated buffer containing the
 full content of that file (with some conditions: see also
 
 This would return C<data> as a newly allocated buffer containing the
 full content of that file (with some conditions: see also


@@ -176,11 +186,11 @@ L</DOWNLOADING> below), or C<NULL> if there was an error.
 As another example, to create a top-level directory on that filesystem
 called C<"var"> you would do:
 
 As another example, to create a top-level directory on that filesystem
 called C<"var"> you would do:
 

- guestfs_mkdir (handle, "/var");
+ guestfs_mkdir (g, "/var");

 
 To create a symlink you could do:
 
 
 To create a symlink you could do:
 

- guestfs_ln_s (handle, "/etc/init.d/portmap",
+ guestfs_ln_s (g, "/etc/init.d/portmap",

                "/etc/rc3.d/S30portmap");
 
 Libguestfs will reject attempts to use relative paths.  There is no
                "/etc/rc3.d/S30portmap");
 
 Libguestfs will reject attempts to use relative paths.  There is no


@@ -192,7 +202,7 @@ conditions after each call.  (Other language bindings turn these
 errors into exceptions).
 
 File writes are affected by the per-handle umask, set by calling
 errors into exceptions).
 
 File writes are affected by the per-handle umask, set by calling

-C<guestfs_umask> and defaulting to 022.
+C<guestfs_umask> and defaulting to 022.  See L</UMASK>.

 
 =head2 PARTITIONING
 
 
 =head2 PARTITIONING
 


@@ -427,6 +437,23 @@ When new files are created, you may need to label them explicitly,
 for example by running the external command
 C<restorecon pathname>.
 
 for example by running the external command
 C<restorecon pathname>.
 

+=head2 UMASK
+
+Certain calls are affected by the current file mode creation mask (the
+"umask").  In particular ones which create files or directories, such
+as C<guestfs_touch>, C<guestfs_mknod> or C<guestfs_mkdir>.  This
+affects either the default mode that the file is created with or
+modifies the mode that you supply.
+
+The default umask is C<022>, so files are created with modes such as
+C<0644> and directories with C<0755>.
+
+There are two ways to avoid being affected by umask.  Either set umask
+to 0 (call C<guestfs_umask (g, 0)> early after launching).  Or call
+C<guestfs_chmod> after creating each file or directory.
+
+For more information about umask, see L<umask(2)>.
+

 =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


@@ -462,9 +489,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(handle,path)> is
-C<$handle-E<gt>mount($path)> in Perl, C<handle.mount(path)> in Python,
-and C<Guestfs.mount handle path> in OCaml.  In other words, a
+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

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


@@ -545,10 +572,10 @@ When modifying a filesystem from C or another language, you B<must>
 unmount all filesystems and call L</guestfs_sync> explicitly before
 you close the libguestfs handle.  You can also call:
 
 unmount all filesystems and call L</guestfs_sync> explicitly before
 you close the libguestfs handle.  You can also call:
 

- guestfs_set_autosync (handle, 1);
+ guestfs_set_autosync (g, 1);

 
 

-to have the unmount/sync done automatically for you when the handle is
-closed.  (This feature is called "autosync", L</guestfs_set_autosync>
+to have the unmount/sync done automatically for you when the handle 'g'
+is closed.  (This feature is called "autosync", L</guestfs_set_autosync>

 q.v.)
 
 If you forget to do this, then it is entirely possible that your
 q.v.)
 
 If you forget to do this, then it is entirely possible that your


@@ -641,7 +668,7 @@ L</ERROR HANDLING> section below.
 
 =head2 guestfs_close
 
 
 =head2 guestfs_close
 

- void guestfs_close (guestfs_h *handle);
+ void guestfs_close (guestfs_h *g);

 
 This closes the connection handle and frees up all resources used.
 
 
 This closes the connection handle and frees up all resources used.
 


@@ -660,9 +687,9 @@ handler using C<guestfs_set_out_of_memory_handler>.
 
 =head2 guestfs_last_error
 
 
 =head2 guestfs_last_error
 

- const char *guestfs_last_error (guestfs_h *handle);
+ const char *guestfs_last_error (guestfs_h *g);

 
 

-This returns the last error message that happened on C<handle>.  If
+This returns the last error message that happened on C<g>.  If

 there has not been an error since the handle was created, then this
 returns C<NULL>.
 
 there has not been an error since the handle was created, then this
 returns C<NULL>.
 


@@ -675,10 +702,10 @@ largest number of results.
 
 =head2 guestfs_set_error_handler
 
 
 =head2 guestfs_set_error_handler
 

- typedef void (*guestfs_error_handler_cb) (guestfs_h *handle,
+ typedef void (*guestfs_error_handler_cb) (guestfs_h *g,

                                            void *data,
                                            const char *msg);
                                            void *data,
                                            const char *msg);

- void guestfs_set_error_handler (guestfs_h *handle,
+ void guestfs_set_error_handler (guestfs_h *g,

                                  guestfs_error_handler_cb cb,
                                  void *data);
 
                                  guestfs_error_handler_cb cb,
                                  void *data);
 


@@ -696,7 +723,7 @@ If you set C<cb> to C<NULL> then I<no> handler is called.
 
 =head2 guestfs_get_error_handler
 
 
 =head2 guestfs_get_error_handler
 

- guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle,
+ guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,

                                                      void **data_rtn);
 
 Returns the current error handler callback.
                                                      void **data_rtn);
 
 Returns the current error handler callback.


@@ -704,7 +731,7 @@ 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 *handle,
+ int 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
                                         guestfs_abort_cb);
 
 The callback C<cb> will be called if there is an out of memory


@@ -717,7 +744,7 @@ situations.
 
 =head2 guestfs_get_out_of_memory_handler
 
 
 =head2 guestfs_get_out_of_memory_handler
 

- guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle);
+ guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);

 
 This returns the current out of memory handler.
 
 
 This returns the current out of memory handler.
 


@@ -958,7 +985,7 @@ this function with C<cb> set to C<NULL>.
 
  typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
                                          char *buf, int len);
 
  typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
                                          char *buf, int len);

- void guestfs_set_log_message_callback (guestfs_h *handle,
+ void guestfs_set_log_message_callback (guestfs_h *g,

                                         guestfs_log_message_cb cb,
                                         void *opaque);
 
                                         guestfs_log_message_cb cb,
                                         void *opaque);
 


@@ -973,7 +1000,7 @@ discarded.
 =head2 guestfs_set_subprocess_quit_callback
 
  typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);
 =head2 guestfs_set_subprocess_quit_callback
 
  typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);

- void guestfs_set_subprocess_quit_callback (guestfs_h *handle,
+ void guestfs_set_subprocess_quit_callback (guestfs_h *g,

                                             guestfs_subprocess_quit_cb cb,
                                             void *opaque);
 
                                             guestfs_subprocess_quit_cb cb,
                                             void *opaque);
 


@@ -985,7 +1012,7 @@ any state to the CONFIG state).
 =head2 guestfs_set_launch_done_callback
 
  typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
 =head2 guestfs_set_launch_done_callback
 
  typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);

- void guestfs_set_launch_done_callback (guestfs_h *handle,
+ void guestfs_set_launch_done_callback (guestfs_h *g,

                                         guestfs_ready_cb cb,
                                         void *opaque);
 
                                         guestfs_ready_cb cb,
                                         void *opaque);
 


@@ -1273,6 +1300,69 @@ 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.
 

+=head1 LIBGUESTFS VERSION NUMBERS
+
+Since April 2010, libguestfs has started to make separate development
+and stable releases, along with corresponding branches in our git
+repository.  These separate releases can be identified by version
+number:
+
+                 even numbers for stable: 1.2.x, 1.4.x, ...
+       .-------- odd numbers for development: 1.3.x, 1.5.x, ...
+       |
+       v
+ 1  .  3  .  5
+ ^           ^
+ |           |
+ |           `-------- sub-version
+ |
+ `------ always '1' because we don't change the ABI
+
+Thus "1.3.5" is the 5th update to the development branch "1.3".
+
+As time passes we cherry pick fixes from the development branch and
+backport those into the stable branch, the effect being that the
+stable branch should get more stable and less buggy over time.  So the
+stable releases are ideal for people who don't need new features but
+would just like the software to work.
+
+Our criteria for backporting changes are:
+
+=over 4
+
+=item *
+
+Documentation changes which don't affect any code are
+backported unless the documentation refers to a future feature
+which is not in stable.
+
+=item *
+
+Bug fixes which are not controversial, fix obvious problems, and
+have been well tested are backported.
+
+=item *
+
+Simple rearrangements of code which shouldn't affect how it works get
+backported.  This is so that the code in the two branches doesn't get
+too far out of step, allowing us to backport future fixes more easily.
+
+=item *
+
+We I<don't> backport new features, new APIs, new tools etc, except in
+one exceptional case: the new feature is required in order to
+implement an important bug fix.
+
+=back
+
+A new stable branch starts when we think the new features in
+development are substantial and compelling enough over the current
+stable branch to warrant it.  When that happens we create new stable
+and development versions 1.N.0 and 1.(N+1).0 [N is even].  The new
+dot-oh release won't necessarily be so stable at this point, but by
+backporting fixes from development, that branch will stabilize over
+time.
+

 =head1 ENVIRONMENT VARIABLES
 
 =over 4
 =head1 ENVIRONMENT VARIABLES
 
 =over 4


@@ -1284,7 +1374,7 @@ Pass additional options to the guest kernel.
 =item LIBGUESTFS_DEBUG
 
 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This
 =item LIBGUESTFS_DEBUG
 
 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This

-has the same effect as calling C<guestfs_set_verbose (handle, 1)>.
+has the same effect as calling C<guestfs_set_verbose (g, 1)>.

 
 =item LIBGUESTFS_MEMSIZE
 
 
 =item LIBGUESTFS_MEMSIZE
 


@@ -1309,7 +1399,7 @@ See also L</QEMU WRAPPERS> above.
 =item LIBGUESTFS_TRACE
 
 Set C<LIBGUESTFS_TRACE=1> to enable command traces.  This
 =item LIBGUESTFS_TRACE
 
 Set C<LIBGUESTFS_TRACE=1> to enable command traces.  This

-has the same effect as calling C<guestfs_set_trace (handle, 1)>.
+has the same effect as calling C<guestfs_set_trace (g, 1)>.

 
 =item TMPDIR
 
 
 =item TMPDIR
 


@@ -1326,8 +1416,21 @@ enough.
 =head1 SEE ALSO
 
 L<guestfish(1)>,
 =head1 SEE ALSO
 
 L<guestfish(1)>,

+L<guestmount(1)>,
+L<virt-cat(1)>,
+L<virt-df(1)>,
+L<virt-edit(1)>,
+L<virt-inspector(1)>,
+L<virt-list-filesystems(1)>,
+L<virt-list-partitions(1)>,
+L<virt-ls(1)>,
+L<virt-make-fs(1)>,
+L<virt-rescue(1)>,
+L<virt-tar(1)>,
+L<virt-win-reg(1)>,

 L<qemu(1)>,
 L<febootstrap(1)>,
 L<qemu(1)>,
 L<febootstrap(1)>,

+L<hivex(3)>,

 L<http://libguestfs.org/>.
 
 Tools with a similar purpose:
 L<http://libguestfs.org/>.
 
 Tools with a similar purpose: