This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH] manual: Document the O_TMPFILE flag


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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]