'\" et
.TH LINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
link, linkat
\(em link one file to another file
.SH SYNOPSIS
.LP
.nf
#include <unistd.h>
.P
int link(const char *\fIpath1\fP, const char *\fIpath2\fP);
.P
#include <fcntl.h>
.P
int linkat(int \fIfd1\fP, const char *\fIpath1\fP, int \fIfd2\fP,
    const char *\fIpath2\fP, int \fIflag\fP);
.fi
.SH DESCRIPTION
The
\fIlink\fR()
function shall create a new link (directory entry) for the existing file,
.IR path1 .
.P
The
.IR path1
argument points to a pathname naming an existing file. The
.IR path2
argument points to a pathname naming the new directory entry to be
created. The
\fIlink\fR()
function shall atomically create a new link for the existing file and
the link count of the file shall be incremented by one.
.P
If
.IR path1
names a directory,
\fIlink\fR()
shall fail unless the process has appropriate privileges and the
implementation supports using
\fIlink\fR()
on directories.
.P
If
.IR path1
names a symbolic link, it is implementation-defined whether
\fIlink\fR()
follows the symbolic link, or creates a new link to the symbolic
link itself.
.P
Upon successful completion,
\fIlink\fR()
shall mark for update the last file status change timestamp of the
file. Also, the last data modification and last file status change
timestamps of the directory that contains the new entry shall be marked
for update.
.P
If
\fIlink\fR()
fails, no link shall be created and the link count of the file shall
remain unchanged.
.P
The implementation may require that the calling process has permission
to access the existing file.
.P
The
\fIlinkat\fR()
function shall be equivalent to the
\fIlink\fR()
function except that symbolic links shall be handled as specified by
the value of
.IR flag
(see below) and except in the case where either
.IR path1
or
.IR path2
or both are relative paths. In this case a relative path
.IR path1
is interpreted relative to the directory associated with the file
descriptor
.IR fd1
instead of the current working directory and similarly for
.IR path2
and the file descriptor
.IR fd2 .
If the access mode of the open file description associated with the
file descriptor is not O_SEARCH, the function shall check whether
directory searches are permitted using the current permissions of
the directory underlying the file descriptor. If the access mode is
O_SEARCH, the function shall not perform the check.
.P
Values for
.IR flag
are constructed by a bitwise-inclusive OR of flags from the following
list, defined in
.IR <fcntl.h> :
.IP AT_SYMLINK_FOLLOW 6
.br
If
.IR path1
names a symbolic link, a new link for the target of the symbolic link
is created.
.P
If
\fIlinkat\fR()
is passed the special value AT_FDCWD in the
.IR fd1
or
.IR fd2
parameter, the current working directory shall be used for the respective
.IR path
argument. If both
.IR fd1
and
.IR fd2
have value AT_FDCWD, the behavior shall be identical to a call to
\fIlink\fR(),
except that symbolic links shall be handled as specified by the value of
.IR flag .
.P
If the AT_SYMLINK_FOLLOW flag is clear in the
.IR flag
argument and the
.IR path1
argument names a symbolic link, a new link is created for the symbolic
link
.IR path1
and not its target.
.SH "RETURN VALUE"
Upon successful completion, these functions shall return 0. Otherwise,
these functions shall return \-1 and set
.IR errno
to indicate the error.
.br
.SH ERRORS
These functions shall fail if:
.TP
.BR EACCES
A component of either path prefix denies search permission, or the
requested link requires writing in a directory that denies write
permission, or the calling process does not have permission to access
the existing file and this is required by the implementation.
.TP
.BR EEXIST
The
.IR path2
argument resolves to an existing directory entry or refers to a symbolic
link.
.TP
.BR ELOOP
A loop exists in symbolic links encountered during resolution of the
.IR path1
or
.IR path2
argument.
.TP
.BR EMLINK
The number of links to the file named by
.IR path1
would exceed
{LINK_MAX}.
.TP
.BR ENAMETOOLONG
.br
The length of a component of a pathname is longer than
{NAME_MAX}.
.TP
.BR ENOENT
A component of either path prefix does not exist; the file named by
.IR path1
does not exist; or
.IR path1
or
.IR path2
points to an empty string.
.TP
.BR ENOENT " or " ENOTDIR
.br
The
.IR path1
argument names an existing non-directory file, and the
.IR path2
argument contains at least one non-\c
<slash>
character and ends with one or more trailing
<slash>
characters. If
.IR path2
without the trailing
<slash>
characters would name an existing file, an
.BR [ENOENT] 
error shall not occur.
.TP
.BR ENOSPC
The directory to contain the link cannot be extended.
.TP
.BR ENOTDIR
A component of either path prefix names an existing file that is neither
a directory nor a symbolic link to a directory, or the
.IR path1
argument contains at least one non-\c
<slash>
character and ends with one or more trailing
<slash>
characters and the last pathname component names an existing file
that is neither a directory nor a symbolic link to a directory, or the
.IR path1
argument names an existing non-directory file and the
.IR path2
argument names a nonexistent file, contains at least one non-\c
<slash>
character, and ends with one or more trailing
<slash>
characters.
.TP
.BR EPERM
The file named by
.IR path1
is a directory and either the calling process does not have appropriate
privileges or the implementation prohibits using
\fIlink\fR()
on directories.
.TP
.BR EROFS
The requested link requires writing in a directory on a read-only file
system.
.TP
.BR EXDEV
The link named by
.IR path2
and the file named by
.IR path1
are on different file systems and the implementation does not support
links between file systems.
.TP
.BR EXDEV
.IR path1
refers to a named STREAM.
.P
The
\fIlinkat\fR()
function shall fail if:
.TP
.BR EACCES
The access mode of the open file description associated with
.IR fd1
or
.IR fd2
is not O_SEARCH and the permissions of the directory underlying
.IR fd1
or
.IR fd2 ,
respectively, do not permit directory searches.
.TP
.BR EBADF
The
.IR path1
or
.IR path2
argument does not specify an absolute path and the
.IR fd1
or
.IR fd2
argument, respectively, is neither AT_FDCWD nor a valid file descriptor
open for reading or searching.
.TP
.BR ENOTDIR
The
.IR path1
or
.IR path2
argument is not an absolute path and
.IR fd1
or
.IR fd2 ,
respectively, is a file descriptor associated with a non-directory file.
.P
These functions may fail if:
.TP
.BR ELOOP
More than
{SYMLOOP_MAX}
symbolic links were encountered during resolution of the
.IR path1
or
.IR path2
argument.
.TP
.BR ENAMETOOLONG
.br
The length of a pathname exceeds
{PATH_MAX},
or pathname resolution of a symbolic link produced an intermediate
result with a length that exceeds
{PATH_MAX}.
.br
.P
The
\fIlinkat\fR()
function may fail if:
.TP
.BR EINVAL
The value of the
.IR flag
argument is not valid.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
.SS "Creating a Link to a File"
.P
The following example shows how to create a link to a file named
.BR /home/cnd/mod1
by creating a new directory entry named
.BR /modules/pass1 .
.sp
.RS 4
.nf

#include <unistd.h>
.P
char *path1 = "/home/cnd/mod1";
char *path2 = "/modules/pass1";
int   status;
\&...
status = link (path1, path2);
.fi
.P
.RE
.SS "Creating a Link to a File Within a Program"
.P
In the following program example, the
\fIlink\fR()
function links the
.BR /etc/passwd
file (defined as
.BR PASSWDFILE )
to a file named
.BR /etc/opasswd
(defined as
.BR SAVEFILE ),
which is used to save the current password file. Then, after removing
the current password file (defined as
.BR PASSWDFILE ),
the new password file is saved as the current password file using the
\fIlink\fR()
function again.
.sp
.RS 4
.nf

#include <unistd.h>
.P
#define LOCKFILE "/etc/ptmp"
#define PASSWDFILE "/etc/passwd"
#define SAVEFILE "/etc/opasswd"
\&...
/* Save current password file */
link (PASSWDFILE, SAVEFILE);
.P
/* Remove current password file. */
unlink (PASSWDFILE);
.P
/* Save new password file as current password file. */
link (LOCKFILE,PASSWDFILE);
.fi
.P
.RE
.SH "APPLICATION USAGE"
Some implementations do allow links between file systems.
.P
If
.IR path1
refers to a symbolic link, application developers should use
\fIlinkat\fR()
with appropriate flags to select whether or not the symbolic link should
be resolved.
.SH RATIONALE
Linking to a directory is restricted to the superuser
in most historical implementations because this capability may produce
loops in the file hierarchy or otherwise corrupt the file system. This volume of POSIX.1\(hy2017
continues that philosophy by prohibiting
\fIlink\fR()
and
\fIunlink\fR()
from doing this. Other functions could do it if the implementor designed
such an extension.
.P
Some historical implementations allow linking of files on different file
systems. Wording was added to explicitly allow this optional behavior.
.P
The exception for cross-file system links is intended to apply only to
links that are programmatically indistinguishable from ``hard'' links.
.P
The purpose of the
\fIlinkat\fR()
function is to link files in directories other than the current working
directory without exposure to race conditions. Any part of the path of
a file could be changed in parallel to a call to
\fIlink\fR(),
resulting in unspecified behavior. By opening a file descriptor for the
directory of both the existing file and the target location and using the
\fIlinkat\fR()
function it can be guaranteed that the both filenames are in the desired
directories.
.P
The AT_SYMLINK_FOLLOW flag allows for implementing both common behaviors
of the
\fIlink\fR()
function. The POSIX specification requires that if
.IR path1
is a symbolic link, a new link for the target of the symbolic link is
created. Many systems by default or as an alternative provide a mechanism
to avoid the implicit symbolic link lookup and create a new link for
the symbolic link itself.
.P
Earlier versions of this standard specified only the
\fIlink\fR()
function, and required it to behave like
\fIlinkat\fR()
with the AT_SYMLINK_FOLLOW flag. However, historical practice from SVR4
and Linux kernels had
\fIlink\fR()
behaving like
\fIlinkat\fR()
with no flags, and many systems that attempted to provide a conforming
\fIlink\fR()
function did so in a way that was rarely used, and when it was used
did not conform to the standard (e.g., by not being atomic, or by
dereferencing the symbolic link incorrectly). Since applications could
not rely on
\fIlink\fR()
following links in practice, the
\fIlinkat\fR()
function was added taking a flag to specify the desired behavior
for the application.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIrename\fR\^(\|)",
.IR "\fIsymlink\fR\^(\|)",
.IR "\fIunlink\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<fcntl.h>\fP",
.IR "\fB<unistd.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .