]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
ac56b6a8 | 2 | .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
a469d976 | 3 | .\" and Copyright (C) 2006, 2014 Michael Kerrisk |
fea681da | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
fea681da MK |
26 | .\" |
27 | .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> | |
28 | .\" Modified 1994-08-21 by Michael Haardt | |
c11b1abf | 29 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
7502db97 | 30 | .\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2 |
fea681da | 31 | .\" |
4b8c67d9 | 32 | .TH LINK 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 33 | .SH NAME |
a469d976 | 34 | link, linkat \- make a new name for a file |
fea681da | 35 | .SH SYNOPSIS |
a469d976 | 36 | .nf |
fea681da | 37 | .B #include <unistd.h> |
68e4db0a | 38 | .PP |
fea681da | 39 | .BI "int link(const char *" oldpath ", const char *" newpath ); |
dbfe9c70 | 40 | .PP |
a469d976 MK |
41 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
42 | .B #include <unistd.h> | |
68e4db0a | 43 | .PP |
a469d976 MK |
44 | .BI "int linkat(int " olddirfd ", const char *" oldpath , |
45 | .BI " int " newdirfd ", const char *" newpath ", int " flags ); | |
46 | .fi | |
68e4db0a | 47 | .PP |
a469d976 MK |
48 | .in -4n |
49 | Feature Test Macro Requirements for glibc (see | |
50 | .BR feature_test_macros (7)): | |
51 | .in | |
68e4db0a | 52 | .PP |
a469d976 MK |
53 | .BR linkat (): |
54 | .PD 0 | |
55 | .ad l | |
56 | .RS 4 | |
57 | .TP 4 | |
58 | Since glibc 2.10: | |
b0da7b8b | 59 | _POSIX_C_SOURCE\ >=\ 200809L |
a469d976 MK |
60 | .TP |
61 | Before glibc 2.10: | |
62 | _ATFILE_SOURCE | |
63 | .RE | |
64 | .ad | |
65 | .PD | |
fea681da | 66 | .SH DESCRIPTION |
e511ffb6 | 67 | .BR link () |
fea681da | 68 | creates a new link (also known as a hard link) to an existing file. |
efeece04 | 69 | .PP |
fea681da MK |
70 | If |
71 | .I newpath | |
587ca6cf | 72 | exists, it will |
fea681da MK |
73 | .I not |
74 | be overwritten. | |
efeece04 | 75 | .PP |
fea681da MK |
76 | This new name may be used exactly as the old one for any operation; |
77 | both names refer to the same file (and so have the same permissions | |
78 | and ownership) and it is impossible to tell which name was the | |
2d986c92 | 79 | "original". |
a469d976 MK |
80 | .SS linkat() |
81 | The | |
82 | .BR linkat () | |
83 | system call operates in exactly the same way as | |
cadd38ba | 84 | .BR link (), |
a469d976 | 85 | except for the differences described here. |
efeece04 | 86 | .PP |
a469d976 MK |
87 | If the pathname given in |
88 | .I oldpath | |
89 | is relative, then it is interpreted relative to the directory | |
90 | referred to by the file descriptor | |
91 | .I olddirfd | |
92 | (rather than relative to the current working directory of | |
93 | the calling process, as is done by | |
cadd38ba | 94 | .BR link () |
a469d976 | 95 | for a relative pathname). |
efeece04 | 96 | .PP |
a469d976 MK |
97 | If |
98 | .I oldpath | |
99 | is relative and | |
100 | .I olddirfd | |
101 | is the special value | |
102 | .BR AT_FDCWD , | |
103 | then | |
104 | .I oldpath | |
105 | is interpreted relative to the current working | |
106 | directory of the calling process (like | |
cadd38ba | 107 | .BR link ()). |
efeece04 | 108 | .PP |
a469d976 MK |
109 | If |
110 | .I oldpath | |
111 | is absolute, then | |
112 | .I olddirfd | |
113 | is ignored. | |
efeece04 | 114 | .PP |
a469d976 MK |
115 | The interpretation of |
116 | .I newpath | |
117 | is as for | |
118 | .IR oldpath , | |
119 | except that a relative pathname is interpreted relative | |
120 | to the directory referred to by the file descriptor | |
121 | .IR newdirfd . | |
efeece04 | 122 | .PP |
a469d976 MK |
123 | The following values can be bitwise ORed in |
124 | .IR flags : | |
125 | .TP | |
126 | .BR AT_EMPTY_PATH " (since Linux 2.6.39)" | |
127 | .\" commit 11a7b371b64ef39fc5fb1b6f2218eef7c4d035e3 | |
128 | If | |
129 | .I oldpath | |
130 | is an empty string, create a link to the file referenced by | |
131 | .IR olddirfd | |
132 | (which may have been obtained using the | |
133 | .BR open (2) | |
134 | .B O_PATH | |
135 | flag). | |
136 | In this case, | |
137 | .I olddirfd | |
217d5738 | 138 | can refer to any type of file except a directory. |
4ec5bffa | 139 | This will generally not work if the file has a link count of zero (files |
7dee406b AL |
140 | created with |
141 | .BR O_TMPFILE | |
142 | and without | |
143 | .BR O_EXCL | |
144 | are an exception). | |
6fffae19 | 145 | The caller must have the |
a469d976 | 146 | .BR CAP_DAC_READ_SEARCH |
7dee406b | 147 | capability in order to use this flag. |
a469d976 MK |
148 | This flag is Linux-specific; define |
149 | .B _GNU_SOURCE | |
150 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
151 | to obtain its definition. | |
152 | .TP | |
153 | .BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)" | |
154 | By default, | |
155 | .BR linkat (), | |
156 | does not dereference | |
157 | .I oldpath | |
158 | if it is a symbolic link (like | |
cadd38ba | 159 | .BR link ()). |
a469d976 MK |
160 | The flag |
161 | .B AT_SYMLINK_FOLLOW | |
162 | can be specified in | |
163 | .I flags | |
164 | to cause | |
165 | .I oldpath | |
166 | to be dereferenced if it is a symbolic link. | |
7dee406b | 167 | If procfs is mounted, |
4ec5bffa MK |
168 | this can be used as an alternative to |
169 | .BR AT_EMPTY_PATH , | |
6fffae19 | 170 | like this: |
efeece04 | 171 | .IP |
4ec5bffa | 172 | .in +4n |
b8302363 | 173 | .EX |
4ec5bffa MK |
174 | linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd, |
175 | newname, AT_SYMLINK_FOLLOW); | |
b8302363 | 176 | .EE |
e646a1ba | 177 | .in |
a469d976 MK |
178 | .PP |
179 | Before kernel 2.6.18, the | |
180 | .I flags | |
181 | argument was unused, and had to be specified as 0. | |
182 | .PP | |
183 | See | |
184 | .BR openat (2) | |
185 | for an explanation of the need for | |
186 | .BR linkat (). | |
47297adb | 187 | .SH RETURN VALUE |
c13182ef MK |
188 | On success, zero is returned. |
189 | On error, \-1 is returned, and | |
fea681da MK |
190 | .I errno |
191 | is set appropriately. | |
192 | .SH ERRORS | |
193 | .TP | |
194 | .B EACCES | |
195 | Write access to the directory containing | |
196 | .I newpath | |
197 | is denied, or search permission is denied for one of the directories | |
198 | in the path prefix of | |
199 | .I oldpath | |
200 | or | |
201 | .IR newpath . | |
202 | (See also | |
ad7cc990 | 203 | .BR path_resolution (7).) |
fea681da | 204 | .TP |
a1f01685 | 205 | .B EDQUOT |
9ee4a2b6 | 206 | The user's quota of disk blocks on the filesystem has been exhausted. |
a1f01685 | 207 | .TP |
fea681da MK |
208 | .B EEXIST |
209 | .I newpath | |
210 | already exists. | |
211 | .TP | |
212 | .B EFAULT | |
213 | .IR oldpath " or " newpath " points outside your accessible address space." | |
214 | .TP | |
215 | .B EIO | |
216 | An I/O error occurred. | |
217 | .TP | |
218 | .B ELOOP | |
219 | Too many symbolic links were encountered in resolving | |
220 | .IR oldpath " or " newpath . | |
221 | .TP | |
222 | .B EMLINK | |
223 | The file referred to by | |
224 | .I oldpath | |
225 | already has the maximum number of links to it. | |
fb257aa8 MK |
226 | For example, on an |
227 | .BR ext4 (5) | |
228 | filesystem that does not employ the | |
229 | .I dir_index | |
230 | feature, the limit on the number of hard links to a file is 65,000; on | |
231 | .BR btrfs (5), | |
232 | the limit is 65,535 links. | |
fea681da MK |
233 | .TP |
234 | .B ENAMETOOLONG | |
235 | .IR oldpath " or " newpath " was too long." | |
236 | .TP | |
237 | .B ENOENT | |
238 | A directory component in | |
239 | .IR oldpath " or " newpath | |
240 | does not exist or is a dangling symbolic link. | |
241 | .TP | |
242 | .B ENOMEM | |
243 | Insufficient kernel memory was available. | |
244 | .TP | |
245 | .B ENOSPC | |
246 | The device containing the file has no room for the new directory | |
247 | entry. | |
248 | .TP | |
249 | .B ENOTDIR | |
250 | A component used as a directory in | |
251 | .IR oldpath " or " newpath | |
252 | is not, in fact, a directory. | |
253 | .TP | |
254 | .B EPERM | |
255 | .I oldpath | |
256 | is a directory. | |
257 | .TP | |
258 | .B EPERM | |
9ee4a2b6 | 259 | The filesystem containing |
fea681da MK |
260 | .IR oldpath " and " newpath |
261 | does not support the creation of hard links. | |
262 | .TP | |
dc51f1ff MK |
263 | .BR EPERM " (since Linux 3.6)" |
264 | The caller does not have permission to create a hard link to this file | |
265 | (see the description of | |
c98da6cf | 266 | .IR /proc/sys/fs/protected_hardlinks |
dc51f1ff MK |
267 | in |
268 | .BR proc (5)). | |
269 | .TP | |
5fae754f MK |
270 | .B EPERM |
271 | .I oldpath | |
272 | is marked immutable or append-only. | |
273 | (See | |
274 | .BR ioctl_iflags (2).) | |
275 | .TP | |
fea681da | 276 | .B EROFS |
9ee4a2b6 | 277 | The file is on a read-only filesystem. |
fea681da MK |
278 | .TP |
279 | .B EXDEV | |
280 | .IR oldpath " and " newpath | |
9ee4a2b6 MK |
281 | are not on the same mounted filesystem. |
282 | (Linux permits a filesystem to be mounted at multiple points, but | |
2777b1ca | 283 | .BR link () |
2d5d4b0d | 284 | does not work across different mount points, |
9ee4a2b6 | 285 | even if the same filesystem is mounted on both.) |
a469d976 MK |
286 | .PP |
287 | The following additional errors can occur for | |
288 | .BR linkat (): | |
289 | .TP | |
290 | .B EBADF | |
291 | .I olddirfd | |
292 | or | |
293 | .I newdirfd | |
294 | is not a valid file descriptor. | |
295 | .TP | |
296 | .B EINVAL | |
297 | An invalid flag value was specified in | |
298 | .IR flags . | |
299 | .TP | |
300 | .B ENOENT | |
301 | .B AT_EMPTY_PATH | |
302 | was specified in | |
303 | .IR flags , | |
304 | but the caller did not have the | |
305 | .B CAP_DAC_READ_SEARCH | |
306 | capability. | |
307 | .TP | |
308 | .B ENOENT | |
309 | An attempt was made to link to the | |
310 | .I /proc/self/fd/NN | |
311 | file corresponding to a file descriptor created with | |
efeece04 | 312 | .IP |
a469d976 | 313 | open(path, O_TMPFILE | O_EXCL, mode); |
efeece04 | 314 | .IP |
a469d976 MK |
315 | See |
316 | .BR open (2). | |
317 | .TP | |
d29f746e MK |
318 | .B ENOENT |
319 | .I oldpath | |
320 | is a relative pathname and | |
321 | .I olddirfd | |
322 | refers to a directory that has been deleted, | |
323 | or | |
324 | .I newpath | |
325 | is a relative pathname and | |
326 | .I newdirfd | |
327 | refers to a directory that has been deleted. | |
328 | .TP | |
a469d976 MK |
329 | .B ENOTDIR |
330 | .I oldpath | |
331 | is relative and | |
332 | .I olddirfd | |
333 | is a file descriptor referring to a file other than a directory; | |
334 | or similar for | |
335 | .I newpath | |
336 | and | |
337 | .I newdirfd | |
d81d8506 MK |
338 | .TP |
339 | .B EPERM | |
340 | .BR AT_EMPTY_PATH | |
341 | was specified in | |
342 | .IR flags , | |
343 | .I oldpath | |
344 | is an empty string, and | |
345 | .IR olddirfd | |
346 | refers to a directory. | |
a469d976 MK |
347 | .SH VERSIONS |
348 | .BR linkat () | |
349 | was added to Linux in kernel 2.6.16; | |
350 | library support was added to glibc in version 2.4. | |
47297adb | 351 | .SH CONFORMING TO |
a469d976 | 352 | .BR link (): |
bcd157a8 | 353 | SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008. |
a1d5f77c MK |
354 | .\" SVr4 documents additional ENOLINK and |
355 | .\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP. | |
356 | .\" X/OPEN does not document EFAULT, ENOMEM or EIO. | |
efeece04 | 357 | .PP |
a469d976 MK |
358 | .BR linkat (): |
359 | POSIX.1-2008. | |
fea681da MK |
360 | .SH NOTES |
361 | Hard links, as created by | |
e511ffb6 | 362 | .BR link (), |
9ee4a2b6 | 363 | cannot span filesystems. |
c13182ef | 364 | Use |
0bfa087b | 365 | .BR symlink (2) |
fea681da | 366 | if this is required. |
efeece04 | 367 | .PP |
490df3ae | 368 | POSIX.1-2001 says that |
e511ffb6 | 369 | .BR link () |
c13182ef | 370 | should dereference |
490df3ae MK |
371 | .I oldpath |
372 | if it is a symbolic link. | |
e2067e32 MK |
373 | However, since kernel 2.0, |
374 | .\" more precisely: since kernel 1.3.56 | |
375 | Linux does not do so: if | |
490df3ae MK |
376 | .I oldpath |
377 | is a symbolic link, then | |
378 | .I newpath | |
379 | is created as a (hard) link to the same symbolic link file | |
c13182ef | 380 | (i.e., |
490df3ae MK |
381 | .I newpath |
382 | becomes a symbolic link to the same file that | |
383 | .I oldpath | |
384 | refers to). | |
385 | Some other implementations behave in the same manner as Linux. | |
386 | .\" For example, the default Solaris compilation environment | |
387 | .\" behaves like Linux, and contributors to a March 2005 | |
388 | .\" thread in the Austin mailing list reported that some | |
aa651b39 | 389 | .\" other (System V) implementations did/do the same -- MTK, Apr 05 |
e2067e32 MK |
390 | POSIX.1-2008 changes the specification of |
391 | .BR link (), | |
392 | making it implementation-dependent whether or not | |
393 | .I oldpath | |
394 | is dereferenced if it is a symbolic link. | |
115e8dca | 395 | For precise control over the treatment of symbolic links when |
6ed16784 | 396 | creating a link, use |
dba0e4da | 397 | .BR linkat (). |
c71a9ed7 MK |
398 | .SS Glibc notes |
399 | On older kernels where | |
400 | .BR linkat () | |
401 | is unavailable, the glibc wrapper function falls back to the use of | |
402 | .BR link (), | |
403 | unless the | |
404 | .B AT_SYMLINK_FOLLOW | |
405 | is specified. | |
406 | When | |
407 | .I oldpath | |
408 | and | |
409 | .I newpath | |
410 | are relative pathnames, | |
411 | glibc constructs pathnames based on the symbolic links in | |
412 | .IR /proc/self/fd | |
413 | that correspond to the | |
414 | .I olddirfd | |
415 | and | |
416 | .IR newdirfd | |
417 | arguments. | |
fea681da | 418 | .SH BUGS |
9ee4a2b6 | 419 | On NFS filesystems, the return code may be wrong in case the NFS server |
c13182ef MK |
420 | performs the link creation and dies before it can say so. |
421 | Use | |
fea681da MK |
422 | .BR stat (2) |
423 | to find out if the link got created. | |
47297adb | 424 | .SH SEE ALSO |
fea681da MK |
425 | .BR ln (1), |
426 | .BR open (2), | |
fea681da MK |
427 | .BR rename (2), |
428 | .BR stat (2), | |
429 | .BR symlink (2), | |
0c2b92ba | 430 | .BR unlink (2), |
a9cfde1d | 431 | .BR path_resolution (7), |
ad22ad55 | 432 | .BR symlink (7) |