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

readlink.3p (7077B)


  1. '\" et
  2. .TH READLINK "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. readlink, readlinkat
  12. \(em read the contents of a symbolic link
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. ssize_t readlink(const char *restrict \fIpath\fP, char *restrict \fIbuf\fP,
  19. size_t \fIbufsize\fP);
  20. .P
  21. #include <fcntl.h>
  22. .P
  23. ssize_t readlinkat(int \fIfd\fP, const char *restrict \fIpath\fP,
  24. char *restrict \fIbuf\fP, size_t \fIbufsize\fP);
  25. .fi
  26. .SH DESCRIPTION
  27. The
  28. \fIreadlink\fR()
  29. function shall place the contents of the symbolic link referred to by
  30. .IR path
  31. in the buffer
  32. .IR buf
  33. which has size
  34. .IR bufsize .
  35. If the number of bytes in the symbolic link is less than
  36. .IR bufsize ,
  37. the contents of the remainder of
  38. .IR buf
  39. are unspecified. If the
  40. .IR buf
  41. argument is not large enough to contain the link content, the first
  42. .IR bufsize
  43. bytes shall be placed in
  44. .IR buf .
  45. .P
  46. If the value of
  47. .IR bufsize
  48. is greater than
  49. {SSIZE_MAX},
  50. the result is implementation-defined.
  51. .P
  52. Upon successful completion,
  53. \fIreadlink\fR()
  54. shall mark for update the last data access timestamp of the symbolic
  55. link.
  56. .P
  57. The
  58. \fIreadlinkat\fR()
  59. function shall be equivalent to the
  60. \fIreadlink\fR()
  61. function except in the case where
  62. .IR path
  63. specifies a relative path. In this case the symbolic link whose content
  64. is read is relative to the directory associated with the file
  65. descriptor
  66. .IR fd
  67. instead of the current working directory. If the access mode of the
  68. open file description associated with the file descriptor is not
  69. O_SEARCH, the function shall check whether directory searches are
  70. permitted using the current permissions of the directory underlying
  71. the file descriptor. If the access mode is O_SEARCH, the function
  72. shall not perform the check.
  73. .P
  74. If
  75. \fIreadlinkat\fR()
  76. is passed the special value AT_FDCWD in the
  77. .IR fd
  78. parameter, the current working directory shall be used and the behavior
  79. shall be identical to a call to
  80. \fIreadlink\fR().
  81. .SH "RETURN VALUE"
  82. Upon successful completion, these functions shall return the count of
  83. bytes placed in the buffer. Otherwise, these functions shall return a
  84. value of \-1, leave the buffer unchanged, and set
  85. .IR errno
  86. to indicate the error.
  87. .SH ERRORS
  88. These functions shall fail if:
  89. .TP
  90. .BR EACCES
  91. Search permission is denied for a component of the path prefix of
  92. .IR path .
  93. .TP
  94. .BR EINVAL
  95. The
  96. .IR path
  97. argument names a file that is not a symbolic link.
  98. .TP
  99. .BR EIO
  100. An I/O error occurred while reading from the file system.
  101. .TP
  102. .BR ELOOP
  103. A loop exists in symbolic links encountered during resolution of the
  104. .IR path
  105. argument.
  106. .TP
  107. .BR ENAMETOOLONG
  108. .br
  109. The length of a component of a pathname is longer than
  110. {NAME_MAX}.
  111. .TP
  112. .BR ENOENT
  113. A component of
  114. .IR path
  115. does not name an existing file or
  116. .IR path
  117. is an empty string.
  118. .TP
  119. .BR ENOTDIR
  120. A component of the path prefix names an existing file that is neither
  121. a directory nor a symbolic link to a directory, or the
  122. .IR path
  123. argument contains at least one non-\c
  124. <slash>
  125. character and ends with one or more trailing
  126. <slash>
  127. characters and the last pathname component names an existing file that
  128. is neither a directory nor a symbolic link to a directory.
  129. .br
  130. .P
  131. The
  132. \fIreadlinkat\fR()
  133. function shall fail if:
  134. .TP
  135. .BR EACCES
  136. The access mode of the open file description associated with
  137. .IR fd
  138. is not O_SEARCH and the permissions of the directory underlying
  139. .IR fd
  140. do not permit directory searches.
  141. .TP
  142. .BR EBADF
  143. The
  144. .IR path
  145. argument does not specify an absolute path and the
  146. .IR fd
  147. argument is neither AT_FDCWD nor a valid file descriptor open for reading
  148. or searching.
  149. .TP
  150. .BR ENOTDIR
  151. The
  152. .IR path
  153. argument is not an absolute path and
  154. .IR fd
  155. is a file descriptor associated with a non-directory file.
  156. .P
  157. These functions may fail if:
  158. .TP
  159. .BR ELOOP
  160. More than
  161. {SYMLOOP_MAX}
  162. symbolic links were encountered during resolution of the
  163. .IR path
  164. argument.
  165. .TP
  166. .BR ENAMETOOLONG
  167. .br
  168. The length of a pathname exceeds
  169. {PATH_MAX},
  170. or pathname resolution of a symbolic link produced an intermediate
  171. result with a length that exceeds
  172. {PATH_MAX}.
  173. .LP
  174. .IR "The following sections are informative."
  175. .SH EXAMPLES
  176. .SS "Reading the Name of a Symbolic Link"
  177. .P
  178. The following example shows how to read the name of a symbolic link
  179. named
  180. .BR /modules/pass1 .
  181. .sp
  182. .RS 4
  183. .nf
  184. #include <unistd.h>
  185. .P
  186. char buf[1024];
  187. ssize_t len;
  188. \&...
  189. if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1)
  190. buf[len] = \(aq\e0\(aq;
  191. .fi
  192. .P
  193. .RE
  194. .SH "APPLICATION USAGE"
  195. Conforming applications should not assume that the returned contents of
  196. the symbolic link are null-terminated.
  197. .SH RATIONALE
  198. The type associated with
  199. .IR bufsiz
  200. is a
  201. .BR size_t
  202. in order to be consistent with both the ISO\ C standard and the definition of
  203. \fIread\fR().
  204. The behavior specified for
  205. \fIreadlink\fR()
  206. when
  207. .IR bufsiz
  208. is zero represents historical practice. For this case, the standard
  209. developers considered a change whereby
  210. \fIreadlink\fR()
  211. would return the number of non-null bytes contained in the symbolic
  212. link with the buffer
  213. .IR buf
  214. remaining unchanged; however, since the
  215. .BR stat
  216. structure member
  217. .IR st_size
  218. value can be used to determine the size of buffer necessary to contain
  219. the contents of the symbolic link as returned by
  220. \fIreadlink\fR(),
  221. this proposal was rejected, and the historical practice retained.
  222. .P
  223. The purpose of the
  224. \fIreadlinkat\fR()
  225. function is to read the content of symbolic links in directories other
  226. than the current working directory without exposure to race conditions.
  227. Any part of the path of a file could be changed in parallel to a call
  228. to
  229. \fIreadlink\fR(),
  230. resulting in unspecified behavior. By opening a file descriptor for
  231. the target directory and using the
  232. \fIreadlinkat\fR()
  233. function it can be guaranteed that the symbolic link read is located
  234. relative to the desired directory.
  235. .SH "FUTURE DIRECTIONS"
  236. None.
  237. .SH "SEE ALSO"
  238. .IR "\fIfstatat\fR\^(\|)",
  239. .IR "\fIsymlink\fR\^(\|)"
  240. .P
  241. The Base Definitions volume of POSIX.1\(hy2017,
  242. .IR "\fB<fcntl.h>\fP",
  243. .IR "\fB<unistd.h>\fP"
  244. .\"
  245. .SH COPYRIGHT
  246. Portions of this text are reprinted and reproduced in electronic form
  247. from IEEE Std 1003.1-2017, Standard for Information Technology
  248. -- Portable Operating System Interface (POSIX), The Open Group Base
  249. Specifications Issue 7, 2018 Edition,
  250. Copyright (C) 2018 by the Institute of
  251. Electrical and Electronics Engineers, Inc and The Open Group.
  252. In the event of any discrepancy between this version and the original IEEE and
  253. The Open Group Standard, the original IEEE and The Open Group Standard
  254. is the referee document. The original Standard can be obtained online at
  255. http://www.opengroup.org/unix/online.html .
  256. .PP
  257. Any typographical or formatting errors that appear
  258. in this page are most likely
  259. to have been introduced during the conversion of the source files to
  260. man page format. To report such errors, see
  261. https://www.kernel.org/doc/man-pages/reporting_bugs.html .