manual: Clarify File Access Modes section and add O_PATH
Commit Message
Kees Cook reported that the current text is misleading:
<https://lore.kernel.org/lkml/202005150847.2B1ED8F81@keescook/>
---
manual/llio.texi | 68 ++++++++++++++++++++++++++++++++++----------------------
1 file changed, 42 insertions(+), 26 deletions(-)
Comments
Hi Florian,
On 5/18/20 9:49 AM, Florian Weimer wrote:
> Kees Cook reported that the current text is misleading:
>
> <https://lore.kernel.org/lkml/202005150847.2B1ED8F81@keescook/>
>
> ---
> manual/llio.texi | 68 ++++++++++++++++++++++++++++++++++----------------------
> 1 file changed, 42 insertions(+), 26 deletions(-)
>
> diff --git a/manual/llio.texi b/manual/llio.texi
> index 6db4a70836..dd206b1b91 100644
> --- a/manual/llio.texi
> +++ b/manual/llio.texi
> @@ -3564,9 +3564,8 @@ The symbols in this section are defined in the header file
> @subsection File Access Modes
>
> The file access modes allow a file descriptor to be used for reading,
> -writing, or both. (On @gnuhurdsystems{}, they can also allow none of these,
> -and allow execution of the file as a program.) The access modes are chosen
> -when the file is opened, and never change.
> +writing, both, or neither. The access modes are chosen when the file
> +is opened, and never change.
>
> @deftypevr Macro int O_RDONLY
> @standards{POSIX.1, fcntl.h}
> @@ -3583,6 +3582,42 @@ Open the file for write access.
> Open the file for both reading and writing.
> @end deftypevr
>
> +@deftypevr Macro int O_PATH
> +@standards{Linux, fcntl.h}
> +Obtain a file descriptor for the file, but do not open this file for
> +reading or writing. Permission checks for the file itself are skipped
> +when the file is opened (but permission to access the directory that
> +contains it is still needed), and permissions are checked when the
> +descriptor is used later.
> +
> +For example, such descriptors can be used with the @code{fexecve}
> +function (@pxref{Executing a File}).
> +
> +This access mode is specific to Linux. On @gnuhurdsystems{}, it is
> +possible to use @code{O_EXEC} explicitly, or specify no access modes
> +at all (see below).
> +@end deftypevr
> +
> +To determine the file access mode with @code{fcntl}, you must extract
> +the access mode bits from the retrieved file status flags. The
> +portable way to extract the file access mode bits is with
> +@code{O_ACCMODE}.
> +
> +@deftypevr Macro int O_ACCMODE
> +@standards{POSIX.1, fcntl.h}
> +
> +This macro stands for a mask that can be bitwise-ANDed with the file
s/stands for a mask/is a mask/ ?
> +status flag value to produce a value representing the file access
s/produce a value representing the/extract the bits representing the/ ?
> +mode. Usually, The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or
> +@code{O_RDWR}.
> +@end deftypevr
> +
> +If the mode is zero, it means that a non-standard access mode has been
> +used.
Either I misunderstand the previous sentence, or I think it is
wrong. O_RDONLY has the value 0; that's a standard access mode.
> See @code{O_PATH} above and @code{O_EXEC} below. These
> +non-standard access modes are identified by individual bits can
> +therefore be checked directly (without masking with @code{O_ACCMODE}
> +first).
> +
> On @gnuhurdsystems{} (and not on other systems), @code{O_RDONLY} and
Not a problem with your patch, but in the above, better would be:
s/and/but/
> @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
> and it is valid for either bit to be set or clear. This means that
> @@ -3591,40 +3626,21 @@ mode of zero is permissible; it allows no operations that do input or
> output to the file, but does allow other operations such as
> @code{fchmod}. On @gnuhurdsystems{}, since ``read-only'' or ``write-only''
> is a misnomer, @file{fcntl.h} defines additional names for the file
> -access modes. These names are preferred when writing GNU-specific code.
> -But most programs will want to be portable to other POSIX.1 systems and
> -should use the POSIX.1 names above instead.
> +access modes.
I do think removing this advice about POSIX is a bad move.
Why do you want to advise people to use GNU-specific names?
(I suspect I must be missing something...)
> @deftypevr Macro int O_READ
> @standards{GNU, fcntl.h (optional)}
> -Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU.
> +Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU/Hurd.
> @end deftypevr
>
> @deftypevr Macro int O_WRITE
> @standards{GNU, fcntl.h (optional)}
> -Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU.
> +Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU/Hurd.
> @end deftypevr
>
> @deftypevr Macro int O_EXEC
> @standards{GNU, fcntl.h (optional)}
> -Open the file for executing. Only defined on GNU.
> -@end deftypevr
> -
> -To determine the file access mode with @code{fcntl}, you must extract
> -the access mode bits from the retrieved file status flags. On
> -@gnuhurdsystems{},
> -you can just test the @code{O_READ} and @code{O_WRITE} bits in
> -the flags word. But in other POSIX.1 systems, reading and writing
> -access modes are not stored as distinct bit flags. The portable way to
> -extract the file access mode bits is with @code{O_ACCMODE}.
> -
> -@deftypevr Macro int O_ACCMODE
> -@standards{POSIX.1, fcntl.h}
> -This macro stands for a mask that can be bitwise-ANDed with the file
> -status flag value to produce a value representing the file access mode.
> -The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
> -(On @gnuhurdsystems{} it could also be zero, and it never includes the
> -@code{O_EXEC} bit.)
> +Open the file for executing. Only defined on GNU/Hurd.
> @end deftypevr
>
> @node Open-time Flags
Thanks,
Michael
* Michael Kerrisk:
>> +mode. Usually, The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or
>> +@code{O_RDWR}.
>> +@end deftypevr
>> +
>> +If the mode is zero, it means that a non-standard access mode has been
>> +used.
>
> Either I misunderstand the previous sentence, or I think it is
> wrong. O_RDONLY has the value 0; that's a standard access mode.
Meh, I had forgotten about that. That makes the interaction of
O_ACCMODE and non-POSIX access modes certainly more complicated.
I'll have to think about it.
>> @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
>> and it is valid for either bit to be set or clear. This means that
>> @@ -3591,40 +3626,21 @@ mode of zero is permissible; it allows no operations that do input or
>> output to the file, but does allow other operations such as
>> @code{fchmod}. On @gnuhurdsystems{}, since ``read-only'' or ``write-only''
>> is a misnomer, @file{fcntl.h} defines additional names for the file
>> -access modes. These names are preferred when writing GNU-specific code.
>> -But most programs will want to be portable to other POSIX.1 systems and
>> -should use the POSIX.1 names above instead.
>> +access modes.
>
> I do think removing this advice about POSIX is a bad move.
> Why do you want to advise people to use GNU-specific names?
> (I suspect I must be missing something...)
“GNU-specific code” is ambiguous. We sometimes talk about the
platform-independent GNU API, meaning the API that glibc provides on all
ports. But here, “GNU-specific” really means “Hurd-specific”.
Thanks,
Florian
Hi Florian,
[...]
> >> @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
> >> and it is valid for either bit to be set or clear. This means that
> >> @@ -3591,40 +3626,21 @@ mode of zero is permissible; it allows no operations that do input or
> >> output to the file, but does allow other operations such as
> >> @code{fchmod}. On @gnuhurdsystems{}, since ``read-only'' or ``write-only''
> >> is a misnomer, @file{fcntl.h} defines additional names for the file
> >> -access modes. These names are preferred when writing GNU-specific code.
> >> -But most programs will want to be portable to other POSIX.1 systems and
> >> -should use the POSIX.1 names above instead.
> >> +access modes.
> >
> > I do think removing this advice about POSIX is a bad move.
> > Why do you want to advise people to use GNU-specific names?
> > (I suspect I must be missing something...)
>
> “GNU-specific code” is ambiguous. We sometimes talk about the
> platform-independent GNU API, meaning the API that glibc provides on all
> ports. But here, “GNU-specific” really means “Hurd-specific”.
Got it. On second thoughts, I think your change here is fune.
Thanks,
Michael
@@ -3564,9 +3564,8 @@ The symbols in this section are defined in the header file
@subsection File Access Modes
The file access modes allow a file descriptor to be used for reading,
-writing, or both. (On @gnuhurdsystems{}, they can also allow none of these,
-and allow execution of the file as a program.) The access modes are chosen
-when the file is opened, and never change.
+writing, both, or neither. The access modes are chosen when the file
+is opened, and never change.
@deftypevr Macro int O_RDONLY
@standards{POSIX.1, fcntl.h}
@@ -3583,6 +3582,42 @@ Open the file for write access.
Open the file for both reading and writing.
@end deftypevr
+@deftypevr Macro int O_PATH
+@standards{Linux, fcntl.h}
+Obtain a file descriptor for the file, but do not open this file for
+reading or writing. Permission checks for the file itself are skipped
+when the file is opened (but permission to access the directory that
+contains it is still needed), and permissions are checked when the
+descriptor is used later.
+
+For example, such descriptors can be used with the @code{fexecve}
+function (@pxref{Executing a File}).
+
+This access mode is specific to Linux. On @gnuhurdsystems{}, it is
+possible to use @code{O_EXEC} explicitly, or specify no access modes
+at all (see below).
+@end deftypevr
+
+To determine the file access mode with @code{fcntl}, you must extract
+the access mode bits from the retrieved file status flags. The
+portable way to extract the file access mode bits is with
+@code{O_ACCMODE}.
+
+@deftypevr Macro int O_ACCMODE
+@standards{POSIX.1, fcntl.h}
+
+This macro stands for a mask that can be bitwise-ANDed with the file
+status flag value to produce a value representing the file access
+mode. Usually, The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or
+@code{O_RDWR}.
+@end deftypevr
+
+If the mode is zero, it means that a non-standard access mode has been
+used. See @code{O_PATH} above and @code{O_EXEC} below. These
+non-standard access modes are identified by individual bits can
+therefore be checked directly (without masking with @code{O_ACCMODE}
+first).
+
On @gnuhurdsystems{} (and not on other systems), @code{O_RDONLY} and
@code{O_WRONLY} are independent bits that can be bitwise-ORed together,
and it is valid for either bit to be set or clear. This means that
@@ -3591,40 +3626,21 @@ mode of zero is permissible; it allows no operations that do input or
output to the file, but does allow other operations such as
@code{fchmod}. On @gnuhurdsystems{}, since ``read-only'' or ``write-only''
is a misnomer, @file{fcntl.h} defines additional names for the file
-access modes. These names are preferred when writing GNU-specific code.
-But most programs will want to be portable to other POSIX.1 systems and
-should use the POSIX.1 names above instead.
+access modes.
@deftypevr Macro int O_READ
@standards{GNU, fcntl.h (optional)}
-Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU.
+Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU/Hurd.
@end deftypevr
@deftypevr Macro int O_WRITE
@standards{GNU, fcntl.h (optional)}
-Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU.
+Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU/Hurd.
@end deftypevr
@deftypevr Macro int O_EXEC
@standards{GNU, fcntl.h (optional)}
-Open the file for executing. Only defined on GNU.
-@end deftypevr
-
-To determine the file access mode with @code{fcntl}, you must extract
-the access mode bits from the retrieved file status flags. On
-@gnuhurdsystems{},
-you can just test the @code{O_READ} and @code{O_WRITE} bits in
-the flags word. But in other POSIX.1 systems, reading and writing
-access modes are not stored as distinct bit flags. The portable way to
-extract the file access mode bits is with @code{O_ACCMODE}.
-
-@deftypevr Macro int O_ACCMODE
-@standards{POSIX.1, fcntl.h}
-This macro stands for a mask that can be bitwise-ANDed with the file
-status flag value to produce a value representing the file access mode.
-The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
-(On @gnuhurdsystems{} it could also be zero, and it never includes the
-@code{O_EXEC} bit.)
+Open the file for executing. Only defined on GNU/Hurd.
@end deftypevr
@node Open-time Flags