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

access.3p (11534B)


  1. '\" et
  2. .TH ACCESS "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. access, faccessat
  12. \(em determine accessibility of a file
  13. descriptor
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <unistd.h>
  18. .P
  19. int access(const char *\fIpath\fP, int \fIamode\fP);
  20. .P
  21. #include <fcntl.h>
  22. .P
  23. int faccessat(int \fIfd\fP, const char *\fIpath\fP, int \fIamode\fP, int \fIflag\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. The
  27. \fIaccess\fR()
  28. function shall check the file named by the pathname pointed to by the
  29. .IR path
  30. argument for accessibility according to the bit pattern contained in
  31. .IR amode .
  32. The checks for accessibility (including directory permissions
  33. checked during pathname resolution) shall be performed using the
  34. real user ID in place of the effective user ID and the real group
  35. ID in place of the effective group ID.
  36. .P
  37. The value of
  38. .IR amode
  39. is either the bitwise-inclusive OR of the access permissions to be
  40. checked (R_OK, W_OK, X_OK) or the existence test (F_OK).
  41. .P
  42. If any access permissions are checked, each shall be checked
  43. individually, as described in the Base Definitions volume of POSIX.1\(hy2017,
  44. .IR "Section 4.5" ", " "File Access Permissions",
  45. except that where that description refers to execute permission for
  46. a process with appropriate privileges, an implementation may indicate
  47. success for X_OK even if execute permission is not granted to any user.
  48. .P
  49. The
  50. \fIfaccessat\fR()
  51. function, when called with a
  52. .IR flag
  53. value of zero, shall be equivalent to the
  54. \fIaccess\fR()
  55. function, except in the case where
  56. .IR path
  57. specifies a relative path. In this case the file whose accessibility is
  58. to be determined shall be located relative to the directory associated
  59. with the file descriptor
  60. .IR fd
  61. instead of the current working directory.
  62. If the access mode of the open file description associated with
  63. the file descriptor is not O_SEARCH, the function shall check
  64. whether directory searches are permitted using the current
  65. permissions of the directory underlying the file descriptor.
  66. If the access mode is O_SEARCH, the function shall not perform the check.
  67. .P
  68. If
  69. \fIfaccessat\fR()
  70. is passed the special value AT_FDCWD in the
  71. .IR fd
  72. parameter, the current working directory shall be used and, if flag is
  73. zero, the behavior shall be identical to a call to
  74. \fIaccess\fR().
  75. .P
  76. Values for
  77. .IR flag
  78. are constructed by a bitwise-inclusive OR of flags from the following
  79. list, defined in
  80. .IR <fcntl.h> :
  81. .IP AT_EACCESS 12
  82. The checks for accessibility (including directory permissions
  83. checked during pathname resolution) shall be performed using the
  84. effective user ID and group ID instead of the real user ID and group ID
  85. as required in a call to
  86. \fIaccess\fR().
  87. .SH "RETURN VALUE"
  88. Upon successful completion, these functions shall return 0. Otherwise,
  89. these functions shall return \-1 and set
  90. .IR errno
  91. to indicate the error.
  92. .SH ERRORS
  93. These functions shall fail if:
  94. .TP
  95. .BR EACCES
  96. Permission bits of the file mode do not permit the requested access, or
  97. search permission is denied on a component of the path prefix.
  98. .TP
  99. .BR ELOOP
  100. A loop exists in symbolic links encountered during resolution of the
  101. .IR path
  102. argument.
  103. .TP
  104. .BR ENAMETOOLONG
  105. .br
  106. The length of a component of a pathname is longer than
  107. {NAME_MAX}.
  108. .TP
  109. .BR ENOENT
  110. A component of
  111. .IR path
  112. does not name an existing file or
  113. .IR path
  114. is an empty string.
  115. .TP
  116. .BR ENOTDIR
  117. A component of the path prefix names an existing file that is neither
  118. a directory nor a symbolic link to a directory, or the
  119. .IR path
  120. argument contains at least one non-\c
  121. <slash>
  122. character and ends with one or more trailing
  123. <slash>
  124. characters and the last pathname component names an existing file
  125. that is neither a directory nor a symbolic link to a directory.
  126. .TP
  127. .BR EROFS
  128. Write access is requested for a file on a read-only file system.
  129. .P
  130. The
  131. \fIfaccessat\fR()
  132. function shall fail if:
  133. .TP
  134. .BR EACCES
  135. The access mode of the open file description associated with
  136. .IR fd
  137. is not O_SEARCH and the permissions of the directory underlying
  138. .IR fd
  139. do not permit directory searches.
  140. .TP
  141. .BR EBADF
  142. The
  143. .IR path
  144. argument does not specify an absolute path and the
  145. .IR fd
  146. argument is neither AT_FDCWD nor a valid file descriptor open
  147. for reading or searching.
  148. .TP
  149. .BR ENOTDIR
  150. The
  151. .IR path
  152. argument is not an absolute path and
  153. .IR fd
  154. is a file descriptor associated with a non-directory file.
  155. .P
  156. These functions may fail if:
  157. .TP
  158. .BR EINVAL
  159. The value of the \fIamode\fP argument is invalid.
  160. .TP
  161. .BR ELOOP
  162. More than
  163. {SYMLOOP_MAX}
  164. symbolic links were encountered during resolution of the
  165. .IR path
  166. argument.
  167. .TP
  168. .BR ENAMETOOLONG
  169. .br
  170. The length of a pathname exceeds
  171. {PATH_MAX},
  172. or pathname resolution of a symbolic link produced an intermediate
  173. result with a length that exceeds
  174. {PATH_MAX}.
  175. .TP
  176. .BR ETXTBSY
  177. Write access is requested for a pure procedure (shared text) file that
  178. is being executed.
  179. .P
  180. The
  181. \fIfaccessat\fR()
  182. function may fail if:
  183. .TP
  184. .BR EINVAL
  185. The value of the
  186. .IR flag
  187. argument is not valid.
  188. .LP
  189. .IR "The following sections are informative."
  190. .SH EXAMPLES
  191. .SS "Testing for the Existence of a File"
  192. .P
  193. The following example tests whether a file named
  194. .BR myfile
  195. exists in the
  196. .BR /tmp
  197. directory.
  198. .sp
  199. .RS 4
  200. .nf
  201. #include <unistd.h>
  202. \&...
  203. int result;
  204. const char *pathname = "/tmp/myfile";
  205. .P
  206. result = access (pathname, F_OK);
  207. .fi
  208. .P
  209. .RE
  210. .SH "APPLICATION USAGE"
  211. Use of these functions is discouraged since by the time the
  212. returned information is acted upon, it is out-of-date. (That is,
  213. acting upon the information always leads to a time-of-check-to-time-of-use
  214. race condition.) An application should instead attempt the action
  215. itself and handle the
  216. .BR [EACCES]
  217. error that occurs if the file is not accessible (with a change of
  218. effective user and group IDs beforehand, and perhaps a change back
  219. afterwards, in the case where
  220. \fIaccess\fR()
  221. or
  222. \fIfaccessat\fR()
  223. without AT_EACCES would have been used.)
  224. .P
  225. Historically, one of the uses of
  226. \fIaccess\fR()
  227. was in set-user-ID root programs to check whether the user running
  228. the program had access to a file. This relied on ``super-user''
  229. privileges which were granted based on the effective user ID being
  230. zero, so that when
  231. \fIaccess\fR()
  232. used the real user ID to check accessibility those privileges
  233. were not taken into account. On newer systems where privileges
  234. can be assigned which have no association with user or group IDs,
  235. if a program with such privileges calls
  236. \fIaccess\fR(),
  237. the change of IDs has no effect on the privileges and therefore
  238. they are taken into account in the accessibility checks. Thus,
  239. \fIaccess\fR()
  240. (and
  241. \fIfaccessat\fR()
  242. with flag zero) cannot be used for this historical purpose in
  243. such programs. Likewise, if a system provides any additional or
  244. alternate file access control mechanisms that are not user ID-based,
  245. they will still be taken into account.
  246. .P
  247. If a relative pathname is used, no account is taken of whether
  248. the current directory (or the directory associated with the
  249. file descriptor
  250. .IR fd )
  251. is accessible via any absolute pathname. Applications using
  252. \fIaccess\fR(),
  253. or
  254. \fIfaccessat\fR()
  255. without AT_EACCES, may consequently act as if the file would be
  256. accessible to a user with the real user ID and group ID of the
  257. process when such a user would not in practice be able to access the file
  258. because access would be denied at some point above the current directory
  259. (or the directory associated with the file descriptor
  260. .IR fd )
  261. in the file hierarchy.
  262. .P
  263. If
  264. \fIaccess\fR()
  265. or
  266. \fIfaccessat\fR()
  267. is used with W_OK to check for write access to a directory which has
  268. the S_ISVTX bit set, a return value indicating the directory is
  269. writable can be misleading since some operations on files in the
  270. directory would not be permitted based on the ownership of those files
  271. (see the Base Definitions volume of POSIX.1\(hy2017,
  272. .IR "Section 4.3" ", " "Directory Protection").
  273. .P
  274. Additional values of
  275. .IR amode
  276. other than the set defined in the description may be valid; for
  277. example, if a system has extended access controls.
  278. .P
  279. The use of the AT_EACCESS value for
  280. .IR flag
  281. enables functionality not available in
  282. \fIaccess\fR().
  283. .SH RATIONALE
  284. In early proposals, some inadequacies in the
  285. \fIaccess\fR()
  286. function led to the creation of an
  287. \fIeaccess\fR()
  288. function because:
  289. .IP " 1." 4
  290. Historical implementations of
  291. \fIaccess\fR()
  292. do not test file access correctly when the process'
  293. real user ID is
  294. superuser. In particular, they always return zero when testing execute
  295. permissions without regard to whether the file is executable.
  296. .IP " 2." 4
  297. The superuser has complete access to all files on a system. As a
  298. consequence, programs started by the superuser and switched to the
  299. effective user ID
  300. with lesser privileges cannot use
  301. \fIaccess\fR()
  302. to test their file access permissions.
  303. .P
  304. However, the historical model of
  305. \fIeaccess\fR()
  306. does not resolve problem (1), so this volume of POSIX.1\(hy2017 now allows
  307. \fIaccess\fR()
  308. to behave in the desired way because several implementations have
  309. corrected the problem. It was also argued that problem (2) is more
  310. easily solved by using
  311. \fIopen\fR(),
  312. \fIchdir\fR(),
  313. or one of the
  314. .IR exec
  315. functions as appropriate and responding to the error, rather than
  316. creating a new function that would not be as reliable. Therefore,
  317. \fIeaccess\fR()
  318. is not included in this volume of POSIX.1\(hy2017.
  319. .P
  320. The sentence concerning appropriate privileges and execute permission
  321. bits
  322. reflects the two possibilities implemented by historical
  323. implementations when checking superuser access for X_OK.
  324. .P
  325. New implementations are discouraged from returning X_OK unless at least
  326. one execution permission bit is set.
  327. .P
  328. The purpose of the
  329. \fIfaccessat\fR()
  330. function is to enable the checking of the accessibility of files in
  331. directories other than the current working directory without exposure
  332. to race conditions. Any part of the path of a file could be changed in
  333. parallel to a call to
  334. \fIaccess\fR(),
  335. resulting in unspecified behavior. By opening a file descriptor for
  336. the target directory and using the
  337. \fIfaccessat\fR()
  338. function it can be guaranteed that the file tested for accessibility is
  339. located relative to the desired directory.
  340. .SH "FUTURE DIRECTIONS"
  341. These functions may be formally deprecated (for example, by shading
  342. them OB) in a future version of this standard.
  343. .SH "SEE ALSO"
  344. .IR "\fIchmod\fR\^(\|)",
  345. .IR "\fIfstatat\fR\^(\|)"
  346. .P
  347. The Base Definitions volume of POSIX.1\(hy2017,
  348. .IR "Section 4.5" ", " "File Access Permissions",
  349. .IR "\fB<fcntl.h>\fP",
  350. .IR "\fB<unistd.h>\fP"
  351. .\"
  352. .SH COPYRIGHT
  353. Portions of this text are reprinted and reproduced in electronic form
  354. from IEEE Std 1003.1-2017, Standard for Information Technology
  355. -- Portable Operating System Interface (POSIX), The Open Group Base
  356. Specifications Issue 7, 2018 Edition,
  357. Copyright (C) 2018 by the Institute of
  358. Electrical and Electronics Engineers, Inc and The Open Group.
  359. In the event of any discrepancy between this version and the original IEEE and
  360. The Open Group Standard, the original IEEE and The Open Group Standard
  361. is the referee document. The original Standard can be obtained online at
  362. http://www.opengroup.org/unix/online.html .
  363. .PP
  364. Any typographical or formatting errors that appear
  365. in this page are most likely
  366. to have been introduced during the conversion of the source files to
  367. man page format. To report such errors, see
  368. https://www.kernel.org/doc/man-pages/reporting_bugs.html .