FPATHCONF
Section: POSIX Programmer's Manual (3P)
Updated: 2017
Page Index
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.
NAME
fpathconf,
pathconf
--- get configurable pathname variables
SYNOPSIS
#include <unistd.h>
long fpathconf(int fildes, int name);
long pathconf(const char *path, int name);
DESCRIPTION
The
fpathconf()
and
pathconf()
functions shall determine the current value of a configurable limit or
option (
variable) that is associated with a file or directory.
For
pathconf(),
the
path
argument points to the pathname of a file or directory.
For
fpathconf(),
the
fildes
argument is an open file descriptor.
The
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
<limits.h>
or
<unistd.h>
and the symbolic constants, defined in
<unistd.h>,
are the corresponding values used for
name.
| Variable | Value of name | 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
|
|
Requirements
- 1.
-
If
path
or
fildes
refers to a directory, the value returned shall apply to the directory
itself.
- 2.
-
If
path
or
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.
- 3.
-
If
path
or
fildes
refers to a directory, the value returned shall apply to filenames
within the directory.
- 4.
-
If
path
or
fildes
does not refer to a directory, it is unspecified whether an
implementation supports an association of the variable name with the
specified file.
- 5.
-
If
path
or
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.
- 6.
-
If
path
refers to a FIFO, or
fildes
refers to a pipe or FIFO, the value returned shall apply to the
referenced object. If
path
or
fildes
refers to a directory, the value returned shall apply to any FIFO that
exists or can be created within the directory. If
path
or
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.
- 7.
-
If
path
or
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.
- 8.
-
If
path
or
fildes
refers to a directory, it is unspecified whether an implementation
supports an association of the variable name with the specified file.
- 9.
-
If
path
or
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.
- 10.
-
If
path
or
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.
RETURN VALUE
If
name
is an invalid value, both
pathconf()
and
fpathconf()
shall return -1 and set
errno
to indicate the error.
If the variable corresponding to
name
is described in
<limits.h>
as a maximum or minimum value and the variable has no limit for the
path or file descriptor, both
pathconf()
and
fpathconf()
shall return -1 without changing
errno.
Note that indefinite limits do not imply infinite limits; see
<limits.h>.
If the implementation needs to use
path
to determine the value of
name
and the implementation does not support the association of
name
with the file specified by
path,
or if the process did not have appropriate privileges to query the
file specified by
path,
or
path
does not exist,
pathconf()
shall return -1 and set
errno
to indicate the error.
If the implementation needs to use
fildes
to determine the value of
name
and the implementation does not support the association of
name
with the file specified by
fildes,
or if
fildes
is an invalid file descriptor,
fpathconf()
shall return -1 and set
errno
to indicate the error.
Otherwise,
pathconf()
or
fpathconf()
shall return the current variable value for the file or directory
without changing
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
<limits.h>
or
<unistd.h>.
If the variable corresponding to
name
is dependent on an unsupported option, the results are unspecified.
ERRORS
The
pathconf()
function shall fail if:
- EINVAL
-
The value of
name
is not valid.
- EOVERFLOW
-
The value of
name
is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than
{LONG_MAX}.
The
pathconf()
function may fail if:
- EACCES
-
Search permission is denied for a component of the path prefix.
- EINVAL
-
The implementation does not support an association of the variable
name
with the specified file.
- ELOOP
-
A loop exists in symbolic links encountered during resolution of the
path
argument.
- ELOOP
-
More than
{SYMLOOP_MAX}
symbolic links were encountered during resolution of the
path
argument.
- ENAMETOOLONG
-
The length of a component of a pathname is longer than
{NAME_MAX}.
- ENAMETOOLONG
-
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}.
- ENOENT
-
A component of
path
does not name an existing file or
path
is an empty string.
- 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
path
argument contains at least one non-<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.
The
fpathconf()
function shall fail if:
- EINVAL
-
The value of
name
is not valid.
- EOVERFLOW
-
The value of
name
is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than
{LONG_MAX}.
The
fpathconf()
function may fail if:
- EBADF
-
The
fildes
argument is not a valid file descriptor.
- EINVAL
-
The implementation does not support an association of the variable
name
with the specified file.
The following sections are informative.
EXAMPLES
None.
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}.
RATIONALE
The
pathconf()
function was proposed immediately after the
sysconf()
function when it was realized that some configurable values may differ
across file system, directory, or device boundaries.
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
<limits.h>
on such a system.
Therefore, various useful values can be queried on any pathname or file
descriptor, assuming that appropriate privileges
are in place.
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.
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
chown()
function and look for an error in case it happens.)
Unlike the values returned by
sysconf(),
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
pathconf(),
the file system in question may have been unmounted and remounted with
different characteristics.
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
path
or
fildes
to return that value and is, therefore, not required to detect
any of the errors except the meaning of
[EINVAL]
that indicates that the value of
name
is not valid for that variable, and the
[EOVERFLOW]
error that indicates the value to be returned is larger than
{LONG_MAX}.
If the value of any of the limits is unspecified (logically
infinite), they will not be defined in
<limits.h>
and the
pathconf()
and
fpathconf()
functions return -1 without changing
errno.
This can be distinguished from the case of giving an unrecognized
name
argument because
errno
is set to
[EINVAL]
in this case.
Since -1 is a valid return value for the
pathconf()
and
fpathconf()
functions, applications should set
errno
to zero before calling them and check
errno
only if the return value is -1.
For the case of
{SYMLINK_MAX},
since both
pathconf()
and
open()
follow symbolic links, there is no way that
path
or
fildes
could refer to a symbolic link.
It was the intention of IEEE Std 1003.1d-1999 that the following variables:
-
{POSIX_ALLOC_SIZE_MIN}
{POSIX_REC_INCR_XFER_SIZE}
{POSIX_REC_MAX_XFER_SIZE}
{POSIX_REC_MIN_XFER_SIZE}
{POSIX_REC_XFER_ALIGN}
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).
The
[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.
FUTURE DIRECTIONS
None.
SEE ALSO
chown(),
confstr(),
sysconf()
The Base Definitions volume of POSIX.1-2017,
<limits.h>,
<unistd.h>
The Shell and Utilities volume of POSIX.1-2017,
getconf
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 .
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 .