From: Richard Jones <rjones@redhat.com>
Date: Mon, 19 Apr 2010 19:55:15 +0000 (+0100)
Subject: Document umask (RHBZ#582548, RHBZ#583554).
X-Git-Tag: 1.3.6~13
X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=commitdiff_plain;h=c2a8efc548d6f997049cbb3d63bab360b0d946b6

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

diff --git a/src/guestfs.pod b/src/guestfs.pod
index cf70d5d..779ecc5 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -202,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
-C<guestfs_umask> and defaulting to 022.
+C<guestfs_umask> and defaulting to 022.  See L</UMASK>.
 
 =head2 PARTITIONING
 
@@ -437,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>.
 
+=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