1FPATHCONF(3P) POSIX Programmer's Manual FPATHCONF(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 fpathconf, pathconf — get configurable pathname variables
13
15 #include <unistd.h>
16 long fpathconf(int fildes, int name);
18 long pathconf(const char *path, int name);
19
21 The fpathconf() and pathconf() functions shall determine the current
22 value of a configurable limit or option (variable) that is associated
23 with a file or directory.
24 For pathconf(), the path argument points to the pathname of a file or
26 directory.
27 For fpathconf(), the fildes argument is an open file descriptor.
29 The name argument represents the variable to be queried relative to
31 that file or directory. Implementations shall support all of the vari‐
32 ables listed in the following table and may support others. The vari‐
33 ables in the following table come from <limits.h> or <unistd.h> and the
34 symbolic constants, defined in <unistd.h>, are the corresponding values
35 used for name.
36 ┌────────────────────────────┬──────────────────────────┬──────────────┐
38 │ Variable │ Value of name │ Requirements │
39 ├────────────────────────────┼──────────────────────────┼──────────────┤
40 │{FILESIZEBITS} │ _PC_FILESIZEBITS │ 4,7 │
41 │{LINK_MAX} │ _PC_LINK_MAX │ 1 │
42 │{MAX_CANON} │ _PC_MAX_CANON │ 2 │
43 │{MAX_INPUT} │ _PC_MAX_INPUT │ 2 │
44 │{NAME_MAX} │ _PC_NAME_MAX │ 3,4 │
45 │{PATH_MAX} │ _PC_PATH_MAX │ 4,5 │
46 │{PIPE_BUF} │ _PC_PIPE_BUF │ 6 │
47 │{POSIX2_SYMLINKS} │ _PC_2_SYMLINKS │ 4 │
48 │{POSIX_ALLOC_SIZE_MIN} │ _PC_ALLOC_SIZE_MIN │ 10 │
49 │{POSIX_REC_INCR_XFER_SIZE} │ _PC_REC_INCR_XFER_SIZE │ 10 │
50 │{POSIX_REC_MAX_XFER_SIZE} │ _PC_REC_MAX_XFER_SIZE │ 10 │
51 │{POSIX_REC_MIN_XFER_SIZE} │ _PC_REC_MIN_XFER_SIZE │ 10 │
52 │{POSIX_REC_XFER_ALIGN} │ _PC_REC_XFER_ALIGN │ 10 │
53 │{SYMLINK_MAX} │ _PC_SYMLINK_MAX │ 4,9 │
54 │_POSIX_CHOWN_RESTRICTED │ _PC_CHOWN_RESTRICTED │ 7 │
55 │_POSIX_NO_TRUNC │ _PC_NO_TRUNC │ 3,4 │
56 │_POSIX_VDISABLE │ _PC_VDISABLE │ 2 │
57 │_POSIX_ASYNC_IO │ _PC_ASYNC_IO │ 8 │
58 │_POSIX_PRIO_IO │ _PC_PRIO_IO │ 8 │
59 │_POSIX_SYNC_IO │ _PC_SYNC_IO │ 8 │
60 │_POSIX_TIMESTAMP_RESOLUTION │ _PC_TIMESTAMP_RESOLUTION │ 1 │
61 └────────────────────────────┴──────────────────────────┴──────────────┘
62 Requirements
63 1. If path or fildes refers to a directory, the value returned shall
64 apply to the directory itself.
65 2. If path or fildes does not refer to a terminal file, it is unspeci‐
67 fied whether an implementation supports an association of the vari‐
68 able name with the specified file.
69 3. If path or fildes refers to a directory, the value returned shall
71 apply to filenames within the directory.
72 4. If path or fildes does not refer to a directory, it is unspecified
74 whether an implementation supports an association of the variable
75 name with the specified file.
76 5. If path or fildes refers to a directory, the value returned shall
78 be the maximum length of a relative pathname that would not cross
79 any mount points when the specified directory is the working direc‐
80 tory.
81 6. If path refers to a FIFO, or fildes refers to a pipe or FIFO, the
83 value returned shall apply to the referenced object. If path or
84 fildes refers to a directory, the value returned shall apply to any
85 FIFO that exists or can be created within the directory. If path or
86 fildes refers to any other type of file, it is unspecified whether
87 an implementation supports an association of the variable name with
88 the specified file.
89 7. If path or fildes refers to a directory, the value returned shall
91 apply to any files, other than directories, that exist or can be
92 created within the directory.
93 8. If path or fildes refers to a directory, it is unspecified whether
95 an implementation supports an association of the variable name with
96 the specified file.
97 9. If path or fildes refers to a directory, the value returned shall
99 be the maximum length of the string that a symbolic link in that
100 directory can contain.
101 10. If path or fildes des does not refer to a regular file, it is
103 unspecified whether an implementation supports an association of
104 the variable name with the specified file. If an implementation
105 supports such an association for other than a regular file, the
106 value returned is unspecified.
107
109 If name is an invalid value, both pathconf() and fpathconf() shall
110 return -1 and set errno to indicate the error.
111 If the variable corresponding to name is described in <limits.h> as a
113 maximum or minimum value and the variable has no limit for the path or
114 file descriptor, both pathconf() and fpathconf() shall return -1 with‐
115 out changing errno. Note that indefinite limits do not imply infinite
116 limits; see <limits.h>.
117 If the implementation needs to use path to determine the value of name
119 and the implementation does not support the association of name with
120 the file specified by path, or if the process did not have appropriate
121 privileges to query the file specified by path, or path does not exist,
122 pathconf() shall return -1 and set errno to indicate the error.
123 If the implementation needs to use fildes to determine the value of
125 name and the implementation does not support the association of name
126 with the file specified by fildes, or if fildes is an invalid file
127 descriptor, fpathconf() shall return -1 and set errno to indicate the
128 error.
129 Otherwise, pathconf() or fpathconf() shall return the current variable
131 value for the file or directory without changing errno. The value
132 returned shall not be more restrictive than the corresponding value
133 available to the application when it was compiled with the implementa‐
134 tion's <limits.h> or <unistd.h>.
135 If the variable corresponding to name is dependent on an unsupported
137 option, the results are unspecified.
138
140 The pathconf() function shall fail if:
141 EINVAL The value of name is not valid.
143 EOVERFLOW
145 The value of name is _PC_TIMESTAMP_RESOLUTION and the resolution
146 is larger than {LONG_MAX}.
147 The pathconf() function may fail if:
149 EACCES Search permission is denied for a component of the path prefix.
151 EINVAL The implementation does not support an association of the vari‐
153 able name with the specified file.
154 ELOOP A loop exists in symbolic links encountered during resolution of
156 the path argument.
157 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
159 resolution of the path argument.
160 ENAMETOOLONG
162 The length of a component of a pathname is longer than
163 {NAME_MAX}.
164 ENAMETOOLONG
166 The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
167 tion of a symbolic link produced an intermediate result with a
168 length that exceeds {PATH_MAX}.
169 ENOENT A component of path does not name an existing file or path is an
171 empty string.
172 ENOTDIR
174 A component of the path prefix names an existing file that is
175 neither a directory nor a symbolic link to a directory, or the
176 path argument contains at least one non-<slash> character and
177 ends with one or more trailing <slash> characters and the last
178 pathname component names an existing file that is neither a
179 directory nor a symbolic link to a directory.
180 The fpathconf() function shall fail if:
182 EINVAL The value of name is not valid.
184 EOVERFLOW
186 The value of name is _PC_TIMESTAMP_RESOLUTION and the resolution
187 is larger than {LONG_MAX}.
188 The fpathconf() function may fail if:
190 EBADF The fildes argument is not a valid file descriptor.
192 EINVAL The implementation does not support an association of the vari‐
194 able name with the specified file.
195 The following sections are informative.
197
199 None.
200
202 Application developers should check whether an option, such as
203 _POSIX_ADVISORY_INFO, is supported prior to obtaining and using values
204 for related variables such as {POSIX_ALLOC_SIZE_MIN}.
205
207 The pathconf() function was proposed immediately after the sysconf()
208 function when it was realized that some configurable values may differ
209 across file system, directory, or device boundaries.
210 For example, {NAME_MAX} frequently changes between System V and BSD-
212 based file systems; System V uses a maximum of 14, BSD 255. On an
213 implementation that provides both types of file systems, an application
214 would be forced to limit all pathname components to 14 bytes, as this
215 would be the value specified in <limits.h> on such a system.
216 Therefore, various useful values can be queried on any pathname or file
218 descriptor, assuming that appropriate privileges are in place.
219 The value returned for the variable {PATH_MAX} indicates the longest
221 relative pathname that could be given if the specified directory is the
222 current working directory of the process. A process may not always be
223 able to generate a name that long and use it if a subdirectory in the
224 pathname crosses into a more restrictive file system. Note that imple‐
225 mentations are allowed to accept pathnames longer than {PATH_MAX} bytes
226 long, but are not allowed to return pathnames longer than this unless
227 the user specifies a larger buffer using a function that provides a
228 buffer size argument.
229 The value returned for the variable _POSIX_CHOWN_RESTRICTED also
231 applies to directories that do not have file systems mounted on them.
232 The value may change when crossing a mount point, so applications that
233 need to know should check for each directory. (An even easier check is
234 to try the chown() function and look for an error in case it happens.)
235 Unlike the values returned by sysconf(), the pathname-oriented vari‐
237 ables are potentially more volatile and are not guaranteed to remain
238 constant throughout the lifetime of the process. For example, in
239 between two calls to pathconf(), the file system in question may have
240 been unmounted and remounted with different characteristics.
241 Also note that most of the errors are optional. If one of the variables
243 always has the same value on an implementation, the implementation need
244 not look at path or fildes to return that value and is, therefore, not
245 required to detect any of the errors except the meaning of [EINVAL]
246 that indicates that the value of name is not valid for that variable,
247 and the [EOVERFLOW] error that indicates the value to be returned is
248 larger than {LONG_MAX}.
249 If the value of any of the limits is unspecified (logically infinite),
251 they will not be defined in <limits.h> and the pathconf() and fpath‐
252 conf() functions return -1 without changing errno. This can be distin‐
253 guished from the case of giving an unrecognized name argument because
254 errno is set to [EINVAL] in this case.
255 Since -1 is a valid return value for the pathconf() and fpathconf()
257 functions, applications should set errno to zero before calling them
258 and check errno only if the return value is -1.
259 For the case of {SYMLINK_MAX}, since both pathconf() and open() follow
261 symbolic links, there is no way that path or fildes could refer to a
262 symbolic link.
263 It was the intention of IEEE Std 1003.1d‐1999 that the following vari‐
265 ables:
266 {POSIX_ALLOC_SIZE_MIN} {POSIX_REC_INCR_XFER_SIZE}
268 {POSIX_REC_MAX_XFER_SIZE} {POSIX_REC_MIN_XFER_SIZE}
269 {POSIX_REC_XFER_ALIGN}
270 only applied to regular files, but Note 10 also permits implementation
272 of the advisory semantics on other file types unique to an implementa‐
273 tion (for example, a character special device).
274 The [EOVERFLOW] error for _PC_TIMESTAMP_RESOLUTION cannot occur on
276 POSIX-compliant file systems because POSIX requires a timestamp resolu‐
277 tion no larger than one second. Even on 32-bit systems, this can be
278 represented without overflow.
279
281 None.
282
284 chown(), confstr(), sysconf()
285 The Base Definitions volume of POSIX.1‐2017, <limits.h>, <unistd.h>
287 The Shell and Utilities volume of POSIX.1‐2017, getconf
289
291 Portions of this text are reprinted and reproduced in electronic form
292 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
293 table Operating System Interface (POSIX), The Open Group Base Specifi‐
294 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
295 Electrical and Electronics Engineers, Inc and The Open Group. In the
296 event of any discrepancy between this version and the original IEEE and
297 The Open Group Standard, the original IEEE and The Open Group Standard
298 is the referee document. The original Standard can be obtained online
299 at http://www.opengroup.org/unix/online.html .
300 Any typographical or formatting errors that appear in this page are
302 most likely to have been introduced during the conversion of the source
303 files to man page format. To report such errors, see https://www.ker‐
304 nel.org/doc/man-pages/reporting_bugs.html .
305IEEE/The Open Group 2017 FPATHCONF(3P)