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] source_file target_file
16 ln [-fs] source_file ... target_dir
18
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 IEEE Std 1003.1-2001, the behavior
36 is implementation-defined.
37 The corresponding destination path for each source_file shall be the
39 concatenation of the target directory pathname, a slash character, and
40 the last pathname component of the source_file. The second synopsis
41 form shall be assumed when the final operand names an existing direc‐
42 tory.
43 For each source_file:
45 1. If the destination path exists:
47 a. If the -f option is not specified, ln shall write a diagnostic
49 message to standard error, do nothing more with the current
50 source_file, and go on to any remaining source_files.
51 b. Actions shall be performed equivalent to the unlink() function
53 defined in the System Interfaces volume of
54 IEEE Std 1003.1-2001, called using destination as the path
55 argument. If this fails for any reason, ln shall write a diag‐
56 nostic message to standard error, do nothing more with the cur‐
57 rent source_file, and go on to any remaining source_files.
58 2. If the -s option is specified, ln shall create a symbolic link
60 named by the destination path and containing as its pathname
61 source_file. The ln utility shall do nothing more with source_file
62 and shall go on to any remaining files.
63 3. If source_file is a symbolic link, actions shall be performed
65 equivalent to the link() function using the object that source_file
66 references as the path1 argument and the destination path as the
67 path2 argument. The ln utility shall do nothing more with
68 source_file and shall go on to any remaining files.
69 4. Actions shall be performed equivalent to the link() function
71 defined in the System Interfaces volume of IEEE Std 1003.1-2001
72 using source_file as the path1 argument, and the destination path
73 as the path2 argument.
74
76 The ln utility shall conform to the Base Definitions volume of
77 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
78 The following option shall be supported:
80 -f Force existing destination pathnames to be removed to allow the
82 link.
83 -s Create symbolic links instead of hard links.
85
88 The following operands shall be supported:
89 source_file
91 A pathname of a file to be linked. If the -s option is speci‐
92 fied, no restrictions on the type of file or on its existence
93 shall be made. If the -s option is not specified, whether a
94 directory can be linked is implementation-defined.
95 target_file
97 The pathname of the new directory entry to be created.
98 target_dir
100 A pathname of an existing directory in which the new directory
101 entries are created.
102
105 Not used.
106
108 None.
109
111 The following environment variables shall affect the execution of ln:
112 LANG Provide a default value for the internationalization variables
114 that are unset or null. (See the Base Definitions volume of
115 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
116 ables for the precedence of internationalization variables used
117 to determine the values of locale categories.)
118 LC_ALL If set to a non-empty string value, override the values of all
120 the other internationalization variables.
121 LC_CTYPE
123 Determine the locale for the interpretation of sequences of
124 bytes of text data as characters (for example, single-byte as
125 opposed to multi-byte characters in arguments).
126 LC_MESSAGES
128 Determine the locale that should be used to affect the format
129 and contents of diagnostic messages written to standard error.
130 NLSPATH
132 Determine the location of message catalogs for the processing of
133 LC_MESSAGES .
134
137 Default.
138
140 Not used.
141
143 The standard error shall be used only for diagnostic messages.
144
146 None.
147
149 None.
150
152 The following exit values shall be returned:
153 0 All the specified files were linked successfully.
155 >0 An error occurred.
157
160 Default.
161 The following sections are informative.
163
165 None.
166
168 None.
169
171 Some historic versions of ln (including the one specified by the SVID)
172 unlink the destination file, if it exists, by default. If the mode does
173 not permit writing, these versions prompt for confirmation before
174 attempting the unlink. In these versions the -f option causes ln not to
175 attempt to prompt for confirmation.
176 This allows ln to succeed in creating links when the target file
178 already exists, even if the file itself is not writable (although the
179 directory must be). Early proposals specified this functionality.
180 This volume of IEEE Std 1003.1-2001 does not allow the ln utility to
182 unlink existing destination paths by default for the following reasons:
183 * The ln utility has historically been used to provide locking for
185 shell applications, a usage that is incompatible with ln unlinking
186 the destination path by default. There was no corresponding techni‐
187 cal advantage to adding this functionality.
188 * This functionality gave ln the ability to destroy the link structure
190 of files, which changes the historical behavior of ln.
191 * This functionality is easily replicated with a combination of rm and
193 ln.
194 * It is not historical practice in many systems; BSD and BSD-derived
196 systems do not support this behavior. Unfortunately, whichever
197 behavior is selected can cause scripts written expecting the other
198 behavior to fail.
199 * It is preferable that ln perform in the same manner as the link()
201 function, which does not permit the target to exist already.
202 This volume of IEEE Std 1003.1-2001 retains the -f option to provide
204 support for shell scripts depending on the SVID semantics. It seems
205 likely that shell scripts would not be written to handle prompting by
206 ln and would therefore have specified the -f option.
207 The -f option is an undocumented feature of many historical versions of
209 the ln utility, allowing linking to directories. These versions require
210 modification.
211 Early proposals of this volume of IEEE Std 1003.1-2001 also required a
213 -i option, which behaved like the -i options in cp and mv, prompting
214 for confirmation before unlinking existing files. This was not histori‐
215 cal practice for the ln utility and has been omitted.
216
218 None.
219
221 chmod(), find, pax, rm, the System Interfaces volume of
222 IEEE Std 1003.1-2001, link(), unlink()
223
225 Portions of this text are reprinted and reproduced in electronic form
226 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
227 -- Portable Operating System Interface (POSIX), The Open Group Base
228 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
229 Electrical and Electronics Engineers, Inc and The Open Group. In the
230 event of any discrepancy between this version and the original IEEE and
231 The Open Group Standard, the original IEEE and The Open Group Standard
232 is the referee document. The original Standard can be obtained online
233 at http://www.opengroup.org/unix/online.html .
234IEEE/The Open Group 2003 LN(1P)