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