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.1 (Berkeley) 07/27/92 7.\" 8.Dd 9.Dt SYMLINK 7 10.Os BSD 4 11.Sh NAME 12.Nm symlink 13.Nd describe 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 atomic object is found. Cycles are avoided by 27placing an upper limit on the number of links that may be followed. 28An error results if this limit is exceeded. 29.Pp 30There are three domains for which symbolic link policy is established: 31system calls that take file name arguments, 32utilities that take file name arguments, and 33utilities that traverse file hierarchies. 34.Pp 35The system calls that do not follow symbolic links are 36.Xr lstat 2 , 37.Xr readlink 2 , 38.Xr rename 2 , 39and 40.Xr unlink 2 . 41All other system calls follow the symbolic link. 42.Pp 43The utilities that do not follow symbolic links are 44.Xr mv 1 45and 46.Xr rm 1 . 47For compatibility with historic systems, the 48.Xr ls 1 49utility follows symbolic links listed on the command line, unless the 50.Fl F , 51.Fl d 52or 53.Fl l 54options are specified. 55However, if the 56.Fl L 57option is specified, 58.Xr ls 1 59always follows symbolic links. 60All other utilities follow symbolic links. 61.Pp 62Another issue in symbolic link handling is traversal of a file hierarchy. 63File hierarchies can be traversed either ``logically'', by following 64symbolic links that point to directories, or ``physically'', by not 65following such links. 66.Pp 67The following utilities can perform traversals: 68.Xr chflags 1 , 69.Xr chgrp 1 , 70.Xr chmod 1 , 71.Xr chown 8 , 72.Xr cp 1 , 73.Xr du 1 , 74.Xr find 1 , 75.Xr ls 1 , 76.Xr rm 1 77and 78.Xr tar 1 . 79All of these utilities, except for 80.Xr cp , 81.Xr ls 82and 83.Xr rm , 84operate according to the following rules. 85.Pp 86By default, these utilities do a physical traversal, never following any 87symbolic links. 88If the 89.Fl H 90option is specified, the utility will follow symbolic links specified 91on the command line. 92If the 93.Fl h 94option is specified, the utilities do a logical traversal, following all 95symbolic links whether specified on the command line or encountered while 96descending the file hierarchy. 97The 98.Fl H 99flag is intended to make the command line name space look like the logical 100name space and the 101.Fl h 102flag is intended to make the entire hierarchy look like the logical name 103space. 104.Pp 105The utilities 106.Xr cp , 107.Xr ls 108and 109.Xr rm 110are exceptions to these rules. 111.Pp 112To maintain compatibility with historic systems, 113.Xr cp 114always follows symbolic links on the command line. 115The 116.Fl H 117and 118.Fl h 119options have the effects described above only when the 120.Fl R 121flag is specified. 122.Pp 123.Xr Rm 124operates on the name, not the object it points to, and therefore never 125follows a symbolic link. 126The 127.Xr rm 128utility does not support the 129.Fl H 130or 131.Fl h 132options. 133.Pp 134To maintain compatibility with historic systems, the 135.Xr ls 136utility follows all symbolic links in the file hierarchy, including ones 137listed on the command line, only when the 138.Fl L 139option is specified. 140The 141.Xr ls 142utility does not support the 143.Fl H 144or 145.Fl h 146options. 147.Sh SEE ALSO 148.Xr chflags 1 , 149.Xr chgrp 1 , 150.Xr chmod 1 , 151.Xr cp 1 , 152.Xr du 1 , 153.Xr find 1 , 154.Xr ln 1 , 155.Xr ls 1 , 156.Xr mv 1 , 157.Xr rm 1 , 158.Xr tar 1 , 159.Xr lstat 2 , 160.Xr readlink 2 , 161.Xr rename 2 , 162.Xr unlink 2 , 163.Xr chown 8 164