| blob | bf6f230c02ccb4a4db007542bb48b5c001d76280 |
1 '\" te
2 .\" Copyright (c) 1994, X/Open Company Limited. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
7 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
8 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 .\" This notice shall appear on any product containing this material.
10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
12 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 .TH FPATHCONF 2 "Sep 1, 2009"
14 .SH NAME
15 fpathconf, pathconf \- get configurable pathname variables
16 .SH SYNOPSIS
17 .LP
18 .nf
19 #include <unistd.h>
21 \fBlong\fR \fBfpathconf\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIname\fR);
22 .fi
24 .LP
25 .nf
26 \fBlong\fR \fBpathconf\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR \fIname\fR);
27 .fi
29 .SH DESCRIPTION
30 .sp
31 .LP
32 The \fBfpathconf()\fR and \fBpathconf()\fR functions determine the current
33 value of a configurable limit or option ( variable ) that is associated with a
34 file or directory.
35 .sp
36 .LP
37 For \fBpathconf()\fR, the \fIpath\fR argument points to the pathname of a file
38 or directory.
39 .sp
40 .LP
41 For \fBfpathconf()\fR, the \fIfildes\fR argument is an open file descriptor.
42 .sp
43 .LP
44 The \fIname\fR argument represents the variable to be queried relative to that
45 file or directory. The variables in the following table come from
46 <\fBlimits.h\fR> or <\fBunistd.h\fR> and the symbolic constants, defined in
47 <\fBunistd.h\fR>, are the corresponding values used for \fIname:\fR
48 .sp
50 .sp
51 .TS
52 box;
53 c | c | c
54 l | l | l .
55 Variable Value of \fIname\fR Notes
56 _
57 {\fBACL_ENABLED\fR} \fB_PC_ACL_ENABLED\fR 10
58 _
59 {\fBFILESIZEBITS\fR} \fB_PC_FILESIZEBITS\fR 3,4
60 _
61 {\fBLINK_MAX\fR} \fB_PC_LINK_MAX\fR 1
62 _
63 {\fBMAX_CANON\fR} \fB_PC_MAX_CANON\fR 2
64 _
65 {\fBMAX_INPUT\fR} \fB_PC_MAX_INPUT\fR 2
66 _
67 {\fBMIN_HOLE_SIZE\fR} \fB_PC_MIN_HOLE_SIZE\fR 11
68 _
69 {\fBNAME_MAX\fR} \fB_PC_NAME_MAX\fR 3, 4
70 _
71 {\fBPATH_MAX\fR} \fB_PC_PATH_MAX\fR 4,5
72 _
73 {\fBPIPE_BUF\fR} \fB_PC_PIPE_BUF\fR 6
74 _
75 {\fBPOSIX_ALLOC_SIZE_MIN\fR} \fB_PC_ALLOC_SIZE_MIN\fR
76 _
77 {\fBPOSIX_REC_INCR_XFER_SIZE\fR} \fB_PC_REC_INCR_XFER_SIZE\fR
78 _
79 {\fBPOSIX_REC_MAX_XFER_SIZE\fR} \fB_PC_REC_MAX_XFER_SIZE\fR
80 _
81 {\fBPOSIX_REC_MIN_XFER_SIZE\fR} \fB_PC_REC_MIN_XFER_SIZE\fR
82 _
83 {\fBPOSIX_REC_XFER_ALIGN\fR} \fB_PC_REC_XFER_ALIGN\fR
84 _
85 {\fBSYMLINK_MAX\fR} \fB_PC_SYMLINK_MAX\fR 4, 9
86 _
87 {\fBXATTR_ENABLED\fR} \fB_PC_XATTR_ENABLED\fR 1
88 _
89 {\fBSATTR_ENABLED\fR} \fB_PC_SATTR_ENABLED\fR
90 _
91 {\fBXATTR_EXISTS\fR} \fB_PC_XATTR_EXISTS\fR 1
92 _
93 {\fBSATTR_EXISTS\fR} \fB_PC_SATTR_EXISTS\fR
94 _
95 {\fBACCESS_FILTERING\fR} \fB_PC_ACCESS_FILTERING\fR 12
96 _
97 \fB_POSIX_CHOWN_RESTRICTED\fR \fB_PC_CHOWN_RESTRICTED\fR 7
98 _
99 \fB_POSIX_NO_TRUNC\fR \fB_PC_NO_TRUNC\fR 3, 4
100 _
101 \fB_POSIX_VDISABLE\fR \fB_PC_VDISABLE\fR 2
102 _
103 \fB_POSIX_ASYNC_IO\fR \fB_PC_ASYNC_IO\fR 8
104 _
105 \fB_POSIX_PRIO_IO\fR \fB_PC_PRIO_IO\fR 8
106 _
107 \fB_POSIX_SYNC_IO\fR \fB_PC_SYNC_IO\fR 8
108 _
109 \fB_POSIX_TIMESTAMP_RESOLUTION\fR \fB_PC_TIMESTAMP_RESOLUTION\fR 1
110 .TE
112 .sp
113 .LP
114 \fBNotes:\fR
115 .RS +4
116 .TP
117 1.
118 If \fIpath\fR or \fIfildes\fR refers to a directory, the value returned
119 applies to the directory itself.
120 .RE
121 .RS +4
122 .TP
123 2.
124 If \fIpath\fR or \fIfildes\fR does not refer to a terminal file, it is
125 unspecified whether an implementation supports an association of the variable
126 name with the specified file.
127 .RE
128 .RS +4
129 .TP
130 3.
131 If \fIpath\fR or \fIfildes\fR refers to a directory, the value returned
132 applies to filenames within the directory.
133 .RE
134 .RS +4
135 .TP
136 4.
137 If \fIpath\fR or \fIfildes\fR does not refer to a directory, it is
138 unspecified whether an implementation supports an association of the variable
139 name with the specified file.
140 .RE
141 .RS +4
142 .TP
143 5.
144 If \fIpath\fR or \fIfildes\fR refers to a directory, the value returned is
145 the maximum length of a relative pathname when the specified directory is the
146 working directory.
147 .RE
148 .RS +4
149 .TP
150 6.
151 If \fIpath\fR refers to a FIFO, or \fIfildes\fR refers to a pipe or FIFO,
152 the value returned applies to the referenced object. If \fIpath\fR or
153 \fIfildes\fR refers to a directory, the value returned applies to any FIFO that
154 exists or can be created within the directory. If \fIpath\fR or \fIfildes\fR
155 refers to any other type of file, it is unspecified whether an implementation
156 supports an association of the variable name with the specified file.
157 .RE
158 .RS +4
159 .TP
160 7.
161 If \fIpath\fR or \fIfildes\fR refers to a directory, the value returned
162 applies to any files, other than directories, that exist or can be created
163 within the directory.
164 .RE
165 .RS +4
166 .TP
167 8.
168 If \fIpath\fR or \fIfildes\fR refers to a directory, it is unspecified
169 whether an implementation supports an association of the variable name with the
170 specified file.
171 .RE
172 .RS +4
173 .TP
174 9.
175 If \fIpath\fR or \fIfildes\fR refers to a directory, the value returned is
176 the maximum length of the string that a symbolic link in that directory can
177 contain.
178 .RE
179 .RS +4
180 .TP
181 10.
182 If \fIpath\fR or \fIfildes\fR refers to a file or directory in a file
183 system that supports ACLs, the value returned is the bitwise inclusive OR of
184 the following flags associated with ACL types supported by the file system;
185 otherwise 0 is returned.
186 .sp
187 .ne 2
188 .na
189 \fB\fB_ACL_ACE_ENABLED\fR\fR
190 .ad
191 .RS 23n
192 The file system supports ACE ACLs.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fB_ACL_ACLENT_ENABLED\fR\fR
199 .ad
200 .RS 23n
201 The file system supports UFS aclent ACLs.
202 .RE
204 .RE
205 .RS +4
206 .TP
207 11.
208 If a filesystem supports the reporting of holes (see \fBlseek\fR(2),
209 \fBpathconf()\fR and \fBfpathconf()\fR return a positive number that represents
210 the minimum hole size returned in bytes. The offsets of holes returned will be
211 aligned to this same value. A special value of 1 is returned if the filesystem
212 does not specify the minimum hole size but still reports holes.
213 .RE
214 .RS +4
215 .TP
216 12.
217 If \fIpath\fR or \fIfildes\fR refers to a directory and the file system in
218 which the directory resides supports access filtering, a non-zero value is
219 returned. Otherwise, 0 is returned.
220 .RE
221 .SH RETURN VALUES
222 .sp
223 .LP
224 If \fIname\fR is an invalid value, both \fBpathconf()\fR and \fBfpathconf()\fR
225 return \fB\(mi1\fR and \fBerrno\fR is set to indicate the error.
226 .sp
227 .LP
228 If the variable corresponding to \fIname\fR has no limit for the \fIpath\fR or
229 file descriptor, both \fBpathconf()\fR and \fBfpathconf()\fR return \fB\(mi1\fR
230 without changing \fBerrno\fR. If \fBpathconf()\fR needs to use \fIpath\fR to
231 determine the value of \fIname\fR and \fBpathconf()\fR does not support the
232 association of \fIname\fR with the file specified by \fIpath\fR, or if the
233 process did not have appropriate privileges to query the file specified by
234 \fIpath\fR, or \fIpath\fR does not exist, \fBpathconf()\fR returns \fB\(mi1\fR
235 and \fBerrno\fR is set to indicate the error.
236 .sp
237 .LP
238 If \fBfpathconf()\fR needs to use \fIfildes\fR to determine the value of
239 \fIname\fR and \fBfpathconf()\fR does not support the association of \fIname\fR
240 with the file specified by \fIfildes\fR, or if \fIfildes\fR is an invalid file
241 descriptor, \fBfpathconf()\fR returns \fB\(mi1\fR and \fBerrno\fR is set to
242 indicate the error.
243 .sp
244 .LP
245 Otherwise \fBpathconf()\fR or \fBfpathconf()\fR returns the current variable
246 value for the file or directory without changing \fBerrno\fR. The value
247 returned will not be more restrictive than the corresponding value available to
248 the application when it was compiled with <\fBlimits.h\fR> or <\fBunistd.h\fR>.
249 .SH ERRORS
250 .sp
251 .LP
252 The \fBpathconf()\fR function will fail if:
253 .sp
254 .ne 2
255 .na
256 \fB\fBEINVAL\fR\fR
257 .ad
258 .RS 10n
259 The value of \fIname\fR is not valid.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fBELOOP\fR\fR
266 .ad
267 .RS 10n
268 A loop exists in symbolic links encountered during resolution of the \fIpath\fR
269 argument.
270 .RE
272 .sp
273 .LP
274 The \fBfpathconf()\fR function will fail if:
275 .sp
276 .ne 2
277 .na
278 \fB\fBEINVAL\fR\fR
279 .ad
280 .RS 10n
281 The value of \fIname\fR is not valid.
282 .RE
284 .sp
285 .LP
286 The \fBpathconf()\fR function may fail if:
287 .sp
288 .ne 2
289 .na
290 \fB\fBEACCES\fR\fR
291 .ad
292 .RS 16n
293 Search permission is denied for a component of the path prefix.
294 .RE
296 .sp
297 .ne 2
298 .na
299 \fB\fBEINVAL\fR\fR
300 .ad
301 .RS 16n
302 An association of the variable \fIname\fR with the specified file is not
303 supported.
304 .RE
306 .sp
307 .ne 2
308 .na
309 \fB\fBENAMETOOLONG\fR\fR
310 .ad
311 .RS 16n
312 The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR} or a pathname
313 component is longer than {\fBNAME_MAX\fR}.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fBENAMETOOLONG\fR\fR
320 .ad
321 .RS 16n
322 As a result of encountering a symbolic link in resolution of the \fIpath\fR
323 argument, the length of the substituted pathname string exceeded
324 {\fBPATH_MAX\fR}.
325 .RE
327 .sp
328 .ne 2
329 .na
330 \fB\fBENOENT\fR\fR
331 .ad
332 .RS 16n
333 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
334 empty string.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fB\fBENOTDIR\fR\fR
341 .ad
342 .RS 16n
343 A component of the path prefix is not a directory.
344 .RE
346 .sp
347 .LP
348 The \fBfpathconf()\fR function may fail if:
349 .sp
350 .ne 2
351 .na
352 \fB\fBEBADF\fR\fR
353 .ad
354 .RS 10n
355 The \fIfildes\fR argument is not a valid file descriptor.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fBEINVAL\fR\fR
362 .ad
363 .RS 10n
364 An association of the variable \fIname\fR with the specified file is not
365 supported.
366 .RE
368 .SH USAGE
369 .sp
370 .LP
371 The {\fBSYMLINK_MAX\fR} variable applies only to the \fBfpathconf()\fR
372 function.
373 .SH ATTRIBUTES
374 .sp
375 .LP
376 See \fBattributes\fR(5) for descriptions of the following attributes:
377 .sp
379 .sp
380 .TS
381 box;
382 c | c
383 l | l .
384 ATTRIBUTE TYPE ATTRIBUTE VALUE
385 _
386 Interface Stability Committed
387 _
388 MT-Level Async-Signal-Safe
389 _
390 Standard See \fBstandards\fR(5).
391 .TE
393 .SH SEE ALSO
394 .sp
395 .LP
396 \fBlseek\fR(2), \fBconfstr\fR(3C), \fBlimits.h\fR(3HEAD), \fBsysconf\fR(3C),
397 \fBattributes\fR(5), \fBstandards\fR(5)