Message ID | 20171103213714.8303C41F1E4EF@oldenburg.str.redhat.com |
---|---|
State | New |
Headers | show |
Series | manual: Document the O_TMPFILE flag | expand |
Hi, Florian Weimer wrote: > --- a/manual/llio.texi > +++ b/manual/llio.texi > @@ -3478,6 +3478,25 @@ If set, the file will be created if it doesn't already exist. [...] > +@deftypevr Macro int O_TMPFILE > +@standards{GNU, fcntl.h} If this flag is specified, functions in the For the other flags there's a line break after the } here. I don't know whether it matters. > +@code{open} family create an unnamed temporary file in the directory > +@var{filename}. The @code{O_TMPFILE} flag must be combined with @var{filename} isn't defined here. How about "the named directory"? > +@code{O_WRONLY} or @code{O_RDWR}, and the @var{mode} argument is > +required. The file can later be given a name using @code{linkat}. To > +prevent that, specify the @code{O_EXCL} flag at open time. To prevent what? Can you describe an example scenario where O_EXCL would be used? > + > +Not all kernels support this open flag. If this flag is unsupported, > +the function call fails with an error of @code{EINVAL}. If the > +underlying file system does not support the @code{O_TMPFILE} flag, an > +@code{EOPNOTSUPP} error is the result. > + > +The @code{O_TMPFILE} flag is a GNU extension. The rest looks good. Thanks, Jonathan
On 11/03/2017 10:58 PM, Jonathan Nieder wrote: > Hi, > > Florian Weimer wrote: > >> --- a/manual/llio.texi >> +++ b/manual/llio.texi >> @@ -3478,6 +3478,25 @@ If set, the file will be created if it doesn't already exist. > [...] >> +@deftypevr Macro int O_TMPFILE >> +@standards{GNU, fcntl.h} If this flag is specified, functions in the > > For the other flags there's a line break after the } here. I don't > know whether it matters. Okay, I will add that here, too. >> +@code{open} family create an unnamed temporary file in the directory >> +@var{filename}. The @code{O_TMPFILE} flag must be combined with > > @var{filename} isn't defined here. How about "the named directory"? It is defined for the open functions. I wasn't sure how to incorporate the fact that the pathname argument is overloaded without totally reorganizing how this information is presented. >> +@code{O_WRONLY} or @code{O_RDWR}, and the @var{mode} argument is >> +required. The file can later be given a name using @code{linkat}. To >> +prevent that, specify the @code{O_EXCL} flag at open time. > > To prevent what? Can you describe an example scenario where O_EXCL > would be used? Giving a name using linkat. Is this really unclear? > The rest looks good. Thanks. Florian
Florian Weimer wrote: > On 11/03/2017 10:58 PM, Jonathan Nieder wrote: >> @var{filename} isn't defined here. How about "the named directory"? > > It is defined for the open functions. I wasn't sure how to incorporate the > fact that the pathname argument is overloaded without totally reorganizing > how this information is presented. What did you think of the suggestion "the named directory"? @var{filename} isn't defined anywhere on the https://www.gnu.org/software/libc/manual/html_node/Open_002dtime-Flags.html page. A reader would have to switch to the single-page version and use ctrl+f. >>> +@code{O_WRONLY} or @code{O_RDWR}, and the @var{mode} argument is >>> +required. The file can later be given a name using @code{linkat}. To >>> +prevent that, specify the @code{O_EXCL} flag at open time. >> >> To prevent what? Can you describe an example scenario where O_EXCL >> would be used? > > Giving a name using linkat. Is this really unclear? It was unclear to me because I couldn't imagine a situation where I'd want to prevent giving the file a name. That led me to second-guess what "that" means. I suspect the simplest way to make it clearer would be to give a suggestion of why someone would want to prevent giving the file a name. E.g. The file can later be given a name using @code{linkat}, which can be undesirable if [scenario described here]. To prevent that, specify the @code{O_EXCL} flag at open time. Sorry I don't have a better suggestion. The problem is that I still don't know what the intended use is. Is it for sandboxing? Thanks, Jonathan
On Fri, 2017-11-03 at 23:51 +0100, Florian Weimer wrote: > +@code{O_WRONLY} or @code{O_RDWR}, and the @var{mode} argument is > > > +required. The file can later be given a name using > > > @code{linkat}. To > > > +prevent that, specify the @code{O_EXCL} flag at open time. > > > > To prevent what? Can you describe an example scenario where O_EXCL > > would be used? > > Giving a name using linkat. Is this really unclear? There's certainly something a bit jarring about that language. I think this might just be because the reference manual is a relatively formal document and the use of the vague "that" as the object seems a bit wrong in that context. But anyway, you could avoid this problem by rephrasing it into a single sentence: "Unless @code{O_EXCL} was specified at open time, the file can later be given a name using @code{linkat}." Or something. But I also agree with the comment that it'd be useful to have a bit of explanation as to when this is a useful thing to do. p.
On 11/04/2017 12:13 AM, Phil Blundell wrote: > On Fri, 2017-11-03 at 23:51 +0100, Florian Weimer wrote: >> +@code{O_WRONLY} or @code{O_RDWR}, and the @var{mode} argument is >>>> +required. The file can later be given a name using >>>> @code{linkat}. To >>>> +prevent that, specify the @code{O_EXCL} flag at open time. >>> >>> To prevent what? Can you describe an example scenario where O_EXCL >>> would be used? >> >> Giving a name using linkat. Is this really unclear? > > There's certainly something a bit jarring about that language. I think > this might just be because the reference manual is a relatively formal > document and the use of the vague "that" as the object seems a bit > wrong in that context. > > But anyway, you could avoid this problem by rephrasing it into a single > sentence: > > "Unless @code{O_EXCL} was specified at open time, the file can later be > given a name using @code{linkat}." I really try to avoid “unless” because I assume it is often confusing. > Or something. But I also agree with the comment that it'd be useful to > have a bit of explanation as to when this is a useful thing to do. I added a bit more explanation. As far as I'm concerned, the O_EXCL flag is a bit of a stretch, and I don't think it's useful. I also attempted to improve the wording regarding the pathname argument. Thanks, Florian 2017-11-03 Florian Weimer <fweimer@redhat.com> * manual/llio.texi (Open-time Flags): Document O_TMPFILE. diff --git a/manual/llio.texi b/manual/llio.texi index e72c53c785..10ad546723 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -3478,6 +3478,34 @@ If set, the file will be created if it doesn't already exist. If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails if the specified file already exists. This is guaranteed to never clobber an existing file. + +The @code{O_EXCL} flag has a special meaning in combination with +@code{O_TMPFILE}; see below. +@end deftypevr + +@deftypevr Macro int O_TMPFILE +@standards{GNU, fcntl.h} +If this flag is specified, functions in the @code{open} family create an +unnamed temporary file. In this case, the pathname argument to the +@code{open} family of functions (@pxref{Opening and Closing Files}) is +interpreted as the directory in which the temporary file is created +(thus determining the file system which provides the storage for the +file). The @code{O_TMPFILE} flag must be combined with @code{O_WRONLY} +or @code{O_RDWR}, and the @var{mode} argument is required. + +The temporary file can later be given a name using @code{linkat}, +turning it into a regular file. This allows the atomic creation of a +file with the specific file attributes (mode and extended attributes) +and file contents. If, for security reasons, it is not desirable that a +name can be given to the file, the @code{O_EXCL} flag can be specified +along with @code{O_TMPFILE}. + +Not all kernels support this open flag. If this flag is unsupported, an +attempt to create an unnamed temporary file fails with an error of +@code{EINVAL}. If the underlying file system does not support the +@code{O_TMPFILE} flag, an @code{EOPNOTSUPP} error is the result. + +The @code{O_TMPFILE} flag is a GNU extension. @end deftypevr @deftypevr Macro int O_NONBLOCK
Florian Weimer wrote: > I added a bit more explanation. As far as I'm concerned, the O_EXCL flag is > a bit of a stretch, and I don't think it's useful. When I tried to think it through, I came to the same conclusion. > I also attempted to improve the wording regarding the pathname argument. Looks good. Thanks for your patient work. Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
diff --git a/manual/llio.texi b/manual/llio.texi index e72c53c785..b2123beefe 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -3478,6 +3478,25 @@ If set, the file will be created if it doesn't already exist. If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails if the specified file already exists. This is guaranteed to never clobber an existing file. + +The @code{O_EXCL} flag has a special meaning in combination with +@code{O_TMPFILE}; see below. +@end deftypevr + +@deftypevr Macro int O_TMPFILE +@standards{GNU, fcntl.h} If this flag is specified, functions in the +@code{open} family create an unnamed temporary file in the directory +@var{filename}. The @code{O_TMPFILE} flag must be combined with +@code{O_WRONLY} or @code{O_RDWR}, and the @var{mode} argument is +required. The file can later be given a name using @code{linkat}. To +prevent that, specify the @code{O_EXCL} flag at open time. + +Not all kernels support this open flag. If this flag is unsupported, +the function call fails with an error of @code{EINVAL}. If the +underlying file system does not support the @code{O_TMPFILE} flag, an +@code{EOPNOTSUPP} error is the result. + +The @code{O_TMPFILE} flag is a GNU extension. @end deftypevr @deftypevr Macro int O_NONBLOCK