Document umask (RHBZ#582548, RHBZ#583554).

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 2e608c6..779ecc5 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.
 


@@ -807,7 +834,7 @@ need the compile time check as well):
    dl = dlopen (NULL, RTLD_LAZY);
    if (!dl) {
      fprintf (stderr, "dlopen: %s\n", dlerror ());
    dl = dlopen (NULL, RTLD_LAZY);
    if (!dl) {
      fprintf (stderr, "dlopen: %s\n", dlerror ());

-     exit (1);
+     exit (EXIT_FAILURE);

    }
    has_function = dlsym (dl, "guestfs_dd") != NULL;
    dlclose (dl);
    }
    has_function = dlsym (dl, "guestfs_dd") != NULL;
    dlclose (dl);


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


@@ -1284,7 +1311,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 +1336,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 +1353,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: