[PATCH 1/2] open.2: Clarify which create mode bits are relevant

[PATCH 1/2] open.2: Clarify which create mode bits are relevant

[Andreas Gruenbacher]

Clarify that on Linux, the S_ISUID, S_ISGID, and S_IVTX bits in the create mode
are also honored.

Instead of repeating the S_I* definitions here, incompletely, refer to stat(2).

Signed-off-by: Andreas Gruenbacher <agruenba-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
 man2/open.2 | 51 +++++++++++----------------------------------------
 man2/stat.2 |  6 +++---
 2 files changed, 14 insertions(+), 43 deletions(-)

diff --git a/man2/open.2 b/man2/open.2
index 053bab1..96ee576 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -258,7 +258,12 @@ described in
 .RS
 .PP
 .I mode
-specifies the permissions to use in case a new file is created.
+specifies the permissions to use in case a new file is created; see
+the definition of the file permission mask values in
+.BR stat (2).
+When bits other than the file permission bits are set in
+.IR mode ,
+the effect is unspecified; for Linux, see below.
 This argument must be supplied when
 .B O_CREAT
 or
@@ -282,45 +287,6 @@ newly created file; the
 .BR open ()
 call that creates a read-only file may well return a read/write
 file descriptor.
-.PP
-The following symbolic constants are provided for
-.IR mode :
-.TP 9
-.B S_IRWXU
-00700 user (file owner) has read, write and execute permission
-.TP
-.B S_IRUSR
-00400 user has read permission
-.TP
-.B S_IWUSR
-00200 user has write permission
-.TP
-.B S_IXUSR
-00100 user has execute permission
-.TP
-.B S_IRWXG
-00070 group has read, write and execute permission
-.TP
-.B S_IRGRP
-00040 group has read permission
-.TP
-.B S_IWGRP
-00020 group has write permission
-.TP
-.B S_IXGRP
-00010 group has execute permission
-.TP
-.B S_IRWXO
-00007 others have read, write and execute permission
-.TP
-.B S_IROTH
-00004 others have read permission
-.TP
-.B S_IWOTH
-00002 others have write permission
-.TP
-.B S_IXOTH
-00001 others have execute permission
 .RE
 .TP
 .BR O_DIRECT " (since Linux 2.4.10)"
@@ -1489,6 +1455,11 @@ as a performance option which is disabled by default.
 interface is just stupid, and was probably designed by a deranged monkey
 on some serious mind-controlling substances."\(emLinus
 .RE
+.SH NOTES
+Under Linux, apart from the permission bits, the
+.BR S_ISUID ", " S_ISGID ", and " S_ISVTX
+.I mode
+bits are also honored.
 .SH BUGS
 Currently, it is not possible to enable signal-driven
 I/O by specifying
diff --git a/man2/stat.2 b/man2/stat.2
index a78ffaf..aa9494f 100644
--- a/man2/stat.2
+++ b/man2/stat.2
@@ -381,18 +381,18 @@ S_ISUID	0004000	set-user-ID bit
 S_ISGID	0002000	set-group-ID bit (see below)
 S_ISVTX	0001000	sticky bit (see below)
 
-S_IRWXU	  00700	mask for file owner permissions
+S_IRWXU	  00700	owner has read, write and execute permission
 S_IRUSR	  00400	owner has read permission
 S_IWUSR	  00200	owner has write permission
 S_IXUSR	  00100	owner has execute permission
 
-S_IRWXG	  00070	mask for group permissions
+S_IRWXG	  00070	group has read, write and execute permission
 S_IRGRP	  00040	group has read permission
 S_IWGRP	  00020	group has write permission
 S_IXGRP	  00010	group has execute permission
 
 S_IRWXO	  00007	T{
-mask for permissions for others (not in group)
+others (not in group) have read, write and execute permission
 T}
 S_IROTH	  00004	others have read permission
 S_IWOTH	  00002	others have write permission
-- 
2.1.0

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/2] umask.2, open.2, mknod.2, mkdir.2: Explain what default acls do

[Andreas Gruenbacher]

Explain the effect that default acls have (instead of the umask) in umask.2.
Mention that default acls can have an affect in open.2, mknod.2, and mkdir.2.

Signed-off-by: Andreas Gruenbacher <agruenba-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
 man2/mkdir.2 |  5 ++---
 man2/mknod.2 |  5 +++--
 man2/open.2  |  3 ++-
 man2/umask.2 | 11 +++++++++++
 4 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/man2/mkdir.2 b/man2/mkdir.2
index 41fad55..42fc26b 100644
--- a/man2/mkdir.2
+++ b/man2/mkdir.2
@@ -54,7 +54,8 @@ The argument
 specifies the permissions to use.
 It is modified by the process's
 .I umask
-in the usual way: the permissions of the created directory are
+in the usual way: in the absence of a default acl, the permissions of the
+created directory are
 .RI ( mode " & ~" umask " & 0777)."
 Other mode bits of the created directory depend on the operating system.
 For Linux, see below.
@@ -212,8 +213,6 @@ POSIX.1-2008.
 Under Linux, apart from the permission bits, only the
 .B S_ISVTX
 mode bit is honored.
-That is, under Linux the created directory actually gets mode
-.RI ( mode " & ~" umask " & 01777)."
 See also
 .BR stat (2).
 .PP
diff --git a/man2/mknod.2 b/man2/mknod.2
index e93c345..7a8dd1e 100644
--- a/man2/mknod.2
+++ b/man2/mknod.2
@@ -63,8 +63,9 @@ listed below and the permissions for the new node.
 
 The permissions are modified by the process's
 .I umask
-in the usual way: the permissions of the created node are
-.IR "(mode & ~umask)" .
+in the usual way: in the absence of a default acl, the permissions of the
+created node are
+.RI ( mode " & ~" umask ).
 
 The file type must be one of
 .BR S_IFREG ,
diff --git a/man2/open.2 b/man2/open.2
index 96ee576..7508222 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -280,7 +280,8 @@ is ignored.
 The effective permissions are modified by
 the process's
 .I umask
-in the usual way: The permissions of the created file are
+in the usual way: In the absence of a default acl, the permissions of the
+created file are
 .IR "(mode\ &\ ~umask)" .
 Note that this mode applies only to future accesses of the
 newly created file; the
diff --git a/man2/umask.2 b/man2/umask.2
index e5e5750..905f2cd 100644
--- a/man2/umask.2
+++ b/man2/umask.2
@@ -63,6 +63,17 @@ argument to
 and
 .BR mkdir (2).
 
+Alternatively, if the parent directory has a default acl (see
+.BR acl (5)),
+the umask is ignored, the default acl is inherited, the permission bits are set
+based on the inherited acl, and permission bits absent in the
+.I mode
+argument are turned off.  For example, the default acl
+u::rwx,g::r-x,o::r-x is equivalent to a umask of 022, and with a
+.I mode
+argument of 0666 (rw-rw-rw-), the resulting file permissions are 0644
+(rw-r--r--).
+
 The constants that should be used to specify
 .I mask
 are described under
-- 
2.1.0

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] umask.2, open.2, mknod.2, mkdir.2: Explain what default acls do

[Michael Kerrisk (man-pages)]

Hi Andreas,

I applied, but fixed a little, including one important detail below.

On 04/13/2015 07:38 PM, Andreas Gruenbacher wrote:
> Explain the effect that default acls have (instead of the umask) in umask.2.
> Mention that default acls can have an affect in open.2, mknod.2, and mkdir.2.
> 
> Signed-off-by: Andreas Gruenbacher <agruenba-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> ---
>  man2/mkdir.2 |  5 ++---
>  man2/mknod.2 |  5 +++--
>  man2/open.2  |  3 ++-
>  man2/umask.2 | 11 +++++++++++
>  4 files changed, 18 insertions(+), 6 deletions(-)
> 
> diff --git a/man2/mkdir.2 b/man2/mkdir.2
> index 41fad55..42fc26b 100644
> --- a/man2/mkdir.2
> +++ b/man2/mkdir.2
> @@ -54,7 +54,8 @@ The argument
>  specifies the permissions to use.
>  It is modified by the process's
>  .I umask
> -in the usual way: the permissions of the created directory are
> +in the usual way: in the absence of a default acl, the permissions of the
> +created directory are
>  .RI ( mode " & ~" umask " & 0777)."
>  Other mode bits of the created directory depend on the operating system.
>  For Linux, see below.
> @@ -212,8 +213,6 @@ POSIX.1-2008.
>  Under Linux, apart from the permission bits, only the
>  .B S_ISVTX
>  mode bit is honored.
> -That is, under Linux the created directory actually gets mode
> -.RI ( mode " & ~" umask " & 01777)."

You dropped a "1" from the expression here. I restored it.

Thanks for the patch!

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] open.2: Clarify which create mode bits are relevant

[Michael Kerrisk (man-pages)]

Hi Andreas,

On 04/13/2015 07:38 PM, Andreas Gruenbacher wrote:
> Clarify that on Linux, the S_ISUID, S_ISGID, and S_IVTX bits in the create mode
> are also honored.
> 
> Instead of repeating the S_I* definitions here, incompletely, refer to stat(2).

Thanks for the patch.

I'd have preferred it in three pieces, though, I think:

1) Improve stat(2)
2) Remove mode bits from open(92)
3) Explain that open(2) honors the S_ISVTX, S_ISUID, and S_ISGID.

What I did was to:

Accept (1).

Reject (2), since I'd rather save the reader of open(3) the trouble of 
consulting another page (and open(2) is likely a more often used man page 
than stat(2)).

Do (3) in a rather different way, that captures your intent. The changes are
already pushed to Git, in case you want to take a look.

Cheers,

Michael

> Signed-off-by: Andreas Gruenbacher <agruenba-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> ---
>  man2/open.2 | 51 +++++++++++----------------------------------------
>  man2/stat.2 |  6 +++---
>  2 files changed, 14 insertions(+), 43 deletions(-)
> 
> diff --git a/man2/open.2 b/man2/open.2
> index 053bab1..96ee576 100644
> --- a/man2/open.2
> +++ b/man2/open.2
> @@ -258,7 +258,12 @@ described in
>  .RS
>  .PP
>  .I mode
> -specifies the permissions to use in case a new file is created.
> +specifies the permissions to use in case a new file is created; see
> +the definition of the file permission mask values in
> +.BR stat (2).
> +When bits other than the file permission bits are set in
> +.IR mode ,
> +the effect is unspecified; for Linux, see below.
>  This argument must be supplied when
>  .B O_CREAT
>  or
> @@ -282,45 +287,6 @@ newly created file; the
>  .BR open ()
>  call that creates a read-only file may well return a read/write
>  file descriptor.
> -.PP
> -The following symbolic constants are provided for
> -.IR mode :
> -.TP 9
> -.B S_IRWXU
> -00700 user (file owner) has read, write and execute permission
> -.TP
> -.B S_IRUSR
> -00400 user has read permission
> -.TP
> -.B S_IWUSR
> -00200 user has write permission
> -.TP
> -.B S_IXUSR
> -00100 user has execute permission
> -.TP
> -.B S_IRWXG
> -00070 group has read, write and execute permission
> -.TP
> -.B S_IRGRP
> -00040 group has read permission
> -.TP
> -.B S_IWGRP
> -00020 group has write permission
> -.TP
> -.B S_IXGRP
> -00010 group has execute permission
> -.TP
> -.B S_IRWXO
> -00007 others have read, write and execute permission
> -.TP
> -.B S_IROTH
> -00004 others have read permission
> -.TP
> -.B S_IWOTH
> -00002 others have write permission
> -.TP
> -.B S_IXOTH
> -00001 others have execute permission
>  .RE
>  .TP
>  .BR O_DIRECT " (since Linux 2.4.10)"
> @@ -1489,6 +1455,11 @@ as a performance option which is disabled by default.
>  interface is just stupid, and was probably designed by a deranged monkey
>  on some serious mind-controlling substances."\(emLinus
>  .RE
> +.SH NOTES
> +Under Linux, apart from the permission bits, the
> +.BR S_ISUID ", " S_ISGID ", and " S_ISVTX
> +.I mode
> +bits are also honored.
>  .SH BUGS
>  Currently, it is not possible to enable signal-driven
>  I/O by specifying
> diff --git a/man2/stat.2 b/man2/stat.2
> index a78ffaf..aa9494f 100644
> --- a/man2/stat.2
> +++ b/man2/stat.2
> @@ -381,18 +381,18 @@ S_ISUID	0004000	set-user-ID bit
>  S_ISGID	0002000	set-group-ID bit (see below)
>  S_ISVTX	0001000	sticky bit (see below)
>  
> -S_IRWXU	  00700	mask for file owner permissions
> +S_IRWXU	  00700	owner has read, write and execute permission
>  S_IRUSR	  00400	owner has read permission
>  S_IWUSR	  00200	owner has write permission
>  S_IXUSR	  00100	owner has execute permission
>  
> -S_IRWXG	  00070	mask for group permissions
> +S_IRWXG	  00070	group has read, write and execute permission
>  S_IRGRP	  00040	group has read permission
>  S_IWGRP	  00020	group has write permission
>  S_IXGRP	  00010	group has execute permission
>  
>  S_IRWXO	  00007	T{
> -mask for permissions for others (not in group)
> +others (not in group) have read, write and execute permission
>  T}
>  S_IROTH	  00004	others have read permission
>  S_IWOTH	  00002	others have write permission
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] open.2: Clarify which create mode bits are relevant

[Andreas Grünbacher]

Michael,

thanks for your further improvements. I agree with most of them, some
things didn't go so well though:


Commit "stat.2: Tighten wording: use 'mode bit' rather than
'permission bit'" is bad:

The stat man page distinguishes between the "file type component" and
"file permissions component" of the mode; now this distinction is
broken. Also, the second sentence now even makes less sense (not that
it did make much sense before):

"According to POSIX.1-2001, lstat() on a symbolic link need return
valid information only in the st_size field and the file-type
component of the st_mode field of the stat structure.  POSIX.1-2008
tightens the specification, requiring lstat() to return valid
information in all fields except the mode bits in st_mode."

My guess wuold be that POSIX.1-2008 actually requires valid permission
bits as well.


Commit "mkdir.2: Fix a small error added by Andreas's patch" is also bad:

The mkdir(2) man page was describing the general behavior under
DESCRIPTION and the Linux behavior under NOTES; it should still do so
but now it doesn't anymore.


Thanks,
Andreas
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] open.2: Clarify which create mode bits are relevant

[Michael Kerrisk (man-pages)]

Hi Andreas,

On 04/21/2015 03:02 PM, Andreas Grünbacher wrote:
> Michael,
> 
> thanks for your further improvements. I agree with most of them, some
> things didn't go so well though:
> 
> 
> Commit "stat.2: Tighten wording: use 'mode bit' rather than
> 'permission bit'" is bad:
> 
> The stat man page distinguishes between the "file type component" and
> "file permissions component" of the mode; now this distinction is
> broken. Also, the second sentence now even makes less sense (not that
> it did make much sense before):

The thing is, POSIX goes into slightly finer granularity than that, 
and that's why I made these changes (though it may be that further
tweaks are still required).

POSIX breaks down st_mode as follows:

* File type
* File mode, which consists of:
    (1) The permissions bits
    (2) The three bits S_ISVTX, S_ISUID, S_ISGID

Quoting POSIX:

[[
3.169 File Mode Bits
A file's file permission bits, set-user-ID-on-execution bit 
(S_ISUID), set-group-ID-on-execution bit (S_ISGID), and, on
directories, the restricted deletion flag bit (S_ISVTX).

3.175 File Permission Bits
Information about a file that is used, along with other 
information, to determine whether a process has read, write, or
execute/search permission to a file. The bits are divided into three
parts: owner, group, and other. Each part is used with the 
corresponding file class of processes. These bits are contained in 
the file mode.
]]

I.e., the file mode bits are a superset of the filer permission bits.

And then in the specification of open(), POSIX says:

    When bits other than the file permission bits are set, 
    the effect is unspecified.

So, that's the impetus for my changes. And now I've added this text to stat(2):

       POSIX  refers  to the 12 st_mode bits corresponding to the mask
       07777 as the file mode bits and the least  significant  9  bits
       (00777) as the file permission bits.

With all of that said, does the changes to stat(2) (and other pages)
seem okay to you now?

> "According to POSIX.1-2001, lstat() on a symbolic link need return
> valid information only in the st_size field and the file-type
> component of the st_mode field of the stat structure.  POSIX.1-2008
> tightens the specification, requiring lstat() to return valid
> information in all fields except the mode bits in st_mode."
> 
> My guess wuold be that POSIX.1-2008 actually requires valid permission
> bits as well.

But it doesn't. The file type in st_mode is required to be valid, but the 
(12) file _mode_ bits are not. POSIX says:

       For symbolic links, the st_mode member shall contain meaningful
       information  when used with the file type macros. The file mode
       bits in st_mode are unspecified.

> Commit "mkdir.2: Fix a small error added by Andreas's patch" is also bad:
> 
> The mkdir(2) man page was describing the general behavior under
> DESCRIPTION and the Linux behavior under NOTES; it should still do so
> but now it doesn't anymore.

The problem I saw was that the page was somewhat contradictory. But I 
see that you're right, that I mushed things somewhat in trying to fix
this. I've reworked the text now. Hopefully you find it better. Thanks
for spotting the mess up.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html