substantial rewrite of description of 'mask'

diff --git a/man2/umask.2 b/man2/umask.2
index 40918928f7f24288e5c1c33515779521e2d86ef4..df1b1d41de535a530ce536c233fd0b6e9a3d996a 100644 (file)
--- a/man2/umask.2
+++ b/man2/umask.2
@@ -1,6 +1,7 @@
 .\" Hey Emacs! This file is -*- nroff -*- source.
 .\"
 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
+.\" and Copyright (c) 2006, Michael Kerrisk (mtk-manpages@gmx.net)
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -27,7 +28,8 @@
 .\" Modified Tue Oct 22 22:39:04 1996 by Eric S. Raymond <esr@thyrsus.com>
 .\" Modified Thu May  1 06:05:54 UTC 1997 by Nicolás Lichtmaier
 .\"  <nick@debian.com> with Lars Wirzenius <liw@iki.fi> suggestion
-.TH UMASK 2 1998-08-09 "Linux" "Linux Programmer's Manual"
+.\" 2006-05-13, mtk, substantial rewrite of description of 'mask'
+.TH UMASK 2 2006-05-13 "Linux" "Linux Programmer's Manual"
 .SH NAME
 umask \- set file mode creation mask
 .SH SYNOPSIS
@@ -50,15 +52,37 @@ and other system calls that create files
 .\" but NOT the System V IPC *get() calls
 to modify the permissions placed on newly created files or directories.
 Specifically, permissions in the umask are turned off from
-the \fBmode\fR argument to
+the \fImode\fR argument to
 .BR open (2)
 and
-.BR mkdir (2)
-(so, for example, the common umask default value of 022 results in new
-files being created with permissions 0666 & ~022 = 0644 = rw-r--r--
-in the usual case where the \fBmode\fR is specified to
+.BR mkdir (2).
+
+The constants that should be used to specify 
+.I mask
+are described under
+.BR stat (2).
+
+The typical default value for the process umask is
+S_IWGRP\ |\ S_IWOTH
+(octal 022).
+In the usual case where the
+.I mode
+argument to 
 .BR open (2)
-as 0666).
+is specified as:
+.nf
+
+    S_IRUSR | S_IWUSR | S_IRGRP | S_IWRGRP | S_IROTH | S_IWOTH
+
+.fi
+(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
+(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.
@@ -67,4 +91,5 @@ SVr4, SVID, POSIX, X/OPEN, 4.3BSD
 .SH "SEE ALSO"
 .BR chmod (2),
 .BR mkdir (2),
-.BR open (2)
+.BR open (2),
+.BR stat (2)