logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

ln.1p (12439B)


  1. '\" et
  2. .TH LN "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. ln
  12. \(em link files
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. ln \fB[\fR-fs\fB] [\fR-L|-P\fB] \fIsource_file target_file\fR
  17. .P
  18. ln \fB[\fR-fs\fB] [\fR-L|-P\fB] \fIsource_file\fR... \fItarget_dir\fR
  19. .fi
  20. .SH DESCRIPTION
  21. In the first synopsis form, the
  22. .IR ln
  23. utility shall create a new directory entry (link) at the
  24. destination path specified by the
  25. .IR target_file
  26. operand. If the
  27. .BR \-s
  28. option is specified, a symbolic link shall be created for the file
  29. specified by the
  30. .IR source_file
  31. operand. This first synopsis form shall be assumed when the final
  32. operand does not name an existing directory; if more than two operands
  33. are specified and the final is not an existing directory, an error
  34. shall result.
  35. .P
  36. In the second synopsis form, the
  37. .IR ln
  38. utility shall create a new directory entry (link), or if the
  39. .BR \-s
  40. option is specified a symbolic link, for each file specified by a
  41. .IR source_file
  42. operand, at a destination path in the existing directory named by
  43. .IR target_dir .
  44. .P
  45. If the last operand specifies an existing file of a type not
  46. specified by the System Interfaces volume of POSIX.1\(hy2017, the behavior is implementation-defined.
  47. .P
  48. The corresponding destination path for each
  49. .IR source_file
  50. shall be the concatenation of the target directory pathname, a
  51. <slash>
  52. character if the target directory pathname did not end in a
  53. <slash>,
  54. and the last pathname component of the
  55. .IR source_file .
  56. The second synopsis form shall be assumed when the final operand names
  57. an existing directory.
  58. .P
  59. For each
  60. .IR source_file :
  61. .IP " 1." 4
  62. If the destination path exists and was created by a previous step,
  63. it is unspecified whether
  64. .IR ln
  65. shall write a diagnostic message to standard error, do nothing more with
  66. the current
  67. .IR source_file ,
  68. and go on to any remaining
  69. .IR source_file s;
  70. or will continue processing the current
  71. .IR source_file .
  72. If the destination path exists:
  73. .RS 4
  74. .IP " a." 4
  75. If the
  76. .BR \-f
  77. option is not specified,
  78. .IR ln
  79. shall write a diagnostic message to standard error, do nothing more
  80. with the current
  81. .IR source_file ,
  82. and go on to any remaining
  83. .IR source_file s.
  84. .IP " b." 4
  85. If the destination path names the same directory entry as the current
  86. .IR source_file
  87. .IR ln
  88. shall write a diagnostic message to standard error, do nothing more with
  89. the current
  90. .IR source_file ,
  91. and go on to any remaining
  92. .IR source_file s .
  93. .IP " c." 4
  94. Actions shall be performed equivalent to the
  95. \fIunlink\fR()
  96. function defined in the System Interfaces volume of POSIX.1\(hy2017, called using the destination path as the
  97. .IR path
  98. argument. If this fails for any reason,
  99. .IR ln
  100. shall write a diagnostic message to standard error, do nothing more
  101. with the current
  102. .IR source_file ,
  103. and go on to any remaining
  104. .IR source_file s.
  105. .RE
  106. .IP " 2." 4
  107. If the
  108. .BR \-s
  109. option is specified, actions shall be performed equivalent to the
  110. \fIsymlink\fR()
  111. function with
  112. .IR source_file
  113. as the
  114. .IR path1
  115. argument and the destination path as the
  116. .IR path2
  117. argument. The
  118. .IR ln
  119. utility shall do nothing more with
  120. .IR source_file
  121. and shall go on to any remaining files.
  122. .IP " 3." 4
  123. If
  124. .IR source_file
  125. is a symbolic link:
  126. .RS 4
  127. .IP " a." 4
  128. If the
  129. .BR \-P
  130. option is in effect, actions shall be performed equivalent to the
  131. \fIlinkat\fR()
  132. function with
  133. .IR source_file
  134. as the
  135. .IR path1
  136. argument, the destination path as the
  137. .IR path2
  138. argument, AT_FDCWD as the
  139. .IR fd1
  140. and
  141. .IR fd2
  142. arguments, and zero as the
  143. .IR flag
  144. argument.
  145. .IP " b." 4
  146. If the
  147. .BR \-L
  148. option is in effect, actions shall be performed equivalent to the
  149. \fIlinkat\fR()
  150. function with
  151. .IR source_file
  152. as the
  153. .IR path1
  154. argument, the destination path as the
  155. .IR path2
  156. argument, AT_FDCWD as the
  157. .IR fd1
  158. and
  159. .IR fd2
  160. arguments, and AT_SYMLINK_FOLLOW as the
  161. .IR flag
  162. argument.
  163. .P
  164. The
  165. .IR ln
  166. utility shall do nothing more with
  167. .IR source_file
  168. and shall go on to any remaining files.
  169. .RE
  170. .IP " 4." 4
  171. Actions shall be performed equivalent to the
  172. \fIlink\fR()
  173. function defined in the System Interfaces volume of POSIX.1\(hy2017 using
  174. .IR source_file
  175. as the
  176. .IR path1
  177. argument, and the destination path as the
  178. .IR path2
  179. argument.
  180. .SH OPTIONS
  181. The
  182. .IR ln
  183. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  184. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  185. .P
  186. The following options shall be supported:
  187. .IP "\fB\-f\fP" 10
  188. Force existing destination pathnames to be removed to allow the link.
  189. .IP "\fB\-L\fP" 10
  190. For each
  191. .IR source_file
  192. operand that names a file of type symbolic link, create a (hard)
  193. link to the file referenced by the symbolic link.
  194. .IP "\fB\-P\fP" 10
  195. For each
  196. .IR source_file
  197. operand that names a file of type symbolic link, create a (hard)
  198. link to the symbolic link itself.
  199. .IP "\fB\-s\fP" 10
  200. Create symbolic links instead of hard links. If the
  201. .BR \-s
  202. option is specified, the
  203. .BR \-L
  204. and
  205. .BR \-P
  206. options shall be silently ignored.
  207. .P
  208. Specifying more than one of the mutually-exclusive options
  209. .BR \-L
  210. and
  211. .BR \-P
  212. shall not be considered an error. The last option specified shall
  213. determine the behavior of the utility (unless the
  214. .BR \-s
  215. option causes it to be ignored).
  216. .P
  217. If the
  218. .BR \-s
  219. option is not specified and neither a
  220. .BR \-L
  221. nor a
  222. .BR \-P
  223. option is specified, it is implementation-defined which of the
  224. .BR \-L
  225. and
  226. .BR \-P
  227. options will be used as the default.
  228. .SH OPERANDS
  229. The following operands shall be supported:
  230. .IP "\fIsource_file\fR" 10
  231. A pathname of a file to be linked. If the
  232. .BR \-s
  233. option is specified, no restrictions on the type of file or on its
  234. existence shall be made. If the
  235. .BR \-s
  236. option is not specified, whether a directory can be linked is
  237. implementation-defined.
  238. .IP "\fItarget_file\fR" 10
  239. The pathname of the new directory entry to be created.
  240. .IP "\fItarget_dir\fR" 10
  241. A pathname of an existing directory in which the new directory entries
  242. are created.
  243. .SH STDIN
  244. Not used.
  245. .SH "INPUT FILES"
  246. None.
  247. .SH "ENVIRONMENT VARIABLES"
  248. The following environment variables shall affect the execution of
  249. .IR ln :
  250. .IP "\fILANG\fP" 10
  251. Provide a default value for the internationalization variables that are
  252. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  253. .IR "Section 8.2" ", " "Internationalization Variables"
  254. for the precedence of internationalization variables used to determine
  255. the values of locale categories.)
  256. .IP "\fILC_ALL\fP" 10
  257. If set to a non-empty string value, override the values of all the
  258. other internationalization variables.
  259. .IP "\fILC_CTYPE\fP" 10
  260. Determine the locale for the interpretation of sequences of bytes of
  261. text data as characters (for example, single-byte as opposed to
  262. multi-byte characters in arguments).
  263. .IP "\fILC_MESSAGES\fP" 10
  264. .br
  265. Determine the locale that should be used to affect the format and
  266. contents of diagnostic messages written to standard error.
  267. .IP "\fINLSPATH\fP" 10
  268. Determine the location of message catalogs for the processing of
  269. .IR LC_MESSAGES .
  270. .SH "ASYNCHRONOUS EVENTS"
  271. Default.
  272. .SH STDOUT
  273. Not used.
  274. .SH STDERR
  275. The standard error shall be used only for diagnostic messages.
  276. .SH "OUTPUT FILES"
  277. None.
  278. .SH "EXTENDED DESCRIPTION"
  279. None.
  280. .SH "EXIT STATUS"
  281. The following exit values shall be returned:
  282. .IP "\00" 6
  283. All the specified files were linked successfully.
  284. .IP >0 6
  285. An error occurred.
  286. .SH "CONSEQUENCES OF ERRORS"
  287. Default.
  288. .LP
  289. .IR "The following sections are informative."
  290. .SH "APPLICATION USAGE"
  291. None.
  292. .SH EXAMPLES
  293. None.
  294. .SH RATIONALE
  295. The CONSEQUENCES OF ERRORS section does not require
  296. .IR ln
  297. .BR \-f
  298. .IR "a b"
  299. to remove
  300. .IR b
  301. if a subsequent link operation would fail.
  302. .P
  303. Some historic versions of
  304. .IR ln
  305. (including the one specified by the SVID) unlink the destination file,
  306. if it exists, by default. If the mode does not permit writing, these
  307. versions prompt for confirmation before attempting the unlink. In these
  308. versions the
  309. .BR \-f
  310. option causes
  311. .IR ln
  312. not to attempt to prompt for confirmation.
  313. .P
  314. This allows
  315. .IR ln
  316. to succeed in creating links when the target file already exists, even
  317. if the file itself is not writable (although the directory must be).
  318. Early proposals specified this functionality.
  319. .P
  320. This volume of POSIX.1\(hy2017 does not allow the
  321. .IR ln
  322. utility to unlink existing destination paths by default for the
  323. following reasons:
  324. .IP " *" 4
  325. The
  326. .IR ln
  327. utility has historically been used to provide locking for shell
  328. applications, a usage that is incompatible with
  329. .IR ln
  330. unlinking the destination path by default. There was no corresponding
  331. technical advantage to adding this functionality.
  332. .IP " *" 4
  333. This functionality gave
  334. .IR ln
  335. the ability to destroy the link structure of files, which changes the
  336. historical behavior of
  337. .IR ln .
  338. .IP " *" 4
  339. This functionality is easily replicated with a combination of
  340. .IR rm
  341. and
  342. .IR ln .
  343. .IP " *" 4
  344. It is not historical practice in many systems; BSD and BSD-derived
  345. systems do not support this behavior. Unfortunately, whichever behavior
  346. is selected can cause scripts written expecting the other behavior to
  347. fail.
  348. .IP " *" 4
  349. It is preferable that
  350. .IR ln
  351. perform in the same manner as the
  352. \fIlink\fR()
  353. function, which does not permit the target to exist already.
  354. .P
  355. This volume of POSIX.1\(hy2017 retains the
  356. .BR \-f
  357. option to provide support for shell scripts depending on the SVID
  358. semantics. It seems likely that shell scripts would not be written to
  359. handle prompting by
  360. .IR ln
  361. and would therefore have specified the
  362. .BR \-f
  363. option.
  364. .P
  365. The
  366. .BR \-f
  367. option is an undocumented feature of many historical versions of the
  368. .IR ln
  369. utility, allowing linking to directories. These versions require
  370. modification.
  371. .P
  372. Early proposals of this volume of POSIX.1\(hy2017 also required a
  373. .BR \-i
  374. option, which behaved like the
  375. .BR \-i
  376. options in
  377. .IR cp
  378. and
  379. .IR mv ,
  380. prompting for confirmation before unlinking existing files. This was
  381. not historical practice for the
  382. .IR ln
  383. utility and has been omitted.
  384. .P
  385. The
  386. .BR \-L
  387. and
  388. .BR \-P
  389. options allow for implementing both common behaviors of the
  390. .IR ln
  391. utility. Earlier versions of this standard did not specify these options
  392. and required the behavior now described for the
  393. .BR \-L
  394. option. Many systems by default or as an alternative provided a
  395. non-conforming
  396. .IR ln
  397. utility with the behavior now described for the
  398. .BR \-P
  399. option. Since applications could not rely on
  400. .IR ln
  401. following links in practice, the
  402. .BR \-L
  403. and
  404. .BR \-P
  405. options were added to specify the desired behavior for the application.
  406. .P
  407. The
  408. .BR \-L
  409. and
  410. .BR \-P
  411. options are ignored when
  412. .BR \-s
  413. is specified in order to allow an alias to be created to alter the
  414. default behavior when creating hard links (for example,
  415. .IR alias
  416. .IR ln =\(aq\c
  417. .IR ln
  418. .BR \-L \(aq).
  419. They serve no purpose when
  420. .BR \-s
  421. is specified, since
  422. .IR source_file
  423. is then just a string to be used as the contents of the created symbolic
  424. link and need not exist as a file.
  425. .P
  426. The specification ensures that
  427. .IR ln
  428. .BR a
  429. .BR a
  430. with or without the
  431. .BR \-f
  432. option will not unlink the file
  433. .BR a .
  434. Earlier versions of this standard were unclear in this case.
  435. .SH "FUTURE DIRECTIONS"
  436. None.
  437. .SH "SEE ALSO"
  438. .IR "\fIchmod\fR\^",
  439. .IR "\fIfind\fR\^",
  440. .IR "\fIpax\fR\^",
  441. .IR "\fIrm\fR\^"
  442. .P
  443. The Base Definitions volume of POSIX.1\(hy2017,
  444. .IR "Chapter 8" ", " "Environment Variables",
  445. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  446. .P
  447. The System Interfaces volume of POSIX.1\(hy2017,
  448. .IR "\fIlink\fR\^(\|)",
  449. .IR "\fIunlink\fR\^(\|)"
  450. .\"
  451. .SH COPYRIGHT
  452. Portions of this text are reprinted and reproduced in electronic form
  453. from IEEE Std 1003.1-2017, Standard for Information Technology
  454. -- Portable Operating System Interface (POSIX), The Open Group Base
  455. Specifications Issue 7, 2018 Edition,
  456. Copyright (C) 2018 by the Institute of
  457. Electrical and Electronics Engineers, Inc and The Open Group.
  458. In the event of any discrepancy between this version and the original IEEE and
  459. The Open Group Standard, the original IEEE and The Open Group Standard
  460. is the referee document. The original Standard can be obtained online at
  461. http://www.opengroup.org/unix/online.html .
  462. .PP
  463. Any typographical or formatting errors that appear
  464. in this page are most likely
  465. to have been introduced during the conversion of the source files to
  466. man page format. To report such errors, see
  467. https://www.kernel.org/doc/man-pages/reporting_bugs.html .