Re: [PATCH] manual: Document the O_TMPFILE flag

[Florian Weimer <fweimer at redhat dot com>]

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