1SYMLINK(7) Linux Programmer's Manual SYMLINK(7)
2
6 symlink - symbolic link handling
7
9 Symbolic links are files that act as pointers to other files. To
10 understand their behavior, you must first understand how hard links
11 work.
12 A hard link to a file is indistinguishable from the original file
14 because it is a reference to the object underlying the original file‐
15 name. (To be precise: each of the hard links to a file is a reference
16 to the same inode number, where an inode number is an index into the
17 inode table, which contains metadata about all files on a filesystem.
18 See stat(2).) Changes to a file are independent of the name used to
19 reference the file. Hard links may not refer to directories (to pre‐
20 vent the possibility of loops within the filesystem tree, which would
21 confuse many programs) and may not refer to files on different filesys‐
22 tems (because inode numbers are not unique across filesystems).
23 A symbolic link is a special type of file whose contents are a string
25 that is the pathname of another file, the file to which the link
26 refers. (The contents of a symbolic link can be read using read‐
27 link(2).) In other words, a symbolic link is a pointer to another
28 name, and not to an underlying object. For this reason, symbolic links
29 may refer to directories and may cross filesystem boundaries.
30 There is no requirement that the pathname referred to by a symbolic
32 link should exist. A symbolic link that refers to a pathname that does
33 not exist is said to be a dangling link.
34 Because a symbolic link and its referenced object coexist in the
36 filesystem name space, confusion can arise in distinguishing between
37 the link itself and the referenced object. On historical systems, com‐
38 mands and system calls adopted their own link-following conventions in
39 a somewhat ad-hoc fashion. Rules for a more uniform approach, as they
40 are implemented on Linux and other systems, are outlined here. It is
41 important that site-local applications also conform to these rules, so
42 that the user interface can be as consistent as possible.
43 Symbolic link ownership, permissions, and timestamps
45 The owner and group of an existing symbolic link can be changed using
46 lchown(2). The only time that the ownership of a symbolic link matters
47 is when the link is being removed or renamed in a directory that has
48 the sticky bit set (see stat(2)).
49 The last access and last modification timestamps of a symbolic link can
51 be changed using utimensat(2) or lutimes(3).
52 On Linux, the permissions of a symbolic link are not used in any opera‐
54 tions; the permissions are always 0777 (read, write, and execute for
55 all user categories), and can't be changed. (Note that there are some
56 "magic" symbolic links in the /proc directory tree—for example, the
57 /proc/[pid]/fd/* files—that have different permissions.)
58 Obtaining a file descriptor that refers to a symbolic link
60 Using the combination of the O_PATH and O_NOFOLLOW flags to open(2)
61 yields a file descriptor that can be passed as the dirfd argument in
62 system calls such as fstatat(2), fchownat(2), fchmodat(2), linkat(2),
63 and readlinkat(2), in order to operate on the symbolic link itself
64 (rather than the file to which it refers).
65 By default (i.e., if the AT_SYMLINK_FOLLOW flag is not specified), if
67 name_to_handle_at(2) is applied to a symbolic link, it yields a handle
68 for the symbolic link (rather than the file to which it refers). One
69 can then obtain a file descriptor for the symbolic link (rather than
70 the file to which it refers) by specifying the O_PATH flag in a subse‐
71 quent call to open_by_handle_at(2). Again, that file descriptor can be
72 used in the aforementioned system calls to operate on the symbolic link
73 itself.
74 Handling of symbolic links by system calls and commands
76 Symbolic links are handled either by operating on the link itself, or
77 by operating on the object referred to by the link. In the latter
78 case, an application or system call is said to follow the link. Sym‐
79 bolic links may refer to other symbolic links, in which case the links
80 are dereferenced until an object that is not a symbolic link is found,
81 a symbolic link that refers to a file which does not exist is found, or
82 a loop is detected. (Loop detection is done by placing an upper limit
83 on the number of links that may be followed, and an error results if
84 this limit is exceeded.)
85 There are three separate areas that need to be discussed. They are as
87 follows:
88 1. Symbolic links used as filename arguments for system calls.
90 2. Symbolic links specified as command-line arguments to utilities that
92 are not traversing a file tree.
93 3. Symbolic links encountered by utilities that are traversing a file
95 tree (either specified on the command line or encountered as part of
96 the file hierarchy walk).
97 Before describing the treatment of symbolic links by system calls and
99 commands, we require some terminology. Given a pathname of the form
100 a/b/c, the part preceding the final slash (i.e., a/b) is called the
101 dirname component, and the part following the final slash (i.e., c) is
102 called the basename component.
103 Treatment of symbolic links in system calls
105 The first area is symbolic links used as filename arguments for system
106 calls.
107 The treatment of symbolic links within a pathname passed to a system
109 call is as follows:
110 1. Within the dirname component of a pathname, symbolic links are
112 always followed in nearly every system call. (This is also true for
113 commands.) The one exception is openat2(2), which provides flags
114 that can be used to explicitly prevent following of symbolic links
115 in the dirname component.
116 2. Except as noted below, all system calls follow symbolic links in the
118 basename component of a pathname. For example, if there were a sym‐
119 bolic link slink which pointed to a file named afile, the system
120 call open("slink" ...) would return a file descriptor referring to
121 the file afile.
122 Various system calls do not follow links in the basename component of a
124 pathname, and operate on the symbolic link itself. They are:
125 lchown(2), lgetxattr(2), llistxattr(2), lremovexattr(2), lsetxattr(2),
126 lstat(2), readlink(2), rename(2), rmdir(2), and unlink(2).
127 Certain other system calls optionally follow symbolic links in the
129 basename component of a pathname. They are: faccessat(2), fchownat(2),
130 fstatat(2), linkat(2), name_to_handle_at(2), open(2), openat(2),
131 open_by_handle_at(2), and utimensat(2); see their manual pages for
132 details. Because remove(3) is an alias for unlink(2), that library
133 function also does not follow symbolic links. When rmdir(2) is applied
134 to a symbolic link, it fails with the error ENOTDIR.
135 link(2) warrants special discussion. POSIX.1-2001 specifies that
137 link(2) should dereference oldpath if it is a symbolic link. However,
138 Linux does not do this. (By default, Solaris is the same, but the
139 POSIX.1-2001 specified behavior can be obtained with suitable compiler
140 options.) POSIX.1-2008 changed the specification to allow either
141 behavior in an implementation.
142 Commands not traversing a file tree
144 The second area is symbolic links, specified as command-line filename
145 arguments, to commands which are not traversing a file tree.
146 Except as noted below, commands follow symbolic links named as command-
148 line arguments. For example, if there were a symbolic link slink which
149 pointed to a file named afile, the command cat slink would display the
150 contents of the file afile.
151 It is important to realize that this rule includes commands which may
153 optionally traverse file trees; for example, the command chown file is
154 included in this rule, while the command chown -R file, which performs
155 a tree traversal, is not. (The latter is described in the third area,
156 below.)
157 If it is explicitly intended that the command operate on the symbolic
159 link instead of following the symbolic link—for example, it is desired
160 that chown slink change the ownership of the file that slink is,
161 whether it is a symbolic link or not—then the -h option should be used.
162 In the above example, chown root slink would change the ownership of
163 the file referred to by slink, while chown -h root slink would change
164 the ownership of slink itself.
165 There are some exceptions to this rule:
167 * The mv(1) and rm(1) commands do not follow symbolic links named as
169 arguments, but respectively attempt to rename and delete them.
170 (Note, if the symbolic link references a file via a relative path,
171 moving it to another directory may very well cause it to stop work‐
172 ing, since the path may no longer be correct.)
173 * The ls(1) command is also an exception to this rule. For compatibil‐
175 ity with historic systems (when ls(1) is not doing a tree walk—that
176 is, -R option is not specified), the ls(1) command follows symbolic
177 links named as arguments if the -H or -L option is specified, or if
178 the -F, -d, or -l options are not specified. (The ls(1) command is
179 the only command where the -H and -L options affect its behavior even
180 though it is not doing a walk of a file tree.)
181 * The file(1) command is also an exception to this rule. The file(1)
183 command does not follow symbolic links named as argument by default.
184 The file(1) command does follow symbolic links named as argument if
185 the -L option is specified.
186 Commands traversing a file tree
188 The following commands either optionally or always traverse file trees:
189 chgrp(1), chmod(1), chown(1), cp(1), du(1), find(1), ls(1), pax(1),
190 rm(1), and tar(1).
191 It is important to realize that the following rules apply equally to
193 symbolic links encountered during the file tree traversal and symbolic
194 links listed as command-line arguments.
195 The first rule applies to symbolic links that reference files other
197 than directories. Operations that apply to symbolic links are per‐
198 formed on the links themselves, but otherwise the links are ignored.
199 The command rm -r slink directory will remove slink, as well as any
201 symbolic links encountered in the tree traversal of directory, because
202 symbolic links may be removed. In no case will rm(1) affect the file
203 referred to by slink.
204 The second rule applies to symbolic links that refer to directories.
206 Symbolic links that refer to directories are never followed by default.
207 This is often referred to as a "physical" walk, as opposed to a "logi‐
208 cal" walk (where symbolic links that refer to directories are fol‐
209 lowed).
210 Certain conventions are (should be) followed as consistently as possi‐
212 ble by commands that perform file tree walks:
213 * A command can be made to follow any symbolic links named on the com‐
215 mand line, regardless of the type of file they reference, by specify‐
216 ing the -H (for "half-logical") flag. This flag is intended to make
217 the command-line name space look like the logical name space. (Note,
218 for commands that do not always do file tree traversals, the -H flag
219 will be ignored if the -R flag is not also specified.)
220 For example, the command chown -HR user slink will traverse the file
222 hierarchy rooted in the file pointed to by slink. Note, the -H is
223 not the same as the previously discussed -h flag. The -H flag causes
224 symbolic links specified on the command line to be dereferenced for
225 the purposes of both the action to be performed and the tree walk,
226 and it is as if the user had specified the name of the file to which
227 the symbolic link pointed.
228 * A command can be made to follow any symbolic links named on the com‐
230 mand line, as well as any symbolic links encountered during the tra‐
231 versal, regardless of the type of file they reference, by specifying
232 the -L (for "logical") flag. This flag is intended to make the
233 entire name space look like the logical name space. (Note, for com‐
234 mands that do not always do file tree traversals, the -L flag will be
235 ignored if the -R flag is not also specified.)
236 For example, the command chown -LR user slink will change the owner
238 of the file referred to by slink. If slink refers to a directory,
239 chown will traverse the file hierarchy rooted in the directory that
240 it references. In addition, if any symbolic links are encountered in
241 any file tree that chown traverses, they will be treated in the same
242 fashion as slink.
243 * A command can be made to provide the default behavior by specifying
245 the -P (for "physical") flag. This flag is intended to make the
246 entire name space look like the physical name space.
247 For commands that do not by default do file tree traversals, the -H,
249 -L, and -P flags are ignored if the -R flag is not also specified. In
250 addition, you may specify the -H, -L, and -P options more than once;
251 the last one specified determines the command's behavior. This is
252 intended to permit you to alias commands to behave one way or the
253 other, and then override that behavior on the command line.
254 The ls(1) and rm(1) commands have exceptions to these rules:
256 * The rm(1) command operates on the symbolic link, and not the file it
258 references, and therefore never follows a symbolic link. The rm(1)
259 command does not support the -H, -L, or -P options.
260 * To maintain compatibility with historic systems, the ls(1) command
262 acts a little differently. If you do not specify the -F, -d or -l
263 options, ls(1) will follow symbolic links specified on the command
264 line. If the -L flag is specified, ls(1) follows all symbolic links,
265 regardless of their type, whether specified on the command line or
266 encountered in the tree walk.
267
269 chgrp(1), chmod(1), find(1), ln(1), ls(1), mv(1), namei(1), rm(1),
270 lchown(2), link(2), lstat(2), readlink(2), rename(2), symlink(2),
271 unlink(2), utimensat(2), lutimes(3), path_resolution(7)
272
274 This page is part of release 5.07 of the Linux man-pages project. A
275 description of the project, information about reporting bugs, and the
276 latest version of this page, can be found at
277 https://www.kernel.org/doc/man-pages/.
278Linux 2020-06-09 SYMLINK(7)