Debian Codegraph @

upstream/debian-unstable/man3/fpathconf.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright 2017, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .\" FIXME Probably all of the following should be documented:
9 .\" _PC_SYNC_IO,
10 .\" _PC_ASYNC_IO,
11 .\" _PC_PRIO_IO,
12 .\" _PC_SOCK_MAXBUF,
13 .\" _PC_FILESIZEBITS,
14 .\" _PC_REC_INCR_XFER_SIZE,
15 .\" _PC_REC_MAX_XFER_SIZE,
16 .\" _PC_REC_MIN_XFER_SIZE,
17 .\" _PC_REC_XFER_ALIGN,
18 .\" _PC_ALLOC_SIZE_MIN,
19 .\" _PC_SYMLINK_MAX,
20 .\" _PC_2_SYMLINKS
21 .\"
22 .TH fpathconf 3 2026-02-08 "Linux man-pages 6.18"
23 .SH NAME
24 fpathconf, pathconf \- get configuration values for files
25 .SH LIBRARY
26 Standard C library
27 .RI ( libc ,\~ \-lc )
28 .SH SYNOPSIS
29 .nf
30 .B #include <unistd.h>
31 .P
32 .BI "long fpathconf(int " fd ", int " name );
33 .BI "long pathconf(const char *" path ", int " name );
34 .fi
35 .SH DESCRIPTION
36 .BR fpathconf ()
37 gets a value for the configuration option
38 .I name
39 for the open file descriptor
40 .IR fd .
41 .P
42 .BR pathconf ()
43 gets a value for configuration option
44 .I name
45 for the filename
46 .IR path .
47 .P
48 The corresponding macros defined in
49 .I <unistd.h>
50 are minimum values;
51 if an application wants to take advantage of
52 values which may change,
53 a call to
54 .BR fpathconf ()
55 or
56 .BR pathconf ()
57 can be made, which may yield more liberal results.
58 .P
59 Setting
60 .I name
61 equal to one of the following constants returns the following
62 configuration options:
63 .TP
64 .B _PC_LINK_MAX
65 The maximum number of links to the file.
66 If
67 .I fd
68 or
69 .I path
70 refer to a directory, then the value applies to the whole directory.
71 The corresponding macro is
72 .BR _POSIX_LINK_MAX .
73 .TP
74 .B _PC_MAX_CANON
75 The maximum length of a formatted input line, where
76 .I fd
77 or
78 .I path
79 must refer to a terminal.
80 The corresponding macro is
81 .BR _POSIX_MAX_CANON .
82 .TP
83 .B _PC_MAX_INPUT
84 The maximum length of an input line, where
85 .I fd
86 or
87 .I path
88 must refer to a terminal.
89 The corresponding macro is
90 .BR _POSIX_MAX_INPUT .
91 .TP
92 .B _PC_NAME_MAX
93 The maximum length of a filename in the directory
94 .I path
95 or
96 .I fd
97 that the process is allowed to create.
98 The corresponding macro is
99 .BR _POSIX_NAME_MAX .
100 .TP
101 .B _PC_PATH_MAX
102 The maximum length of a relative pathname when
103 .I path
104 or
105 .I fd
106 is the current working directory.
107 The corresponding macro is
108 .BR _POSIX_PATH_MAX .
109 .TP
110 .B _PC_PIPE_BUF
111 The maximum number of bytes that can be written atomically to a pipe of FIFO.
112 For
113 .BR fpathconf (),
114 .I fd
115 should refer to a pipe or FIFO.
116 For
117 .BR fpathconf (),
118 .I path
119 should refer to a FIFO or a directory;
120 in the latter case,
121 the returned value corresponds to FIFOs created in that directory.
122 The corresponding macro is
123 .BR _POSIX_PIPE_BUF .
124 .TP
125 .B _PC_CHOWN_RESTRICTED
126 This returns a positive value if the use of
127 .BR chown (2)
128 and
129 .BR fchown (2)
130 for changing a file's user ID is restricted to a process
131 with appropriate privileges,
132 and changing a file's group ID to a value other than the process's
133 effective group ID or one of its supplementary group IDs
134 is restricted to a process with appropriate privileges.
135 According to POSIX.1,
136 this variable shall always be defined with a value other than \-1.
137 The corresponding macro is
138 .BR _POSIX_CHOWN_RESTRICTED .
139 .IP
140 If
141 .I fd
142 or
143 .I path
144 refers to a directory,
145 then the return value applies to all files in that directory.
146 .TP
147 .B _PC_NO_TRUNC
148 This returns nonzero if accessing filenames longer than
149 .B _POSIX_NAME_MAX
150 generates an error.
151 The corresponding macro is
152 .BR _POSIX_NO_TRUNC .
153 .TP
154 .B _PC_VDISABLE
155 This returns nonzero if special character processing can be disabled, where
156 .I fd
157 or
158 .I path
159 must refer to a terminal.
160 .SH RETURN VALUE
161 The return value of these functions is one of the following:
162 .IP \[bu] 3
163 On error, \-1 is returned and
164 .I errno
165 is set to indicate the error
166 (for example,
167 .BR EINVAL ,
168 indicating that
169 .I name
170 is invalid).
171 .IP \[bu]
172 If
173 .I name
174 corresponds to a maximum or minimum limit, and that limit is indeterminate,
175 \-1 is returned and
176 .I errno
177 is not changed.
178 (To distinguish an indeterminate limit from an error, set
179 .I errno
180 to zero before the call, and then check whether
181 .I errno
182 is nonzero when \-1 is returned.)
183 .IP \[bu]
184 If
185 .I name
186 corresponds to an option,
187 a positive value is returned if the option is supported,
188 and \-1 is returned if the option is not supported.
189 .IP \[bu]
190 Otherwise,
191 the current value of the option or limit is returned.
192 This value will not be more restrictive than
193 the corresponding value that was described to the application in
194 .I <unistd.h>
195 or
196 .I <limits.h>
197 when the application was compiled.
198 .SH ERRORS
199 .TP
200 .B EACCES
201 .RB ( pathconf ())
202 Search permission is denied for one of the directories in the path prefix of
203 .IR path .
204 .TP
205 .B EBADF
206 .RB ( fpathconf ())
207 .I fd
208 is not a valid file descriptor.
209 .TP
210 .B EINVAL
211 .I name
212 is invalid.
213 .TP
214 .B EINVAL
215 The implementation does not support an association of
216 .I name
217 with the specified file.
218 .TP
219 .B ELOOP
220 .RB ( pathconf ())
221 Too many symbolic links were encountered while resolving
222 .IR path .
223 .TP
224 .B ENAMETOOLONG
225 .RB ( pathconf ())
226 .I path
227 is too long.
228 .TP
229 .B ENOENT
230 .RB ( pathconf ())
231 A component of
232 .I path
233 does not exist, or
234 .I path
235 is an empty string.
236 .TP
237 .B ENOTDIR
238 .RB ( pathconf ())
239 A component used as a directory in
240 .I path
241 is not in fact a directory.
242 .SH ATTRIBUTES
243 For an explanation of the terms used in this section, see
244 .BR attributes (7).
245 .TS
246 allbox;
247 lbx lb lb
248 l l l.
249 Interface Attribute Value
250 T{
251 .na
252 .nh
253 .BR fpathconf (),
254 .BR pathconf ()
255 T} Thread safety MT-Safe
256 .TE
257 .SH STANDARDS
258 POSIX.1-2008.
259 .SH HISTORY
260 POSIX.1-2001.
261 .SH NOTES
262 Files with name lengths longer than the value returned for
263 .I name
264 equal to
265 .B _PC_NAME_MAX
266 may exist in the given directory.
267 .P
268 Some returned values may be huge;
269 they are not suitable for allocating memory.
270 .SH SEE ALSO
271 .BR getconf (1),
272 .BR open (2),
273 .BR statfs (2),
274 .BR confstr (3),
275 .BR sysconf (3)