manual: Document the O_TMPFILE flag

2017-11-03  Florian Weimer  <fweimer@redhat.com>

	* manual/llio.texi (Open-time Flags): Document O_TMPFILE.

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>