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

NAME

12       ln — link files
13

SYNOPSIS

15       ln [-fs] [-L|-P] source_file target_file
16
17       ln [-fs] [-L|-P] source_file... target_dir
18

DESCRIPTION

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
28       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
33       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
37       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
43       For each source_file:
44
45        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
51            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
55            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
60            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
67        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
73        3. If source_file is a symbolic link:
74
75            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
81            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
87           The  ln utility shall do nothing more with source_file and shall go
88           on to any remaining files.
89
90        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

OPTIONS

96       The  ln  utility  shall  conform  to  the  Base  Definitions  volume of
97       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
98
99       The following options shall be supported:
100
101       -f        Force existing destination pathnames to be removed  to  allow
102                 the link.
103
104       -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
108       -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
111       -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
115       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
120       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

OPERANDS

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

STDIN

141       Not used.
142

INPUT FILES

144       None.
145

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

171       Default.
172

STDOUT

174       Not used.
175

STDERR

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

OUTPUT FILES

180       None.
181

EXTENDED DESCRIPTION

183       None.
184

EXIT STATUS

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

CONSEQUENCES OF ERRORS

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

APPLICATION USAGE

198       None.
199

EXAMPLES

201       None.
202

RATIONALE

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
207       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
213       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
217       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
220        *  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
225        *  This functionality gave ln the ability to destroy the  link  struc‐
226           ture of files, which changes the historical behavior of ln.
227
228        *  This  functionality  is  easily replicated with a combination of rm
229           and ln.
230
231        *  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
236        *  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
239       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
244       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
248       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
253       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
261       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
268       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

FUTURE DIRECTIONS

273       None.
274

SEE ALSO

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