Debian Codegraph @

upstream/debian-unstable/man2/link.2

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