execve.2, exec.3: Consistently use the term 'pathname' (not 'path')

[thirdparty/man-pages.git] / man2 / umask.2

diff --git a/man2/umask.2 b/man2/umask.2
index de414bf55f0940ad1ebd6b387162cfd8464f8bea..e74e8ef06be428ed973edc91998997748fb8bec4 100644 (file)
--- a/man2/umask.2
+++ b/man2/umask.2
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2006, 2008, Michael Kerrisk (mtk.manpages@gmail.com)
+.\" Copyright (c) 2006, 2008, Michael Kerrisk <mtk.manpages@gmail.com>
 .\" (A few fragments remain from an earlier (1992) version written in
 .\" 1992 by Drew Eckhardt <drew@cs.colorado.edu>.)
 .\"
@@ -31,14 +31,14 @@
 .\"  <nick@debian.com> with Lars Wirzenius <liw@iki.fi> suggestion
 .\" 2006-05-13, mtk, substantial rewrite of description of 'mask'
 .\" 2008-01-09, mtk, a few rewrites and additions.
-.TH UMASK 2 2008-01-09 "Linux" "Linux Programmer's Manual"
+.TH UMASK 2 2017-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
 umask \- set file mode creation mask
 .SH SYNOPSIS
 .B #include <sys/types.h>
 .br
 .B #include <sys/stat.h>
-.sp
+.PP
 .BI "mode_t umask(mode_t " mask );
 .SH DESCRIPTION
 .BR umask ()
@@ -47,7 +47,7 @@ sets the calling process's file mode creation mask (umask) to
 & 0777 (i.e., only the file permission bits of
 .I mask
 are used), and returns the previous value of the mask.
-
+.PP
 The umask is used by
 .BR open (2),
 .BR mkdir (2),
@@ -62,7 +62,7 @@ argument to
 .BR open (2)
 and
 .BR mkdir (2).
-
+.PP
 Alternatively, if the parent directory has a default ACL (see
 .BR acl (5)),
 the umask is ignored, the default ACL is inherited,
@@ -71,19 +71,19 @@ and permission bits absent in the
 .I mode
 argument are turned off.
 For example, the following default ACL is equivalent to a umask of 022:
-
+.PP
     u::rwx,g::r-x,o::r-x
-
+.PP
 Combining the effect of this default ACL with a
 .I mode
 argument of 0666 (rw-rw-rw-), the resulting file permissions would be 0644
 (rw-r--r--).
-
+.PP
 The constants that should be used to specify
 .I mask
-are described under
-.BR stat (2).
-
+are described in
+.BR inode (7).
+.PP
 The typical default value for the process umask is
 .I S_IWGRP\ |\ S_IWOTH
 (octal 022).
@@ -92,31 +92,52 @@ In the usual case where the
 argument to
 .BR open (2)
 is specified as:
-.nf
-
-    S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH
-
-.fi
+.PP
+.in +4n
+.EX
+S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH
+.EE
+.in
+.PP
 (octal 0666) when creating a new file, the permissions on the
 resulting file will be:
-.nf
-
-    S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH
-
-.fi
+.PP
+.in +4n
+.EX
+S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH
+.EE
+.in
+.PP
 (because 0666 & ~022 = 0644; i.e., rw\-r\-\-r\-\-).
 .SH RETURN VALUE
 This system call always succeeds and the previous value of the mask
 is returned.
 .SH CONFORMING TO
-SVr4, 4.3BSD, POSIX.1-2001.
+POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 .SH NOTES
 A child process created via
 .BR fork (2)
 inherits its parent's umask.
 The umask is left unchanged by
 .BR execve (2).
-
+.PP
+It is impossible to use
+.BR umask ()
+to fetch a process's umask without at the same time changing it.
+A second call to
+.BR umask ()
+would then be needed to restore the umask.
+The nonatomicity of these two steps provides the potential
+for races in multithreaded programs.
+.PP
+Since Linux 4.7, the umask of any process can be viewed via the
+.I Umask
+field of
+.IR /proc/[pid]/status .
+Inspecting this field in
+.IR /proc/self/status
+allows a process to retrieve its umask without at the same time changing it.
+.PP
 The umask setting also affects the permissions assigned to POSIX IPC objects
 .RB ( mq_open (3),
 .BR sem_open (3),