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. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)symlink.7 8.3 (Berkeley) 3/31/94
33 .\" $FreeBSD: src/bin/ln/symlink.7,v 1.25 2002/08/21 17:32:32 trhodes Exp $
40 .Nd symbolic link handling
41 .Sh SYMBOLIC LINK HANDLING
42 Symbolic links are files that act as pointers to other files.
43 To understand their behavior, you must first understand how hard links
45 A hard link to a file is indistinguishable from the original file because
46 it is a reference to the object underlying the original file name.
47 Changes to a file are independent of the name used to reference the
49 Hard links may not refer to directories and may not reference files
50 on different file systems.
51 A symbolic link contains the name of the file to which it is linked,
52 i.e. it is a pointer to another name, and not to an underlying object.
53 For this reason, symbolic links may reference directories and may span
56 Because a symbolic link and its referenced object coexist in the file system
57 name space, confusion can arise in distinguishing between the link itself
58 and the referenced object.
59 Historically, commands and system calls have adopted their own link
60 following conventions in a somewhat ad-hoc fashion.
61 Rules for more a uniform approach, as they are implemented in this system,
63 It is important that local applications conform to these rules, too,
64 so that the user interface can be as consistent as possible.
66 Symbolic links are handled either by operating on the link itself,
67 or by operating on the object referenced by the link.
69 an application or system call is said to
72 Symbolic links may reference other symbolic links,
73 in which case the links are dereferenced until an object that is
74 not a symbolic link is found,
75 a symbolic link which references a file which doesn't exist is found,
76 or a loop is detected.
77 (Loop detection is done by placing an upper limit on the number of
78 links that may be followed, and an error results if this limit is
81 There are three separate areas that need to be discussed.
84 .Bl -enum -compact -offset indent
86 Symbolic links used as file name arguments for system calls.
88 Symbolic links specified as command line arguments to utilities that
89 are not traversing a file tree.
91 Symbolic links encountered by utilities that are traversing a file tree
92 (either specified on the command line or encountered as part of the
96 The first area is symbolic links used as file name arguments for
99 Except as noted below, all system calls follow symbolic links.
100 For example, if there were a symbolic link
102 which pointed to a file named
105 .Dq Li open("slink" ...\&)
106 would return a file descriptor to the file
109 There are nine system calls that do not follow links, and which operate
110 on the symbolic link itself.
126 it also does not follow symbolic links.
129 is applied to a symbolic link, it fails with the error
132 The owner and group of an existing symbolic link can be changed by
136 The flags, access permissions, owner/group and modification time of
137 an existing symbolic link can be changed by means of the
143 system calls, respectively.
144 Of these, only the flags are used by the system;
145 the access permissions and ownership are ignored.
149 system differs from historical
151 systems in that the system call
153 has been changed to follow symbolic links.
156 system call was added later when the limitations of the new
159 .Ss Commands not traversing a file tree.
160 The second area is symbolic links, specified as command line file
161 name arguments, to commands which are not traversing a file tree.
163 Except as noted below, commands follow symbolic links named as command
165 For example, if there were a symbolic link
167 which pointed to a file named
171 would display the contents of the file
174 It is important to realize that this rule includes commands which may
175 optionally traverse file trees, e.g. the command
177 is included in this rule, while the command
178 .Dq Li "chown -R file"
180 (The latter is described in the third area, below.)
182 If it is explicitly intended that the command operate on the symbolic
183 link instead of following the symbolic link, e.g., it is desired that
185 change the ownership of the file that
187 is, whether it is a symbolic link or not, the
189 option should be used.
190 In the above example,
191 .Dq Li "chown root slink"
192 would change the ownership of the file referenced by
195 .Dq Li "chown -h root slink"
196 would change the ownership of
200 There are four exceptions to this rule.
205 commands do not follow symbolic links named as arguments,
206 but respectively attempt to rename and delete them.
207 (Note, if the symbolic link references a file via a relative path,
208 moving it to another directory may very well cause it to stop working,
209 since the path may no longer be correct.)
213 command is also an exception to this rule.
214 For compatibility with historic systems (when
216 is not doing a tree walk, i.e. the
218 option is not specified),
221 command follows symbolic links named as arguments if the
231 options are not specified. (The
233 command is the only command where the
237 options affect its behavior even though it is not doing a walk of
242 command is also an exception to this rule.
245 command does not follow symbolic links named as argument by default.
248 command does follow symbolic links named as argument if
254 system differs from historical
260 commands follow symbolic links specified on the command line.
261 .Ss Commands traversing a file tree.
262 The following commands either optionally or always traverse file trees:
276 It is important to realize that the following rules apply equally to
277 symbolic links encountered during the file tree traversal and symbolic
278 links listed as command line arguments.
280 The first rule applies to symbolic links that reference files that are
281 not of type directory.
282 Operations that apply to symbolic links are performed on the links
283 themselves, but otherwise the links are ignored.
286 .Dq Li "rm -r slink directory"
289 as well as any symbolic links encountered in the tree traversal of
291 because symbolic links may be removed.
294 affect the file which
296 references in any way.
298 The second rule applies to symbolic links that reference files of type
300 Symbolic links which reference files of type directory are never
303 This is often referred to as a
305 walk, as opposed to a
307 walk (where symbolic links referencing directories are followed).
309 As consistently as possible, you can make commands doing a file tree
310 walk follow any symbolic links named on the command line, regardless
311 of the type of file they reference, by specifying the
316 This flag is intended to make the command line name space look
317 like the logical name space.
318 (Note, for commands that do not always do file tree traversals, the
320 flag will be ignored if the
322 flag is not also specified.)
324 For example, the command
325 .Dq Li "chown -HR user slink"
326 will traverse the file hierarchy rooted in the file pointed to by
330 is not the same as the previously discussed
335 flag causes symbolic links specified on the command line to be
336 dereferenced both for the purposes of the action to be performed
337 and the tree walk, and it is as if the user had specified the
338 name of the file to which the symbolic link pointed.
340 As consistently as possible, you can make commands doing a file tree
341 walk follow any symbolic links named on the command line, as well as
342 any symbolic links encountered during the traversal, regardless of
343 the type of file they reference, by specifying the
348 This flag is intended to make the entire name space look like
349 the logical name space.
350 (Note, for commands that do not always do file tree traversals, the
352 flag will be ignored if the
354 flag is not also specified.)
356 For example, the command
357 .Dq Li "chown -LR user slink"
358 will change the owner of the file referenced by
362 references a directory,
364 will traverse the file hierarchy rooted in the directory that it
366 In addition, if any symbolic links are encountered in any file tree that
368 traverses, they will be treated in the same fashion as
371 As consistently as possible, you can specify the default behavior by
377 This flag is intended to make the entire name space look like the
380 For commands that do not by default do file tree traversals, the
385 flags are ignored if the
387 flag is not also specified.
388 In addition, you may specify the
393 options more than once; the last one specified determines the
395 This is intended to permit you to alias commands to behave one way
396 or the other, and then override that behavior on the command line.
402 commands have exceptions to these rules.
405 command operates on the symbolic link, and not the file it references,
406 and therefore never follows a symbolic link.
409 command does not support the
416 To maintain compatibility with historic systems,
419 command acts a little differently. If you do not specify the
426 will follow symbolic links specified on the command line. If the
430 follows all symbolic links,
431 regardless of their type,
432 whether specified on the command line or encountered in the tree walk.
projects / apple / file_cmds.git / blob