link.2: Merge text of linkat(2)

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

man2/link.2

@@ -1,5 +1,6 @@
 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
 .\"             and Copyright (C) 1993 Michael Haardt, Ian Jackson.
+.\" and Copyright (C) 2006, 2014 Michael Kerrisk
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -28,13 +29,40 @@
 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
 .\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2
 .\"
-.TH LINK 2 2013-01-27 "Linux" "Linux Programmer's Manual"
+.TH LINK 2 2014-02-21 "Linux" "Linux Programmer's Manual"
 .SH NAME
-link \- make a new name for a file
+link, linkat \- make a new name for a file
 .SH SYNOPSIS
+.nf
 .B #include <unistd.h>
 .sp
 .BI "int link(const char *" oldpath ", const char *" newpath );
+.sp
+.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.B #include <unistd.h>
+.sp
+.BI "int linkat(int " olddirfd ", const char *" oldpath ,
+.BI "           int " newdirfd ", const char *" newpath ", int " flags );
+.fi
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR linkat ():
+.PD 0
+.ad l
+.RS 4
+.TP 4
+Since glibc 2.10:
+_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
+.TP
+Before glibc 2.10:
+_ATFILE_SOURCE
+.RE
+.ad
+.PD
 .SH DESCRIPTION
 .BR link ()
 creates a new link (also known as a hard link) to an existing file.
@@ -49,6 +77,102 @@ This new name may be used exactly as the old one for any operation;
 both names refer to the same file (and so have the same permissions
 and ownership) and it is impossible to tell which name was the
 "original".
+.SS linkat()
+The
+.BR linkat ()
+system call operates in exactly the same way as
+.BR link (2),
+except for the differences described here.
+
+If the pathname given in
+.I oldpath
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I olddirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR link (2)
+for a relative pathname).
+
+If
+.I oldpath
+is relative and
+.I olddirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I oldpath
+is interpreted relative to the current working
+directory of the calling process (like
+.BR link (2)).
+
+If
+.I oldpath
+is absolute, then
+.I olddirfd
+is ignored.
+
+The interpretation of
+.I newpath
+is as for
+.IR oldpath ,
+except that a relative pathname is interpreted relative
+to the directory referred to by the file descriptor
+.IR newdirfd .
+
+The following values can be bitwise 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)).
+This flag is Linux-specific; define
+.B _GNU_SOURCE
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+.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)).
+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.
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR linkat ().
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
@@ -135,11 +259,60 @@ are not on the same mounted filesystem.
 .BR link ()
 does not work across different mount points,
 even if the same filesystem is mounted on both.)
+.PP
+The following additional errors can occur for
+.BR linkat ():
+.TP
+.B EBADF
+.I olddirfd
+or
+.I newdirfd
+is not a valid file descriptor.
+.TP
+.B EINVAL
+An invalid flag value was specified in
+.IR flags .
+.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 ENOENT
+An attempt was made to link to the
+.I /proc/self/fd/NN
+file corresponding to a file descriptor created with
+
+    open(path, O_TMPFILE | O_EXCL, mode);
+
+See
+.BR open (2).
+.TP
+.B ENOTDIR
+.I oldpath
+is relative and
+.I olddirfd
+is a file descriptor referring to a file other than a directory;
+or similar for
+.I newpath
+and
+.I newdirfd
+.SH VERSIONS
+.BR linkat ()
+was added to Linux in kernel 2.6.16;
+library support was added to glibc in version 2.4.
 .SH CONFORMING TO
+.BR link ():
 SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES).
 .\" SVr4 documents additional ENOLINK and
 .\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP.
 .\" X/OPEN does not document EFAULT, ENOMEM or EIO.
+
+.BR linkat ():
+POSIX.1-2008.
 .SH NOTES
 Hard links, as created by
 .BR link (),
@@ -186,7 +359,6 @@ Use
 to find out if the link got created.
 .SH SEE ALSO
 .BR ln (1),
-.BR linkat (2),
 .BR open (2),
 .BR rename (2),
 .BR stat (2),