NAME
link —
make a hard file link
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <unistd.h>
int
link(
const char
*name1,
const char
*name2);
#include <fcntl.h>
int
linkat(
int
fd1,
const char
*name1,
int fd2,
const char *name2,
int flags);
DESCRIPTION
The
link() function call atomically creates the specified
directory entry (hard link)
name2 with the attributes of
the underlying object pointed at by
name1. If the link
is successful: the link count of the underlying object is incremented;
name1 and
name2 share equal access
and rights to the underlying object.
If
name1 is removed, the file
name2
is not deleted and the link count of the underlying object is decremented.
name1 must exist for the hard link to succeed and both
name1 and
name2 must be in the
same file system.
name1 may not be a directory unless
the caller is the super-user and the file system containing it supports
linking to directories.
linkat() works the same way as
link() except
if
name1 (resp.
name2) is
relative. In that case, it is looked up from a directory whose file descriptor
was passed as
fd1 (resp.
fd2).
Search permission is required on the directories named by
fd1 and
fd2.
fd1 or
fd2 can be set to
AT_FDCWD
in order to specify the current directory.
When operating on a symlink,
link() resolves the symlink and
creates a hard link on the target.
linkat() will do the same
if
AT_SYMLINK_FOLLOW
is set in
flags, but it will link on the symlink itself if the
flag is clear.
RETURN VALUES
The
link() and
linkat() functions return the
value 0 if successful; otherwise the value -1 is returned and the
global variable
errno is set to indicate the error.
ERRORS
link() and
linkat() will fail and no link
will be created if:
-
-
- [
EACCES
]
- A component of either path prefix denies search permission,
or the requested link requires writing in a directory with a mode that
denies write permission.
-
-
- [
EDQUOT
]
- The directory in which the entry for the new link is being
placed cannot be extended because the user's quota of disk blocks on the
file system containing the directory has been exhausted.
-
-
- [
EEXIST
]
- The link named by name2 does
exist.
-
-
- [
EFAULT
]
- One of the pathnames specified is outside the process's
allocated address space.
-
-
- [
EIO
]
- An I/O error occurred while reading from or writing to the
file system to make the directory entry.
-
-
- [
ELOOP
]
- Too many symbolic links were encountered in translating one
of the pathnames.
-
-
- [
EMLINK
]
- The link count of the file named by
name1 would exceed
{
LINK_MAX
}.
-
-
- [
ENAMETOOLONG
]
- A component of a pathname exceeded
{
NAME_MAX
} characters, or an entire path name
exceeded {PATH_MAX
} characters.
-
-
- [
ENOENT
]
- A component of either path prefix does not exist, or the
file named by name1 does not exist.
-
-
- [
ENOSPC
]
- The directory in which the entry for the new link is being
placed cannot be extended because there is no space left on the file
system containing the directory.
-
-
- [
ENOTDIR
]
- A component of either path prefix is not a directory.
-
-
- [
EOPNOTSUPP
]
- The file system containing the file named by
name1 does not support links.
-
-
- [
EPERM
]
- The file named by name1 is a
directory and the effective user ID is not super-user, or the file system
containing the file does not permit the use of link() on
a directory.
-
-
- [
EROFS
]
- The requested link requires writing in a directory on a
read-only file system.
-
-
- [
EXDEV
]
- The link named by name2 and the file
named by name1 are on different file systems.
In addition,
linkat() will fail if:
-
-
- [
EBADF
]
- name1 or name2
does not specify an absolute path and fd1 or
fd2, respectively, is neither
AT_FDCWD
nor a valid file descriptor open for
reading or searching.
-
-
- [
ENOTDIR
]
- name1 or name2
is not an absolute path and fd1 or
fd2, respectively, is a file descriptor associated
with a non-directory file.
SEE ALSO
symlink(2),
unlink(2)
STANDARDS
The
link() function conforms to
IEEE Std
1003.1-1990 (“POSIX.1”).
linkat()
conforms to
IEEE Std 1003.1-2008
(“POSIX.1”).