| blob | 147e9d32d3322e89e3399570b14571bde994ce09 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
46 .\"
47 .TH LN 1 "Oct 25, 2017"
48 .SH NAME
49 ln \- make hard or symbolic links to files
50 .SH SYNOPSIS
51 .LP
52 .nf
53 \fB/usr/bin/ln\fR [\fB-fs\fR] \fIsource_file\fR [\fItarget\fR]
54 .fi
56 .LP
57 .nf
58 \fB/usr/bin/ln\fR [\fB-fs\fR] \fIsource_file\fR... \fItarget\fR
59 .fi
61 .SH DESCRIPTION
62 .sp
63 .LP
64 In the first synopsis form, the \fBln\fR utility creates a new directory entry
65 (link) for the file specified by \fIsource_file\fR, at the destination path
66 specified by \fItarget\fR. If \fItarget\fR is not specified, the link is made
67 in the current directory. This first synopsis form is assumed when the final
68 operand does not name an existing directory; if more than two operands are
69 specified and the final is not an existing directory, an error will result.
70 .sp
71 .LP
72 In the second synopsis form, the \fBln\fR utility creates a new directory entry
73 for each file specified by a \fIsource_file\fR operand, at a destination path
74 in the existing directory named by \fItarget\fR.
75 .sp
76 .LP
77 The \fBln\fR utility may be used to create both hard links and symbolic links.
78 A hard link is a pointer to a file and is indistinguishable from the original
79 directory entry. Any changes to a file are effective independent of the name
80 used to reference the file. Hard links may not span file systems and may not
81 refer to directories.
82 .sp
83 .LP
84 \fBln\fR by default creates hard links. \fIsource_file\fR is linked to
85 \fItarget\fR. If \fItarget\fR is a directory, another file named
86 \fIsource_file\fR is created in \fItarget\fR and linked to the original
87 \fIsource_file\fR.
88 .sp
89 .LP
90 If \fItarget\fR is an existing file and the \fB-f\fR option is not specified,
91 \fBln\fR will write a diagnostic message to standard error, do nothing more
92 with the current \fIsource_file\fR, and go on to any remaining
93 \fIsource_file\fRs.
94 .sp
95 .LP
96 A symbolic link is an indirect pointer to a file; its directory entry contains
97 the name of the file to which it is linked. Symbolic links may span file
98 systems and may refer to directories.
99 .sp
100 .LP
101 File permissions for \fItarget\fR may be different from those displayed with an
102 \fB-l\fR listing of the \fBls\fR(1) command. To display the permissions of
103 \fItarget\fR, use \fBls\fR \fB-lL\fR. See \fBstat\fR(2) for more information.
104 .sp
105 .LP
106 When creating a hard link, and the source file is itself a symbolic link, the
107 target will be a hard link to the file referenced by the symbolic link, not to
108 the symbolic link object itself (\fIsource_file\fR).
109 .SH OPTIONS
110 .sp
111 .LP
112 The following options are supported:
113 .sp
114 .ne 2
115 .na
116 \fB\fB-f\fR\fR
117 .ad
118 .RS 6n
119 Links files without questioning the user, even if the mode of \fItarget\fR
120 forbids writing. This is the default if the standard input is not a terminal.
121 .RE
123 .sp
124 .ne 2
125 .na
126 \fB\fB-s\fR\fR
127 .ad
128 .RS 6n
129 Creates a symbolic link.
130 .sp
131 If the \fB-s\fR option is used with two arguments, \fItarget\fR may be an
132 existing directory or a non-existent file. If \fItarget\fR already exists and
133 is not a directory, an error is returned. \fIsource_file\fR may be any path
134 name and need not exist. If it exists, it may be a file or directory and may
135 reside on a different file system from \fItarget\fR. If \fItarget\fR is an
136 existing directory, a file is created in directory \fItarget\fR whose name is
137 \fIsource_file\fR or the last component of \fIsource_file\fR. This file is a
138 symbolic link that references \fIsource_file\fR. If \fItarget\fR does not
139 exist, a file with name \fItarget\fR is created and it is a symbolic link that
140 references \fIsource_file\fR.
141 .sp
142 If the \fB-s\fR option is used with more than two arguments, \fItarget\fR must
143 be an existing directory or an error will be returned. For each
144 \fIsource_file\fR, a link is created in \fItarget\fR whose name is the last
145 component of \fIsource_file\fR. Each new \fIsource_file\fR is a symbolic link
146 to the original \fIsource_file\fR. The files and \fItarget\fR may reside on
147 different file systems.
148 .RE
150 .SS "/usr/bin/ln"
151 .sp
152 .LP
153 The following option is supported for \fB/usr/bin/ln\fR only:
154 .sp
155 .ne 2
156 .na
157 \fB\fB-n\fR\fR
158 .ad
159 .RS 6n
160 If \fItarget\fR is an existing file, writes a diagnostic message to stderr and
161 goes on to any remaining \fIsource_file\fRs. The \fB-f\fR option overrides this
162 option. This is the default behavior and is silently ignored.
163 .RE
165 .SH OPERANDS
166 .sp
167 .LP
168 The following operands are supported:
169 .sp
170 .ne 2
171 .na
172 \fB\fIsource_file\fR\fR
173 .ad
174 .RS 15n
175 A path name of a file to be linked. This can be either a regular or special
176 file. If the \fB-s\fR option is specified, \fIsource_file\fR can also be a
177 directory.
178 .RE
180 .sp
181 .ne 2
182 .na
183 \fB\fItarget\fR\fR
184 .ad
185 .RS 15n
186 The path name of the new directory entry to be created, or of an existing
187 directory in which the new directory entries are to be created.
188 .RE
190 .SH ENVIRONMENT VARIABLES
191 .sp
192 .LP
193 See \fBenviron\fR(5) for descriptions of the following environment variables
194 that affect the execution of \fBln\fR: \fBLANG\fR, \fBLC_ALL\fR,
195 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
196 .SH EXIT STATUS
197 .sp
198 .LP
199 The following exit values are returned:
200 .sp
201 .ne 2
202 .na
203 \fB\fB0\fR\fR
204 .ad
205 .RS 6n
206 All the specified files were linked successfully
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fB>0\fR\fR
213 .ad
214 .RS 6n
215 An error occurred.
216 .RE
218 .SH ATTRIBUTES
219 .sp
220 .LP
221 See \fBattributes\fR(5) for descriptions of the following attributes:
222 .SS "/usr/bin/ln"
223 .sp
225 .sp
226 .TS
227 box;
228 c | c
229 l | l .
230 ATTRIBUTE TYPE ATTRIBUTE VALUE
231 _
232 CSI Enabled
233 _
234 Interface Stability Standard
235 .TE
237 .SH SEE ALSO
238 .sp
239 .LP
240 \fBchmod\fR(1), \fBls\fR(1), \fBstat\fR(2), \fBattributes\fR(5),
241 \fBenviron\fR(5), \fBstandards\fR(5)
242 .SH NOTES
243 .sp
244 .LP
245 A symbolic link to a directory behaves differently than you might expect in
246 certain cases. While an \fBls\fR(1) command on such a link displays the files
247 in the pointed-to directory, entering \fBls\fR \fB-l\fR displays information
248 about the link itself:
249 .sp
250 .in +2
251 .nf
252 example% \fBln -s dir link\fR
253 example% \fBls link\fR
254 file1 file2 file3 file4
255 example% \fBls -l link\fR
256 lrwxrwxrwx 1 user 7 Jan 11 23:27 link -> dir
257 .fi
258 .in -2
259 .sp
261 .sp
262 .LP
263 When you change to a directory (see \fBcd\fR(1)) through a symbolic link, using
264 \fB/usr/bin/sh\fR or \fB/usr/bin/csh\fR, you wind up in the pointed-to location
265 within the file system. This means that the parent of the new working directory
266 is not the parent of the symbolic link, but rather, the parent of the
267 pointed-to directory. This will also happen when using \fBcd\fR with the
268 \fB-P\fR option from \fB/usr/bin/ksh\fR or \fB/usr/bin/sh\fR. For
269 instance, in the following case, the final working directory is \fB/usr\fR and
270 not \fB/home/user/linktest\fR.
271 .sp
272 .in +2
273 .nf
274 example% \fBpwd\fR
275 /home/user/linktest
276 example% \fBln -s /usr/tmp symlink\fR
277 example% \fBcd symlink\fR
278 example% \fBcd .\|.\fR
279 example% \fBpwd\fR
280 /usr
281 .fi
282 .in -2
283 .sp
285 .sp
286 .LP
287 C shell users can avoid any resulting navigation problems by using the
288 \fBpushd\fR and \fBpopd\fR built-in commands instead of \fBcd\fR.