1LN(1P)                     POSIX Programmer's Manual                    LN(1P)
2
3
4

PROLOG

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
11

NAME

13       ln — link files
14

SYNOPSIS

16       ln [−fs] [−L|−P] source_file target_file
17
18       ln [−fs] [−L|−P] source_file... target_dir
19

DESCRIPTION

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
29       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
34       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
38       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
44       For each source_file:
45
46        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
52            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
56            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
61            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
68        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
74        3. If source_file is a symbolic link:
75
76            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
82            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
88           The  ln utility shall do nothing more with source_file and shall go
89           on to any remaining files.
90
91        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

OPTIONS

97       The  ln  utility  shall  conform  to  the  Base  Definitions  volume of
98       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
99
100       The following options shall be supported:
101
102       −f        Force existing destination pathnames to be removed  to  allow
103                 the link.
104
105       −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
109       −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
112       −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
116       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
121       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

OPERANDS

126       The following operands shall be supported:
127
128       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
134       target_file
135                 The pathname of the new directory entry to be created.
136
137       target_dir
138                 A pathname of an existing directory in which the  new  direc‐
139                 tory entries are created.
140

STDIN

142       Not used.
143

INPUT FILES

145       None.
146

ENVIRONMENT VARIABLES

148       The following environment variables shall affect the execution of ln:
149
150       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
156       LC_ALL    If  set  to  a non-empty string value, override the values of
157                 all the other internationalization variables.
158
159       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
163       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
168       NLSPATH   Determine the location of message catalogs for the processing
169                 of LC_MESSAGES.
170

ASYNCHRONOUS EVENTS

172       Default.
173

STDOUT

175       Not used.
176

STDERR

178       The standard error shall be used only for diagnostic messages.
179

OUTPUT FILES

181       None.
182

EXTENDED DESCRIPTION

184       None.
185

EXIT STATUS

187       The following exit values shall be returned:
188
189        0    All the specified files were linked successfully.
190
191       >0    An error occurred.
192

CONSEQUENCES OF ERRORS

194       Default.
195
196       The following sections are informative.
197

APPLICATION USAGE

199       None.
200

EXAMPLES

202       None.
203

RATIONALE

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
208       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
214       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
218       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
221        *  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
226        *  This functionality gave ln the ability to destroy the  link  struc‐
227           ture of files, which changes the historical behavior of ln.
228
229        *  This  functionality  is  easily replicated with a combination of rm
230           and ln.
231
232        *  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
237        *  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
240       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
245       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
249       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
254       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
262       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
269       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

FUTURE DIRECTIONS

274       None.
275

SEE ALSO

277       chmod, find, pax, rm
278
279       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
280       Variables, Section 12.2, Utility Syntax Guidelines
281
282       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
296       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 .
300
301
302
303IEEE/The Open Group                  2013                               LN(1P)
Impressum