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 mount points, even if
145 the same filesystem is mounted on both.)
146 The following additional errors can occur for linkat():
148 EBADF olddirfd or newdirfd is not a valid file descriptor.
150 EINVAL An invalid flag value was specified in flags.
152 ENOENT AT_EMPTY_PATH was specified in flags, but the caller did not
154 have the CAP_DAC_READ_SEARCH capability.
155 ENOENT An attempt was made to link to the /proc/self/fd/NN file corre‐
157 sponding to a file descriptor created with
158 open(path, O_TMPFILE | O_EXCL, mode);
160 See open(2).
162 ENOENT An attempt was made to link to a /proc/self/fd/NN file corre‐
164 sponding to a file that has been deleted.
165 ENOENT oldpath is a relative pathname and olddirfd refers to a direc‐
167 tory that has been deleted, or newpath is a relative pathname
168 and newdirfd refers to a directory that has been deleted.
169 ENOTDIR
171 oldpath is relative and olddirfd is a file descriptor referring
172 to a file other than a directory; or similar for newpath and
173 newdirfd
174 EPERM AT_EMPTY_PATH was specified in flags, oldpath is an empty
176 string, and olddirfd refers to a directory.
177
179 linkat() was added to Linux in kernel 2.6.16; library support was added
180 to glibc in version 2.4.
181
183 link(): SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008.
184 linkat(): POSIX.1-2008.
186
188 Hard links, as created by link(), cannot span filesystems. Use sym‐
189 link(2) if this is required.
190 POSIX.1-2001 says that link() should dereference oldpath if it is a
192 symbolic link. However, since kernel 2.0, Linux does not do so: if
193 oldpath is a symbolic link, then newpath is created as a (hard) link to
194 the same symbolic link file (i.e., newpath becomes a symbolic link to
195 the same file that oldpath refers to). Some other implementations be‐
196 have in the same manner as Linux. POSIX.1-2008 changes the specifica‐
197 tion of link(), making it implementation-dependent whether or not old‐
198 path is dereferenced if it is a symbolic link. For precise control
199 over the treatment of symbolic links when creating a link, use
200 linkat().
201 Glibc notes
203 On older kernels where linkat() is unavailable, the glibc wrapper func‐
204 tion falls back to the use of link(), unless the AT_SYMLINK_FOLLOW is
205 specified. When oldpath and newpath are relative pathnames, glibc con‐
206 structs pathnames based on the symbolic links in /proc/self/fd that
207 correspond to the olddirfd and newdirfd arguments.
208
210 On NFS filesystems, the return code may be wrong in case the NFS server
211 performs the link creation and dies before it can say so. Use stat(2)
212 to find out if the link got created.
213
215 ln(1), open(2), rename(2), stat(2), symlink(2), unlink(2), path_resolu‐
216 tion(7), symlink(7)
217
219 This page is part of release 5.12 of the Linux man-pages project. A
220 description of the project, information about reporting bugs, and the
221 latest version of this page, can be found at
222 https://www.kernel.org/doc/man-pages/.
223Linux 2021-03-22 LINK(2)