.\" 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
.\" 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.
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 (),
+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 ()
+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 ()).
+
+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 ()).
+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
.BR EPERM " (since Linux 3.6)"
The caller does not have permission to create a hard link to this file
(see the description of
-.IR /proc/sys/fs/protected_hardlink
+.IR /proc/sys/fs/protected_hardlinks
in
.BR proc (5)).
.TP
.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
-SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES).
+.BR link ():
+SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008.
.\" 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 (),
.I oldpath
is dereferenced if it is a symbolic link.
For precise control over the treatment of symbolic links when
-creating a link, see
+creating a link, use
.BR linkat (2).
.SH BUGS
On NFS filesystems, the return code may be wrong in case the NFS server
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),