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

symlink.3p (8184B)


  1. '\" et
  2. .TH SYMLINK "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. symlink, symlinkat
  12. \(em make a symbolic link
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int symlink(const char *\fIpath1\fP, const char *\fIpath2\fP);
  19. .P
  20. #include <fcntl.h>
  21. .P
  22. int symlinkat(const char *\fIpath1\fP, int \fIfd\fP, const char *\fIpath2\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIsymlink\fR()
  27. function shall create a symbolic link called
  28. .IR path2
  29. that contains the string pointed to by
  30. .IR path1
  31. (\c
  32. .IR path2
  33. is the name of the symbolic link created,
  34. .IR path1
  35. is the string contained in the symbolic link).
  36. .P
  37. The string pointed to by
  38. .IR path1
  39. shall be treated only as a string and shall not be validated
  40. as a pathname.
  41. .P
  42. If the
  43. \fIsymlink\fR()
  44. function fails for any reason other than
  45. .BR [EIO] ,
  46. any file named by
  47. .IR path2
  48. shall be unaffected.
  49. .P
  50. If
  51. .IR path2
  52. names a symbolic link,
  53. \fIsymlink\fR()
  54. shall fail and set
  55. .IR errno
  56. to
  57. .BR [EEXIST] .
  58. .P
  59. The symbolic link's user ID shall be set to the process' effective
  60. user ID. The symbolic link's group ID shall be set to the group
  61. ID of the parent directory or to the effective group ID of the
  62. process. Implementations shall provide a way to initialize the symbolic
  63. link's group ID to the group ID of the parent directory. Implementations
  64. may, but need not, provide an implementation-defined way to initialize the
  65. symbolic link's group ID to the effective group ID of the calling process.
  66. .P
  67. The values of the file mode bits for the created symbolic link are
  68. unspecified. All interfaces specified by POSIX.1\(hy2008 shall behave as if the
  69. contents of symbolic links can always be read, except that the value of
  70. the file mode bits returned in the
  71. .IR st_mode
  72. field of the
  73. .BR stat
  74. structure is unspecified.
  75. .P
  76. Upon successful completion,
  77. \fIsymlink\fR()
  78. shall mark for update the last data access, last data modification,
  79. and last file status change timestamps of the symbolic link. Also,
  80. the last data modification and last file status change timestamps of
  81. the directory that contains the new entry shall be marked for update.
  82. .P
  83. The
  84. \fIsymlinkat\fR()
  85. function shall be equivalent to the
  86. \fIsymlink\fR()
  87. function except in the case where
  88. .IR path2
  89. specifies a relative path. In this case the symbolic link is created
  90. relative to the directory associated with the file descriptor
  91. .IR fd
  92. instead of the current working directory. If the access mode of the
  93. open file description associated with the file descriptor is not
  94. O_SEARCH, the function shall check whether directory searches are
  95. permitted using the current permissions of the directory underlying
  96. the file descriptor. If the access mode is O_SEARCH, the function
  97. shall not perform the check.
  98. .P
  99. If
  100. \fIsymlinkat\fR()
  101. is passed the special value AT_FDCWD in the
  102. .IR fd
  103. parameter, the current working directory shall be used and the behavior
  104. shall be identical to a call to
  105. \fIsymlink\fR().
  106. .SH "RETURN VALUE"
  107. Upon successful completion, these functions shall return 0.
  108. Otherwise, these functions shall return \-1 and set
  109. .IR errno
  110. to indicate the error.
  111. .SH ERRORS
  112. These functions shall fail if:
  113. .TP
  114. .BR EACCES
  115. Write permission is denied in the directory where the symbolic link is
  116. being created, or search permission is denied for a component of the
  117. path prefix of
  118. .IR path2 .
  119. .TP
  120. .BR EEXIST
  121. The
  122. .IR path2
  123. argument names an existing file.
  124. .TP
  125. .BR EIO
  126. An I/O error occurs while reading from or writing to the file system.
  127. .TP
  128. .BR ELOOP
  129. A loop exists in symbolic links encountered during resolution of the
  130. .IR path2
  131. argument.
  132. .TP
  133. .BR ENAMETOOLONG
  134. .br
  135. The length of a component of the pathname specified by the
  136. .IR path2
  137. argument is longer than
  138. {NAME_MAX}
  139. or the length of the
  140. .IR path1
  141. argument is longer than
  142. {SYMLINK_MAX}.
  143. .TP
  144. .BR ENOENT
  145. A component of the path prefix of
  146. .IR path2
  147. does not name an existing file or
  148. .IR path2
  149. is an empty string.
  150. .TP
  151. .BR ENOENT " or " ENOTDIR
  152. .br
  153. The
  154. .IR path2
  155. argument contains at least one non-\c
  156. <slash>
  157. character and ends with one or more trailing
  158. <slash>
  159. characters. If
  160. .IR path2
  161. without the trailing
  162. <slash>
  163. characters would name an existing file, an
  164. .BR [ENOENT]
  165. error shall not occur.
  166. .TP
  167. .BR ENOSPC
  168. The directory in which the entry for the new symbolic link is being
  169. placed cannot be extended because no space is left on the file system
  170. containing the directory, or the new symbolic link cannot be created
  171. because no space is left on the file system which shall contain the
  172. link, or the file system is out of file-allocation resources.
  173. .TP
  174. .BR ENOTDIR
  175. A component of the path prefix of
  176. .IR path2
  177. names an existing file that is neither a directory nor a symbolic link
  178. to a directory.
  179. .TP
  180. .BR EROFS
  181. The new symbolic link would reside on a read-only file system.
  182. .P
  183. The
  184. \fIsymlinkat\fR()
  185. function shall fail if:
  186. .TP
  187. .BR EACCES
  188. The access mode of the open file description associated with
  189. .IR fd
  190. is not O_SEARCH and the permissions of the directory underlying
  191. .IR fd
  192. do not permit directory searches.
  193. .TP
  194. .BR EBADF
  195. The
  196. .IR path2
  197. argument does not specify an absolute path and the
  198. .IR fd
  199. argument is neither AT_FDCWD nor a valid file descriptor open for reading
  200. or searching.
  201. .TP
  202. .BR ENOTDIR
  203. The
  204. .IR path2
  205. argument is not an absolute path and
  206. .IR fd
  207. is a file descriptor associated with a non-directory file.
  208. .P
  209. These functions may fail if:
  210. .TP
  211. .BR ELOOP
  212. More than
  213. {SYMLOOP_MAX}
  214. symbolic links were encountered during resolution of the
  215. .IR path2
  216. argument.
  217. .TP
  218. .BR ENAMETOOLONG
  219. .br
  220. The length of the
  221. .IR path2
  222. argument exceeds
  223. {PATH_MAX}
  224. or pathname resolution of a symbolic link in the
  225. .IR path2
  226. argument produced an intermediate result with a length that exceeds
  227. {PATH_MAX}.
  228. .LP
  229. .IR "The following sections are informative."
  230. .SH EXAMPLES
  231. None.
  232. .SH "APPLICATION USAGE"
  233. Like a hard link, a symbolic link allows a file to have multiple
  234. logical names. The presence of a hard link guarantees the existence of
  235. a file, even after the original name has been removed. A symbolic link
  236. provides no such assurance; in fact, the file named by the
  237. .IR path1
  238. argument need not exist when the link is created. A symbolic link can
  239. cross file system boundaries.
  240. .P
  241. Normal permission checks are made on each component of the symbolic
  242. link pathname during its resolution.
  243. .SH RATIONALE
  244. The purpose of the
  245. \fIsymlinkat\fR()
  246. function is to create symbolic links in directories other than the
  247. current working directory without exposure to race conditions. Any part
  248. of the path of a file could be changed in parallel to a call to
  249. \fIsymlink\fR(),
  250. resulting in unspecified behavior. By opening a file descriptor for
  251. the target directory and using the
  252. \fIsymlinkat\fR()
  253. function it can be guaranteed that the created symbolic link is located
  254. relative to the desired directory.
  255. .SH "FUTURE DIRECTIONS"
  256. None.
  257. .SH "SEE ALSO"
  258. .IR "\fIfdopendir\fR\^(\|)",
  259. .IR "\fIfstatat\fR\^(\|)",
  260. .IR "\fIlchown\fR\^(\|)",
  261. .IR "\fIlink\fR\^(\|)",
  262. .IR "\fIopen\fR\^(\|)",
  263. .IR "\fIreadlink\fR\^(\|)",
  264. .IR "\fIrename\fR\^(\|)",
  265. .IR "\fIunlink\fR\^(\|)"
  266. .P
  267. The Base Definitions volume of POSIX.1\(hy2017,
  268. .IR "\fB<fcntl.h>\fP",
  269. .IR "\fB<unistd.h>\fP"
  270. .\"
  271. .SH COPYRIGHT
  272. Portions of this text are reprinted and reproduced in electronic form
  273. from IEEE Std 1003.1-2017, Standard for Information Technology
  274. -- Portable Operating System Interface (POSIX), The Open Group Base
  275. Specifications Issue 7, 2018 Edition,
  276. Copyright (C) 2018 by the Institute of
  277. Electrical and Electronics Engineers, Inc and The Open Group.
  278. In the event of any discrepancy between this version and the original IEEE and
  279. The Open Group Standard, the original IEEE and The Open Group Standard
  280. is the referee document. The original Standard can be obtained online at
  281. http://www.opengroup.org/unix/online.html .
  282. .PP
  283. Any typographical or formatting errors that appear
  284. in this page are most likely
  285. to have been introduced during the conversion of the source files to
  286. man page format. To report such errors, see
  287. https://www.kernel.org/doc/man-pages/reporting_bugs.html .