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