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

fpathconf.3p (13196B)


  1. '\" et
  2. .TH FPATHCONF "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. fpathconf,
  12. pathconf
  13. \(em get configurable pathname variables
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <unistd.h>
  18. .P
  19. long fpathconf(int \fIfildes\fP, int \fIname\fP);
  20. long pathconf(const char *\fIpath\fP, int \fIname\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIfpathconf\fR()
  25. and
  26. \fIpathconf\fR()
  27. functions shall determine the current value of a configurable limit or
  28. option (\fIvariable\fP) that is associated with a file or directory.
  29. .P
  30. For
  31. \fIpathconf\fR(),
  32. the
  33. .IR path
  34. argument points to the pathname of a file or directory.
  35. .P
  36. For
  37. \fIfpathconf\fR(),
  38. the
  39. .IR fildes
  40. argument is an open file descriptor.
  41. .P
  42. The
  43. .IR name
  44. argument represents the variable to be queried relative to that file or
  45. directory. Implementations shall support all of the variables listed in
  46. the following table and may support others. The variables in the
  47. following table come from
  48. .IR <limits.h>
  49. or
  50. .IR <unistd.h>
  51. and the symbolic constants, defined in
  52. .IR <unistd.h> ,
  53. are the corresponding values used for
  54. .IR name .
  55. .TS
  56. center box tab(!);
  57. cB | cB | cB
  58. l | l | l.
  59. Variable!Value of \fIname\fP!Requirements
  60. _
  61. {FILESIZEBITS}!_PC_FILESIZEBITS!4,\|7
  62. {LINK_MAX}!_PC_LINK_MAX!1
  63. {MAX_CANON}!_PC_MAX_CANON!2
  64. {MAX_INPUT}!_PC_MAX_INPUT!2
  65. {NAME_MAX}!_PC_NAME_MAX!3,\|4
  66. {PATH_MAX}!_PC_PATH_MAX!4,\|5
  67. {PIPE_BUF}!_PC_PIPE_BUF!6
  68. {POSIX2_SYMLINKS}!_PC_2_SYMLINKS!4
  69. {POSIX_ALLOC_SIZE_MIN}!_PC_ALLOC_SIZE_MIN!10
  70. {POSIX_REC_INCR_XFER_SIZE}!_PC_REC_INCR_XFER_SIZE!10
  71. {POSIX_REC_MAX_XFER_SIZE}!_PC_REC_MAX_XFER_SIZE!10
  72. {POSIX_REC_MIN_XFER_SIZE}!_PC_REC_MIN_XFER_SIZE!10
  73. {POSIX_REC_XFER_ALIGN}!_PC_REC_XFER_ALIGN!10
  74. {SYMLINK_MAX}!_PC_SYMLINK_MAX!4,\|9
  75. _POSIX_CHOWN_RESTRICTED!_PC_CHOWN_RESTRICTED!7
  76. _POSIX_NO_TRUNC!_PC_NO_TRUNC!3,\|4
  77. _POSIX_VDISABLE!_PC_VDISABLE!2
  78. _POSIX_ASYNC_IO!_PC_ASYNC_IO!8
  79. _POSIX_PRIO_IO!_PC_PRIO_IO!8
  80. _POSIX_SYNC_IO!_PC_SYNC_IO!8
  81. _POSIX_TIMESTAMP_RESOLUTION!_PC_TIMESTAMP_RESOLUTION!1
  82. .TE
  83. .SS "Requirements"
  84. .IP " 1." 4
  85. If
  86. .IR path
  87. or
  88. .IR fildes
  89. refers to a directory, the value returned shall apply to the directory
  90. itself.
  91. .IP " 2." 4
  92. If
  93. .IR path
  94. or
  95. .IR fildes
  96. does not refer to a terminal file, it is unspecified whether an
  97. implementation supports an association of the variable name with the
  98. specified file.
  99. .IP " 3." 4
  100. If
  101. .IR path
  102. or
  103. .IR fildes
  104. refers to a directory, the value returned shall apply to filenames
  105. within the directory.
  106. .IP " 4." 4
  107. If
  108. .IR path
  109. or
  110. .IR fildes
  111. does not refer to a directory, it is unspecified whether an
  112. implementation supports an association of the variable name with the
  113. specified file.
  114. .IP " 5." 4
  115. If
  116. .IR path
  117. or
  118. .IR fildes
  119. refers to a directory, the value returned shall be the maximum length
  120. of a relative pathname that would not cross any mount points when the
  121. specified directory is the working directory.
  122. .IP " 6." 4
  123. If
  124. .IR path
  125. refers to a FIFO, or
  126. .IR fildes
  127. refers to a pipe or FIFO, the value returned shall apply to the
  128. referenced object. If
  129. .IR path
  130. or
  131. .IR fildes
  132. refers to a directory, the value returned shall apply to any FIFO that
  133. exists or can be created within the directory. If
  134. .IR path
  135. or
  136. .IR fildes
  137. refers to any other type of file, it is unspecified whether an
  138. implementation supports an association of the variable name with the
  139. specified file.
  140. .IP " 7." 4
  141. If
  142. .IR path
  143. or
  144. .IR fildes
  145. refers to a directory, the value returned shall apply to any files,
  146. other than directories, that exist or can be created within the
  147. directory.
  148. .IP " 8." 4
  149. If
  150. .IR path
  151. or
  152. .IR fildes
  153. refers to a directory, it is unspecified whether an implementation
  154. supports an association of the variable name with the specified file.
  155. .IP " 9." 4
  156. If
  157. .IR path
  158. or
  159. .IR fildes
  160. refers to a directory, the value returned shall be the maximum length
  161. of the string that a symbolic link in that directory can contain.
  162. .IP 10. 4
  163. If
  164. .IR path
  165. or
  166. .IR fildes
  167. des does not refer to a regular file, it is unspecified whether an
  168. implementation supports an association of the variable name with the
  169. specified file. If an implementation supports such an association for
  170. other than a regular file, the value returned is unspecified.
  171. .SH "RETURN VALUE"
  172. If
  173. .IR name
  174. is an invalid value, both
  175. \fIpathconf\fR()
  176. and
  177. \fIfpathconf\fR()
  178. shall return \-1 and set
  179. .IR errno
  180. to indicate the error.
  181. .P
  182. If the variable corresponding to
  183. .IR name
  184. is described in
  185. .IR <limits.h>
  186. as a maximum or minimum value and the variable has no limit for the
  187. path or file descriptor, both
  188. \fIpathconf\fR()
  189. and
  190. \fIfpathconf\fR()
  191. shall return \-1 without changing
  192. .IR errno .
  193. Note that indefinite limits do not imply infinite limits; see
  194. .IR <limits.h> .
  195. .P
  196. If the implementation needs to use
  197. .IR path
  198. to determine the value of
  199. .IR name
  200. and the implementation does not support the association of
  201. .IR name
  202. with the file specified by
  203. .IR path ,
  204. or if the process did not have appropriate privileges to query the
  205. file specified by
  206. .IR path ,
  207. or
  208. .IR path
  209. does not exist,
  210. \fIpathconf\fR()
  211. shall return \-1 and set
  212. .IR errno
  213. to indicate the error.
  214. .P
  215. If the implementation needs to use
  216. .IR fildes
  217. to determine the value of
  218. .IR name
  219. and the implementation does not support the association of
  220. .IR name
  221. with the file specified by
  222. .IR fildes ,
  223. or if
  224. .IR fildes
  225. is an invalid file descriptor,
  226. \fIfpathconf\fR()
  227. shall return \-1 and set
  228. .IR errno
  229. to indicate the error.
  230. .P
  231. Otherwise,
  232. \fIpathconf\fR()
  233. or
  234. \fIfpathconf\fR()
  235. shall return the current variable value for the file or directory
  236. without changing
  237. .IR errno .
  238. The value returned shall not be more restrictive than the corresponding
  239. value available to the application when it was compiled with the
  240. implementation's
  241. .IR <limits.h>
  242. or
  243. .IR <unistd.h> .
  244. .P
  245. If the variable corresponding to
  246. .IR name
  247. is dependent on an unsupported option, the results are unspecified.
  248. .SH ERRORS
  249. The
  250. \fIpathconf\fR()
  251. function shall fail if:
  252. .TP
  253. .BR EINVAL
  254. The value of
  255. .IR name
  256. is not valid.
  257. .TP
  258. .BR EOVERFLOW
  259. The value of
  260. .IR name
  261. is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than
  262. {LONG_MAX}.
  263. .br
  264. .P
  265. The
  266. \fIpathconf\fR()
  267. function may fail if:
  268. .TP
  269. .BR EACCES
  270. Search permission is denied for a component of the path prefix.
  271. .TP
  272. .BR EINVAL
  273. The implementation does not support an association of the variable
  274. .IR name
  275. with the specified file.
  276. .TP
  277. .BR ELOOP
  278. A loop exists in symbolic links encountered during resolution of the
  279. .IR path
  280. argument.
  281. .TP
  282. .BR ELOOP
  283. More than
  284. {SYMLOOP_MAX}
  285. symbolic links were encountered during resolution of the
  286. .IR path
  287. argument.
  288. .TP
  289. .BR ENAMETOOLONG
  290. .br
  291. The length of a component of a pathname is longer than
  292. {NAME_MAX}.
  293. .TP
  294. .BR ENAMETOOLONG
  295. .br
  296. The length of a pathname exceeds
  297. {PATH_MAX},
  298. or pathname resolution of a symbolic link produced an intermediate
  299. result with a length that exceeds
  300. {PATH_MAX}.
  301. .TP
  302. .BR ENOENT
  303. A component of
  304. .IR path
  305. does not name an existing file or
  306. .IR path
  307. is an empty string.
  308. .TP
  309. .BR ENOTDIR
  310. A component of the path prefix names an existing file that is neither
  311. a directory nor a symbolic link to a directory, or the
  312. .IR path
  313. argument contains at least one non-\c
  314. <slash>
  315. character and ends with one or more trailing
  316. <slash>
  317. characters and the last pathname component names an existing file
  318. that is neither a directory nor a symbolic link to a directory.
  319. .P
  320. The
  321. \fIfpathconf\fR()
  322. function shall fail if:
  323. .TP
  324. .BR EINVAL
  325. The value of
  326. .IR name
  327. is not valid.
  328. .TP
  329. .BR EOVERFLOW
  330. The value of
  331. .IR name
  332. is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than
  333. {LONG_MAX}.
  334. .P
  335. The
  336. \fIfpathconf\fR()
  337. function may fail if:
  338. .TP
  339. .BR EBADF
  340. The
  341. .IR fildes
  342. argument is not a valid file descriptor.
  343. .TP
  344. .BR EINVAL
  345. The implementation does not support an association of the variable
  346. .IR name
  347. with the specified file.
  348. .LP
  349. .IR "The following sections are informative."
  350. .SH EXAMPLES
  351. None.
  352. .SH "APPLICATION USAGE"
  353. Application developers should check whether an option, such as
  354. _POSIX_ADVISORY_INFO, is supported prior to obtaining and using values
  355. for related variables such as
  356. {POSIX_ALLOC_SIZE_MIN}.
  357. .SH RATIONALE
  358. The
  359. \fIpathconf\fR()
  360. function was proposed immediately after the
  361. \fIsysconf\fR()
  362. function when it was realized that some configurable values may differ
  363. across file system, directory, or device boundaries.
  364. .P
  365. For example,
  366. {NAME_MAX}
  367. frequently changes between System V and
  368. BSD-based file systems; System V uses a maximum of 14, BSD 255. On an
  369. implementation that provides both types of file systems, an application
  370. would be forced to limit all pathname components to 14 bytes, as this
  371. would be the value specified in
  372. .IR <limits.h>
  373. on such a system.
  374. .P
  375. Therefore, various useful values can be queried on any pathname or file
  376. descriptor, assuming that appropriate privileges
  377. are in place.
  378. .P
  379. The value returned for the variable
  380. {PATH_MAX}
  381. indicates the longest relative pathname that could be given if the
  382. specified directory is the current working directory of the process. A
  383. process may not always be able to generate a name that long and use it
  384. if a subdirectory in the pathname crosses into a more restrictive file
  385. system. Note that implementations are allowed to accept pathnames
  386. longer than
  387. {PATH_MAX}
  388. bytes long, but are not allowed to return pathnames longer than this
  389. unless the user specifies a larger buffer using a function that provides
  390. a buffer size argument.
  391. .P
  392. The value returned for the variable _POSIX_CHOWN_RESTRICTED
  393. also applies to directories that do not have file systems mounted on
  394. them. The value may change when crossing a mount point, so
  395. applications that need to know should check for each directory. (An
  396. even easier check is to try the
  397. \fIchown\fR()
  398. function and look for an error in case it happens.)
  399. .P
  400. Unlike the values returned by
  401. \fIsysconf\fR(),
  402. the pathname-oriented variables are potentially more volatile and are
  403. not guaranteed to remain constant throughout the lifetime of the process.
  404. For example, in between two calls to
  405. \fIpathconf\fR(),
  406. the file system in question may have been unmounted and remounted with
  407. different characteristics.
  408. .P
  409. Also note that most of the errors are optional. If one of the
  410. variables always has the same value on an implementation, the
  411. implementation need not look at
  412. .IR path
  413. or
  414. .IR fildes
  415. to return that value and is, therefore, not required to detect
  416. any of the errors except the meaning of
  417. .BR [EINVAL]
  418. that indicates that the value of
  419. .IR name
  420. is not valid for that variable, and the
  421. .BR [EOVERFLOW]
  422. error that indicates the value to be returned is larger than
  423. {LONG_MAX}.
  424. .P
  425. If the value of any of the limits is unspecified (logically
  426. infinite), they will not be defined in
  427. .IR <limits.h>
  428. and the
  429. \fIpathconf\fR()
  430. and
  431. \fIfpathconf\fR()
  432. functions return \-1 without changing
  433. .IR errno .
  434. This can be distinguished from the case of giving an unrecognized
  435. .IR name
  436. argument because
  437. .IR errno
  438. is set to
  439. .BR [EINVAL]
  440. in this case.
  441. .P
  442. Since \-1 is a valid return value for the
  443. \fIpathconf\fR()
  444. and
  445. \fIfpathconf\fR()
  446. functions, applications should set
  447. .IR errno
  448. to zero before calling them and check
  449. .IR errno
  450. only if the return value is \-1.
  451. .P
  452. For the case of
  453. {SYMLINK_MAX},
  454. since both
  455. \fIpathconf\fR()
  456. and
  457. \fIopen\fR()
  458. follow symbolic links, there is no way that
  459. .IR path
  460. or
  461. .IR fildes
  462. could refer to a symbolic link.
  463. .P
  464. It was the intention of IEEE\ Std 1003.1d\(hy1999 that the following variables:
  465. .sp
  466. .RS
  467. {POSIX_ALLOC_SIZE_MIN}
  468. {POSIX_REC_INCR_XFER_SIZE}
  469. {POSIX_REC_MAX_XFER_SIZE}
  470. {POSIX_REC_MIN_XFER_SIZE}
  471. {POSIX_REC_XFER_ALIGN}
  472. .RE
  473. .P
  474. only applied to regular files, but Note 10 also permits implementation
  475. of the advisory semantics on other file types unique to an
  476. implementation (for example, a character special device).
  477. .P
  478. The
  479. .BR [EOVERFLOW]
  480. error for _PC_TIMESTAMP_RESOLUTION cannot occur on POSIX-compliant
  481. file systems because POSIX requires a timestamp resolution no
  482. larger than one second. Even on 32-bit systems, this can be
  483. represented without overflow.
  484. .SH "FUTURE DIRECTIONS"
  485. None.
  486. .SH "SEE ALSO"
  487. .IR "\fIchown\fR\^(\|)",
  488. .IR "\fIconfstr\fR\^(\|)",
  489. .IR "\fIsysconf\fR\^(\|)"
  490. .P
  491. The Base Definitions volume of POSIX.1\(hy2017,
  492. .IR "\fB<limits.h>\fP",
  493. .IR "\fB<unistd.h>\fP"
  494. .P
  495. The Shell and Utilities volume of POSIX.1\(hy2017,
  496. .IR "\fIgetconf\fR\^"
  497. .\"
  498. .SH COPYRIGHT
  499. Portions of this text are reprinted and reproduced in electronic form
  500. from IEEE Std 1003.1-2017, Standard for Information Technology
  501. -- Portable Operating System Interface (POSIX), The Open Group Base
  502. Specifications Issue 7, 2018 Edition,
  503. Copyright (C) 2018 by the Institute of
  504. Electrical and Electronics Engineers, Inc and The Open Group.
  505. In the event of any discrepancy between this version and the original IEEE and
  506. The Open Group Standard, the original IEEE and The Open Group Standard
  507. is the referee document. The original Standard can be obtained online at
  508. http://www.opengroup.org/unix/online.html .
  509. .PP
  510. Any typographical or formatting errors that appear
  511. in this page are most likely
  512. to have been introduced during the conversion of the source files to
  513. man page format. To report such errors, see
  514. https://www.kernel.org/doc/man-pages/reporting_bugs.html .