PATHCONF(2) | System Calls Manual | PATHCONF(2)

# NAME

`pathconf`, `pathconfat`, `fpathconf` — get configurable pathname variables

# SYNOPSIS

`#include <unistd.h>`

long
`pathconf`(const char *path, int name);

long
`fpathconf`(int fd, int name);

`#include <fcntl.h>`

long
`pathconfat`(int fd, const char *path, int name, int flag);

# DESCRIPTION

The `pathconf`(), `pathconfat`(), and `fpathconf`() functions provide a method for applications to determine the current value of a configurable system limit or option variable associated with a pathname or file descriptor.

For `pathconf`(), the path argument is the name of a file or directory. For `fpathconf`(), the fd argument is an open file descriptor. The name argument specifies the system variable to be queried. Symbolic constants for each name value are found in the include file `<unistd.h>`.

The available values are as follows:

`_PC_LINK_MAX`
  The maximum file link count.
`_PC_MAX_CANON`
  The maximum number of bytes in a terminal canonical input line.
`_PC_MAX_INPUT`
  The maximum number of bytes for which space is available in a terminal input queue.
`_PC_NAME_MAX`
  The maximum number of bytes in a file name.
`_PC_PATH_MAX`
  The maximum number of bytes in a pathname.
`_PC_PIPE_BUF`
  The maximum number of bytes which will be written atomically to a pipe.
`_PC_CHOWN_RESTRICTED`
  Returns 1 if appropriate privileges are required for the chown(2) system call, otherwise 0. IEEE Std 1003.1-2001 (“POSIX.1”) requires appropriate privilege in all cases, but this behavior was optional in prior editions of the standard.
`_PC_NO_TRUNC`
  Returns 1 if attempts to use pathname components longer than {`NAME_MAX`} will result in an [`ENAMETOOLONG`] error; otherwise, such components will be truncated to {`NAME_MAX`}. IEEE Std 1003.1-2001 (“POSIX.1”) requires the error in all cases, but this behavior was optional in prior editions of the standard, and some non-POSIX-compliant file systems do not support this behavior.
`_PC_VDISABLE`
  Returns the terminal character disabling value.
`_PC_2_SYMLINKS`
  Returns 1 if the filesystem supports the creation of symbolic links within the specified directory; the meaning of `_PC_2_SYMLINKS` is unspecified for non-directory files.
`_PC_ALLOC_SIZE_MIN`
  Minimum number of bytes of storage allocated for any portion of a file.
`_PC_ASYNC_IO`
  Returns 1 if asynchronous I/O is supported, otherwise 0.
`_PC_FILESIZEBITS`
  Number of bits needed to represent the maximum file size.
`_PC_PRIO_IO`
  Returns 1 if prioritized I/O is supported, otherwise 0.
`_PC_REC_INCR_XFER_SIZE`
  Recommended increment for file transfer sizes between _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE.
`_PC_REC_MAX_XFER_SIZE`
  Maximum recommended file transfer size.
`_PC_REC_MIN_XFER_SIZE`
  Minimum recommended file transfer size.
`_PC_REC_XFER_ALIGN`
  Recommended file transfer buffer alignment.
`_PC_SYMLINK_MAX`
  Maximum number of bytes in a symbolic link.
`_PC_SYNC_IO`
  Returns 1 if synchronized I/O is supported, otherwise 0.
`_PC_TIMESTAMP_RESOLUTION`
  The resolution in nanoseconds of file timestamps.

The `pathconfat`() function is equivalent to `pathconf`() except in the case where path specifies a relative path. In this case the file to be changed is determined relative to the directory associated with the file descriptor fd instead of the current working directory.

If `pathconfat`() is passed the special value `AT_FDCWD` (defined in `<fcntl.h>`) in the fd parameter, the current working directory is used. If flag is also zero, the behavior is identical to a call to `pathconf`().

The flag argument is the bitwise OR of zero or more of the following values:

`AT_SYMLINK_NOFOLLOW`
  If path names a symbolic link, then the system variable for the symbolic link is queried.

# RETURN VALUES

If the call to `pathconf`(), `pathconfat`(), or `fpathconf`() is not successful, -1 is returned and errno is set appropriately. Otherwise, if the variable is associated with functionality that does not have a limit in the system, -1 is returned and errno is not modified. Otherwise, the current variable value is returned.

# ERRORS

If any of the following conditions occur, the `pathconf`(), `pathconfat`(), and `fpathconf`() functions shall return -1 and set errno to the corresponding value.

[`EINVAL`]
  The value of the name argument is invalid.
[`EINVAL`]
  The implementation does not support an association of the variable name with the associated file.
[`EIO`]
  An I/O error occurred while reading from the file system.

`pathconf`() and `pathconfat`() will fail if:

[`ENOTDIR`]
  A component of the path prefix is not a directory.
[`ENAMETOOLONG`]
  A component of a pathname exceeded `NAME_MAX` characters (but see `_PC_NO_TRUNC` above), or an entire pathname (including the terminating NUL) exceeded `PATH_MAX` bytes.
[`ENOENT`]
  The named file does not exist.
[`EACCES`]
  Search permission is denied for a component of the path prefix.
[`ELOOP`]
  Too many symbolic links were encountered in translating the pathname.
[`EFAULT`]
  path points outside the process's allocated address space.

Additionally, the `pathconfat`() function will fail if:

[`EINVAL`]
  The value of the flag argument was neither zero nor `AT_SYMLINK_NOFOLLOW`.
[`EBADF`]
  The path argument specifies a relative path and the fd argument is neither `AT_FDCWD` nor a valid file descriptor.
[`ENOTDIR`]
  The path argument specifies a relative path and the fd argument is a valid file descriptor but it does not reference a directory.
[`EACCES`]
  The path argument specifies a relative path but search permission is denied for the directory which the fd file descriptor references.

`fpathconf`() will fail if:

[`EBADF`]
  fd is not a valid open file descriptor.

# SEE ALSO

sysctl(2), sysconf(3)

# STANDARDS

The `pathconf`() and `fpathconf`() functions conform to IEEE Std 1003.1-2008 (“POSIX.1”).

# HISTORY

The `pathconf`() and `fpathconf`() functions first appeared in 4.4BSD. The `pathconfat`() function first appeared in OpenBSD 7.6.

May 18, 2024 | Debian