int link(const char *oldpath, const char *newpath);
#include <fcntl.h> /* Definition of AT_* constants */ #include <unistd.h>
int linkat(int olddirfd, const char *oldpath, int newdirfd, const char *newpath, int flags);
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
- Since glibc 2.10:
- _POSIX_C_SOURCE >= 200809L
- Before glibc 2.10:
- AT_EMPTY_PATH (since Linux 2.6.39)
- If oldpath is an empty string, create a link to the file referenced by olddirfd (which may have been obtained using the open(2) O_PATH flag). In this case, olddirfd can refer to any type of file except a directory. This will generally not work if the file has a link count of zero (files created with O_TMPFILE and without O_EXCL are an exception). The caller must have the CAP_DAC_READ_SEARCH capability in order to use this flag. This flag is Linux-specific; define _GNU_SOURCE to obtain its definition.
- AT_SYMLINK_FOLLOW (since Linux 2.6.18)
- By default, linkat(), does not dereference oldpath if it is a symbolic link (like link()). The flag AT_SYMLINK_FOLLOW can be specified in flags to cause oldpath to be dereferenced if it is a symbolic link. If procfs is mounted, this can be used as an alternative to AT_EMPTY_PATH, like this:
linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd, newname, AT_SYMLINK_FOLLOW);
- Write access to the directory containing newpath is denied, or search permission is denied for one of the directories in the path prefix of oldpath or newpath. (See also path_resolution(7).)
- The user's quota of disk blocks on the filesystem has been exhausted.
- newpath already exists.
- oldpath or newpath points outside your accessible address space.
- An I/O error occurred.
- Too many symbolic links were encountered in resolving oldpath or newpath.
- The file referred to by oldpath already has the maximum number of links to it. For example, on an ext4(5) filesystem that does not employ the dir_index feature, the limit on the number of hard links to a file is 65,000; on btrfs(5), the limit is 65,535 links.
- oldpath or newpath was too long.
- A directory component in oldpath or newpath does not exist or is a dangling symbolic link.
- Insufficient kernel memory was available.
- The device containing the file has no room for the new directory entry.
- A component used as a directory in oldpath or newpath is not, in fact, a directory.
- oldpath is a directory.
- The filesystem containing oldpath and newpath does not support the creation of hard links.
- EPERM (since Linux 3.6)
- The caller does not have permission to create a hard link to this file (see the description of /proc/sys/fs/protected_hardlinks in proc(5)).
- oldpath is marked immutable or append-only. (See ioctl_iflags(2).)
- The file is on a read-only filesystem.
- oldpath and newpath are not on the same mounted filesystem. (Linux permits a filesystem to be mounted at multiple points, but link() does not work across different mount points, even if the same filesystem is mounted on both.)
- olddirfd or newdirfd is not a valid file descriptor.
- An invalid flag value was specified in flags.
- AT_EMPTY_PATH was specified in flags, but the caller did not have the CAP_DAC_READ_SEARCH capability.
- An attempt was made to link to the /proc/self/fd/NN file corresponding to a file descriptor created with
open(path, O_TMPFILE | O_EXCL, mode);
- See open(2).
- oldpath is a relative pathname and olddirfd refers to a directory that has been deleted, or newpath is a relative pathname and newdirfd refers to a directory that has been deleted.
- oldpath is relative and olddirfd is a file descriptor referring to a file other than a directory; or similar for newpath and newdirfd
- AT_EMPTY_PATH was specified in flags, oldpath is an empty string, and olddirfd refers to a directory.