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
12 ln — link files
13
15 ln [-fs] [-L|-P] source_file target_file
16 ln [-fs] [-L|-P] source_file... target_dir
18
20 In the first synopsis form, the ln utility shall create a new directory
21 entry (link) at the destination path specified by the target_file oper‐
22 and. If the -s option is specified, a symbolic link shall be created
23 for the file specified by the source_file operand. This first synopsis
24 form shall be assumed when the final operand does not name an existing
25 directory; if more than two operands are specified and the final is not
26 an existing directory, an error shall result.
27 In the second synopsis form, the ln utility shall create a new direc‐
29 tory entry (link), or if the -s option is specified a symbolic link,
30 for each file specified by a source_file operand, at a destination path
31 in the existing directory named by target_dir.
32 If the last operand specifies an existing file of a type not specified
34 by the System Interfaces volume of POSIX.1‐2017, the behavior is imple‐
35 mentation-defined.
36 The corresponding destination path for each source_file shall be the
38 concatenation of the target directory pathname, a <slash> character if
39 the target directory pathname did not end in a <slash>, and the last
40 pathname component of the source_file. The second synopsis form shall
41 be assumed when the final operand names an existing directory.
42 For each source_file:
44 1. If the destination path exists and was created by a previous step,
46 it is unspecified whether ln shall write a diagnostic message to
47 standard error, do nothing more with the current source_file, and
48 go on to any remaining source_files; or will continue processing
49 the current source_file. If the destination path exists:
50 a. If the -f option is not specified, ln shall write a diagnostic
52 message to standard error, do nothing more with the current
53 source_file, and go on to any remaining source_files.
54 b. If the destination path names the same directory entry as the
56 current source_file ln shall write a diagnostic message to
57 standard error, do nothing more with the current source_file,
58 and go on to any remaining source_files.
59 c. Actions shall be performed equivalent to the unlink() function
61 defined in the System Interfaces volume of POSIX.1‐2017, called
62 using the destination path as the path argument. If this fails
63 for any reason, ln shall write a diagnostic message to standard
64 error, do nothing more with the current source_file, and go on
65 to any remaining source_files.
66 2. If the -s option is specified, actions shall be performed equiva‐
68 lent to the symlink() function with source_file as the path1 argu‐
69 ment and the destination path as the path2 argument. The ln utility
70 shall do nothing more with source_file and shall go on to any
71 remaining files.
72 3. If source_file is a symbolic link:
74 a. If the -P option is in effect, actions shall be performed
76 equivalent to the linkat() function with source_file as the
77 path1 argument, the destination path as the path2 argument,
78 AT_FDCWD as the fd1 and fd2 arguments, and zero as the flag
79 argument.
80 b. If the -L option is in effect, actions shall be performed
82 equivalent to the linkat() function with source_file as the
83 path1 argument, the destination path as the path2 argument,
84 AT_FDCWD as the fd1 and fd2 arguments, and AT_SYMLINK_FOLLOW as
85 the flag argument.
86 The ln utility shall do nothing more with source_file and shall go
88 on to any remaining files.
89 4. Actions shall be performed equivalent to the link() function
91 defined in the System Interfaces volume of POSIX.1‐2017 using
92 source_file as the path1 argument, and the destination path as the
93 path2 argument.
94
96 The ln utility shall conform to the Base Definitions volume of
97 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
98 The following options shall be supported:
100 -f Force existing destination pathnames to be removed to allow
102 the link.
103 -L For each source_file operand that names a file of type sym‐
105 bolic link, create a (hard) link to the file referenced by
106 the symbolic link.
107 -P For each source_file operand that names a file of type sym‐
109 bolic link, create a (hard) link to the symbolic link itself.
110 -s Create symbolic links instead of hard links. If the -s option
112 is specified, the -L and -P options shall be silently
113 ignored.
114 Specifying more than one of the mutually-exclusive options -L and -P
116 shall not be considered an error. The last option specified shall
117 determine the behavior of the utility (unless the -s option causes it
118 to be ignored).
119 If the -s option is not specified and neither a -L nor a -P option is
121 specified, it is implementation-defined which of the -L and -P options
122 will be used as the default.
123
125 The following operands shall be supported:
126 source_file
128 A pathname of a file to be linked. If the -s option is speci‐
129 fied, no restrictions on the type of file or on its existence
130 shall be made. If the -s option is not specified, whether a
131 directory can be linked is implementation-defined.
132 target_file
134 The pathname of the new directory entry to be created.
135 target_dir
137 A pathname of an existing directory in which the new direc‐
138 tory entries are created.
139
141 Not used.
142
144 None.
145
147 The following environment variables shall affect the execution of ln:
148 LANG Provide a default value for the internationalization vari‐
150 ables that are unset or null. (See the Base Definitions vol‐
151 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
152 ables for the precedence of internationalization variables
153 used to determine the values of locale categories.)
154 LC_ALL If set to a non-empty string value, override the values of
156 all the other internationalization variables.
157 LC_CTYPE Determine the locale for the interpretation of sequences of
159 bytes of text data as characters (for example, single-byte as
160 opposed to multi-byte characters in arguments).
161 LC_MESSAGES
163 Determine the locale that should be used to affect the format
164 and contents of diagnostic messages written to standard
165 error.
166 NLSPATH Determine the location of message catalogs for the processing
168 of LC_MESSAGES.
169
171 Default.
172
174 Not used.
175
177 The standard error shall be used only for diagnostic messages.
178
180 None.
181
183 None.
184
186 The following exit values shall be returned:
187 0 All the specified files were linked successfully.
189 >0 An error occurred.
191
193 Default.
194 The following sections are informative.
196
198 None.
199
201 None.
202
204 The CONSEQUENCES OF ERRORS section does not require ln -f a b to remove
205 b if a subsequent link operation would fail.
206 Some historic versions of ln (including the one specified by the SVID)
208 unlink the destination file, if it exists, by default. If the mode does
209 not permit writing, these versions prompt for confirmation before
210 attempting the unlink. In these versions the -f option causes ln not to
211 attempt to prompt for confirmation.
212 This allows ln to succeed in creating links when the target file
214 already exists, even if the file itself is not writable (although the
215 directory must be). Early proposals specified this functionality.
216 This volume of POSIX.1‐2017 does not allow the ln utility to unlink
218 existing destination paths by default for the following reasons:
219 * The ln utility has historically been used to provide locking for
221 shell applications, a usage that is incompatible with ln unlinking
222 the destination path by default. There was no corresponding techni‐
223 cal advantage to adding this functionality.
224 * This functionality gave ln the ability to destroy the link struc‐
226 ture of files, which changes the historical behavior of ln.
227 * This functionality is easily replicated with a combination of rm
229 and ln.
230 * It is not historical practice in many systems; BSD and BSD-derived
232 systems do not support this behavior. Unfortunately, whichever
233 behavior is selected can cause scripts written expecting the other
234 behavior to fail.
235 * It is preferable that ln perform in the same manner as the link()
237 function, which does not permit the target to exist already.
238 This volume of POSIX.1‐2017 retains the -f option to provide support
240 for shell scripts depending on the SVID semantics. It seems likely that
241 shell scripts would not be written to handle prompting by ln and would
242 therefore have specified the -f option.
243 The -f option is an undocumented feature of many historical versions of
245 the ln utility, allowing linking to directories. These versions require
246 modification.
247 Early proposals of this volume of POSIX.1‐2017 also required a -i
249 option, which behaved like the -i options in cp and mv, prompting for
250 confirmation before unlinking existing files. This was not historical
251 practice for the ln utility and has been omitted.
252 The -L and -P options allow for implementing both common behaviors of
254 the ln utility. Earlier versions of this standard did not specify these
255 options and required the behavior now described for the -L option. Many
256 systems by default or as an alternative provided a non-conforming ln
257 utility with the behavior now described for the -P option. Since appli‐
258 cations could not rely on ln following links in practice, the -L and -P
259 options were added to specify the desired behavior for the application.
260 The -L and -P options are ignored when -s is specified in order to
262 allow an alias to be created to alter the default behavior when creat‐
263 ing hard links (for example, alias ln='ln -L'). They serve no purpose
264 when -s is specified, since source_file is then just a string to be
265 used as the contents of the created symbolic link and need not exist as
266 a file.
267 The specification ensures that ln a a with or without the -f option
269 will not unlink the file a. Earlier versions of this standard were
270 unclear in this case.
271
273 None.
274
276 chmod, find, pax, rm
277 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
279 Variables, Section 12.2, Utility Syntax Guidelines
280 The System Interfaces volume of POSIX.1‐2017, link(), unlink()
282
284 Portions of this text are reprinted and reproduced in electronic form
285 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
286 table Operating System Interface (POSIX), The Open Group Base Specifi‐
287 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
288 Electrical and Electronics Engineers, Inc and The Open Group. In the
289 event of any discrepancy between this version and the original IEEE and
290 The Open Group Standard, the original IEEE and The Open Group Standard
291 is the referee document. The original Standard can be obtained online
292 at http://www.opengroup.org/unix/online.html .
293 Any typographical or formatting errors that appear in this page are
295 most likely to have been introduced during the conversion of the source
296 files to man page format. To report such errors, see https://www.ker‐
297 nel.org/doc/man-pages/reporting_bugs.html .
298IEEE/The Open Group 2017 LN(1P)