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.