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

link.3p (12057B)


  1. '\" et
  2. .TH LINK "3P" 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. link, linkat
  12. \(em link one file to another file
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int link(const char *\fIpath1\fP, const char *\fIpath2\fP);
  19. .P
  20. #include <fcntl.h>
  21. .P
  22. int linkat(int \fIfd1\fP, const char *\fIpath1\fP, int \fIfd2\fP,
  23. const char *\fIpath2\fP, int \fIflag\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. The
  27. \fIlink\fR()
  28. function shall create a new link (directory entry) for the existing file,
  29. .IR path1 .
  30. .P
  31. The
  32. .IR path1
  33. argument points to a pathname naming an existing file. The
  34. .IR path2
  35. argument points to a pathname naming the new directory entry to be
  36. created. The
  37. \fIlink\fR()
  38. function shall atomically create a new link for the existing file and
  39. the link count of the file shall be incremented by one.
  40. .P
  41. If
  42. .IR path1
  43. names a directory,
  44. \fIlink\fR()
  45. shall fail unless the process has appropriate privileges and the
  46. implementation supports using
  47. \fIlink\fR()
  48. on directories.
  49. .P
  50. If
  51. .IR path1
  52. names a symbolic link, it is implementation-defined whether
  53. \fIlink\fR()
  54. follows the symbolic link, or creates a new link to the symbolic
  55. link itself.
  56. .P
  57. Upon successful completion,
  58. \fIlink\fR()
  59. shall mark for update the last file status change timestamp of the
  60. file. Also, the last data modification and last file status change
  61. timestamps of the directory that contains the new entry shall be marked
  62. for update.
  63. .P
  64. If
  65. \fIlink\fR()
  66. fails, no link shall be created and the link count of the file shall
  67. remain unchanged.
  68. .P
  69. The implementation may require that the calling process has permission
  70. to access the existing file.
  71. .P
  72. The
  73. \fIlinkat\fR()
  74. function shall be equivalent to the
  75. \fIlink\fR()
  76. function except that symbolic links shall be handled as specified by
  77. the value of
  78. .IR flag
  79. (see below) and except in the case where either
  80. .IR path1
  81. or
  82. .IR path2
  83. or both are relative paths. In this case a relative path
  84. .IR path1
  85. is interpreted relative to the directory associated with the file
  86. descriptor
  87. .IR fd1
  88. instead of the current working directory and similarly for
  89. .IR path2
  90. and the file descriptor
  91. .IR fd2 .
  92. If the access mode of the open file description associated with the
  93. file descriptor is not O_SEARCH, the function shall check whether
  94. directory searches are permitted using the current permissions of
  95. the directory underlying the file descriptor. If the access mode is
  96. O_SEARCH, the function shall not perform the check.
  97. .P
  98. Values for
  99. .IR flag
  100. are constructed by a bitwise-inclusive OR of flags from the following
  101. list, defined in
  102. .IR <fcntl.h> :
  103. .IP AT_SYMLINK_FOLLOW 6
  104. .br
  105. If
  106. .IR path1
  107. names a symbolic link, a new link for the target of the symbolic link
  108. is created.
  109. .P
  110. If
  111. \fIlinkat\fR()
  112. is passed the special value AT_FDCWD in the
  113. .IR fd1
  114. or
  115. .IR fd2
  116. parameter, the current working directory shall be used for the respective
  117. .IR path
  118. argument. If both
  119. .IR fd1
  120. and
  121. .IR fd2
  122. have value AT_FDCWD, the behavior shall be identical to a call to
  123. \fIlink\fR(),
  124. except that symbolic links shall be handled as specified by the value of
  125. .IR flag .
  126. .P
  127. If the AT_SYMLINK_FOLLOW flag is clear in the
  128. .IR flag
  129. argument and the
  130. .IR path1
  131. argument names a symbolic link, a new link is created for the symbolic
  132. link
  133. .IR path1
  134. and not its target.
  135. .SH "RETURN VALUE"
  136. Upon successful completion, these functions shall return 0. Otherwise,
  137. these functions shall return \-1 and set
  138. .IR errno
  139. to indicate the error.
  140. .br
  141. .SH ERRORS
  142. These functions shall fail if:
  143. .TP
  144. .BR EACCES
  145. A component of either path prefix denies search permission, or the
  146. requested link requires writing in a directory that denies write
  147. permission, or the calling process does not have permission to access
  148. the existing file and this is required by the implementation.
  149. .TP
  150. .BR EEXIST
  151. The
  152. .IR path2
  153. argument resolves to an existing directory entry or refers to a symbolic
  154. link.
  155. .TP
  156. .BR ELOOP
  157. A loop exists in symbolic links encountered during resolution of the
  158. .IR path1
  159. or
  160. .IR path2
  161. argument.
  162. .TP
  163. .BR EMLINK
  164. The number of links to the file named by
  165. .IR path1
  166. would exceed
  167. {LINK_MAX}.
  168. .TP
  169. .BR ENAMETOOLONG
  170. .br
  171. The length of a component of a pathname is longer than
  172. {NAME_MAX}.
  173. .TP
  174. .BR ENOENT
  175. A component of either path prefix does not exist; the file named by
  176. .IR path1
  177. does not exist; or
  178. .IR path1
  179. or
  180. .IR path2
  181. points to an empty string.
  182. .TP
  183. .BR ENOENT " or " ENOTDIR
  184. .br
  185. The
  186. .IR path1
  187. argument names an existing non-directory file, and the
  188. .IR path2
  189. argument contains at least one non-\c
  190. <slash>
  191. character and ends with one or more trailing
  192. <slash>
  193. characters. If
  194. .IR path2
  195. without the trailing
  196. <slash>
  197. characters would name an existing file, an
  198. .BR [ENOENT]
  199. error shall not occur.
  200. .TP
  201. .BR ENOSPC
  202. The directory to contain the link cannot be extended.
  203. .TP
  204. .BR ENOTDIR
  205. A component of either path prefix names an existing file that is neither
  206. a directory nor a symbolic link to a directory, or the
  207. .IR path1
  208. argument contains at least one non-\c
  209. <slash>
  210. character and ends with one or more trailing
  211. <slash>
  212. characters and the last pathname component names an existing file
  213. that is neither a directory nor a symbolic link to a directory, or the
  214. .IR path1
  215. argument names an existing non-directory file and the
  216. .IR path2
  217. argument names a nonexistent file, contains at least one non-\c
  218. <slash>
  219. character, and ends with one or more trailing
  220. <slash>
  221. characters.
  222. .TP
  223. .BR EPERM
  224. The file named by
  225. .IR path1
  226. is a directory and either the calling process does not have appropriate
  227. privileges or the implementation prohibits using
  228. \fIlink\fR()
  229. on directories.
  230. .TP
  231. .BR EROFS
  232. The requested link requires writing in a directory on a read-only file
  233. system.
  234. .TP
  235. .BR EXDEV
  236. The link named by
  237. .IR path2
  238. and the file named by
  239. .IR path1
  240. are on different file systems and the implementation does not support
  241. links between file systems.
  242. .TP
  243. .BR EXDEV
  244. .IR path1
  245. refers to a named STREAM.
  246. .P
  247. The
  248. \fIlinkat\fR()
  249. function shall fail if:
  250. .TP
  251. .BR EACCES
  252. The access mode of the open file description associated with
  253. .IR fd1
  254. or
  255. .IR fd2
  256. is not O_SEARCH and the permissions of the directory underlying
  257. .IR fd1
  258. or
  259. .IR fd2 ,
  260. respectively, do not permit directory searches.
  261. .TP
  262. .BR EBADF
  263. The
  264. .IR path1
  265. or
  266. .IR path2
  267. argument does not specify an absolute path and the
  268. .IR fd1
  269. or
  270. .IR fd2
  271. argument, respectively, is neither AT_FDCWD nor a valid file descriptor
  272. open for reading or searching.
  273. .TP
  274. .BR ENOTDIR
  275. The
  276. .IR path1
  277. or
  278. .IR path2
  279. argument is not an absolute path and
  280. .IR fd1
  281. or
  282. .IR fd2 ,
  283. respectively, is a file descriptor associated with a non-directory file.
  284. .P
  285. These functions may fail if:
  286. .TP
  287. .BR ELOOP
  288. More than
  289. {SYMLOOP_MAX}
  290. symbolic links were encountered during resolution of the
  291. .IR path1
  292. or
  293. .IR path2
  294. argument.
  295. .TP
  296. .BR ENAMETOOLONG
  297. .br
  298. The length of a pathname exceeds
  299. {PATH_MAX},
  300. or pathname resolution of a symbolic link produced an intermediate
  301. result with a length that exceeds
  302. {PATH_MAX}.
  303. .br
  304. .P
  305. The
  306. \fIlinkat\fR()
  307. function may fail if:
  308. .TP
  309. .BR EINVAL
  310. The value of the
  311. .IR flag
  312. argument is not valid.
  313. .LP
  314. .IR "The following sections are informative."
  315. .SH EXAMPLES
  316. .SS "Creating a Link to a File"
  317. .P
  318. The following example shows how to create a link to a file named
  319. .BR /home/cnd/mod1
  320. by creating a new directory entry named
  321. .BR /modules/pass1 .
  322. .sp
  323. .RS 4
  324. .nf
  325. #include <unistd.h>
  326. .P
  327. char *path1 = "/home/cnd/mod1";
  328. char *path2 = "/modules/pass1";
  329. int status;
  330. \&...
  331. status = link (path1, path2);
  332. .fi
  333. .P
  334. .RE
  335. .SS "Creating a Link to a File Within a Program"
  336. .P
  337. In the following program example, the
  338. \fIlink\fR()
  339. function links the
  340. .BR /etc/passwd
  341. file (defined as
  342. .BR PASSWDFILE )
  343. to a file named
  344. .BR /etc/opasswd
  345. (defined as
  346. .BR SAVEFILE ),
  347. which is used to save the current password file. Then, after removing
  348. the current password file (defined as
  349. .BR PASSWDFILE ),
  350. the new password file is saved as the current password file using the
  351. \fIlink\fR()
  352. function again.
  353. .sp
  354. .RS 4
  355. .nf
  356. #include <unistd.h>
  357. .P
  358. #define LOCKFILE "/etc/ptmp"
  359. #define PASSWDFILE "/etc/passwd"
  360. #define SAVEFILE "/etc/opasswd"
  361. \&...
  362. /* Save current password file */
  363. link (PASSWDFILE, SAVEFILE);
  364. .P
  365. /* Remove current password file. */
  366. unlink (PASSWDFILE);
  367. .P
  368. /* Save new password file as current password file. */
  369. link (LOCKFILE,PASSWDFILE);
  370. .fi
  371. .P
  372. .RE
  373. .SH "APPLICATION USAGE"
  374. Some implementations do allow links between file systems.
  375. .P
  376. If
  377. .IR path1
  378. refers to a symbolic link, application developers should use
  379. \fIlinkat\fR()
  380. with appropriate flags to select whether or not the symbolic link should
  381. be resolved.
  382. .SH RATIONALE
  383. Linking to a directory is restricted to the superuser
  384. in most historical implementations because this capability may produce
  385. loops in the file hierarchy or otherwise corrupt the file system. This volume of POSIX.1\(hy2017
  386. continues that philosophy by prohibiting
  387. \fIlink\fR()
  388. and
  389. \fIunlink\fR()
  390. from doing this. Other functions could do it if the implementor designed
  391. such an extension.
  392. .P
  393. Some historical implementations allow linking of files on different file
  394. systems. Wording was added to explicitly allow this optional behavior.
  395. .P
  396. The exception for cross-file system links is intended to apply only to
  397. links that are programmatically indistinguishable from ``hard'' links.
  398. .P
  399. The purpose of the
  400. \fIlinkat\fR()
  401. function is to link files in directories other than the current working
  402. directory without exposure to race conditions. Any part of the path of
  403. a file could be changed in parallel to a call to
  404. \fIlink\fR(),
  405. resulting in unspecified behavior. By opening a file descriptor for the
  406. directory of both the existing file and the target location and using the
  407. \fIlinkat\fR()
  408. function it can be guaranteed that the both filenames are in the desired
  409. directories.
  410. .P
  411. The AT_SYMLINK_FOLLOW flag allows for implementing both common behaviors
  412. of the
  413. \fIlink\fR()
  414. function. The POSIX specification requires that if
  415. .IR path1
  416. is a symbolic link, a new link for the target of the symbolic link is
  417. created. Many systems by default or as an alternative provide a mechanism
  418. to avoid the implicit symbolic link lookup and create a new link for
  419. the symbolic link itself.
  420. .P
  421. Earlier versions of this standard specified only the
  422. \fIlink\fR()
  423. function, and required it to behave like
  424. \fIlinkat\fR()
  425. with the AT_SYMLINK_FOLLOW flag. However, historical practice from SVR4
  426. and Linux kernels had
  427. \fIlink\fR()
  428. behaving like
  429. \fIlinkat\fR()
  430. with no flags, and many systems that attempted to provide a conforming
  431. \fIlink\fR()
  432. function did so in a way that was rarely used, and when it was used
  433. did not conform to the standard (e.g., by not being atomic, or by
  434. dereferencing the symbolic link incorrectly). Since applications could
  435. not rely on
  436. \fIlink\fR()
  437. following links in practice, the
  438. \fIlinkat\fR()
  439. function was added taking a flag to specify the desired behavior
  440. for the application.
  441. .SH "FUTURE DIRECTIONS"
  442. None.
  443. .SH "SEE ALSO"
  444. .IR "\fIrename\fR\^(\|)",
  445. .IR "\fIsymlink\fR\^(\|)",
  446. .IR "\fIunlink\fR\^(\|)"
  447. .P
  448. The Base Definitions volume of POSIX.1\(hy2017,
  449. .IR "\fB<fcntl.h>\fP",
  450. .IR "\fB<unistd.h>\fP"
  451. .\"
  452. .SH COPYRIGHT
  453. Portions of this text are reprinted and reproduced in electronic form
  454. from IEEE Std 1003.1-2017, Standard for Information Technology
  455. -- Portable Operating System Interface (POSIX), The Open Group Base
  456. Specifications Issue 7, 2018 Edition,
  457. Copyright (C) 2018 by the Institute of
  458. Electrical and Electronics Engineers, Inc and The Open Group.
  459. In the event of any discrepancy between this version and the original IEEE and
  460. The Open Group Standard, the original IEEE and The Open Group Standard
  461. is the referee document. The original Standard can be obtained online at
  462. http://www.opengroup.org/unix/online.html .
  463. .PP
  464. Any typographical or formatting errors that appear
  465. in this page are most likely
  466. to have been introduced during the conversion of the source files to
  467. man page format. To report such errors, see
  468. https://www.kernel.org/doc/man-pages/reporting_bugs.html .