1.\" Copyright (c) 1980, 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the Institute of Electrical and Electronics Engineers, Inc. 6.\" 7.\" %sccs.include.redist.roff% 8.\" 9.\" @(#)ln.1 6.11 (Berkeley) 06/02/92 10.\" 11.Dd 12.Dt LN 1 13.Os BSD 4 14.Sh NAME 15.Nm ln 16.Nd make links 17.Sh SYNOPSIS 18.Nm ln 19.Op Fl fs 20.Ar source_file 21.Op target_file 22.Nm ln 23.Op Fl fs 24.Ar source_file ... 25.Op target_dir 26.Sh DESCRIPTION 27The 28.Nm ln 29utility creates a new directory entry (linked file) which has the 30same modes as the orginal file. 31It is useful for maintaining multiple copies of a file in many places 32at once without using up storage for the 33.Dq copies ; 34instead, a link 35.Dq points 36to the original copy. 37There are two types of links; hard links and symbolic links. 38How a link 39.Dq points 40to a file is one of the differences between a hard or symbolic link. 41.Pp 42The options are as follows: 43.Bl -tag -width flag 44.It Fl f 45Unlink any already existing file, permitting the link to occur. 46.It Fl s 47Create a symbolic link. 48.El 49.Pp 50By default 51.Nm ln 52makes 53.Em hard 54links. 55A hard link to a file is indistinguishable from the original directory entry; 56any changes to a file are effective independent of the name used to reference 57the file. 58Hard links may not normally refer to directories and may not span file systems. 59.Pp 60A symbolic link contains the name of the file to 61which it is linked. The referenced file is used when an 62.Xr open 2 63operation is performed on the link. 64A 65.Xr stat 2 66on a symbolic link will return the linked-to file; an 67.Xr lstat 2 68must be done to obtain information about the link. 69The 70.Xr readlink 2 71call may be used to read the contents of a symbolic link. 72Symbolic links may span file systems and may refer to directories. 73.Pp 74Given one or two arguments, 75.Nm ln 76creates a link to an existing file 77.Ar source_file . 78If 79.Ar target_file 80is given, the link has that name; 81.Ar target_file 82may also be a directory in which to place the link; 83otherwise it is placed in the current directory. 84If only the directory is specified, the link will be made 85to the last component of 86.Ar source_file . 87.Pp 88Given more than two arguments, 89.Nm ln 90makes links in 91.Ar target_dir 92to all the named source files. 93The links made will have the same name as the files being linked to. 94.Sh SYMBOLIC LINK HANDLING 95There are two issues involved in symbolic link handling. 96The first issue is whether or not the utility or system call operates 97on the symbolic link itself or if it operates on the object to which 98the symbolic link refers. 99The following rules summarize the conventions of symbolic link handling 100in the system. 101Operating on the object referenced by the symbolic link or indirecting 102through symbolic links to directories is termed ``following'' the link. 103.Pp 104The system calls that do not follow symbolic links are 105.Xr lstat 2 , 106.Xr readlink 2 , 107.Xr rename 2 , 108and 109.Xr unlink 2 . 110All other system calls follow the symbolic link. 111.Pp 112The utilities that do not follow symbolic links are 113.Xr mv 1 114and 115.Xr rm 1 . 116For compatibility with historic systems, the 117.Xr ls 118utility follows symbolic links listed on the command line, unless the 119.Fl F , 120.Fl d 121or 122.Fl l 123options are specified. 124However, if the 125.Fl L 126option is specified, 127.Xr ls 128always follows symbolic links. 129All other utilities follow symbolic links. 130.Pp 131The second issue in symbolic link handling is traversal of a file hierarchy. 132There are two ways for file hierarchy oriented utilities to traverse a 133file hierarchy. 134The first is a physical traversal, where the utility does not indirect 135through symbolic links to directories. 136The second is a logical traversal, where the utility does indirect 137through symbolic links to directories. 138.Pp 139The utilities that work with file hierarchies, either optionally or by 140default, are 141.Xr chflags 1 , 142.Xr chgrp 1 , 143.Xr chmod 1 , 144.Xr chown 8 , 145.Xr cp 1 , 146.Xr du 1 , 147.Xr find 1 , 148.Xr ls 1 , 149.Xr rm 1 150and 151.Xr tar 1 . 152All of these utilities, except for 153.Xr cp , 154.Xr ls 155and 156.Xr rm , 157operate according to the following rules. 158.Pp 159By default, these utilities do a physical traversal, never following any 160symbolic links. 161If the 162.Fl H 163option is specified, the utility will follow symbolic links specified 164on the command line. 165If the 166.Fl h 167option is specified, the utilities do a logical traversal, following all 168symbolic links whether specified on the command line or encountered while 169descending the file hierarchy. 170The 171.Fl H 172flag is intended to make the command line name space look like the logical 173name space and the 174.Fl h 175flag is intended to make the entire hierarchy look like the logical name 176space. 177.Pp 178The utilities 179.Xr cp , 180.Xr ls 181and 182.Xr rm 183are exceptions to these rules. 184.Pp 185To maintain compatibility with historic systems, 186.Xr cp 187always follows symbolic links on the command line. 188The 189.Fl H 190and 191.Fl h 192options have the effects described above only when the 193.Fl R 194flag is specified. 195.Pp 196.Xr Rm 197operates on the name, not the object it points to, and therefore never 198follows a symbolic link. 199The 200.Xr rm 201utility does not support the 202.Fl H 203or 204.Fl h 205options. 206.Pp 207To maintain compatibility with historic systems, the 208.Xr ls 209utility follows all symbolic links in the file hierarchy, including ones 210listed on the command line, only when the 211.Fl L 212option is specified. 213The 214.Xr ls 215utility does not support the 216.Fl H 217or 218.Fl h 219options. 220.Sh SEE ALSO 221.Xr link 2 , 222.Xr lstat 2 , 223.Xr readlink 2 , 224.Xr stat 2 , 225.Xr symlink 2 226.Sh HISTORY 227A 228.Nm ln 229command appeared in 230.At v6 . 231