pathconf or fpathconf Subroutine

Purpose

Retrieves file-implementation characteristics.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

long pathconf ( Path, Name) const char *Path; int Name;

long fpathconf( FileDescriptor, Name) int FileDescriptor, Name;

Description

The pathconf subroutine allows an application to determine the characteristics of operations supported by the file system contained by the file named by the Path parameter. Read, write, or execute permission of the named file is not required, but all directories in the path leading to the file must be searchable.

The fpathconf subroutine allows an application to retrieve the same information for an open file.

Parameters

Item	Description
Path	Specifies the path name.
FileDescriptor	Specifies an open file descriptor.
Name	Specifies the configuration attribute to be queried. If this attribute is not applicable to the file specified by the Path or FileDescriptor parameter, the pathconf subroutine returns an error. Symbolic values for the Name parameter are defined in the unistd.h file: _PC_LINK_MAX Specifies the maximum number of links to the file. _PC_MAX_CANON Specifies the maximum number of bytes in a canonical input line. This value is applicable only to terminal devices. _PC_MAX_INPUT Specifies the maximum number of bytes allowed in an input queue. This value is applicable only to terminal devices. _PC_NAME_MAX Specifies the maximum number of bytes in a file name, not including a terminating null character. This number can range from 14 through 255. This value is applicable only to a directory file. _PC_PATH_MAX Specifies the maximum number of bytes in a path name, including a terminating null character. _PC_PIPE_BUF Specifies the maximum number of bytes guaranteed to be written atomically. This value is applicable only to a first-in-first-out (FIFO). _PC_CHOWN_RESTRICTED Returns 0 if the use of the chown subroutine is restricted to a process with appropriate privileges, and if the chown subroutine is restricted to changing the group ID of a file only to the effective group ID of the process or to one of its supplementary group IDs. If XPG_SUS_ENV is set to ON, the _PC_CHOWN_RESTRICTED returns a value greater than zero. _PC_NO_TRUNC Returns 0 if long component names are truncated. This value is applicable only to a directory file. If XPG_SUS_ENV is set to ON, the _PC_NO_TRUNC returns a value greater than zero. _PC_VDISABLE This is always 0. No disabling character is defined. This value is applicable only to a terminal device. _PC_AIX_DISK_PARTITION Determines the physical partition size of the disk. Note: The _PC_AIX_DISK_PARTITION variable is available only to the root user. _PC_AIX_DISK_SIZE Determines the disk size in megabytes. Note: The _PC_AIX_DISK_SIZE variable is available only to the root user. Note: The _PC_FILESIZEBITS and PC_SYNC_IO flags apply to AIX® 4.3 and later releases. _PC_FILESIZEBITS Returns the minimum number of bits required to hold the file system's maximum file size as a signed integer. The smallest value returned is 32. _PC_SYNC_IO Returns -1 if the file system does not support the Synchronized Input and Output option. Any value other than -1 is returned if the file system supports the option.

Item

Description

Path

Specifies the path name.

FileDescriptor

Specifies an open file descriptor.

Name

Specifies the configuration attribute to be queried. If this attribute is not applicable to the file specified by the Path or FileDescriptor parameter, the pathconf subroutine returns an error. Symbolic values for the Name parameter are defined in the unistd.h file:

_PC_LINK_MAX: Specifies the maximum number of links to the file.
_PC_MAX_CANON: Specifies the maximum number of bytes in a canonical input line. This value is applicable only to terminal devices.
_PC_MAX_INPUT: Specifies the maximum number of bytes allowed in an input queue. This value is applicable only to terminal devices.
_PC_NAME_MAX: Specifies the maximum number of bytes in a file name, not including a terminating null character. This number can range from 14 through 255. This value is applicable only to a directory file.
_PC_PATH_MAX: Specifies the maximum number of bytes in a path name, including a terminating null character.
_PC_PIPE_BUF: Specifies the maximum number of bytes guaranteed to be written atomically. This value is applicable only to a first-in-first-out (FIFO).
_PC_CHOWN_RESTRICTED: Returns 0 if the use of the chown subroutine is restricted to a process with appropriate privileges, and if the chown subroutine is restricted to changing the group ID of a file only to the effective group ID of the process or to one of its supplementary group IDs.
If XPG_SUS_ENV is set to ON, the _PC_CHOWN_RESTRICTED returns a value greater than zero.
_PC_NO_TRUNC: Returns 0 if long component names are truncated. This value is applicable only to a directory file.
If XPG_SUS_ENV is set to ON, the _PC_NO_TRUNC returns a value greater than zero.
_PC_VDISABLE: This is always 0. No disabling character is defined. This value is applicable only to a terminal device.
_PC_AIX_DISK_PARTITION: Determines the physical partition size of the disk.
Note: The _PC_AIX_DISK_PARTITION variable is available only to the root user.
_PC_AIX_DISK_SIZE: Determines the disk size in megabytes.
Note: The _PC_AIX_DISK_SIZE variable is available only to the root user.

Note: The _PC_FILESIZEBITS and PC_SYNC_IO flags apply to AIX® 4.3 and later releases.

_PC_FILESIZEBITS: Returns the minimum number of bits required to hold the file system's maximum file size as a signed integer. The smallest value returned is 32.
_PC_SYNC_IO: Returns -1 if the file system does not support the Synchronized Input and Output option. Any value other than -1 is returned if the file system supports the option.

Note:

If the Name parameter has a value of _PC_LINK_MAX, and if the Path or FileDescriptor parameter refers to a directory, the value returned applies to the directory itself.
If the Name parameter has a value of _PC_NAME_MAX or _PC_NO_TRUNC, and if the Path or FileDescriptor parameter refers to a directory, the value returned applies to filenames within the directory.
If the Name parameter has a value if _PC_PATH_MAX, and if the Path or FileDescriptor parameter refers to a directory that is the working directory, the value returned is the maximum length of a relative pathname.
If the Name parameter has a value of _PC_PIPE_BUF, and if the Path parameter refers to a FIFO special file or the FileDescriptor parameter refers to a pipe or a FIFO special file, the value returned applies to the referenced object. If the Path or FileDescriptor parameter refers to a directory, the value returned applies to any FIFO special file that exists or can be created within the directory.
If the Name parameter has a value of _PC_CHOWN_RESTRICTED, and if the Path or FileDescriptor parameter refers to a directory, the value returned applies to any files, other than directories, that exist or can be created within the directory.

Return Values

If the pathconf or fpathconf subroutine is successful, the specified parameter is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error. If the variable corresponding to the Name parameter has no limit for the Path parameter or the FileDescriptor parameter, both the pathconf and fpathconf subroutines return a value of -1 without changing the errno global variable.

Error Codes

The pathconf or fpathconf subroutine fails if the following error occurs:

Item	Description
EINVAL	The name parameter specifies an unknown or inapplicable characteristic.

The pathconf subroutine can also fail if any of the following errors occur:

Item	Description
EACCES	Search permission is denied for a component of the path prefix.
EINVAL	The implementation does not support an association of the Name parameter with the specified file.
ENAMETOOLONG	The length of the Path parameter string exceeds the PATH_MAX value.
ENAMETOOLONG	Pathname resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX.
ENOENT	The named file does not exist or the Path parameter points to an empty string.
ENOTDIR	A component of the path prefix is not a directory.
ELOOP	Too many symbolic links were encountered in resolving path.

The fpathconf subroutine can fail if either of the following errors occur:

Item	Description
EBADF	The File Descriptor parameter is not valid.
EINVAL	The implementation does not support an association of the Name parameter with the specified file.