Message ID | 878shpfzs6.fsf@oldenburg2.str.redhat.com |
---|---|
State | New |
Headers | show |
Series | manual: Clarify File Access Modes section and add O_PATH | expand |
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
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 +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