.\" 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 2014-02-21 "Linux" "Linux Programmer's Manual"
+.TH LINK 2 2014-08-19 "Linux" "Linux Programmer's Manual"
.SH NAME
link, linkat \- make a new name for a file
.SH SYNOPSIS
If
.I newpath
-exists it will
+exists, it will
.I not
be overwritten.
In this case,
.I olddirfd
can refer to any type of file, not just a directory.
+This will generally not work if the file has a link count of zero (files
+created with
+.BR O_TMPFILE
+and without
+.BR O_EXCL
+are an exception).
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)).
+capability in order to use this flag.
This flag is Linux-specific; define
.B _GNU_SOURCE
.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
to cause
.I oldpath
to be dereferenced if it is a symbolic link.
+If procfs is mounted,
+this can be used as an alternative to
+.BR AT_EMPTY_PATH ,
+like this:
+
+.nf
+.in +4n
+linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
+ newname, AT_SYMLINK_FOLLOW);
+.in
+.fi
.PP
Before kernel 2.6.18, the
.I flags
See
.BR open (2).
.TP
+.B ENOENT
+.I oldpath
+is a relative pathname and
+.I olddirfd
+refers to a directory that has been deleted,
+or
+.I newpath
+is a relative pathname and
+.I newdirfd
+refers to a directory that has been deleted.
+.TP
.B ENOTDIR
.I oldpath
is relative and
.I newpath
and
.I newdirfd
+.TP
+.B EPERM
+.BR AT_EMPTY_PATH
+was specified in
+.IR flags ,
+.I oldpath
+is an empty string, and
+.IR olddirfd
+refers to a directory.
.SH VERSIONS
.BR linkat ()
was added to Linux in kernel 2.6.16;
For precise control over the treatment of symbolic links when
creating a link, use
.BR linkat (2).
+.SS Glibc notes
+On older kernels where
+.BR linkat ()
+is unavailable, the glibc wrapper function falls back to the use of
+.BR link (),
+unless the
+.B AT_SYMLINK_FOLLOW
+is specified.
+When
+.I oldpath
+and
+.I newpath
+are relative pathnames,
+glibc constructs pathnames based on the symbolic links in
+.IR /proc/self/fd
+that correspond to the
+.I olddirfd
+and
+.IR newdirfd
+arguments.
.SH BUGS
On NFS filesystems, the return code may be wrong in case the NFS server
performs the link creation and dies before it can say so.
.BR unlink (2),
.BR path_resolution (7),
.BR symlink (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.