| blob | 5b8531901e4397811477ec6a52e3dc6cada0cbcc |
1 .\" $NetBSD: symlink.7,v 1.16 2009/03/11 13:52:19 joerg Exp $
2 .\"
3 .\" Copyright (c) 1992, 1993, 1994
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)symlink.7 8.3 (Berkeley) 3/31/94
31 .\"
32 .Dd June 26, 2009
33 .Dt SYMLINK 7
34 .Os
35 .Sh NAME
36 .Nm symlink
37 .Nd symbolic link handling
38 .Sh DESCRIPTION
39 Symbolic links are files that act as pointers to other files.
40 To understand their behavior, you must first understand how hard links
41 work.
42 .Pp
43 A hard link to a file is indistinguishable from the original file because
44 it is a reference to the object underlying the original file name.
45 Changes to a file are independent of the name used to reference the
46 file.
47 Hard links may not refer to directories and may not reference files
48 on different file systems.
49 .Pp
50 A symbolic link contains the name of the file to which it is linked,
51 i.e.
52 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
54 file systems.
55 .Pp
56 Because a symbolic link and its referenced object coexist in the filesystem
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,
62 are outlined here.
63 It is important that local applications conform to these rules, too,
64 so that the user interface can be as consistent as possible.
65 .Pp
66 Symbolic links are handled either by operating on the link itself,
67 or by operating on the object referenced by the link.
68 In the latter case,
69 an application or system call is said to
70 .Qq follow
71 the link.
72 .Pp
73 Symbolic links may reference other symbolic links,
74 in which case the links are dereferenced until an object that is
75 not a symbolic link is found,
76 a symbolic link which references a file which doesn't exist is found,
77 or a loop is detected.
78 Loop detection is done by placing an upper limit on the number of
79 links that may be followed, and an error results if this limit is
80 exceeded.
81 .Pp
82 There are three separate areas that need to be discussed.
83 They are as follows:
84 .Pp
85 .Bl -enum -compact -offset indent
86 .It
87 Symbolic links used as file name arguments for system calls.
88 .It
89 Symbolic links specified as command line arguments to utilities that
90 are not traversing a file tree.
91 .It
92 Symbolic links encountered by utilities that are traversing a file tree
93 (either specified on the command line or encountered as part of the
94 file hierarchy walk).
95 .El
96 .Ss System calls
97 The first area is symbolic links used as file name arguments for
98 system calls.
99 .Pp
100 Except as noted below, all system calls follow symbolic links.
101 For example, if there were a symbolic link
102 .Qq Li slink
103 which pointed to a file named
104 .Qq Li afile ,
105 the system call
106 .Qq Li open("slink" ...)
107 would return a file descriptor to the file
108 .Qq afile .
109 .Pp
110 There are eight system calls that do not follow links, and which operate
111 on the symbolic link itself.
112 They are:
113 .Xr lchflags 2 ,
114 .Xr lchmod 2 ,
115 .Xr lchown 2 ,
116 .Xr lstat 2 ,
117 .Xr lutimes 2 ,
118 .Xr readlink 2 ,
119 .Xr rename 2 ,
120 and
121 .Xr unlink 2 .
122 Because
123 .Xr remove 3
124 is an alias for
125 .Xr unlink 2 ,
126 it also does not follow symbolic links.
127 .Pp
128 The
129 .Bx 4.4
130 system differs from historical
131 .Bx 4
132 systems in that the system call
133 .Xr chown 2
134 has been changed to follow symbolic links.
135 .Pp
136 If the filesystem is mounted with the
137 .Em symperm
138 .Xr mount 8
139 option, the symbolic link file permission bits have the following effects:
140 .Pp
141 The
142 .Xr readlink 2
143 system call requires read permissions on the symbolic link.
144 .Pp
145 System calls that follow symbolic links will fail without execute/search
146 permissions on all the symbolic links followed.
147 .Pp
148 The write, sticky, set-user-ID-on-execution and set-group-ID-on-execution
149 symbolic link mode bits have no effect on any system calls
150 .Po
151 including
152 .Xr execve 2
153 .Pc .
154 .Ss Commands not traversing a file tree
155 The second area is symbolic links, specified as command line file
156 name arguments, to commands which are not traversing a file tree.
157 .Pp
158 Except as noted below, commands follow symbolic links named as command
159 line arguments.
160 For example, if there were a symbolic link
161 .Qq Li slink
162 which pointed to a file named
163 .Qq Li afile ,
164 the command
165 .Qq Li cat slink
166 would display the contents of the file
167 .Qq Li afile .
168 .Pp
169 It is important to realize that this rule includes commands which may
170 optionally traverse file trees, e.g.
171 the command
172 .Qq Li "chown file"
173 is included in this rule, while the command
174 .Qq Li "chown -R file"
175 is not
176 (The latter is described in the third area, below).
177 .Pp
178 If it is explicitly intended that the command operate on the symbolic
179 link instead of following the symbolic link, e.g., it is desired that
180 .Qq Li "file slink"
181 display the type of file that
182 .Qq Li slink
183 is, whether it is a symbolic link or not, the
184 .Fl h
185 option should be used.
186 In the above example,
187 .Qq Li "file slink"
188 would report the type of the file referenced by
189 .Qq Li slink ,
190 while
191 .Qq Li "file -h slink"
192 would report that
193 .Qq Li slink
194 was a symbolic link.
195 .Pp
196 There are three exceptions to this rule.
197 The
198 .Xr mv 1
199 and
200 .Xr rm 1
201 commands do not follow symbolic links named as arguments,
202 but respectively attempt to rename and delete them.
203 (Note, if the symbolic link references a file via a relative path,
204 moving it to another directory may very well cause it to stop working,
205 since the path may no longer be correct).
206 .Pp
207 The
208 .Xr ls 1
209 command is also an exception to this rule.
210 For compatibility with historic systems (when
211 .Nm ls
212 is not doing a tree walk, i.e.
213 the
214 .Fl R
215 option is not specified),
216 the
217 .Nm ls
218 command follows symbolic links named as arguments if the
219 .Fl L
220 option is specified,
221 or if the
222 .Fl F ,
223 .Fl d
224 or
225 .Fl l
226 options are not specified.
227 (If the
228 .Fl L
229 option is specified,
230 .Nm ls
231 always follows symbolic links.
232 .Nm ls
233 is the only command where the
234 .Fl L
235 option affects its behavior even though it is not doing a walk of
236 a file tree).
237 .Pp
238 The
239 .Bx 4.4
240 system differs from historical
241 .Bx 4
242 systems in that the
243 .Nm chown ,
244 .Nm chgrp
245 and
246 .Nm file
247 commands follow symbolic links specified on the command line.
248 .Ss Commands traversing a file tree
249 The following commands either optionally or always traverse file trees:
250 .Xr chflags 1 ,
251 .Xr chgrp 1 ,
252 .Xr chmod 1 ,
253 .Xr cp 1 ,
254 .Xr du 1 ,
255 .Xr find 1 ,
256 .Xr ls 1 ,
257 .Xr pax 1 ,
258 .Xr rm 1 ,
259 .Xr tar 1
260 and
261 .Xr chown 8 .
262 .Pp
263 It is important to realize that the following rules apply equally to
264 symbolic links encountered during the file tree traversal and symbolic
265 links listed as command line arguments.
266 .Pp
267 The first rule applies to symbolic links that reference files that are
268 not of type directory.
269 Operations that apply to symbolic links are performed on the links
270 themselves, but otherwise the links are ignored.
271 .Pp
272 For example, the command
273 .Qq Li "chown -R user slink directory"
274 will ignore
275 .Qq Li slink ,
276 because the
277 .Fl h
278 flag must be used to change owners of symbolic links.
279 Any symbolic links encountered during the tree traversal will also be
280 ignored.
281 The command
282 .Qq Li "rm -r slink directory"
283 will remove
284 .Qq Li slink ,
285 as well as any symbolic links encountered in the tree traversal of
286 .Qq Li directory ,
287 because symbolic links may be removed.
288 In no case will either
289 .Nm chown
290 or
291 .Nm rm
292 affect the file which
293 .Qq Li slink
294 references in any way.
295 .Pp
296 The second rule applies to symbolic links that reference files of type
297 directory.
298 Symbolic links which reference files of type directory are never
299 .Qq followed
300 by default.
301 This is often referred to as a
302 .Qq physical
303 walk, as opposed to a
304 .Qq logical
305 walk (where symbolic links referencing directories are followed).
306 .Pp
307 As consistently as possible, you can make commands doing a file tree
308 walk follow any symbolic links named on the command line, regardless
309 of the type of file they reference, by specifying the
310 .Fl H
311 (for
312 .Qq half\-logical )
313 flag.
314 This flag is intended to make the command line name space look
315 like the logical name space.
316 (Note, for commands that do not always do file tree traversals, the
317 .Fl H
318 flag will be ignored if the
319 .Fl R
320 flag is not also specified).
321 .Pp
322 For example, the command
323 .Qq Li "chown -HR user slink"
324 will traverse the file hierarchy rooted in the file pointed to by
325 .Qq Li slink .
326 Note, the
327 .Fl H
328 is not the same as the previously discussed
329 .Fl h
330 flag.
331 The
332 .Fl H
333 flag causes symbolic links specified on the command line to be
334 dereferenced both for the purposes of the action to be performed
335 and the tree walk, and it is as if the user had specified the
336 name of the file to which the symbolic link pointed.
337 .Pp
338 As consistently as possible, you can make commands doing a file tree
339 walk follow any symbolic links named on the command line, as well as
340 any symbolic links encountered during the traversal, regardless of
341 the type of file they reference, by specifying the
342 .Fl L
343 (for
344 .Qq logical )
345 flag.
346 This flag is intended to make the entire name space look like
347 the logical name space.
348 (Note, for commands that do not always do file tree traversals, the
349 .Fl L
350 flag will be ignored if the
351 .Fl R
352 flag is not also specified).
353 .Pp
354 For example, the command
355 .Qq Li "chown -LR user slink"
356 will change the owner of the file referenced by
357 .Qq Li slink .
358 If
359 .Qq Li slink
360 references a directory,
361 .Nm chown
362 will traverse the file hierarchy rooted in the directory that it
363 references.
364 In addition, if any symbolic links are encountered in any file tree that
365 .Nm chown
366 traverses, they will be treated in the same fashion as
367 .Qq Li slink .
368 .Pp
369 As consistently as possible, you can specify the default behavior by
370 specifying the
371 .Fl P
372 (for
373 .Qq physical )
374 flag.
375 This flag is intended to make the entire name space look like the
376 physical name space.
377 .Pp
378 For commands that do not by default do file tree traversals, the
379 .Fl H ,
380 .Fl L
381 and
382 .Fl P
383 flags are ignored if the
384 .Fl R
385 flag is not also specified.
386 In addition, you may specify the
387 .Fl H ,
388 .Fl L
389 and
390 .Fl P
391 options more than once; the last one specified determines the
392 command's behavior.
393 This is intended to permit you to alias commands to behave one way
394 or the other, and then override that behavior on the command line.
395 .Pp
396 The
397 .Xr ls 1
398 and
399 .Xr rm 1
400 commands have exceptions to these rules.
401 The
402 .Nm rm
403 command operates on the symbolic link, and not the file it references,
404 and therefore never follows a symbolic link.
405 The
406 .Nm rm
407 command does not support the
408 .Fl H ,
409 .Fl L
410 or
411 .Fl P
412 options.
413 .Pp
414 To maintain compatibility with historic systems,
415 the
416 .Nm ls
417 command never follows symbolic links unless the
418 .Fl L
419 flag is specified.
420 If the
421 .Fl L
422 flag is specified,
423 .Nm ls
424 follows all symbolic links,
425 regardless of their type,
426 whether specified on the command line or encountered in the tree walk.
427 The
428 .Nm ls
429 command does not support the
430 .Fl H
431 or
432 .Fl P
433 options.
434 .Sh MAGIC SYMLINKS
435 Magic symlinks can be enabled by setting
436 .Dq vfs.generic.magiclinks
437 with
438 .Xr sysctl 8 .
439 When magic symlinks are enabled
440 .Dq magic
441 patterns in symlinks are expanded.
442 Those patterns begin with
443 .Dq @
444 .Pq an at-sign ,
445 and end at the end of the pathname component
446 .Po
447 i.e. at the next
448 .Dq / ,
449 or at the end of the symbolic link if there are no more slashes
450 .Pc .
451 .Pp
452 To illustrate the pattern matching rules, assume that
453 .Dq @foo
454 is a valid magic string:
455 .Pp
456 .Bl -tag -width @foo/barxxxxx -offset indent -compact
457 .It @foo
458 would be matched
459 .It @foo/bar
460 would be matched
461 .It bar@foo
462 would be matched
463 .It @foobar
464 would not be matched
465 .El
466 .Pp
467 Magic strings may also be delimited with
468 .Sq {
469 and
470 .Sq }
471 characters, allowing for more complex patterns in symbolic links such as:
472 .Bd -literal -offset indent
473 @{var1}-@{var2}.@{var3}
474 .Ed
475 .Pp
476 The following patterns are supported:
477 .Bl -tag -width @machine_arch
478 .It @domainname
479 Expands to the machine's domain name, as set by
480 .Xr setdomainname 3 .
481 .It @hostname
482 Expands to the machine's host name, as set by
483 .Xr sethostname 3 .
484 .It @emul
485 Expands to the name of the current process's emulation.
486 .It @kernel_ident
487 Expands to the name of the
488 .Xr config 1
489 file used to generate the running kernel.
490 .It @machine
491 Expands to the value of
492 .Li MACHINE
493 for the system
494 .Po
495 equivalent to the output of
496 .Dq uname -m
497 .Pc .
498 .It @machine_arch
499 Expands to the value of
500 .Li MACHINE_ARCH
501 for the system
502 .Po
503 equivalent to the output of
504 .Dq uname -p
505 .Pc .
506 .It @osrelease
507 Expands to the operating system release of the running kernel
508 .Po
509 equivalent to the output of
510 .Dq uname -r
511 .Pc .
512 .It @ostype
513 Expands to the operating system type of the running kernel
514 .Po
515 equivalent to the output of
516 .Dq uname -s
517 .Pc .
518 This will always be
519 .Dq NetBSD
520 on
521 .Nx
522 systems.
523 .It @ruid
524 Expands to the real user-id of the process.
525 .It @uid
526 Expands to the effective user-id of the process.
527 .It @rgid
528 Expands to the real group-id of the process.
529 .It @gid
530 Expands to the effective group-id of the process.
531 .El
532 .Sh SEE ALSO
533 .Xr chflags 1 ,
534 .Xr chgrp 1 ,
535 .Xr chmod 1 ,
536 .Xr cp 1 ,
537 .Xr du 1 ,
538 .Xr find 1 ,
539 .Xr ln 1 ,
540 .Xr ls 1 ,
541 .Xr mv 1 ,
542 .Xr pax 1 ,
543 .Xr rm 1 ,
544 .Xr tar 1 ,
545 .Xr uname 1 ,
546 .Xr chown 2 ,
547 .Xr execve 2 ,
548 .Xr lchflags 2 ,
549 .Xr lchmod 2 ,
550 .Xr lchown 2 ,
551 .Xr lstat 2 ,
552 .Xr lutimes 2 ,
553 .Xr mount 2 ,
554 .Xr readlink 2 ,
555 .Xr rename 2 ,
556 .Xr symlink 2 ,
557 .Xr unlink 2 ,
558 .Xr fts 3 ,
559 .Xr remove 3 ,
560 .Xr chown 8 ,
561 .Xr mount 8
562 .Sh HISTORY
563 Magic symlinks appeared in
564 .Nx 4.0 .