pathconf or fpathconf Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

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

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, not 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.
_PC_NO_TRUNC: Returns 0 if long component names are truncated. This value is applicable only to a directory file.
_PC_VDISABLE: This is always 0. No disabling character is defined. This value is applicable only to a terminal device.

Note: The _PC_FILESIZEBITS and PC_SYNC_IO flags apply to AIX Version 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.

Notes:
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:

EINVAL

The name parameter specifies an unknown or inapplicable characteristic.

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

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:

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

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The chown subroutine, confstr subroutine, sysconf subroutine.

Files, Directories, and File Systems for Programmers, Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.