[v2] manual: Clarify File Access Modes section and add O_PATH

Kees Cook reported that the current text is misleading:

  <https://lore.kernel.org/lkml/202005150847.2B1ED8F81@keescook/>

---
Changes in v2: I picked up Michael's suggestions and tried to get
  it right when masking with O_ACCMODE works and when it does not.

 manual/llio.texi | 70 ++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 43 insertions(+), 27 deletions(-)

Hi FLoriab,

On 12/2/20 1:03 PM, Florian Weimer wrote:
> Kees Cook reported that the current text is misleading:
> 
>   <https://lore.kernel.org/lkml/202005150847.2B1ED8F81@keescook/>
> 
> ---
> Changes in v2: I picked up Michael's suggestions and tried to get
>   it right when masking with O_ACCMODE works and when it does not.
> 
>  manual/llio.texi | 70 ++++++++++++++++++++++++++++++++++----------------------
>  1 file changed, 43 insertions(+), 27 deletions(-)
> 
> diff --git a/manual/llio.texi b/manual/llio.texi
> index 6db4a70836..75a2fe685c 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

Perhaps: s/are chosen/are determined/

> +is opened, and never change.
>  
>  @deftypevr Macro int O_RDONLY
>  @standards{POSIX.1, fcntl.h}
> @@ -3583,7 +3582,43 @@ Open the file for write access.
>  Open the file for both reading and writing.
>  @end deftypevr
>  
> -On @gnuhurdsystems{} (and not on other systems), @code{O_RDONLY} and
> +@deftypevr Macro int O_PATH
> +@standards{Linux, fcntl.h}
> +Obtain a file descriptor for the file, but do not open this file for

s/this/the/

> +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.

Perhaps a little more idiomatic: s/used later/later used/

> +
> +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
> +
> +The portable file access modes @code{O_RDONLY}, @code{O_WRONLY}, and
> +@code{O_RDWR} may not correspond to individual bits.  To determine the
> +file access mode with @code{fcntl}, you must extract the access mode
> +bits from the retrieved file status flags, using the @code{O_ACCMODE}
> +mask.
> +
> +@deftypevr Macro int O_ACCMODE
> +@standards{POSIX.1, fcntl.h}
> +
> +This macro is a mask that can be bitwise-ANDed with the file status flag
> +value to recover the file access mode, assuming that a standard file
> +access mode is in use.

You switch between "access modes" earlier and "access mode" here.
I myself tend to use the singular, though I see that POSIX is also
a little fuzzy in its use of plural vs singular.

Thanks,

Michael


> +@end deftypevr
> +
> +If a non-standard file access mode is used (such as @code{O_PATH} or
> +@code{O_EXEC}), masking with @code{O_ACCMODE} may give incorrect
> +results.  These non-standard access modes are identified by individual
> +bits and have to be checked directly (without masking with
> +@code{O_ACCMODE} first).
> +
> +On @gnuhurdsystems{} (but 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
>  @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}.  A file access
> @@ -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
>

* Michael Kerrisk:

>> +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.
>
> Perhaps a little more idiomatic: s/used later/later used/

“is used later on"?

> You switch between "access modes" earlier and "access mode" here.
> I myself tend to use the singular, though I see that POSIX is also
> a little fuzzy in its use of plural vs singular.

I changed the introduction to singular in v3.  Now “modes” refer to
multiple different O_* constants, I think, so it should be consistent.

As discussed a while back, the idea that O_RDWR consists of multiple
access modes is predominantly Hurd-specific.

Thanks,
Florian