Re: [PATCH] manual: Document the O_TMPFILE flag

[Jonathan Nieder <jrnieder at gmail dot com>]

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