1 .\" Copyright (c) 1992, 1993, 1994
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)symlink.7 8.3 (Berkeley) 3/31/94
29 .\" $FreeBSD: src/bin/ln/symlink.7,v 1.13.2.7 2003/03/03 19:04:46 trhodes Exp $
36 .Nd symbolic link handling
37 .Sh SYMBOLIC LINK HANDLING
38 Symbolic links are files that act as pointers to other files.
39 To understand their behavior, you must first understand how hard links
41 A hard link to a file is indistinguishable from the original file because
42 it is a reference to the object underlying the original file name.
43 Changes to a file are independent of the name used to reference the
45 Hard links may not refer to directories and may not reference files
46 on different file systems.
47 A symbolic link contains the name of the file to which it is linked,
48 i.e. it is a pointer to another name, and not to an underlying object.
49 For this reason, symbolic links may reference directories and may span
52 Because a symbolic link and its referenced object coexist in the file system
53 name space, confusion can arise in distinguishing between the link itself
54 and the referenced object.
55 Historically, commands and system calls have adopted their own link
56 following conventions in a somewhat ad-hoc fashion.
57 Rules for more a uniform approach, as they are implemented in this system,
59 It is important that local applications conform to these rules, too,
60 so that the user interface can be as consistent as possible.
62 Symbolic links are handled either by operating on the link itself,
63 or by operating on the object referenced by the link.
65 an application or system call is said to
68 Symbolic links may reference other symbolic links,
69 in which case the links are dereferenced until an object that is
70 not a symbolic link is found,
71 a symbolic link which references a file which doesn't exist is found,
72 or a loop is detected.
73 (Loop detection is done by placing an upper limit on the number of
74 links that may be followed, and an error results if this limit is
77 There are three separate areas that need to be discussed.
80 .Bl -enum -compact -offset indent
82 Symbolic links used as file name arguments for system calls.
84 Symbolic links specified as command line arguments to utilities that
85 are not traversing a file tree.
87 Symbolic links encountered by utilities that are traversing a file tree
88 (either specified on the command line or encountered as part of the
92 The first area is symbolic links used as file name arguments for
95 Except as noted below, all system calls follow symbolic links.
96 For example, if there were a symbolic link
98 which pointed to a file named
101 .Dq Li open("slink" ...\&)
102 would return a file descriptor to the file
105 There are six system calls that do not follow links, and which operate
106 on the symbolic link itself.
119 it also does not follow symbolic links.
122 is applied to a symbolic link, it fails with the error
125 The owner and group of an existing symbolic link can be changed by
129 The other file attributes, such as the modification time and access
130 permissions, are not used by the system and cannot be changed.
134 system differs from historical
136 systems in that the system call
138 has been changed to follow symbolic links.
141 system call was added later when the limitations of the new
144 .Ss Commands not traversing a file tree.
145 The second area is symbolic links, specified as command line file
146 name arguments, to commands which are not traversing a file tree.
148 Except as noted below, commands follow symbolic links named as command
150 For example, if there were a symbolic link
152 which pointed to a file named
156 would display the contents of the file
159 It is important to realize that this rule includes commands which may
160 optionally traverse file trees, e.g. the command
162 is included in this rule, while the command
163 .Dq Li "chown -R file"
165 (The latter is described in the third area, below.)
167 If it is explicitly intended that the command operate on the symbolic
168 link instead of following the symbolic link, e.g., it is desired that
170 change the ownership of the file that
172 is, whether it is a symbolic link or not, the
174 option should be used.
175 In the above example,
176 .Dq Li "chown root slink"
177 would change the ownership of the file referenced by
180 .Dq Li "chown -h root slink"
181 would change the ownership of
185 There are four exceptions to this rule.
190 commands do not follow symbolic links named as arguments,
191 but respectively attempt to rename and delete them.
192 (Note, if the symbolic link references a file via a relative path,
193 moving it to another directory may very well cause it to stop working,
194 since the path may no longer be correct.)
198 command is also an exception to this rule.
199 For compatibility with historic systems (when
201 is not doing a tree walk, i.e. the
203 option is not specified),
206 command follows symbolic links named as arguments if the
216 options are not specified. (The
218 command is the only command where the
222 options affect its behavior even though it is not doing a walk of
227 command is also an exception to this rule.
230 command does not follow symbolic links named as argument by default.
233 command does follow symbolic links named as argument if
239 system differs from historical
245 commands follow symbolic links specified on the command line.
246 .Ss Commands traversing a file tree.
247 The following commands either optionally or always traverse file trees:
261 It is important to realize that the following rules apply equally to
262 symbolic links encountered during the file tree traversal and symbolic
263 links listed as command line arguments.
265 The first rule applies to symbolic links that reference files that are
266 not of type directory.
267 Operations that apply to symbolic links are performed on the links
268 themselves, but otherwise the links are ignored.
270 For example, the command
271 .Dq Li "chown -R user slink directory"
274 because symbolic links in this system do not have owners.
275 Any symbolic links encountered during the tree traversal will also be
278 .Dq Li "rm -r slink directory"
281 as well as any symbolic links encountered in the tree traversal of
283 because symbolic links may be removed.
284 In no case will either
288 affect the file which
290 references in any way.
292 The second rule applies to symbolic links that reference files of type
294 Symbolic links which reference files of type directory are never
297 This is often referred to as a
299 walk, as opposed to a
301 walk (where symbolic links referencing directories are followed).
303 As consistently as possible, you can make commands doing a file tree
304 walk follow any symbolic links named on the command line, regardless
305 of the type of file they reference, by specifying the
310 This flag is intended to make the command line name space look
311 like the logical name space.
312 (Note, for commands that do not always do file tree traversals, the
314 flag will be ignored if the
316 flag is not also specified.)
318 For example, the command
319 .Dq Li "chown -HR user slink"
320 will traverse the file hierarchy rooted in the file pointed to by
324 is not the same as the previously discussed
329 flag causes symbolic links specified on the command line to be
330 dereferenced both for the purposes of the action to be performed
331 and the tree walk, and it is as if the user had specified the
332 name of the file to which the symbolic link pointed.
334 As consistently as possible, you can make commands doing a file tree
335 walk follow any symbolic links named on the command line, as well as
336 any symbolic links encountered during the traversal, regardless of
337 the type of file they reference, by specifying the
342 This flag is intended to make the entire name space look like
343 the logical name space.
344 (Note, for commands that do not always do file tree traversals, the
346 flag will be ignored if the
348 flag is not also specified.)
350 For example, the command
351 .Dq Li "chown -LR user slink"
352 will change the owner of the file referenced by
356 references a directory,
358 will traverse the file hierarchy rooted in the directory that it
360 In addition, if any symbolic links are encountered in any file tree that
362 traverses, they will be treated in the same fashion as
365 As consistently as possible, you can specify the default behavior by
371 This flag is intended to make the entire name space look like the
374 For commands that do not by default do file tree traversals, the
379 flags are ignored if the
381 flag is not also specified.
382 In addition, you may specify the
387 options more than once; the last one specified determines the
389 This is intended to permit you to alias commands to behave one way
390 or the other, and then override that behavior on the command line.
396 commands have exceptions to these rules.
399 command operates on the symbolic link, and not the file it references,
400 and therefore never follows a symbolic link.
403 command does not support the
410 To maintain compatibility with historic systems,
413 command acts a little differently. If you do not specify the
420 will follow symbolic links specified on the command line. If the
424 follows all symbolic links,
425 regardless of their type,
426 whether specified on the command line or encountered in the tree walk.