open.2: Significant enhancements to O_TMPFILE discussion

Describe use of linkat() with O_TMPFILE.
Note main use cases for O_TMPFILE.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/open.2

@@ -290,6 +290,9 @@ The following symbolic constants are provided for
 .RE
 .TP
 .BR O_TMPFILE " (Since Linux 3.11)"
+.\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
+.\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
+.\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
 Create an unnamed temporary file.
 The
 .I pathname
@@ -297,8 +300,7 @@ argument specifies a directory;
 an unnamed inode will be created in that directory's filesystem.
 Anything written to the resulting file will be lost when
 the last file descriptor is closed, unless the file is given a name.
-.RS
-.PP
+
 .B O_TMPFILE
 must be specified with one of
 .B O_RDWR
@@ -311,12 +313,50 @@ If
 is not specified, then
 .BR linkat (2)
 can be used to link the temporary file into the filesystem, making it
-permanent.
-.PP
-The
+permanent, using code like the following:
+
+.in +4n
+.nf
+char path[PATH_MAX];
+fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
+        S_IRUSR | S_IWUSR);
+/* File I/O on 'fd'... */
+snprintf(path, PATH_MAX,  "/proc/self/fd/%d", fd);
+linkat(AT_FDCWD, path, AT_FDCWD, argv[2],
+        AT_SYMLINK_FOLLOW);
+.fi
+.in
+
+In this case,
+the
+.BR open ()
 .I mode
-argument determines the inode's mode, as with
+argument determines the file permission mode, as with
 .BR O_CREAT .
+
+There are two main use cases for
+.\" Inspired by http://lwn.net/Articles/559147/
+.BR O_TMPFILE :
+.RS
+.IP * 3
+Improved
+.BR tmpfile (3)
+functionality: race-free creation of temporary files that
+(1) are automatically deleted when closed;
+(2) can never be reached via any pathname;
+(3) are not subject to symlink attacks; and
+(4) do not require the caller to devise unique names.
+.IP *
+Creating a file that is initially invisible, which is then populated
+with data and adjusted to have approriate filesystem attributes
+.RB ( chown (2),
+.BR chmod (2),
+.BR fsetxattr (2),
+etc.)
+before being atomically linked into the filesystem
+in a fully formed state (using
+.BR linkat (2)
+as described above).
 .RE
 .TP
 .BR O_DIRECT " (Since Linux 2.4.10)"
@@ -654,6 +694,21 @@ See
 .BR NOTES
 for more information.
 .TP
+.B EINVAL
+Invalid value in
+.\" In particular, __O_TMPFILE instead of O_TMPFILE
+.IR flags .
+.TP
+.B EINVAL
+.B O_TMPFILE
+was specified in
+.IR flags ,
+but neither
+.B O_WRONLY
+nor
+.B O_RDWR
+was specified.
+.TP
 .B EISDIR
 .I pathname
 refers to a directory and the access requested involved writing
@@ -663,6 +718,18 @@ or
 .B O_RDWR
 is set).
 .TP
+.B EISDIR
+.B O_TMPFILE
+and one of
+.B O_WRONLY
+or
+.B O_RDWR
+were specified in
+.IR flags ,
+but this kernel version does not provide the
+.B O_TMPFILE
+functionality.
+.TP
 .B ELOOP
 Too many symbolic links were encountered in resolving
 .IR pathname ,