1.\" Copyright (c) 1992 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)symlink.7 5.2 (Berkeley) 04/17/93 7.\" 8.Dd 9.Dt SYMLINK 7 10.Os BSD 4 11.Sh NAME 12.Nm symlink 13.Nd symbolic link handling 14.Sh SYMBOLIC LINK HANDLING 15Due to the fact that a symbolic link and its referenced object coexist 16in the file system 17name space, confusion can arise in distinguishing between the link itself 18and the referenced object. Traditionally, utilities and system calls 19have adopted their own link following conventions in an ad-hoc fashion. 20Rules for more a uniform approach are outlined here. 21.Pp 22Symbolic links are handled either by operating on the link itself, or by 23operating on the object referenced by the link. In the latter case, 24an application or system call is said to ``follow'' the link. Symbolic 25links may reference other symbolic links, in which case links are 26dereferenced until an object which is not a symbolic link is found. 27Cycles are avoided by 28placing an upper limit on the number of links that may be followed. 29An error results if this limit is exceeded. 30.Pp 31There are three domains for which symbolic link policy is established: 32system calls that take file name arguments, 33utilities that take file name arguments, and 34utilities that traverse file hierarchies. 35.Pp 36The system calls that do not follow symbolic links are 37.Xr lstat 2 , 38.Xr readlink 2 , 39.Xr rename 2 , 40and 41.Xr unlink 2 . 42All other system calls follow the symbolic link. 43.Pp 44The utilities that do not follow symbolic links named as arguments 45are 46.Xr mv 1 47and 48.Xr rm 1 . 49For compatibility with historic systems, the 50.Xr ls 1 51utility follows symbolic links listed on the command line, unless the 52.Fl F , 53.Fl d 54or 55.Fl l 56options are specified. 57However, if the 58.Fl L 59option is specified, 60.Xr ls 1 61always follows symbolic links. 62All other utilities follow symbolic links listed on the command line. 63.Pp 64The third issue in symbolic link handling is traversal of a file 65hierarchy. 66File hierarchies can be traversed either ``logically'', by following 67symbolic links that point to directories, or ``physically'', by not 68following such links. 69.Pp 70The following utilities can perform traversals: 71.Xr chflags 1 , 72.Xr chgrp 1 , 73.Xr chmod 1 , 74.Xr chown 8 , 75.Xr cp 1 , 76.Xr du 1 , 77.Xr find 1 , 78.Xr ls 1 , 79.Xr rm 1 80and 81.Xr tar 1 . 82All of these utilities, except for 83.Xr cp , 84.Xr ls 85and 86.Xr rm , 87operate according to the following rules. 88.Pp 89By default, these utilities do a physical traversal, never following any 90symbolic links. 91If the 92.Fl H 93option is specified, the utility will follow symbolic links specified 94on the command line. 95If the 96.Fl h 97option is specified, the utilities do a logical traversal, following all 98symbolic links whether specified on the command line or encountered while 99descending the file hierarchy. 100The 101.Fl H 102flag is intended to make the command line name space look like the logical 103name space and the 104.Fl h 105flag is intended to make the entire hierarchy look like the logical name 106space. 107.Pp 108The utilities 109.Xr cp , 110.Xr ls 111and 112.Xr rm 113are exceptions to these rules. 114.Pp 115To maintain compatibility with historic systems, 116.Xr cp 117always follows symbolic links on the command line. 118The 119.Fl H 120and 121.Fl h 122options have the effects described above only when the 123.Fl R 124flag is specified. 125.Pp 126.Xr Rm 127operates on the name, not the object it points to, and therefore never 128follows a symbolic link. 129The 130.Xr rm 131utility does not support the 132.Fl H 133or 134.Fl h 135options. 136.Pp 137To maintain compatibility with historic systems, the 138.Xr ls 139utility follows all symbolic links in the file hierarchy, including ones 140listed on the command line, only when the 141.Fl L 142option is specified. 143The 144.Xr ls 145utility does not support the 146.Fl H 147or 148.Fl h 149options. 150.Sh SEE ALSO 151.Xr chflags 1 , 152.Xr chgrp 1 , 153.Xr chmod 1 , 154.Xr cp 1 , 155.Xr du 1 , 156.Xr find 1 , 157.Xr ln 1 , 158.Xr ls 1 , 159.Xr mv 1 , 160.Xr rm 1 , 161.Xr tar 1 , 162.Xr lstat 2 , 163.Xr readlink 2 , 164.Xr rename 2 , 165.Xr unlink 2 , 166.Xr chown 8 167