1LINK(2) Linux Programmer's Manual LINK(2)
2
6 link, linkat - make a new name for a file
7
9 #include <unistd.h>
10 int link(const char *oldpath, const char *newpath);
12 #include <fcntl.h> /* Definition of AT_* constants */
14 #include <unistd.h>
15 int linkat(int olddirfd, const char *oldpath,
17 int newdirfd, const char *newpath, int flags);
18 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20 linkat():
22 Since glibc 2.10:
23 _POSIX_C_SOURCE >= 200809L
24 Before glibc 2.10:
25 _ATFILE_SOURCE
26
28 link() creates a new link (also known as a hard link) to an existing
29 file.
30 If newpath exists, it will not be overwritten.
32 This new name may be used exactly as the old one for any operation;
34 both names refer to the same file (and so have the same permissions and
35 ownership) and it is impossible to tell which name was the "original".
36 linkat()
38 The linkat() system call operates in exactly the same way as link(),
39 except for the differences described here.
40 If the pathname given in oldpath is relative, then it is interpreted
42 relative to the directory referred to by the file descriptor olddirfd
43 (rather than relative to the current working directory of the calling
44 process, as is done by link() for a relative pathname).
45 If oldpath is relative and olddirfd is the special value AT_FDCWD, then
47 oldpath is interpreted relative to the current working directory of the
48 calling process (like link()).
49 If oldpath is absolute, then olddirfd is ignored.
51 The interpretation of newpath is as for oldpath, except that a relative
53 pathname is interpreted relative to the directory referred to by the
54 file descriptor newdirfd.
55 The following values can be bitwise ORed in flags:
57 AT_EMPTY_PATH (since Linux 2.6.39)
59 If oldpath is an empty string, create a link to the file refer‐
60 enced by olddirfd (which may have been obtained using the
61 open(2) O_PATH flag). In this case, olddirfd can refer to any
62 type of file except a directory. This will generally not work
63 if the file has a link count of zero (files created with O_TMP‐
64 FILE and without O_EXCL are an exception). The caller must have
65 the CAP_DAC_READ_SEARCH capability in order to use this flag.
66 This flag is Linux-specific; define _GNU_SOURCE to obtain its
67 definition.
68 AT_SYMLINK_FOLLOW (since Linux 2.6.18)
70 By default, linkat(), does not dereference oldpath if it is a
71 symbolic link (like link()). The flag AT_SYMLINK_FOLLOW can be
72 specified in flags to cause oldpath to be dereferenced if it is
73 a symbolic link. If procfs is mounted, this can be used as an
74 alternative to AT_EMPTY_PATH, like this:
75 linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
77 newname, AT_SYMLINK_FOLLOW);
78 Before kernel 2.6.18, the flags argument was unused, and had to be
80 specified as 0.
81 See openat(2) for an explanation of the need for linkat().
83
85 On success, zero is returned. On error, -1 is returned, and errno is
86 set to indicate the error.
87
89 EACCES Write access to the directory containing newpath is denied, or
90 search permission is denied for one of the directories in the
91 path prefix of oldpath or newpath. (See also path_resolu‐
92 tion(7).)
93 EDQUOT The user's quota of disk blocks on the filesystem has been ex‐
95 hausted.
96 EEXIST newpath already exists.
98 EFAULT oldpath or newpath points outside your accessible address space.
100 EIO An I/O error occurred.
102 ELOOP Too many symbolic links were encountered in resolving oldpath or
104 newpath.
105 EMLINK The file referred to by oldpath already has the maximum number
107 of links to it. For example, on an ext4(5) filesystem that does
108 not employ the dir_index feature, the limit on the number of
109 hard links to a file is 65,000; on btrfs(5), the limit is 65,535
110 links.
111 ENAMETOOLONG
113 oldpath or newpath was too long.
114 ENOENT A directory component in oldpath or newpath does not exist or is
116 a dangling symbolic link.
117 ENOMEM Insufficient kernel memory was available.
119 ENOSPC The device containing the file has no room for the new directory
121 entry.
122 ENOTDIR
124 A component used as a directory in oldpath or newpath is not, in
125 fact, a directory.
126 EPERM oldpath is a directory.
128 EPERM The filesystem containing oldpath and newpath does not support
130 the creation of hard links.
131 EPERM (since Linux 3.6)
133 The caller does not have permission to create a hard link to
134 this file (see the description of /proc/sys/fs/pro‐
135 tected_hardlinks in proc(5)).
136 EPERM oldpath is marked immutable or append-only. (See
138 ioctl_iflags(2).)
139 EROFS The file is on a read-only filesystem.
141 EXDEV oldpath and newpath are not on the same mounted filesystem.
143 (Linux permits a filesystem to be mounted at multiple points,
144 but link() does not work across different mounts, even if the
145 same filesystem is mounted on both.)
146 The following additional errors can occur for linkat():
148 EBADF oldpath (newpath) is relative but olddirfd (newdirfd) is neither
150 AT_FDCWD nor a valid file descriptor.
151 EINVAL An invalid flag value was specified in flags.
153 ENOENT AT_EMPTY_PATH was specified in flags, but the caller did not
155 have the CAP_DAC_READ_SEARCH capability.
156 ENOENT An attempt was made to link to the /proc/self/fd/NN file corre‐
158 sponding to a file descriptor created with
159 open(path, O_TMPFILE | O_EXCL, mode);
161 See open(2).
163 ENOENT An attempt was made to link to a /proc/self/fd/NN file corre‐
165 sponding to a file that has been deleted.
166 ENOENT oldpath is a relative pathname and olddirfd refers to a direc‐
168 tory that has been deleted, or newpath is a relative pathname
169 and newdirfd refers to a directory that has been deleted.
170 ENOTDIR
172 oldpath is relative and olddirfd is a file descriptor referring
173 to a file other than a directory; or similar for newpath and
174 newdirfd
175 EPERM AT_EMPTY_PATH was specified in flags, oldpath is an empty
177 string, and olddirfd refers to a directory.
178
180 linkat() was added to Linux in kernel 2.6.16; library support was added
181 to glibc in version 2.4.
182
184 link(): SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008.
185 linkat(): POSIX.1-2008.
187
189 Hard links, as created by link(), cannot span filesystems. Use sym‐
190 link(2) if this is required.
191 POSIX.1-2001 says that link() should dereference oldpath if it is a
193 symbolic link. However, since kernel 2.0, Linux does not do so: if
194 oldpath is a symbolic link, then newpath is created as a (hard) link to
195 the same symbolic link file (i.e., newpath becomes a symbolic link to
196 the same file that oldpath refers to). Some other implementations be‐
197 have in the same manner as Linux. POSIX.1-2008 changes the specifica‐
198 tion of link(), making it implementation-dependent whether or not old‐
199 path is dereferenced if it is a symbolic link. For precise control
200 over the treatment of symbolic links when creating a link, use
201 linkat().
202 Glibc notes
204 On older kernels where linkat() is unavailable, the glibc wrapper func‐
205 tion falls back to the use of link(), unless the AT_SYMLINK_FOLLOW is
206 specified. When oldpath and newpath are relative pathnames, glibc con‐
207 structs pathnames based on the symbolic links in /proc/self/fd that
208 correspond to the olddirfd and newdirfd arguments.
209
211 On NFS filesystems, the return code may be wrong in case the NFS server
212 performs the link creation and dies before it can say so. Use stat(2)
213 to find out if the link got created.
214
216 ln(1), open(2), rename(2), stat(2), symlink(2), unlink(2), path_resolu‐
217 tion(7), symlink(7)
218
220 This page is part of release 5.13 of the Linux man-pages project. A
221 description of the project, information about reporting bugs, and the
222 latest version of this page, can be found at
223 https://www.kernel.org/doc/man-pages/.
224Linux 2021-08-27 LINK(2)