Commit | Line | Data |
---|---|---|
8957cdb5 | 1 | .\"- |
984263bc MD |
2 | .\" Copyright (c) 1980, 1990, 1993 |
3 | .\" The Regents of the University of California. All rights reserved. | |
4 | .\" | |
5 | .\" This code is derived from software contributed to Berkeley by | |
6 | .\" the Institute of Electrical and Electronics Engineers, Inc. | |
7 | .\" | |
8 | .\" Redistribution and use in source and binary forms, with or without | |
9 | .\" modification, are permitted provided that the following conditions | |
10 | .\" are met: | |
11 | .\" 1. Redistributions of source code must retain the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer. | |
13 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
14 | .\" notice, this list of conditions and the following disclaimer in the | |
15 | .\" documentation and/or other materials provided with the distribution. | |
dc71b7ab | 16 | .\" 3. Neither the name of the University nor the names of its contributors |
984263bc MD |
17 | .\" may be used to endorse or promote products derived from this software |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)ln.1 8.2 (Berkeley) 12/30/93 | |
8957cdb5 | 33 | .\" $FreeBSD: head/bin/ln/ln.1 244791 2012-12-28 22:06:33Z gjb $ |
984263bc | 34 | .\" |
8957cdb5 | 35 | .Dd March 23, 2015 |
984263bc MD |
36 | .Dt LN 1 |
37 | .Os | |
38 | .Sh NAME | |
39 | .Nm ln , | |
40 | .Nm link | |
8957cdb5 | 41 | .Nd link files |
984263bc MD |
42 | .Sh SYNOPSIS |
43 | .Nm | |
8957cdb5 SW |
44 | .Op Fl L | Fl P | Fl s Op Fl F |
45 | .Op Fl f | iw | |
46 | .Op Fl hnv | |
984263bc MD |
47 | .Ar source_file |
48 | .Op Ar target_file | |
49 | .Nm | |
8957cdb5 SW |
50 | .Op Fl L | Fl P | Fl s Op Fl F |
51 | .Op Fl f | iw | |
52 | .Op Fl hnv | |
984263bc MD |
53 | .Ar source_file ... |
54 | .Ar target_dir | |
55 | .Nm link | |
56 | .Ar source_file Ar target_file | |
57 | .Sh DESCRIPTION | |
58 | The | |
59 | .Nm | |
8957cdb5 SW |
60 | utility creates a new directory entry (linked file) for the file name |
61 | specified by | |
62 | .Ar target_file . | |
63 | The | |
64 | .Ar target_file | |
65 | will be created with the same file modes as the | |
66 | .Ar source_file . | |
984263bc MD |
67 | It is useful for maintaining multiple copies of a file in many places |
68 | at once without using up storage for the | |
69 | .Dq copies ; | |
70 | instead, a link | |
71 | .Dq points | |
72 | to the original copy. | |
73 | There are two types of links; hard links and symbolic links. | |
74 | How a link | |
75 | .Dq points | |
76 | to a file is one of the differences between a hard and symbolic link. | |
77 | .Pp | |
78 | The options are as follows: | |
79 | .Bl -tag -width flag | |
8957cdb5 SW |
80 | .It Fl F |
81 | If the target file already exists and is a directory, then remove it | |
82 | so that the link may occur. | |
83 | The | |
84 | .Fl F | |
85 | option should be used with either | |
86 | .Fl f | |
87 | or | |
88 | .Fl i | |
89 | options. | |
90 | If none is specified, | |
91 | .Fl f | |
92 | is implied. | |
93 | The | |
94 | .Fl F | |
95 | option is a no-op unless | |
96 | .Fl s | |
97 | option is specified. | |
98 | .It Fl L | |
99 | When creating a hard link to a symbolic link, | |
100 | create a hard link to the target of the symbolic link. | |
101 | This is the default. | |
102 | This option cancels the | |
103 | .Fl P | |
104 | option. | |
105 | .It Fl P | |
106 | When creating a hard link to a symbolic link, | |
107 | create a hard link to the symbolic link itself. | |
108 | This option cancels the | |
109 | .Fl L | |
110 | option. | |
984263bc MD |
111 | .It Fl f |
112 | If the target file already exists, | |
113 | then unlink it so that the link may occur. | |
114 | (The | |
115 | .Fl f | |
116 | option overrides any previous | |
117 | .Fl i | |
8957cdb5 SW |
118 | and |
119 | .Fl w | |
984263bc MD |
120 | options.) |
121 | .It Fl h | |
122 | If the | |
123 | .Ar target_file | |
124 | or | |
125 | .Ar target_dir | |
92b221f0 TN |
126 | is a symbolic link, do not follow it. |
127 | This is most useful with the | |
984263bc MD |
128 | .Fl f |
129 | option, to replace a symlink which may point to a directory. | |
130 | .It Fl i | |
131 | Cause | |
132 | .Nm | |
133 | to write a prompt to standard error if the target file exists. | |
134 | If the response from the standard input begins with the character | |
135 | .Sq Li y | |
136 | or | |
137 | .Sq Li Y , | |
138 | then unlink the target file so that the link may occur. | |
139 | Otherwise, do not attempt the link. | |
140 | (The | |
141 | .Fl i | |
142 | option overrides any previous | |
143 | .Fl f | |
144 | options.) | |
145 | .It Fl n | |
146 | Same as | |
147 | .Fl h , | |
148 | for compatibility with other | |
149 | .Nm | |
150 | implementations. | |
151 | .It Fl s | |
152 | Create a symbolic link. | |
153 | .It Fl v | |
154 | Cause | |
155 | .Nm | |
156 | to be verbose, showing files as they are processed. | |
8957cdb5 SW |
157 | .It Fl w |
158 | Warn if the source of a symbolic link does not currently exist. | |
984263bc MD |
159 | .El |
160 | .Pp | |
161 | By default, | |
162 | .Nm | |
163 | makes | |
164 | .Em hard | |
165 | links. | |
166 | A hard link to a file is indistinguishable from the original directory entry; | |
167 | any changes to a file are effectively independent of the name used to reference | |
168 | the file. | |
8957cdb5 | 169 | Directories may not be hardlinked, and hard links may not span file systems. |
984263bc | 170 | .Pp |
8957cdb5 SW |
171 | A symbolic link contains the name of the file to |
172 | which it is linked. | |
92b221f0 | 173 | The referenced file is used when an |
8957cdb5 | 174 | .Xr open 2 |
984263bc MD |
175 | operation is performed on the link. |
176 | A | |
8957cdb5 | 177 | .Xr stat 2 |
984263bc | 178 | on a symbolic link will return the linked-to file; an |
8957cdb5 | 179 | .Xr lstat 2 |
984263bc MD |
180 | must be done to obtain information about the link. |
181 | The | |
8957cdb5 | 182 | .Xr readlink 2 |
984263bc MD |
183 | call may be used to read the contents of a symbolic link. |
184 | Symbolic links may span file systems and may refer to directories. | |
185 | .Pp | |
186 | Given one or two arguments, | |
187 | .Nm | |
188 | creates a link to an existing file | |
8957cdb5 | 189 | .Ar source_file . |
984263bc MD |
190 | If |
191 | .Ar target_file | |
192 | is given, the link has that name; | |
193 | .Ar target_file | |
194 | may also be a directory in which to place the link; | |
195 | otherwise it is placed in the current directory. | |
196 | If only the directory is specified, the link will be made | |
197 | to the last component of | |
8957cdb5 | 198 | .Ar source_file . |
984263bc MD |
199 | .Pp |
200 | Given more than two arguments, | |
201 | .Nm | |
202 | makes links in | |
203 | .Ar target_dir | |
204 | to all the named source files. | |
205 | The links made will have the same name as the files being linked to. | |
206 | .Pp | |
207 | When the utility is called as | |
208 | .Nm link , | |
209 | exactly two arguments must be supplied, | |
210 | neither of which may specify a directory. | |
211 | No options may be supplied in this simple mode of operation, | |
212 | which performs a | |
213 | .Xr link 2 | |
214 | operation using the two passed arguments. | |
921dc27c | 215 | .Sh VARIANT SYMLINKS |
a3220ac5 SW |
216 | .Dx |
217 | supports a special kind of dynamic | |
921dc27c MD |
218 | symbolic link called a |
219 | .Em variant symlink . | |
220 | The | |
221 | .Ar source_file | |
92b221f0 TN |
222 | of a variant symlink may contain one or more variable names. |
223 | Each of these variable names is enclosed in braces and preceded by a | |
921dc27c MD |
224 | dollar sign in the style of variable references in |
225 | .Xr sh 1 | |
226 | and | |
227 | .Xr csh 1 . | |
8680c47c | 228 | .Pp |
92b221f0 | 229 | Whenever a variant symlink is followed, each variable found in |
921dc27c MD |
230 | .Ar source_file |
231 | is replaced by its associated value. | |
232 | In this manner, a variant symlink may resolve to different | |
92b221f0 TN |
233 | paths based on context. |
234 | The facility supports per-process, per-user, and system-wide varsyms. | |
921dc27c MD |
235 | .Pp |
236 | Varsym variables can be set with the | |
237 | .Xr varsym 1 | |
92b221f0 TN |
238 | utility. |
239 | Regular | |
921dc27c | 240 | .Xr environ 7 |
92b221f0 | 241 | environment variables are not used to resolve variant symlinks. |
bd7417df | 242 | .Sh EXAMPLES |
8957cdb5 SW |
243 | Create a symbolic link named |
244 | .Pa /home/src | |
245 | and point it to | |
246 | .Pa /usr/src : | |
247 | .Pp | |
248 | .Dl # ln -s /usr/src /home/src | |
249 | .Pp | |
250 | Hard link | |
251 | .Pa /usr/local/bin/fooprog | |
252 | to file | |
253 | .Pa /usr/local/bin/fooprog-1.0 : | |
254 | .Pp | |
255 | .Dl # ln /usr/local/bin/fooprog-1.0 /usr/local/bin/fooprog | |
256 | .Pp | |
257 | As an exercise, try the following commands: | |
258 | .Bd -literal -offset indent | |
259 | # ls -i /bin/[ | |
260 | 11553 /bin/[ | |
261 | # ls -i /bin/test | |
262 | 11553 /bin/test | |
263 | .Ed | |
264 | .Pp | |
265 | Note that both files have the same inode; that is, | |
266 | .Pa /bin/[ | |
267 | is essentially an alias for the | |
268 | .Xr test 1 | |
269 | command. | |
270 | This hard link exists so | |
271 | .Xr test 1 | |
272 | may be invoked from shell scripts, for example, using the | |
273 | .Li "if [ ]" | |
274 | construct. | |
275 | .Pp | |
276 | In the next example, the second call to | |
277 | .Nm | |
278 | removes the original | |
279 | .Pa foo | |
280 | and creates a replacement pointing to | |
281 | .Pa baz : | |
282 | .Bd -literal -offset indent | |
283 | # mkdir bar baz | |
284 | # ln -s bar foo | |
285 | # ln -shf baz foo | |
286 | .Ed | |
287 | .Pp | |
288 | Without the | |
289 | .Fl h | |
290 | option, this would instead leave | |
291 | .Pa foo | |
292 | pointing to | |
293 | .Pa bar | |
294 | and inside | |
295 | .Pa foo | |
296 | create a new symlink | |
297 | .Pa baz | |
298 | pointing to itself. | |
299 | This results from directory-walking. | |
300 | .Pp | |
301 | An easy rule to remember is that the argument order for | |
302 | .Nm | |
303 | is the same as for | |
304 | .Xr cp 1 : | |
305 | The first argument needs to exist, the second one is created. | |
306 | .Pp | |
307 | A simple variable symlink example: | |
921dc27c | 308 | .Bd -literal -offset indent |
92b221f0 | 309 | sysctl vfs.varsym_enable=1 |
921dc27c MD |
310 | |
311 | ln -s 'a${fubar}b' test | |
312 | ||
313 | echo 'Hello' > axxb | |
314 | echo 'Goodbye' > ayyb | |
315 | ||
316 | varsym fubar=xx; cat test | |
317 | varsym fubar=yy; cat test | |
318 | .Ed | |
984263bc MD |
319 | .Sh COMPATIBILITY |
320 | The | |
321 | .Fl h , | |
322 | .Fl i , | |
8957cdb5 | 323 | .Fl n , |
984263bc | 324 | .Fl v |
8957cdb5 SW |
325 | and |
326 | .Fl w | |
984263bc MD |
327 | options are non-standard and their use in scripts is not recommended. |
328 | They are provided solely for compatibility with other | |
329 | .Nm | |
330 | implementations. | |
921dc27c | 331 | .Pp |
a3220ac5 SW |
332 | Variant symlinks are unique (among BSDs) to |
333 | .Dx . | |
8957cdb5 SW |
334 | .Pp |
335 | The | |
336 | .Fl F | |
337 | option is a | |
338 | .Fx | |
339 | extension and should not be used in portable scripts. | |
d600454b | 340 | .Sh SEE ALSO |
375d1659 | 341 | .Xr varsym 1 , |
d600454b SW |
342 | .Xr link 2 , |
343 | .Xr lstat 2 , | |
344 | .Xr readlink 2 , | |
345 | .Xr stat 2 , | |
346 | .Xr symlink 2 , | |
375d1659 | 347 | .Xr symlink 7 |
984263bc MD |
348 | .Sh STANDARDS |
349 | The | |
350 | .Nm | |
351 | utility conforms to | |
352 | .St -p1003.2-92 . | |
353 | .Pp | |
354 | The simplified | |
355 | .Nm link | |
356 | command conforms to | |
357 | .St -susv2 . | |
358 | .Sh HISTORY | |
359 | An | |
360 | .Nm | |
361 | command appeared in | |
362 | .At v1 . |