Annotation of src/share/man/man7/symlink.7, Revision 1.21
1.21 ! jruoho 1: .\" $NetBSD: symlink.7,v 1.20 2011/04/26 16:57:39 joerg Exp $
1.1 jdolecek 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.
1.6 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 jdolecek 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: .\"
1.21 ! jruoho 32: .Dd June 2, 2011
1.1 jdolecek 33: .Dt SYMLINK 7
34: .Os
35: .Sh NAME
36: .Nm symlink
37: .Nd symbolic link handling
1.4 wiz 38: .Sh DESCRIPTION
1.1 jdolecek 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:
1.16 joerg 84: .Pp
1.1 jdolecek 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
1.3 wiz 96: .Ss System calls
1.1 jdolecek 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
1.5 bjh21 110: There are eight system calls that do not follow links, and which operate
1.1 jdolecek 111: on the symbolic link itself.
112: They are:
1.5 bjh21 113: .Xr lchflags 2 ,
1.1 jdolecek 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
1.2 wiz 130: system differs from historical
1.1 jdolecek 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 .
1.3 wiz 154: .Ss Commands not traversing a file tree
1.1 jdolecek 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.
1.2 wiz 160: For example, if there were a symbolic link
1.1 jdolecek 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.
1.3 wiz 248: .Ss Commands traversing a file tree
1.1 jdolecek 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
1.2 wiz 310: .Fl H
1.1 jdolecek 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.
1.21 ! jruoho 434: .Ss Magic symlinks
! 435: So-called
! 436: .Dq magic symlinks
! 437: can be enabled by setting the
1.13 mjf 438: .Dq vfs.generic.magiclinks
1.21 ! jruoho 439: variable with
1.13 mjf 440: .Xr sysctl 8 .
441: When magic symlinks are enabled
1.7 thorpej 442: .Dq magic
1.13 mjf 443: patterns in symlinks are expanded.
1.7 thorpej 444: Those patterns begin with
445: .Dq @
446: .Pq an at-sign ,
447: and end at the end of the pathname component
448: .Po
449: i.e. at the next
450: .Dq / ,
451: or at the end of the symbolic link if there are no more slashes
452: .Pc .
453: .Pp
454: To illustrate the pattern matching rules, assume that
455: .Dq @foo
456: is a valid magic string:
457: .Pp
458: .Bl -tag -width @foo/barxxxxx -offset indent -compact
459: .It @foo
460: would be matched
461: .It @foo/bar
462: would be matched
463: .It bar@foo
464: would be matched
465: .It @foobar
466: would not be matched
467: .El
468: .Pp
1.9 thorpej 469: Magic strings may also be delimited with
470: .Sq {
471: and
472: .Sq }
473: characters, allowing for more complex patterns in symbolic links such as:
474: .Bd -literal -offset indent
475: @{var1}-@{var2}.@{var3}
476: .Ed
477: .Pp
1.7 thorpej 478: The following patterns are supported:
1.21 ! jruoho 479: .Bl -tag -width @machine_arch -offset indent
1.7 thorpej 480: .It @domainname
481: Expands to the machine's domain name, as set by
482: .Xr setdomainname 3 .
483: .It @hostname
484: Expands to the machine's host name, as set by
485: .Xr sethostname 3 .
1.9 thorpej 486: .It @emul
487: Expands to the name of the current process's emulation.
1.18 christos 488: Defaults to
489: .Dv netbsd .
490: Other valid emulations are:
491: .Dv aout ,
492: .Dv aoutm68k ,
493: .Dv darwin ,
494: .Dv freebsd ,
495: .Dv ibcs2 ,
496: .Dv linux ,
497: .Dv linux32 ,
498: .Dv m68k4k ,
499: .Dv netbsd32 ,
500: .Dv osf1 ,
501: .Dv sunos ,
502: .Dv sunos32 ,
503: .Dv svr4 ,
504: .Dv svr4_32 ,
505: .Dv ultrix ,
506: .Dv vax1k .
1.7 thorpej 507: .It @kernel_ident
508: Expands to the name of the
509: .Xr config 1
510: file used to generate the running kernel.
1.18 christos 511: For example
512: .Dv GENERIC .
1.7 thorpej 513: .It @machine
514: Expands to the value of
515: .Li MACHINE
516: for the system
517: .Po
518: equivalent to the output of
519: .Dq uname -m
1.19 christos 520: or
521: .Xr sysctl 3
522: .Dq hw.machine
1.7 thorpej 523: .Pc .
524: .It @machine_arch
525: Expands to the value of
526: .Li MACHINE_ARCH
527: for the system
528: .Po
529: equivalent to the output of
530: .Dq uname -p
1.19 christos 531: or
532: .Xr sysctl 3
533: .Dq hw.machine_arch
1.7 thorpej 534: .Pc .
535: .It @osrelease
536: Expands to the operating system release of the running kernel
537: .Po
538: equivalent to the output of
539: .Dq uname -r
1.19 christos 540: or
541: .Xr sysctl 3
542: .Dq kern.osrelease
1.7 thorpej 543: .Pc .
544: .It @ostype
545: Expands to the operating system type of the running kernel
546: .Po
547: equivalent to the output of
548: .Dq uname -s
1.19 christos 549: or
550: .Xr sysctl 3
551: .Dq kern.ostype
1.7 thorpej 552: .Pc .
553: This will always be
554: .Dq NetBSD
555: on
556: .Nx
557: systems.
1.13 mjf 558: .It @ruid
1.14 reed 559: Expands to the real user-id of the process.
1.10 elad 560: .It @uid
561: Expands to the effective user-id of the process.
1.17 christos 562: .It @rgid
563: Expands to the real group-id of the process.
564: .It @gid
565: Expands to the effective group-id of the process.
1.7 thorpej 566: .El
1.1 jdolecek 567: .Sh SEE ALSO
568: .Xr chflags 1 ,
569: .Xr chgrp 1 ,
570: .Xr chmod 1 ,
571: .Xr cp 1 ,
572: .Xr du 1 ,
573: .Xr find 1 ,
574: .Xr ln 1 ,
575: .Xr ls 1 ,
576: .Xr mv 1 ,
577: .Xr pax 1 ,
578: .Xr rm 1 ,
579: .Xr tar 1 ,
1.8 wiz 580: .Xr uname 1 ,
1.1 jdolecek 581: .Xr chown 2 ,
582: .Xr execve 2 ,
1.5 bjh21 583: .Xr lchflags 2 ,
1.1 jdolecek 584: .Xr lchmod 2 ,
585: .Xr lchown 2 ,
586: .Xr lstat 2 ,
587: .Xr lutimes 2 ,
588: .Xr mount 2 ,
589: .Xr readlink 2 ,
590: .Xr rename 2 ,
591: .Xr symlink 2 ,
592: .Xr unlink 2 ,
593: .Xr fts 3 ,
594: .Xr remove 3 ,
595: .Xr chown 8 ,
1.3 wiz 596: .Xr mount 8
1.11 rillig 597: .Sh HISTORY
598: Magic symlinks appeared in
599: .Nx 4.0 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to symlink.7 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / share / man / man7