fpathconf.3p (13196B)
- '\" et
- .TH FPATHCONF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- fpathconf,
- pathconf
- \(em get configurable pathname variables
- .SH SYNOPSIS
- .LP
- .nf
- #include <unistd.h>
- .P
- long fpathconf(int \fIfildes\fP, int \fIname\fP);
- long pathconf(const char *\fIpath\fP, int \fIname\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIfpathconf\fR()
- and
- \fIpathconf\fR()
- functions shall determine the current value of a configurable limit or
- option (\fIvariable\fP) that is associated with a file or directory.
- .P
- For
- \fIpathconf\fR(),
- the
- .IR path
- argument points to the pathname of a file or directory.
- .P
- For
- \fIfpathconf\fR(),
- the
- .IR fildes
- argument is an open file descriptor.
- .P
- The
- .IR name
- argument represents the variable to be queried relative to that file or
- directory. Implementations shall support all of the variables listed in
- the following table and may support others. The variables in the
- following table come from
- .IR <limits.h>
- or
- .IR <unistd.h>
- and the symbolic constants, defined in
- .IR <unistd.h> ,
- are the corresponding values used for
- .IR name .
- .TS
- center box tab(!);
- cB | cB | cB
- l | l | l.
- Variable!Value of \fIname\fP!Requirements
- _
- {FILESIZEBITS}!_PC_FILESIZEBITS!4,\|7
- {LINK_MAX}!_PC_LINK_MAX!1
- {MAX_CANON}!_PC_MAX_CANON!2
- {MAX_INPUT}!_PC_MAX_INPUT!2
- {NAME_MAX}!_PC_NAME_MAX!3,\|4
- {PATH_MAX}!_PC_PATH_MAX!4,\|5
- {PIPE_BUF}!_PC_PIPE_BUF!6
- {POSIX2_SYMLINKS}!_PC_2_SYMLINKS!4
- {POSIX_ALLOC_SIZE_MIN}!_PC_ALLOC_SIZE_MIN!10
- {POSIX_REC_INCR_XFER_SIZE}!_PC_REC_INCR_XFER_SIZE!10
- {POSIX_REC_MAX_XFER_SIZE}!_PC_REC_MAX_XFER_SIZE!10
- {POSIX_REC_MIN_XFER_SIZE}!_PC_REC_MIN_XFER_SIZE!10
- {POSIX_REC_XFER_ALIGN}!_PC_REC_XFER_ALIGN!10
- {SYMLINK_MAX}!_PC_SYMLINK_MAX!4,\|9
- _POSIX_CHOWN_RESTRICTED!_PC_CHOWN_RESTRICTED!7
- _POSIX_NO_TRUNC!_PC_NO_TRUNC!3,\|4
- _POSIX_VDISABLE!_PC_VDISABLE!2
- _POSIX_ASYNC_IO!_PC_ASYNC_IO!8
- _POSIX_PRIO_IO!_PC_PRIO_IO!8
- _POSIX_SYNC_IO!_PC_SYNC_IO!8
- _POSIX_TIMESTAMP_RESOLUTION!_PC_TIMESTAMP_RESOLUTION!1
- .TE
- .SS "Requirements"
- .IP " 1." 4
- If
- .IR path
- or
- .IR fildes
- refers to a directory, the value returned shall apply to the directory
- itself.
- .IP " 2." 4
- If
- .IR path
- or
- .IR fildes
- does not refer to a terminal file, it is unspecified whether an
- implementation supports an association of the variable name with the
- specified file.
- .IP " 3." 4
- If
- .IR path
- or
- .IR fildes
- refers to a directory, the value returned shall apply to filenames
- within the directory.
- .IP " 4." 4
- If
- .IR path
- or
- .IR fildes
- does not refer to a directory, it is unspecified whether an
- implementation supports an association of the variable name with the
- specified file.
- .IP " 5." 4
- If
- .IR path
- or
- .IR fildes
- refers to a directory, the value returned shall be the maximum length
- of a relative pathname that would not cross any mount points when the
- specified directory is the working directory.
- .IP " 6." 4
- If
- .IR path
- refers to a FIFO, or
- .IR fildes
- refers to a pipe or FIFO, the value returned shall apply to the
- referenced object. If
- .IR path
- or
- .IR fildes
- refers to a directory, the value returned shall apply to any FIFO that
- exists or can be created within the directory. If
- .IR path
- or
- .IR fildes
- refers to any other type of file, it is unspecified whether an
- implementation supports an association of the variable name with the
- specified file.
- .IP " 7." 4
- If
- .IR path
- or
- .IR fildes
- refers to a directory, the value returned shall apply to any files,
- other than directories, that exist or can be created within the
- directory.
- .IP " 8." 4
- If
- .IR path
- or
- .IR fildes
- refers to a directory, it is unspecified whether an implementation
- supports an association of the variable name with the specified file.
- .IP " 9." 4
- If
- .IR path
- or
- .IR fildes
- refers to a directory, the value returned shall be the maximum length
- of the string that a symbolic link in that directory can contain.
- .IP 10. 4
- If
- .IR path
- or
- .IR fildes
- des does not refer to a regular file, it is unspecified whether an
- implementation supports an association of the variable name with the
- specified file. If an implementation supports such an association for
- other than a regular file, the value returned is unspecified.
- .SH "RETURN VALUE"
- If
- .IR name
- is an invalid value, both
- \fIpathconf\fR()
- and
- \fIfpathconf\fR()
- shall return \-1 and set
- .IR errno
- to indicate the error.
- .P
- If the variable corresponding to
- .IR name
- is described in
- .IR <limits.h>
- as a maximum or minimum value and the variable has no limit for the
- path or file descriptor, both
- \fIpathconf\fR()
- and
- \fIfpathconf\fR()
- shall return \-1 without changing
- .IR errno .
- Note that indefinite limits do not imply infinite limits; see
- .IR <limits.h> .
- .P
- If the implementation needs to use
- .IR path
- to determine the value of
- .IR name
- and the implementation does not support the association of
- .IR name
- with the file specified by
- .IR path ,
- or if the process did not have appropriate privileges to query the
- file specified by
- .IR path ,
- or
- .IR path
- does not exist,
- \fIpathconf\fR()
- shall return \-1 and set
- .IR errno
- to indicate the error.
- .P
- If the implementation needs to use
- .IR fildes
- to determine the value of
- .IR name
- and the implementation does not support the association of
- .IR name
- with the file specified by
- .IR fildes ,
- or if
- .IR fildes
- is an invalid file descriptor,
- \fIfpathconf\fR()
- shall return \-1 and set
- .IR errno
- to indicate the error.
- .P
- Otherwise,
- \fIpathconf\fR()
- or
- \fIfpathconf\fR()
- shall return the current variable value for the file or directory
- without changing
- .IR errno .
- The value returned shall not be more restrictive than the corresponding
- value available to the application when it was compiled with the
- implementation's
- .IR <limits.h>
- or
- .IR <unistd.h> .
- .P
- If the variable corresponding to
- .IR name
- is dependent on an unsupported option, the results are unspecified.
- .SH ERRORS
- The
- \fIpathconf\fR()
- function shall fail if:
- .TP
- .BR EINVAL
- The value of
- .IR name
- is not valid.
- .TP
- .BR EOVERFLOW
- The value of
- .IR name
- is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than
- {LONG_MAX}.
- .br
- .P
- The
- \fIpathconf\fR()
- function may fail if:
- .TP
- .BR EACCES
- Search permission is denied for a component of the path prefix.
- .TP
- .BR EINVAL
- The implementation does not support an association of the variable
- .IR name
- with the specified file.
- .TP
- .BR ELOOP
- A loop exists in symbolic links encountered during resolution of the
- .IR path
- argument.
- .TP
- .BR ELOOP
- More than
- {SYMLOOP_MAX}
- symbolic links were encountered during resolution of the
- .IR path
- argument.
- .TP
- .BR ENAMETOOLONG
- .br
- The length of a component of a pathname is longer than
- {NAME_MAX}.
- .TP
- .BR ENAMETOOLONG
- .br
- The length of a pathname exceeds
- {PATH_MAX},
- or pathname resolution of a symbolic link produced an intermediate
- result with a length that exceeds
- {PATH_MAX}.
- .TP
- .BR ENOENT
- A component of
- .IR path
- does not name an existing file or
- .IR path
- is an empty string.
- .TP
- .BR ENOTDIR
- A component of the path prefix names an existing file that is neither
- a directory nor a symbolic link to a directory, or the
- .IR path
- argument contains at least one non-\c
- <slash>
- character and ends with one or more trailing
- <slash>
- characters and the last pathname component names an existing file
- that is neither a directory nor a symbolic link to a directory.
- .P
- The
- \fIfpathconf\fR()
- function shall fail if:
- .TP
- .BR EINVAL
- The value of
- .IR name
- is not valid.
- .TP
- .BR EOVERFLOW
- The value of
- .IR name
- is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than
- {LONG_MAX}.
- .P
- The
- \fIfpathconf\fR()
- function may fail if:
- .TP
- .BR EBADF
- The
- .IR fildes
- argument is not a valid file descriptor.
- .TP
- .BR EINVAL
- The implementation does not support an association of the variable
- .IR name
- with the specified file.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- Application developers should check whether an option, such as
- _POSIX_ADVISORY_INFO, is supported prior to obtaining and using values
- for related variables such as
- {POSIX_ALLOC_SIZE_MIN}.
- .SH RATIONALE
- The
- \fIpathconf\fR()
- function was proposed immediately after the
- \fIsysconf\fR()
- function when it was realized that some configurable values may differ
- across file system, directory, or device boundaries.
- .P
- For example,
- {NAME_MAX}
- frequently changes between System V and
- BSD-based file systems; System V uses a maximum of 14, BSD 255. On an
- implementation that provides both types of file systems, an application
- would be forced to limit all pathname components to 14 bytes, as this
- would be the value specified in
- .IR <limits.h>
- on such a system.
- .P
- Therefore, various useful values can be queried on any pathname or file
- descriptor, assuming that appropriate privileges
- are in place.
- .P
- The value returned for the variable
- {PATH_MAX}
- indicates the longest relative pathname that could be given if the
- specified directory is the current working directory of the process. A
- process may not always be able to generate a name that long and use it
- if a subdirectory in the pathname crosses into a more restrictive file
- system. Note that implementations are allowed to accept pathnames
- longer than
- {PATH_MAX}
- bytes long, but are not allowed to return pathnames longer than this
- unless the user specifies a larger buffer using a function that provides
- a buffer size argument.
- .P
- The value returned for the variable _POSIX_CHOWN_RESTRICTED
- also applies to directories that do not have file systems mounted on
- them. The value may change when crossing a mount point, so
- applications that need to know should check for each directory. (An
- even easier check is to try the
- \fIchown\fR()
- function and look for an error in case it happens.)
- .P
- Unlike the values returned by
- \fIsysconf\fR(),
- the pathname-oriented variables are potentially more volatile and are
- not guaranteed to remain constant throughout the lifetime of the process.
- For example, in between two calls to
- \fIpathconf\fR(),
- the file system in question may have been unmounted and remounted with
- different characteristics.
- .P
- Also note that most of the errors are optional. If one of the
- variables always has the same value on an implementation, the
- implementation need not look at
- .IR path
- or
- .IR fildes
- to return that value and is, therefore, not required to detect
- any of the errors except the meaning of
- .BR [EINVAL]
- that indicates that the value of
- .IR name
- is not valid for that variable, and the
- .BR [EOVERFLOW]
- error that indicates the value to be returned is larger than
- {LONG_MAX}.
- .P
- If the value of any of the limits is unspecified (logically
- infinite), they will not be defined in
- .IR <limits.h>
- and the
- \fIpathconf\fR()
- and
- \fIfpathconf\fR()
- functions return \-1 without changing
- .IR errno .
- This can be distinguished from the case of giving an unrecognized
- .IR name
- argument because
- .IR errno
- is set to
- .BR [EINVAL]
- in this case.
- .P
- Since \-1 is a valid return value for the
- \fIpathconf\fR()
- and
- \fIfpathconf\fR()
- functions, applications should set
- .IR errno
- to zero before calling them and check
- .IR errno
- only if the return value is \-1.
- .P
- For the case of
- {SYMLINK_MAX},
- since both
- \fIpathconf\fR()
- and
- \fIopen\fR()
- follow symbolic links, there is no way that
- .IR path
- or
- .IR fildes
- could refer to a symbolic link.
- .P
- It was the intention of IEEE\ Std 1003.1d\(hy1999 that the following variables:
- .sp
- .RS
- {POSIX_ALLOC_SIZE_MIN}
- {POSIX_REC_INCR_XFER_SIZE}
- {POSIX_REC_MAX_XFER_SIZE}
- {POSIX_REC_MIN_XFER_SIZE}
- {POSIX_REC_XFER_ALIGN}
- .RE
- .P
- only applied to regular files, but Note 10 also permits implementation
- of the advisory semantics on other file types unique to an
- implementation (for example, a character special device).
- .P
- The
- .BR [EOVERFLOW]
- error for _PC_TIMESTAMP_RESOLUTION cannot occur on POSIX-compliant
- file systems because POSIX requires a timestamp resolution no
- larger than one second. Even on 32-bit systems, this can be
- represented without overflow.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIchown\fR\^(\|)",
- .IR "\fIconfstr\fR\^(\|)",
- .IR "\fIsysconf\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<limits.h>\fP",
- .IR "\fB<unistd.h>\fP"
- .P
- The Shell and Utilities volume of POSIX.1\(hy2017,
- .IR "\fIgetconf\fR\^"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .