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

realpath.3p (6138B)


  1. '\" et
  2. .TH REALPATH "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. realpath
  12. \(em resolve a pathname
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdlib.h>
  17. .P
  18. char *realpath(const char *restrict \fIfile_name\fP,
  19. char *restrict \fIresolved_name\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIrealpath\fR()
  24. function shall derive, from the pathname pointed to by
  25. .IR file_name ,
  26. an absolute pathname that resolves to the same directory entry, whose
  27. resolution does not involve
  28. .BR '.' ,
  29. .BR '..' ,
  30. or symbolic links. If
  31. .IR resolved_name
  32. is a null pointer, the generated pathname shall be stored as a
  33. null-terminated string in a buffer allocated as if by a call to
  34. \fImalloc\fR().
  35. Otherwise, if
  36. {PATH_MAX}
  37. is defined as a constant in the
  38. .IR <limits.h>
  39. header, then the generated pathname shall be stored as a null-terminated
  40. string, up to a maximum of
  41. {PATH_MAX}
  42. bytes, in the buffer pointed to by
  43. .IR resolved_name .
  44. .P
  45. If
  46. .IR resolved_name
  47. is not a null pointer and
  48. {PATH_MAX}
  49. is not defined as a constant in the
  50. .IR <limits.h>
  51. header, the behavior is undefined.
  52. .SH "RETURN VALUE"
  53. Upon successful completion,
  54. \fIrealpath\fR()
  55. shall return a pointer to the buffer containing the resolved name.
  56. Otherwise,
  57. \fIrealpath\fR()
  58. shall return a null pointer and set
  59. .IR errno
  60. to indicate the error.
  61. .P
  62. If the
  63. .IR resolved_name
  64. argument is a null pointer, the pointer returned by
  65. \fIrealpath\fR()
  66. can be passed to
  67. \fIfree\fR().
  68. .P
  69. If the
  70. .IR resolved_name
  71. argument is not a null pointer and the
  72. \fIrealpath\fR()
  73. function fails, the contents of the buffer pointed to by
  74. .IR resolved_name
  75. are undefined.
  76. .SH ERRORS
  77. The
  78. \fIrealpath\fR()
  79. function shall fail if:
  80. .TP
  81. .BR EACCES
  82. Search permission was denied for a component of the path prefix of
  83. .IR file_name .
  84. .TP
  85. .BR EINVAL
  86. The
  87. .IR file_name
  88. argument is a null pointer.
  89. .TP
  90. .BR EIO
  91. An error occurred while reading from the file system.
  92. .TP
  93. .BR ELOOP
  94. A loop exists in symbolic links encountered during resolution of the
  95. .IR file_name
  96. argument.
  97. .TP
  98. .BR ENAMETOOLONG
  99. .br
  100. The length of a component of a pathname is longer than
  101. {NAME_MAX}.
  102. .TP
  103. .BR ENOENT
  104. A component of
  105. .IR file_name
  106. does not name an existing file or
  107. .IR file_name
  108. points to an empty string.
  109. .TP
  110. .BR ENOTDIR
  111. A component of the path prefix names an existing file that is neither
  112. a directory nor a symbolic link to a directory, or the
  113. .IR file_name
  114. argument contains at least one non-\c
  115. <slash>
  116. character and ends with one or more trailing
  117. <slash>
  118. characters and the last pathname component names an existing file that
  119. is neither a directory nor a symbolic link to a directory.
  120. .br
  121. .P
  122. The
  123. \fIrealpath\fR()
  124. function may fail if:
  125. .TP
  126. .BR EACCES
  127. The
  128. .IR file_name
  129. argument does not begin with a
  130. <slash>
  131. and none of the symbolic links (if any) processed during pathname
  132. resolution of
  133. .IR file_name
  134. had contents that began with a
  135. <slash>,
  136. and either search permission was denied for the current directory or
  137. read or search permission was denied for a directory above the current
  138. directory in the file hierarchy.
  139. .TP
  140. .BR ELOOP
  141. More than
  142. {SYMLOOP_MAX}
  143. symbolic links were encountered during resolution of the
  144. .IR file_name
  145. argument.
  146. .TP
  147. .BR ENAMETOOLONG
  148. .br
  149. The length of a pathname exceeds
  150. {PATH_MAX},
  151. or pathname resolution of a symbolic link produced an intermediate
  152. result with a length that exceeds
  153. {PATH_MAX}.
  154. .TP
  155. .BR ENOMEM
  156. Insufficient storage space is available.
  157. .LP
  158. .IR "The following sections are informative."
  159. .SH EXAMPLES
  160. .SS "Generating an Absolute Pathname"
  161. .P
  162. The following example generates an absolute pathname for the file
  163. identified by the
  164. .IR symlinkpath
  165. argument. The generated pathname is stored in the buffer pointed to by
  166. .IR actualpath .
  167. .sp
  168. .RS 4
  169. .nf
  170. #include <stdlib.h>
  171. \&...
  172. char *symlinkpath = "/tmp/symlink/file";
  173. char *actualpath;
  174. .P
  175. actualpath = realpath(symlinkpath, NULL);
  176. if (actualpath != NULL)
  177. {
  178. ... use actualpath ...
  179. .P
  180. free(actualpath);
  181. }
  182. else
  183. {
  184. ... handle error ...
  185. }
  186. .fi
  187. .P
  188. .RE
  189. .SH "APPLICATION USAGE"
  190. For functions that allocate memory as if by
  191. \fImalloc\fR(),
  192. the application should release such memory when it is no longer
  193. required by a call to
  194. \fIfree\fR().
  195. For
  196. \fIrealpath\fR(),
  197. this is the return value.
  198. .SH RATIONALE
  199. Since
  200. \fIrealpath\fR()
  201. has no
  202. .IR length
  203. argument, if
  204. {PATH_MAX}
  205. is not defined as a constant in
  206. .IR <limits.h> ,
  207. applications have no way of determining how large a buffer they need
  208. to allocate for it to be safe to pass to
  209. \fIrealpath\fR().
  210. A
  211. {PATH_MAX}
  212. value obtained from a prior
  213. \fIpathconf\fR()
  214. call is out-of-date by the time
  215. \fIrealpath\fR()
  216. is called. Hence the only reliable way to use
  217. \fIrealpath\fR()
  218. when
  219. {PATH_MAX}
  220. is not defined in
  221. .IR <limits.h>
  222. is to pass a null pointer for
  223. .IR resolved_name
  224. so that
  225. \fIrealpath\fR()
  226. will allocate a buffer of the necessary size.
  227. .SH "FUTURE DIRECTIONS"
  228. None.
  229. .SH "SEE ALSO"
  230. .IR "\fIfpathconf\fR\^(\|)",
  231. .IR "\fIfree\fR\^(\|)",
  232. .IR "\fIgetcwd\fR\^(\|)",
  233. .IR "\fIsysconf\fR\^(\|)"
  234. .P
  235. The Base Definitions volume of POSIX.1\(hy2017,
  236. .IR "\fB<limits.h>\fP",
  237. .IR "\fB<stdlib.h>\fP"
  238. .\"
  239. .SH COPYRIGHT
  240. Portions of this text are reprinted and reproduced in electronic form
  241. from IEEE Std 1003.1-2017, Standard for Information Technology
  242. -- Portable Operating System Interface (POSIX), The Open Group Base
  243. Specifications Issue 7, 2018 Edition,
  244. Copyright (C) 2018 by the Institute of
  245. Electrical and Electronics Engineers, Inc and The Open Group.
  246. In the event of any discrepancy between this version and the original IEEE and
  247. The Open Group Standard, the original IEEE and The Open Group Standard
  248. is the referee document. The original Standard can be obtained online at
  249. http://www.opengroup.org/unix/online.html .
  250. .PP
  251. Any typographical or formatting errors that appear
  252. in this page are most likely
  253. to have been introduced during the conversion of the source files to
  254. man page format. To report such errors, see
  255. https://www.kernel.org/doc/man-pages/reporting_bugs.html .