.\" 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-08-19 "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.
If
.I newpath
-exists it will
+exists, it will
.I not
be overwritten.
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.
+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 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.
+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
+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 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 olddirfd
+is a file descriptor referring to a file other than a directory;
+or similar for
+.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;
+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).
+.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.
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),
.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/.
OSDN Git Service
