linkat.2: Document AT_EMPTY_PATH

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

man2/linkat.2

@@ -22,8 +22,6 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.\" FIXME: Linux 2.6.39 added AT_EMPTY_PATH
-.\"
 .TH LINKAT 2 2012-05-04 "Linux" "Linux Programmer's Manual"
 .SH NAME
 linkat \- create a file link relative to directory file descriptors
@@ -97,19 +95,47 @@ except that a relative pathname is interpreted relative
 to the directory referred to by the file descriptor
 .IR newdirfd .
 
+The following values can be biwise ORed in
+.IR flags :
+.TP
+.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
+.\" commit 11a7b371b64ef39fc5fb1b6f2218eef7c4d035e3
+If
+.I oldpath
+is an empty string, create a link to the file referenced by
+.IR olddirfd 
+(which may have been obtained using the
+.BR open (2)
+.B O_PATH
+flag).
+In this case,
+.I olddirfd
+can refer to any type of file, not just a directory.
+The caller must have the
+.BR CAP_DAC_READ_SEARCH
+capability in order to use this flag;
+this prevents arbitrary users from creating hard links
+using file descriptors received via a UNIX domain socket
+(see the discussion of
+.BR SCM_RIGHTS
+in
+.BR unix (7)).
+.TP
+.BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)"
 By default,
 .BR linkat (),
 does not dereference
 .I oldpath
 if it is a symbolic link (like
 .BR link (2)).
-Since Linux 2.6.18, the flag
+The flag
 .B AT_SYMLINK_FOLLOW
 can be specified in
 .I flags
 to cause
 .I oldpath
 to be dereferenced if it is a symbolic link.
+.PP
 Before kernel 2.6.18, the
 .I flags
 argument was unused, and had to be specified as 0.
@@ -134,6 +160,16 @@ or
 .I newdirfd
 is not a valid file descriptor.
 .TP
+.B ENOENT
+.B AT_EMPTY_PATH
+was specified in
+.IR flags ,
+but the caller did not have the
+.B CAP_DAC_READ_SEARCH
+capability.
+.TP
+.B ENOTDIR
+.TP
 .B ENOTDIR
 .I oldpath
 is relative and