Debian Codegraph @

upstream/debian-unstable/man7/symlink.7

raw
1 .\" Copyright 1992-1994, The Regents of the University of California.
2 .\" Copyright 2008-2014, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: BSD-3-Clause
6 .\"
7 .TH symlink 7 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 symlink \- symbolic link handling
10 .SH DESCRIPTION
11 Symbolic links are files that act as pointers to other files.
12 To understand their behavior, you must first understand how hard links
13 work.
14 .P
15 A hard link to a file is indistinguishable from the original file because
16 it is a reference to the object underlying the original filename.
17 (To be precise: each of the hard links to a file is a reference to
18 the same
19 .IR "inode number" ,
20 where an inode number is an index into the inode table,
21 which contains metadata about all files on a filesystem.
22 See
23 .BR stat (2).)
24 Changes to a file are independent of the name used to reference the file.
25 Hard links may not refer to directories
26 (to prevent the possibility of loops within the filesystem tree,
27 which would confuse many programs)
28 and may not refer to files on different filesystems
29 (because inode numbers are not unique across filesystems).
30 .P
31 A symbolic link is a special type of file whose contents are a string
32 that is the pathname of another file, the file to which the link refers.
33 (The contents of a symbolic link can be read using
34 .BR readlink (2).)
35 In other words, a symbolic link is a pointer to another name,
36 and not to an underlying object.
37 For this reason, symbolic links may refer to directories and may cross
38 filesystem boundaries.
39 .P
40 There is no requirement that the pathname referred to by a symbolic link
41 should exist.
42 A symbolic link that refers to a pathname that does not exist is said
43 to be a
44 .IR "dangling link" .
45 .P
46 Because a symbolic link and its referenced object coexist in the filesystem
47 name space, confusion can arise in distinguishing between the link itself
48 and the referenced object.
49 On historical systems,
50 commands and system calls adopted their own link-following
51 conventions in a somewhat ad-hoc fashion.
52 Rules for a more uniform approach,
53 as they are implemented on Linux and other systems,
54 are outlined here.
55 It is important that site-local applications also conform to these rules,
56 so that the user interface can be as consistent as possible.
57 .\"
58 .SS Magic links
59 There is a special class of symbolic-link-like objects
60 known as "magic links", which
61 can be found in certain pseudofilesystems such as
62 .BR proc (5)
63 (examples include
64 .IR /proc/ pid /exe
65 and
66 .IR /proc/ pid /fd/ *).
67 Unlike normal symbolic links, magic links are not resolved through
68 pathname-expansion, but instead act as direct references to the kernel's own
69 representation of a file handle.
70 As such, these magic links allow users to
71 access files which cannot be referenced with normal paths (such as unlinked
72 files still referenced by a running program ).
73 .P
74 Because they can bypass ordinary
75 .BR mount_namespaces (7)-based
76 restrictions,
77 magic links have been used as attack vectors in various exploits.
78 .\"
79 .SS Symbolic link ownership, permissions, and timestamps
80 The owner and group of an existing symbolic link can be changed
81 using
82 .BR lchown (2).
83 The ownership of a symbolic link matters
84 when the link is being removed or renamed in a directory that
85 has the sticky bit set (see
86 .BR inode (7)),
87 and when the
88 .I fs.protected_symlinks
89 sysctl is set (see
90 .BR proc (5)).
91 .P
92 The last access and last modification timestamps
93 of a symbolic link can be changed using
94 .BR utimensat (2)
95 or
96 .BR lutimes (3).
97 .P
98 .\" Linux does not currently implement an lchmod(2).
99 On Linux, the permissions of an ordinary symbolic link are not used in any
100 operations; the permissions are always 0777 (read, write, and execute for all
101 user categories), and can't be changed.
102 .P
103 However, magic links do not follow this rule.
104 They can have a non-0777 mode,
105 though this mode is not currently used in any permission checks.
106 .\" .P
107 .\" The
108 .\" 4.4BSD
109 .\" system differs from historical
110 .\" 4BSD
111 .\" systems in that the system call
112 .\" .BR chown (2)
113 .\" has been changed to follow symbolic links.
114 .\" The
115 .\" .BR lchown (2)
116 .\" system call was added later when the limitations of the new
117 .\" .BR chown (2)
118 .\" became apparent.
119 .SS Obtaining a file descriptor that refers to a symbolic link
120 Using the combination of the
121 .B O_PATH
122 and
123 .B O_NOFOLLOW
124 flags to
125 .BR open (2)
126 yields a file descriptor that can be passed as the
127 .I dirfd
128 argument in system calls such as
129 .BR fstatat (2),
130 .BR fchownat (2),
131 .BR fchmodat (2),
132 .BR linkat (2),
133 and
134 .BR readlinkat (2),
135 in order to operate on the symbolic link itself
136 (rather than the file to which it refers).
137 .P
138 By default
139 (i.e., if the
140 .B AT_SYMLINK_FOLLOW
141 flag is not specified), if
142 .BR name_to_handle_at (2)
143 is applied to a symbolic link, it yields a handle for the symbolic link
144 (rather than the file to which it refers).
145 One can then obtain a file descriptor for the symbolic link
146 (rather than the file to which it refers)
147 by specifying the
148 .B O_PATH
149 flag in a subsequent call to
150 .BR open_by_handle_at (2).
151 Again, that file descriptor can be used in the
152 aforementioned system calls to operate on the symbolic link itself.
153 .SS Handling of symbolic links by system calls and commands
154 Symbolic links are handled either by operating on the link itself,
155 or by operating on the object referred to by the link.
156 In the latter case,
157 an application or system call is said to
158 .I follow
159 the link.
160 Symbolic links may refer to other symbolic links,
161 in which case the links are dereferenced until an object that is
162 not a symbolic link is found,
163 a symbolic link that refers to a file which does not exist is found,
164 or a loop is detected.
165 (Loop detection is done by placing an upper limit on the number of
166 links that may be followed, and an error results if this limit is
167 exceeded.)
168 .P
169 There are three separate areas that need to be discussed.
170 They are as follows:
171 .IP \[bu] 3
172 Symbolic links used as filename arguments for system calls.
173 .IP \[bu]
174 Symbolic links specified as command-line arguments to utilities that
175 are not traversing a file tree.
176 .IP \[bu]
177 Symbolic links encountered by utilities that are traversing a file tree
178 (either specified on the command line or encountered as part of the
179 file hierarchy walk).
180 .P
181 Before describing the treatment of symbolic links by system calls and commands,
182 we require some terminology.
183 Given a pathname of the form
184 .IR a/b/c ,
185 the part preceding the final slash (i.e.,
186 .IR a/b )
187 is called the
188 .I dirname
189 component, and the part following the final slash (i.e.,
190 .IR c )
191 is called the
192 .I basename
193 component.
194 .\"
195 .SS Treatment of symbolic links in system calls
196 The first area is symbolic links used as filename arguments for
197 system calls.
198 .P
199 The treatment of symbolic links within a pathname passed to
200 a system call is as follows:
201 .IP (1) 5
202 Within the dirname component of a pathname,
203 symbolic links are always followed in nearly every system call.
204 (This is also true for commands.)
205 The one exception is
206 .BR openat2 (2),
207 which provides flags that can be used to explicitly
208 prevent following of symbolic links in the dirname component.
209 .IP (2)
210 Except as noted below,
211 all system calls follow symbolic links
212 in the basename component of a pathname.
213 For example, if there were a symbolic link
214 .I slink
215 which pointed to a file named
216 .IR afile ,
217 the system call
218 .I "open(""slink"" ...\&)"
219 would return a file descriptor referring to the file
220 .IR afile .
221 .P
222 Various system calls do not follow links in
223 the basename component of a pathname,
224 and operate on the symbolic link itself.
225 They are:
226 .BR lchown (2),
227 .BR lgetxattr (2),
228 .BR llistxattr (2),
229 .BR lremovexattr (2),
230 .BR lsetxattr (2),
231 .BR lstat (2),
232 .BR readlink (2),
233 .BR rename (2),
234 .BR rmdir (2),
235 and
236 .BR unlink (2).
237 .P
238 Certain other system calls optionally follow symbolic links
239 in the basename component of a pathname.
240 They are:
241 .BR faccessat (2),
242 .\" Maybe one day: .BR fchownat (2)
243 .BR fchownat (2),
244 .BR fstatat (2),
245 .BR linkat (2),
246 .BR name_to_handle_at (2),
247 .BR open (2),
248 .BR openat (2),
249 .BR open_by_handle_at (2),
250 and
251 .BR utimensat (2);
252 see their manual pages for details.
253 Because
254 .BR remove (3)
255 is an alias for
256 .BR unlink (2),
257 that library function also does not follow symbolic links.
258 When
259 .BR rmdir (2)
260 is applied to a symbolic link, it fails with the error
261 .BR ENOTDIR .
262 .P
263 .BR link (2)
264 warrants special discussion.
265 POSIX.1-2001 specifies that
266 .BR link (2)
267 should dereference
268 .I oldpath
269 if it is a symbolic link.
270 However, Linux does not do this.
271 (By default, Solaris is the same,
272 but the POSIX.1-2001 specified behavior can be obtained with
273 suitable compiler options.)
274 POSIX.1-2008 changed the specification to allow
275 either behavior in an implementation.
276 .SS Commands not traversing a file tree
277 The second area is symbolic links, specified as command-line
278 filename arguments, to commands which are not traversing a file tree.
279 .P
280 Except as noted below, commands follow symbolic links named as
281 command-line arguments.
282 For example, if there were a symbolic link
283 .I slink
284 which pointed to a file named
285 .IR afile ,
286 the command
287 .I "cat slink"
288 would display the contents of the file
289 .IR afile .
290 .P
291 It is important to realize that this rule
292 includes commands which may optionally traverse file trees;
293 for example,
294 the command
295 .I "chown file"
296 is included in this rule, while the command
297 .IR "chown\ \-R file" ,
298 which performs a tree traversal, is not.
299 (The latter is described in the third area, below.)
300 .P
301 If it is explicitly intended
302 that the command operate on the symbolic link
303 instead of following the symbolic link
304 \[em]for example,
305 it is desired that
306 .I "chown slink"
307 change the ownership of the file that
308 .I slink
309 is,
310 whether it is a symbolic link or not\[em]
311 then the
312 .I \-h
313 option should be used.
314 In the above example,
315 .I "chown root slink"
316 would change the ownership of the file referred to by
317 .IR slink ,
318 while
319 .I "chown\ \-h root slink"
320 would change the ownership of
321 .I slink
322 itself.
323 .P
324 There are some exceptions to this rule:
325 .IP \[bu] 3
326 The
327 .BR mv (1)
328 and
329 .BR rm (1)
330 commands do not follow symbolic links named as arguments,
331 but respectively attempt to rename and delete them.
332 (Note, if the symbolic link references a file via a relative path,
333 moving it to another directory may very well cause it to stop working,
334 since the path may no longer be correct.)
335 .IP \[bu]
336 The
337 .BR ls (1)
338 command is also an exception to this rule.
339 For compatibility with historic systems (when
340 .BR ls (1)
341 is not doing a tree walk\[em]that is,
342 .I \-R
343 option is not specified),
344 the
345 .BR ls (1)
346 command follows symbolic links named as arguments if the
347 .I \-H
348 or
349 .I \-L
350 option is specified,
351 or if the
352 .IR \-F ,
353 .IR \-d ,
354 or
355 .I \-l
356 options are not specified.
357 (The
358 .BR ls (1)
359 command is the only command where the
360 .I \-H
361 and
362 .I \-L
363 options affect its behavior even though it is not doing a walk of
364 a file tree.)
365 .IP \[bu]
366 The
367 .BR file (1)
368 command is also an exception to this rule.
369 The
370 .BR file (1)
371 command does not follow symbolic links named as argument by default.
372 The
373 .BR file (1)
374 command does follow symbolic links named as argument if the
375 .I \-L
376 option is specified.
377 .\"
378 .\"The 4.4BSD system differs from historical 4BSD systems in that the
379 .\".BR chown (1)
380 .\"and
381 .\".BR chgrp (1)
382 .\"commands follow symbolic links specified on the command line.
383 .SS Commands traversing a file tree
384 The following commands either optionally or always traverse file trees:
385 .BR chgrp (1),
386 .BR chmod (1),
387 .BR chown (1),
388 .BR cp (1),
389 .BR du (1),
390 .BR find (1),
391 .BR ls (1),
392 .BR pax (1),
393 .BR rm (1),
394 and
395 .BR tar (1).
396 .P
397 It is important to realize that the following rules apply equally to
398 symbolic links encountered during the file tree traversal and symbolic
399 links listed as command-line arguments.
400 .P
401 The
402 .I first rule
403 applies to symbolic links that reference files other than directories.
404 Operations that apply to symbolic links are performed on the links
405 themselves, but otherwise the links are ignored.
406 .P
407 The command
408 .I "rm\ \-r slink directory"
409 will remove
410 .IR slink ,
411 as well as any symbolic links encountered in the tree traversal of
412 .IR directory ,
413 because symbolic links may be removed.
414 In no case will
415 .BR rm (1)
416 affect the file referred to by
417 .IR slink .
418 .P
419 The
420 .I second rule
421 applies to symbolic links that refer to directories.
422 Symbolic links that refer to directories are never followed by default.
423 This is often referred to as a "physical" walk, as opposed to a "logical"
424 walk (where symbolic links that refer to directories are followed).
425 .P
426 Certain conventions are (should be) followed as consistently as
427 possible by commands that perform file tree walks:
428 .IP \[bu] 3
429 A command can be made to follow
430 any symbolic links named on the command line,
431 regardless of the type of file they reference, by specifying the
432 .I \-H
433 (for "half-logical") flag.
434 This flag is intended to make the command-line name space look
435 like the logical name space.
436 (Note, for commands that do not always do file tree traversals, the
437 .I \-H
438 flag will be ignored if the
439 .I \-R
440 flag is not also specified.)
441 .IP
442 For example, the command
443 .I "chown\ \-HR user slink"
444 will traverse the file hierarchy rooted in the file pointed to by
445 .IR slink .
446 Note, the
447 .I \-H
448 is not the same as the previously discussed
449 .I \-h
450 flag.
451 The
452 .I \-H
453 flag causes symbolic links specified on the command line to be
454 dereferenced for the purposes of both the action to be performed
455 and the tree walk, and it is as if the user had specified the
456 name of the file to which the symbolic link pointed.
457 .IP \[bu]
458 A command can be made to
459 follow any symbolic links named on the command line,
460 as well as any symbolic links encountered during the traversal,
461 regardless of the type of file they reference, by specifying the
462 .I \-L
463 (for "logical") flag.
464 This flag is intended to make the entire name space look like
465 the logical name space.
466 (Note, for commands that do not always do file tree traversals, the
467 .I \-L
468 flag will be ignored if the
469 .I \-R
470 flag is not also specified.)
471 .IP
472 For example, the command
473 .I "chown\ \-LR user slink"
474 will change the owner of the file referred to by
475 .IR slink .
476 If
477 .I slink
478 refers to a directory,
479 .B chown
480 will traverse the file hierarchy rooted in the directory that it
481 references.
482 In addition, if any symbolic links are encountered in any file tree that
483 .B chown
484 traverses, they will be treated in the same fashion as
485 .IR slink .
486 .IP \[bu]
487 A command can be made to
488 provide the default behavior by specifying the
489 .I \-P
490 (for "physical") flag.
491 This flag is intended to make the entire name space look like the
492 physical name space.
493 .P
494 For commands that do not by default do file tree traversals, the
495 .IR \-H ,
496 .IR \-L ,
497 and
498 .I \-P
499 flags are ignored if the
500 .I \-R
501 flag is not also specified.
502 In addition, you may specify the
503 .IR \-H ,
504 .IR \-L ,
505 and
506 .I \-P
507 options more than once;
508 the last one specified determines the command's behavior.
509 This is intended to permit you to alias commands to behave one way
510 or the other, and then override that behavior on the command line.
511 .P
512 The
513 .BR ls (1)
514 and
515 .BR rm (1)
516 commands have exceptions to these rules:
517 .IP \[bu] 3
518 The
519 .BR rm (1)
520 command operates on the symbolic link, and not the file it references,
521 and therefore never follows a symbolic link.
522 The
523 .BR rm (1)
524 command does not support the
525 .IR \-H ,
526 .IR \-L ,
527 or
528 .I \-P
529 options.
530 .IP \[bu]
531 To maintain compatibility with historic systems,
532 the
533 .BR ls (1)
534 command acts a little differently.
535 If you do not specify the
536 .IR \-F ,
537 .IR \-d ,
538 or
539 .I \-l
540 options,
541 .BR ls (1)
542 will follow symbolic links specified on the command line.
543 If the
544 .I \-L
545 flag is specified,
546 .BR ls (1)
547 follows all symbolic links,
548 regardless of their type,
549 whether specified on the command line or encountered in the tree walk.
550 .SH SEE ALSO
551 .BR chgrp (1),
552 .BR chmod (1),
553 .BR find (1),
554 .BR ln (1),
555 .BR ls (1),
556 .BR mv (1),
557 .BR namei (1),
558 .BR rm (1),
559 .BR lchown (2),
560 .BR link (2),
561 .BR lstat (2),
562 .BR readlink (2),
563 .BR rename (2),
564 .BR symlink (2),
565 .BR unlink (2),
566 .BR utimensat (2),
567 .BR lutimes (3),
568 .BR path_resolution (7)