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	3,4
{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

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 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 has no limit for the path or file descriptor, both pathconf() and fpathconf() shall return -1 without changing errno. 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.

[ELOOP]

A loop exists in symbolic links encountered during resolution of the path argument.

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]

More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the path argument.

[ENAMETOOLONG]

The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

[ENAMETOOLONG]

As a result of encountering a symbolic link in resolution of the path argument, the length of the substituted pathname string exceeded {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 is not a directory.

The fpathconf() function shall fail if:

[EINVAL]

The value of name is not valid.

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.

EXAMPLES

None.

APPLICATION USAGE

Application writers 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 the appropriate permissions 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 process' current working directory. 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.

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 process' lifetime. 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.

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 eample, a character special device).

FUTURE DIRECTIONS

None.

SEE ALSO

confstr(), sysconf(), the Base Definitions volume of IEEE Std 1003.1-2001, <limits.h>, <unistd.h>, the Shell and Utilities volume of IEEE Std 1003.1-2001, getconf

CHANGE HISTORY

First released in Issue 3. Included for alignment with the POSIX.1-1988 standard.

Issue 5

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension.

Large File Summit extensions are added.

Issue 6

The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

• The DESCRIPTION is updated to include {FILESIZEBITS}.

• The [ELOOP] mandatory error condition is added.

• A second [ENAMETOOLONG] is added as an optional error condition.

The following changes were made to align with the IEEE P1003.1a draft standard:

• The _PC_SYMLINK_MAX entry is added to the table in the DESCRIPTION.

The following pathconf() variables and their associated names are added for alignment with IEEE Std 1003.1d-1999:

{POSIX_ALLOC_SIZE_MIN}
{POSIX_REC_INCR_XFER_SIZE}
{POSIX_REC_MAX_XFER_SIZE}
{POSIX_REC_MIN_XFER_SIZE}
{POSIX_REC_XFER_ALIGN}

IEEE Std 1003.1-2001/Cor 1-2002, item XSH/TC1/D6/18 is applied, changing the fourth paragraph of the DESCRIPTION and removing shading and margin markers from the table. This change is needed since implementations are required to support all of these symbols.

IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/34 is applied, adding the table entry for POSIX2_SYMLINKS in the DESCRIPTION.

IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/35 is applied, updating the DESCRIPTION and RATIONALE sections to clarify behavior for the {POSIX_ALLOC_SIZE_MIN}, {POSIX_REC_INCR_XFER_SIZE}, {POSIX_REC_MAX_XFER_SIZE}, {POSIX_REC_MIN_XFER_SIZE}, and {POSIX_REC_XFER_ALIGN} variables.

IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/36 is applied, updating the RETURN VALUE and APPLICATION USAGE sections to state that the results are unspecified if a variable is dependent on an unsupported option, and advising application writers to check for supported options prior to obtaining and using such values.