1LN(1P) POSIX Programmer's Manual LN(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 ln — link files
14
16 ln [−fs] [−L|−P] source_file target_file
17 ln [−fs] [−L|−P] source_file... target_dir
19
21 In the first synopsis form, the ln utility shall create a new directory
22 entry (link) at the destination path specified by the target_file oper‐
23 and. If the −s option is specified, a symbolic link shall be created
24 for the file specified by the source_file operand. This first synopsis
25 form shall be assumed when the final operand does not name an existing
26 directory; if more than two operands are specified and the final is not
27 an existing directory, an error shall result.
28 In the second synopsis form, the ln utility shall create a new direc‐
30 tory entry (link), or if the −s option is specified a symbolic link,
31 for each file specified by a source_file operand, at a destination path
32 in the existing directory named by target_dir.
33 If the last operand specifies an existing file of a type not specified
35 by the System Interfaces volume of POSIX.1‐2008, the behavior is imple‐
36 mentation-defined.
37 The corresponding destination path for each source_file shall be the
39 concatenation of the target directory pathname, a <slash> character if
40 the target directory pathname did not end in a <slash>, and the last
41 pathname component of the source_file. The second synopsis form shall
42 be assumed when the final operand names an existing directory.
43 For each source_file:
45 1. If the destination path exists and was created by a previous step,
47 it is unspecified whether ln shall write a diagnostic message to
48 standard error, do nothing more with the current source_file, and
49 go on to any remaining source_files; or will continue processing
50 the current source_file. If the destination path exists:
51 a. If the −f option is not specified, ln shall write a diagnostic
53 message to standard error, do nothing more with the current
54 source_file, and go on to any remaining source_files.
55 b. If destination names the same directory entry as the current
57 source_file ln shall write a diagnostic message to standard
58 error, do nothing more with the current source_file, and go on
59 to any remaining source_files.
60 c. Actions shall be performed equivalent to the unlink() function
62 defined in the System Interfaces volume of POSIX.1‐2008, called
63 using destination as the path argument. If this fails for any
64 reason, ln shall write a diagnostic message to standard error,
65 do nothing more with the current source_file, and go on to any
66 remaining source_files.
67 2. If the −s option is specified, actions shall be performed equiva‐
69 lent to the symlink() function with source_file as the path1 argu‐
70 ment and the destination path as the path2 argument. The ln utility
71 shall do nothing more with source_file and shall go on to any
72 remaining files.
73 3. If source_file is a symbolic link:
75 a. If the −P option is in effect, actions shall be performed
77 equivalent to the linkat() function with source_file as the
78 path1 argument, the destination path as the path2 argument,
79 AT_FDCWD as the fd1 and fd2 arguments, and zero as the flag
80 argument.
81 b. If the −L option is in effect, actions shall be performed
83 equivalent to the linkat() function with source_file as the
84 path1 argument, the destination path as the path2 argument,
85 AT_FDCWD as the fd1 and fd2 arguments, and AT_SYMLINK_FOLLOW as
86 the flag argument.
87 The ln utility shall do nothing more with source_file and shall go
89 on to any remaining files.
90 4. Actions shall be performed equivalent to the link() function
92 defined in the System Interfaces volume of POSIX.1‐2008 using
93 source_file as the path1 argument, and the destination path as the
94 path2 argument.
95
97 The ln utility shall conform to the Base Definitions volume of
98 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
99 The following options shall be supported:
101 −f Force existing destination pathnames to be removed to allow
103 the link.
104 −L For each source_file operand that names a file of type sym‐
106 bolic link, create a (hard) link to the file referenced by
107 the symbolic link.
108 −P For each source_file operand that names a file of type sym‐
110 bolic link, create a (hard) link to the symbolic link itself.
111 −s Create symbolic links instead of hard links. If the −s option
113 is specified, the −L and −P options shall be silently
114 ignored.
115 Specifying more than one of the mutually-exclusive options −L and −P
117 shall not be considered an error. The last option specified shall
118 determine the behavior of the utility (unless the −s option causes it
119 to be ignored).
120 If the −s option is not specified and neither a −L nor a −P option is
122 specified, it is implementation-defined which of the −L and −P options
123 will be used as the default.
124
126 The following operands shall be supported:
127 source_file
129 A pathname of a file to be linked. If the −s option is speci‐
130 fied, no restrictions on the type of file or on its existence
131 shall be made. If the −s option is not specified, whether a
132 directory can be linked is implementation-defined.
133 target_file
135 The pathname of the new directory entry to be created.
136 target_dir
138 A pathname of an existing directory in which the new direc‐
139 tory entries are created.
140
142 Not used.
143
145 None.
146
148 The following environment variables shall affect the execution of ln:
149 LANG Provide a default value for the internationalization vari‐
151 ables that are unset or null. (See the Base Definitions vol‐
152 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
153 ables for the precedence of internationalization variables
154 used to determine the values of locale categories.)
155 LC_ALL If set to a non-empty string value, override the values of
157 all the other internationalization variables.
158 LC_CTYPE Determine the locale for the interpretation of sequences of
160 bytes of text data as characters (for example, single-byte as
161 opposed to multi-byte characters in arguments).
162 LC_MESSAGES
164 Determine the locale that should be used to affect the format
165 and contents of diagnostic messages written to standard
166 error.
167 NLSPATH Determine the location of message catalogs for the processing
169 of LC_MESSAGES.
170
172 Default.
173
175 Not used.
176
178 The standard error shall be used only for diagnostic messages.
179
181 None.
182
184 None.
185
187 The following exit values shall be returned:
188 0 All the specified files were linked successfully.
190 >0 An error occurred.
192
194 Default.
195 The following sections are informative.
197
199 None.
200
202 None.
203
205 The CONSEQUENCES OF ERRORS section does not require ln −f a b to remove
206 b if a subsequent link operation would fail.
207 Some historic versions of ln (including the one specified by the SVID)
209 unlink the destination file, if it exists, by default. If the mode does
210 not permit writing, these versions prompt for confirmation before
211 attempting the unlink. In these versions the −f option causes ln not to
212 attempt to prompt for confirmation.
213 This allows ln to succeed in creating links when the target file
215 already exists, even if the file itself is not writable (although the
216 directory must be). Early proposals specified this functionality.
217 This volume of POSIX.1‐2008 does not allow the ln utility to unlink
219 existing destination paths by default for the following reasons:
220 * The ln utility has historically been used to provide locking for
222 shell applications, a usage that is incompatible with ln unlinking
223 the destination path by default. There was no corresponding techni‐
224 cal advantage to adding this functionality.
225 * This functionality gave ln the ability to destroy the link struc‐
227 ture of files, which changes the historical behavior of ln.
228 * This functionality is easily replicated with a combination of rm
230 and ln.
231 * It is not historical practice in many systems; BSD and BSD-derived
233 systems do not support this behavior. Unfortunately, whichever
234 behavior is selected can cause scripts written expecting the other
235 behavior to fail.
236 * It is preferable that ln perform in the same manner as the link()
238 function, which does not permit the target to exist already.
239 This volume of POSIX.1‐2008 retains the −f option to provide support
241 for shell scripts depending on the SVID semantics. It seems likely that
242 shell scripts would not be written to handle prompting by ln and would
243 therefore have specified the −f option.
244 The −f option is an undocumented feature of many historical versions of
246 the ln utility, allowing linking to directories. These versions require
247 modification.
248 Early proposals of this volume of POSIX.1‐2008 also required a −i
250 option, which behaved like the −i options in cp and mv, prompting for
251 confirmation before unlinking existing files. This was not historical
252 practice for the ln utility and has been omitted.
253 The −L and −P options allow for implementing both common behaviors of
255 the ln utility. Earlier versions of this standard did not specify these
256 options and required the behavior now described for the −L option. Many
257 systems by default or as an alternative provided a non-conforming ln
258 utility with the behavior now described for the −P option. Since appli‐
259 cations could not rely on ln following links in practice, the −L and −P
260 options were added to specify the desired behavior for the application.
261 The −L and −P options are ignored when −s is specified in order to
263 allow an alias to be created to alter the default behavior when creat‐
264 ing hard links (for example, alias ln='ln −L'). They serve no purpose
265 when −s is specified, since source_file is then just a string to be
266 used as the contents of the created symbolic link and need not exist as
267 a file.
268 The specification ensures that ln a a with or without the −f option
270 will not unlink the file a. Earlier versions of this standard were
271 unclear in this case.
272
274 None.
275
277 chmod, find, pax, rm
278 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
280 Variables, Section 12.2, Utility Syntax Guidelines
281 The System Interfaces volume of POSIX.1‐2008, link(), unlink()
283
285 Portions of this text are reprinted and reproduced in electronic form
286 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
287 -- Portable Operating System Interface (POSIX), The Open Group Base
288 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
289 cal and Electronics Engineers, Inc and The Open Group. (This is
290 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
291 event of any discrepancy between this version and the original IEEE and
292 The Open Group Standard, the original IEEE and The Open Group Standard
293 is the referee document. The original Standard can be obtained online
294 at http://www.unix.org/online.html .
295 Any typographical or formatting errors that appear in this page are
297 most likely to have been introduced during the conversion of the source
298 files to man page format. To report such errors, see https://www.ker‐
299 nel.org/doc/man-pages/reporting_bugs.html .
300IEEE/The Open Group 2013 LN(1P)