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 System calls
99 The first area is symbolic links used as filename arguments for system
100 calls.
101 Except as noted below, all system calls follow symbolic links. For
103 example, if there were a symbolic link slink which pointed to a file
104 named afile, the system call open("slink" ...) would return a file
105 descriptor referring to the file afile.
106 Various system calls do not follow links, and operate on the symbolic
108 link itself. They are: lchown(2), lgetxattr(2), llistxattr(2), lre‐
109 movexattr(2), lsetxattr(2), lstat(2), readlink(2), rename(2), rmdir(2),
110 and unlink(2).
111 Certain other system calls optionally follow symbolic links. They are:
113 faccessat(2), fchownat(2), fstatat(2), linkat(2), name_to_handle_at(2),
114 open(2), openat(2), open_by_handle_at(2), and utimensat(2); see their
115 manual pages for details. Because remove(3) is an alias for unlink(2),
116 that library function also does not follow symbolic links. When
117 rmdir(2) is applied to a symbolic link, it fails with the error ENOT‐
118 DIR.
119 link(2) warrants special discussion. POSIX.1-2001 specifies that
121 link(2) should dereference oldpath if it is a symbolic link. However,
122 Linux does not do this. (By default, Solaris is the same, but the
123 POSIX.1-2001 specified behavior can be obtained with suitable compiler
124 options.) POSIX.1-2008 changed the specification to allow either
125 behavior in an implementation.
126 Commands not traversing a file tree
128 The second area is symbolic links, specified as command-line filename
129 arguments, to commands which are not traversing a file tree.
130 Except as noted below, commands follow symbolic links named as command-
132 line arguments. For example, if there were a symbolic link slink which
133 pointed to a file named afile, the command cat slink would display the
134 contents of the file afile.
135 It is important to realize that this rule includes commands which may
137 optionally traverse file trees; for example, the command chown file is
138 included in this rule, while the command chown -R file, which performs
139 a tree traversal, is not. (The latter is described in the third area,
140 below.)
141 If it is explicitly intended that the command operate on the symbolic
143 link instead of following the symbolic link—for example, it is desired
144 that chown slink change the ownership of the file that slink is,
145 whether it is a symbolic link or not—the -h option should be used. In
146 the above example, chown root slink would change the ownership of the
147 file referred to by slink, while chown -h root slink would change the
148 ownership of slink itself.
149 There are some exceptions to this rule:
151 * The mv(1) and rm(1) commands do not follow symbolic links named as
153 arguments, but respectively attempt to rename and delete them.
154 (Note, if the symbolic link references a file via a relative path,
155 moving it to another directory may very well cause it to stop work‐
156 ing, since the path may no longer be correct.)
157 * The ls(1) command is also an exception to this rule. For compatibil‐
159 ity with historic systems (when ls(1) is not doing a tree walk—that
160 is, -R option is not specified), the ls(1) command follows symbolic
161 links named as arguments if the -H or -L option is specified, or if
162 the -F, -d, or -l options are not specified. (The ls(1) command is
163 the only command where the -H and -L options affect its behavior even
164 though it is not doing a walk of a file tree.)
165 * The file(1) command is also an exception to this rule. The file(1)
167 command does not follow symbolic links named as argument by default.
168 The file(1) command does follow symbolic links named as argument if
169 the -L option is specified.
170 Commands traversing a file tree
172 The following commands either optionally or always traverse file trees:
173 chgrp(1), chmod(1), chown(1), cp(1), du(1), find(1), ls(1), pax(1),
174 rm(1), and tar(1).
175 It is important to realize that the following rules apply equally to
177 symbolic links encountered during the file tree traversal and symbolic
178 links listed as command-line arguments.
179 The first rule applies to symbolic links that reference files other
181 than directories. Operations that apply to symbolic links are per‐
182 formed on the links themselves, but otherwise the links are ignored.
183 The command rm -r slink directory will remove slink, as well as any
185 symbolic links encountered in the tree traversal of directory, because
186 symbolic links may be removed. In no case will rm(1) affect the file
187 referred to by slink.
188 The second rule applies to symbolic links that refer to directories.
190 Symbolic links that refer to directories are never followed by default.
191 This is often referred to as a "physical" walk, as opposed to a "logi‐
192 cal" walk (where symbolic links that refer to directories are fol‐
193 lowed).
194 Certain conventions are (should be) followed as consistently as possi‐
196 ble by commands that perform file tree walks:
197 * A command can be made to follow any symbolic links named on the com‐
199 mand line, regardless of the type of file they reference, by specify‐
200 ing the -H (for "half-logical") flag. This flag is intended to make
201 the command-line name space look like the logical name space. (Note,
202 for commands that do not always do file tree traversals, the -H flag
203 will be ignored if the -R flag is not also specified.)
204 For example, the command chown -HR user slink will traverse the file
206 hierarchy rooted in the file pointed to by slink. Note, the -H is
207 not the same as the previously discussed -h flag. The -H flag causes
208 symbolic links specified on the command line to be dereferenced for
209 the purposes of both the action to be performed and the tree walk,
210 and it is as if the user had specified the name of the file to which
211 the symbolic link pointed.
212 * A command can be made to follow any symbolic links named on the com‐
214 mand line, as well as any symbolic links encountered during the tra‐
215 versal, regardless of the type of file they reference, by specifying
216 the -L (for "logical") flag. This flag is intended to make the
217 entire name space look like the logical name space. (Note, for com‐
218 mands that do not always do file tree traversals, the -L flag will be
219 ignored if the -R flag is not also specified.)
220 For example, the command chown -LR user slink will change the owner
222 of the file referred to by slink. If slink refers to a directory,
223 chown will traverse the file hierarchy rooted in the directory that
224 it references. In addition, if any symbolic links are encountered in
225 any file tree that chown traverses, they will be treated in the same
226 fashion as slink.
227 * A command can be made to provide the default behavior by specifying
229 the -P (for "physical") flag. This flag is intended to make the
230 entire name space look like the physical name space.
231 For commands that do not by default do file tree traversals, the -H,
233 -L, and -P flags are ignored if the -R flag is not also specified. In
234 addition, you may specify the -H, -L, and -P options more than once;
235 the last one specified determines the command's behavior. This is
236 intended to permit you to alias commands to behave one way or the
237 other, and then override that behavior on the command line.
238 The ls(1) and rm(1) commands have exceptions to these rules:
240 * The rm(1) command operates on the symbolic link, and not the file it
242 references, and therefore never follows a symbolic link. The rm(1)
243 command does not support the -H, -L, or -P options.
244 * To maintain compatibility with historic systems, the ls(1) command
246 acts a little differently. If you do not specify the -F, -d or -l
247 options, ls(1) will follow symbolic links specified on the command
248 line. If the -L flag is specified, ls(1) follows all symbolic links,
249 regardless of their type, whether specified on the command line or
250 encountered in the tree walk.
251
253 chgrp(1), chmod(1), find(1), ln(1), ls(1), mv(1), namei(1), rm(1),
254 lchown(2), link(2), lstat(2), readlink(2), rename(2), symlink(2),
255 unlink(2), utimensat(2), lutimes(3), path_resolution(7)
256
258 This page is part of release 4.15 of the Linux man-pages project. A
259 description of the project, information about reporting bugs, and the
260 latest version of this page, can be found at
261 https://www.kernel.org/doc/man-pages/.
262Linux 2016-10-08 SYMLINK(7)