Commit | Line | Data |
---|---|---|
a4a7cf28 | 1 | .\" Copyright (c) 1992, 1993, 1994 |
afe13027 | 2 | .\" The Regents of the University of California. All rights reserved. |
a7c15f88 KB |
3 | .\" |
4 | .\" %sccs.include.redist.roff% | |
5 | .\" | |
deeed9b6 | 6 | .\" @(#)symlink.7 8.3 (Berkeley) %G% |
a7c15f88 KB |
7 | .\" |
8 | .Dd | |
9 | .Dt SYMLINK 7 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm symlink | |
f2790082 | 13 | .Nd symbolic link handling |
a7c15f88 | 14 | .Sh SYMBOLIC LINK HANDLING |
a4a7cf28 KB |
15 | Symbolic links are files that act as pointers to other files. |
16 | To understand their behavior, you must first understand how hard links | |
17 | work. | |
18 | A hard link to a file is indistinguishable from the original file because | |
19 | it is a reference to the object underlying the original file name. | |
20 | Changes to a file are independent of the name used to reference the | |
21 | file. | |
22 | Hard links may not refer to directories and may not reference files | |
23 | on different file systems. | |
24 | A symbolic link contains the name of the file to which it is linked, | |
25 | i.e. it is a pointer to another name, and not to an underlying object. | |
26 | For this reason, symbolic links may reference directories and may span | |
27 | file systems. | |
28 | .Pp | |
29 | Because a symbolic link and its referenced object coexist in the filesystem | |
30 | name space, confusion can arise in distinguishing between the link itself | |
b47b7483 | 31 | and the referenced object. |
a4a7cf28 KB |
32 | Historically, commands and system calls have adopted their own link |
33 | following conventions in a somewhat ad-hoc fashion. | |
34 | Rules for more a uniform approach, as they are implemented in this system, | |
35 | are outlined here. | |
36 | It is important that local applications conform to these rules, too, | |
deeed9b6 | 37 | so that the user interface can be as consistent as possible. |
a7c15f88 | 38 | .Pp |
a4a7cf28 KB |
39 | Symbolic links are handled either by operating on the link itself, |
40 | or by operating on the object referenced by the link. | |
b47b7483 | 41 | In the latter case, |
a4a7cf28 KB |
42 | an application or system call is said to |
43 | .Dq follow | |
44 | the link. | |
45 | Symbolic links may reference other symbolic links, | |
46 | in which case the links are dereferenced until an object that is | |
47 | not a symbolic link is found, | |
48 | a symbolic link which references a file which doesn't exist is found, | |
49 | or a loop is detected. | |
50 | (Loop detection is done by placing an upper limit on the number of | |
51 | links that may be followed, and an error results if this limit is | |
52 | exceeded.) | |
53 | .Pp | |
54 | There are three separate areas that need to be discussed. | |
55 | They are as follows: | |
56 | .sp | |
57 | .Bl -enum -compact -offset indent | |
58 | .It | |
59 | Symbolic links used as file name arguments for system calls. | |
60 | .It | |
61 | Symbolic links specified as command line arguments to utilities that | |
62 | are not traversing a file tree. | |
63 | .It | |
64 | Symbolic links encountered by utilities that are traversing a file tree | |
65 | (either specified on the command line or encountered as part of the | |
66 | file hierarchy walk). | |
67 | .El | |
68 | .Ss System calls. | |
69 | The first area is symbolic links used as file name arguments for | |
70 | system calls. | |
71 | .Pp | |
72 | Except as noted below, all system calls follow symbolic links. | |
73 | For example, if there were a symbolic link | |
74 | .Dq Li slink | |
75 | which pointed to a file named | |
76 | .Dq Li afile , | |
77 | the system call | |
78 | .Dq Li open("slink" ...) | |
79 | would return a file descriptor to the file | |
80 | .Dq afile . | |
81 | .Pp | |
82 | There are four system calls that do not follow links, and which operate | |
83 | on the symbolic link itself. | |
84 | They are: | |
a7c15f88 KB |
85 | .Xr lstat 2 , |
86 | .Xr readlink 2 , | |
87 | .Xr rename 2 , | |
88 | and | |
89 | .Xr unlink 2 . | |
a4a7cf28 KB |
90 | Because |
91 | .Xr remove 3 | |
92 | is an alias for | |
93 | .Xr unlink 2 , | |
94 | it also does not follow symbolic links. | |
95 | .Pp | |
96 | Unlike other filesystem objects, symbolic links do not have an owner, | |
97 | group, permissions, access and modification times, etc. | |
b47b7483 KM |
98 | The only attributes returned from an |
99 | .Xr lstat 2 | |
100 | that refer to the symbolic link itself are the file type (S_IFLNK), | |
101 | size, blocks, and link count (always 1). | |
a4a7cf28 KB |
102 | The other attributes are filled in from the directory that contains |
103 | the link. | |
104 | For portability reasons, you should be aware that other implementations | |
105 | (including historic implementations of 4BSD), implement symbolic links | |
106 | such that they have the same attributes as any other file. | |
107 | .Pp | |
108 | The | |
109 | .Bx 4.4 | |
110 | system differs from historical 4BSD systems in that the system call | |
111 | .Xr chown 2 | |
112 | has been changed to follow symbolic links. | |
113 | .Ss Commands not traversing a file tree. | |
114 | The second area is symbolic links, specified as command line file | |
115 | name arguments, to commands which are not traversing a file tree. | |
a7c15f88 | 116 | .Pp |
a4a7cf28 KB |
117 | Except as noted below, commands follow symbolic links named as command |
118 | line arguments. | |
119 | For example, if there were a symbolic link | |
120 | .Dq Li slink | |
121 | which pointed to a file named | |
122 | .Dq Li afile , | |
123 | the command | |
124 | .Dq Li cat slink | |
125 | would display the contents of the file | |
126 | .Dq Li afile . | |
127 | .Pp | |
128 | It is important to realize that this rule includes commands which may | |
129 | optionally traverse file trees, e.g. the command | |
130 | .Dq Li "chown file" | |
131 | is included in this rule, while the command | |
132 | .Dq Li "chown -R file" | |
133 | is not. | |
134 | (The latter is described in the third area, below.) | |
135 | .Pp | |
136 | If it is explicitly intended that the command operate on the symbolic | |
137 | link instead of following the symbolic link, e.g., it is desired that | |
138 | .Dq Li "file slink" | |
139 | display the type of file that | |
140 | .Dq Li slink | |
141 | is, whether it is a symbolic link or not, the | |
142 | .Fl h | |
143 | option should be used. | |
144 | In the above example, | |
145 | .Dq Li "file slink" | |
146 | would report the type of the file referenced by | |
147 | .Dq Li slink , | |
148 | while | |
149 | .Dq Li "file -h slink" | |
150 | would report that | |
151 | .Dq Li slink | |
152 | was a symbolic link. | |
153 | .Pp | |
154 | There are three exceptions to this rule. | |
155 | The | |
a7c15f88 KB |
156 | .Xr mv 1 |
157 | and | |
a4a7cf28 KB |
158 | .Xr rm 1 |
159 | commands do not follow symbolic links named as arguments, | |
160 | but respectively attempt to rename and delete them. | |
161 | (Note, if the symbolic link references a file via a relative path, | |
162 | moving it to another directory may very well cause it to stop working, | |
163 | since the path may no longer be correct.) | |
164 | .Pp | |
165 | The | |
a7c15f88 | 166 | .Xr ls 1 |
a4a7cf28 KB |
167 | command is also an exception to this rule. |
168 | For compatibility with historic systems (when | |
169 | .Nm ls | |
170 | is not doing a tree walk, i.e. the | |
171 | .Fl R | |
172 | option is not specified), | |
173 | the | |
174 | .Nm ls | |
175 | command follows symbolic links named as arguments if the | |
176 | .Fl L | |
177 | option is specified, | |
178 | or if the | |
a7c15f88 KB |
179 | .Fl F , |
180 | .Fl d | |
181 | or | |
a4a7cf28 KB |
182 | .Fl l |
183 | options are not specified. | |
184 | (If the | |
a7c15f88 KB |
185 | .Fl L |
186 | option is specified, | |
a4a7cf28 | 187 | .Nm ls |
a7c15f88 | 188 | always follows symbolic links. |
a4a7cf28 KB |
189 | .Nm Ls |
190 | is the only command where the | |
191 | .Fl L | |
192 | option affects its behavior even though it is not doing a walk of | |
193 | a file tree.) | |
a7c15f88 | 194 | .Pp |
a4a7cf28 KB |
195 | The |
196 | .Bx 4.4 | |
197 | system differs from historical 4BSD systems in that the | |
198 | .Nm chown , | |
199 | .Nm chgrp | |
200 | and | |
201 | .Nm file | |
202 | commands follow symbolic links specified on the command line. | |
203 | .Ss Commands traversing a file tree. | |
204 | The following commands either optionally or always traverse file trees: | |
a7c15f88 KB |
205 | .Xr chflags 1 , |
206 | .Xr chgrp 1 , | |
207 | .Xr chmod 1 , | |
a7c15f88 KB |
208 | .Xr cp 1 , |
209 | .Xr du 1 , | |
210 | .Xr find 1 , | |
211 | .Xr ls 1 , | |
a4a7cf28 KB |
212 | .Xr pax 1 , |
213 | .Xr rm 1 , | |
214 | .Xr tar 1 | |
a7c15f88 | 215 | and |
a4a7cf28 | 216 | .Xr chown 8 . |
a7c15f88 | 217 | .Pp |
a4a7cf28 KB |
218 | It is important to realize that the following rules apply equally to |
219 | symbolic links encountered during the file tree traversal and symbolic | |
220 | links listed as command line arguments. | |
221 | .Pp | |
222 | The first rule applies to symbolic links that reference files that are | |
223 | not of type directory. | |
224 | Operations that apply to symbolic links are performed on the links | |
225 | themselves, but otherwise the links are ignored. | |
226 | .Pp | |
227 | For example, the command | |
228 | .Dq Li "chown -R user slink directory" | |
229 | will ignore | |
230 | .Dq Li slink , | |
231 | because symbolic links in this system do not have owners. | |
232 | Any symbolic links encountered during the tree traversal will also be | |
233 | ignored. | |
234 | The command | |
235 | .Dq Li "rm -r slink directory" | |
236 | will remove | |
237 | .Dq Li slink , | |
238 | as well as any symbolic links encountered in the tree traversal of | |
239 | .Dq Li directory , | |
240 | because symbolic links may be removed. | |
241 | In no case will either | |
242 | .Nm chown | |
243 | or | |
244 | .Nm rm | |
245 | affect the file which | |
246 | .Dq Li slink | |
247 | references in any way. | |
248 | .Pp | |
249 | The second rule applies to symbolic links that reference files of type | |
250 | directory. | |
251 | Symbolic links which reference files of type directory are never | |
252 | .Dq followed | |
253 | by default. | |
254 | This is often referred to as a | |
255 | .Dq physical | |
256 | walk, as opposed to a | |
257 | .Dq logical | |
258 | walk (where symbolic links referencing directories are followed). | |
259 | .Pp | |
260 | As consistently as possible, you can make commands doing a file tree | |
261 | walk follow any symbolic links named on the command line, regardless | |
262 | of the type of file they reference, by specifying the | |
a7c15f88 | 263 | .Fl H |
a4a7cf28 KB |
264 | (for |
265 | .Dq half\-logical ) | |
266 | flag. | |
267 | This flag is intended to make the command line name space look | |
268 | like the logical name space. | |
269 | (Note, for commands that do not always do file tree traversals, the | |
270 | .Fl H | |
271 | flag will be ignored if the | |
272 | .Fl R | |
273 | flag is not also specified.) | |
274 | .Pp | |
275 | For example, the command | |
276 | .Dq Li "chown -HR user slink" | |
277 | will traverse the file hierarchy rooted in the file pointed to by | |
278 | .Dq Li slink . | |
279 | Note, the | |
280 | .Fl H | |
281 | is not the same as the previously discussed | |
a7c15f88 | 282 | .Fl h |
a4a7cf28 | 283 | flag. |
a7c15f88 KB |
284 | The |
285 | .Fl H | |
a4a7cf28 | 286 | flag causes symbolic links specified on the command line to be |
deeed9b6 KB |
287 | dereferenced both for the purposes of the action to be performed |
288 | and the tree walk, and it is as if the user had specified the | |
289 | name of the file to which the symbolic link pointed. | |
a7c15f88 | 290 | .Pp |
a4a7cf28 KB |
291 | As consistently as possible, you can make commands doing a file tree |
292 | walk follow any symbolic links named on the command line, as well as | |
293 | any symbolic links encountered during the traversal, regardless of | |
294 | the type of file they reference, by specifying the | |
295 | .Fl L | |
296 | (for | |
297 | .Dq logical ) | |
298 | flag. | |
299 | This flag is intended to make the entire name space look like | |
300 | the logical name space. | |
301 | (Note, for commands that do not always do file tree traversals, the | |
302 | .Fl L | |
303 | flag will be ignored if the | |
304 | .Fl R | |
305 | flag is not also specified.) | |
a7c15f88 | 306 | .Pp |
a4a7cf28 KB |
307 | For example, the command |
308 | .Dq Li "chown -LR user slink" | |
309 | will change the owner of the file referenced by | |
310 | .Dq Li slink . | |
311 | If | |
312 | .Dq Li slink | |
313 | references a directory, | |
314 | .Nm chown | |
315 | will traverse the file hierarchy rooted in the directory that it | |
316 | references. | |
317 | In addition, if any symbolic links are encountered in any file tree that | |
318 | .Nm chown | |
319 | traverses, they will be treated in the same fashion as | |
320 | .Dq Li slink . | |
321 | .Pp | |
322 | As consistently as possible, you can specify the default behavior by | |
323 | specifying the | |
324 | .Fl P | |
325 | (for | |
326 | .Dq physical ) | |
327 | flag. | |
328 | This flag is intended to make the entire name space look like the | |
329 | physical name space. | |
330 | .Pp | |
331 | For commands that do not by default do file tree traversals, the | |
332 | .Fl H , | |
333 | .Fl L | |
334 | and | |
335 | .Fl P | |
336 | flags are ignored if the | |
337 | .Fl R | |
338 | flag is not also specified. | |
deeed9b6 | 339 | In addition, you may specify the |
a4a7cf28 KB |
340 | .Fl H , |
341 | .Fl L | |
342 | and | |
343 | .Fl P | |
deeed9b6 KB |
344 | options more than once; the last one specified determines the |
345 | command's behavior. | |
a4a7cf28 | 346 | This is intended to permit you to alias commands to behave one way |
deeed9b6 | 347 | or the other, and then override that behavior on the command line. |
a7c15f88 | 348 | .Pp |
a7c15f88 | 349 | The |
a4a7cf28 KB |
350 | .Xr ls 1 |
351 | and | |
352 | .Xr rm 1 | |
353 | commands have exceptions to these rules. | |
354 | The | |
355 | .Nm rm | |
356 | command operates on the symbolic link, and not the file it references, | |
357 | and therefore never follows a symbolic link. | |
358 | The | |
359 | .Nm rm | |
360 | command does not support the | |
361 | .Fl H , | |
362 | .Fl L | |
a7c15f88 | 363 | or |
a4a7cf28 | 364 | .Fl P |
a7c15f88 KB |
365 | options. |
366 | .Pp | |
a4a7cf28 KB |
367 | To maintain compatibility with historic systems, |
368 | the | |
369 | .Nm ls | |
370 | command never follows symbolic links unless the | |
371 | .Fl L | |
372 | flag is specified. | |
373 | If the | |
374 | .Fl L | |
375 | flag is specified, | |
376 | .Nm ls | |
377 | follows all symbolic links, | |
378 | regardless of their type, | |
379 | whether specified on the command line or encountered in the tree walk. | |
a7c15f88 | 380 | The |
a4a7cf28 KB |
381 | .Nm ls |
382 | command does not support the | |
a7c15f88 KB |
383 | .Fl H |
384 | or | |
a4a7cf28 | 385 | .Fl P |
a7c15f88 KB |
386 | options. |
387 | .Sh SEE ALSO | |
388 | .Xr chflags 1 , | |
389 | .Xr chgrp 1 , | |
390 | .Xr chmod 1 , | |
391 | .Xr cp 1 , | |
392 | .Xr du 1 , | |
393 | .Xr find 1 , | |
394 | .Xr ln 1 , | |
395 | .Xr ls 1 , | |
396 | .Xr mv 1 , | |
a4a7cf28 | 397 | .Xr pax 1 , |
a7c15f88 KB |
398 | .Xr rm 1 , |
399 | .Xr tar 1 , | |
400 | .Xr lstat 2 , | |
401 | .Xr readlink 2 , | |
402 | .Xr rename 2 , | |
403 | .Xr unlink 2 , | |
a4a7cf28 KB |
404 | .Xr fts 3 , |
405 | .Xr remove 3 , | |
a7c15f88 | 406 | .Xr chown 8 |