pathconf (BPX1PCF, BPX4PCF) — Determine configurable path name variables using a path name

Function

The pathconf callable service determines the current values of a configurable limit or option (variable) that is associated with a file or directory.

Requirements

Parameters

Pathname_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the Pathname parameter.

Pathname

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the Pathname_length parameter

The name that contains the path name of the file. The file has the length that is specified in Pathname_length.

Path names can begin with or without a slash:

• A path name that begins with a slash is an absolute path name. The slash refers to the root directory, and the search for the file starts at the root directory.
• A path name that does not begin with a slash is a relative path name. The search for the file starts at the working directory.

Name

Supplied parameter

Type:

Structure

Length:

Fullword

The name of a fullword that contains a value that indicates the configurable limit or option (variable) that is to be returned in Return_value. Use the BPXYPCF macro to specify which path name variable you want returned; see BPXYPCF — Command values for pathconf and pathconf.

Variable returned	Description
PC_CHOWN_RESTRICTED	Change ownership ( chown (BPX1CHO, BPX4CHO) — Change the owner or group of a file or directory) function is restricted to a process with appropriate privileges (see Authorization), and to changing the group ID (GID) of a file only to the effective group ID of the process or to one of its supplementary group IDs.
PC_LINK_MAX	Maximum value of a file's link count.
PC_MAX_CANON	Maximum number of bytes in a terminal canonical input line.
PC_MAX_INPUT	Minimum number of bytes for which space will be available in a terminal input queue; therefore, the maximum number of bytes a portable application may require to be typed as input before reading them.
PC_NAME_MAX	Maximum number of bytes in a filename (not a string length; count excludes a terminating null).
PC_NO_TRUNC	Path name components longer than 255 bytes generate an error.
PATH_MAX	Maximum number of bytes in a path name (not a string length; count excludes a terminating null).
PIPE_BUF	Maximum number of bytes that can be written atomically when writing to a pipe.
_POSIX_VDISABLE	Terminal special characters maintained by the system can be disabled using this character value. For information on querying and setting these special characters, see tcgetattr (BPX1TGA, BPX4TGA) — Get the attributes for a terminal or tcsetattr (BPX1TSA, BPX4TSA) — Set the attributes for a terminal.
PC_ACL	The security product supports access control lists.
PC_ACL_ENTRIES_MAX	The maximum number of entries that can be placed in an access control list for the specified file.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pathconf service returns the current value of the path name variable corresponding to the Name specified, or -1 if not successful.

If the named path name variable does not have a limit for the specified file, then Return_value is set to -1, and Return_code and Reason_code remain unchanged.

If _POSIX_CHOWN_RESTRICTED is specified for Name, and _POSIX_CHOWN_RESTRICTED is active, Return_value is set to 1.

If _POSIX_CHOWN_RESTRICTED is specified for Name, and _POSIX_CHOWN_RESTRICTED is not active, Return_value is set to 0.

If _POSIX_NO_TRUNC is specified for Name, and _POSIX_NO_TRUNC is active, Return_value is set to 1.

If _POSIX_NO_TRUNC is specified for Name, and _POSIX_NO_TRUNC is not active, Return_value is set to 0.

If PC_ACL is specified for Name, and PC_ACL is supported, Return_value is set to 1.

If PC_ACL is specified for Name, and PC_ACL is not supported, Return_value is set to 0.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pathconf service stores the return code. The pathconf service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values.

If the named path name variable does not have a limit for the specified file, Return_value is -1 and Return_code is unchanged. Otherwise the pathconf service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	Search permission is denied for a component of the path prefix.
EINVAL	See the usage notes for situations in which EINVAL is returned. The following reason code can accompany the return code: JRNotSupportedForFileType.
ELOOP	A loop exists in symbolic links that were encountered during resolution of the Pathname argument. This error is issued if more than 24 symbolic links are detected in the resolution of Pathname.
ENAMETOOLONG	Pathname is longer than 1023 characters; or some component of the path name is longer than 255 characters. Name truncation is not supported.
ENOENT	The named file does not exist; or the Pathname argument points to an empty string. The following reason code can accompany the return code: JRNotSupportedForFileType.
ENOTDIR	A component of the path prefix is not a directory.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pathconf service stores the reason code. The pathconf service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. If Name refers to MAX_CANON, MAX_INPUT, or _POSIX_VDISABLE, the following applies:
   • If Pathname does not refer to a terminal file, the function returns -1 in Return_value, and sets Return_code to EINVAL.
2. If Name refers to NAME_MAX, PATH_MAX, or _POSIX_NO_TRUNC, the following applies:
   • If Pathname does not refer to a directory, the function still returns the requested information using the parent directory of the specified file.
3. If Name refers to PC_PIPE_BUF, the following applies:
   • If Pathname refers to a pipe or a FIFO, the value that is returned applies to the referred to object itself. If Pathname refers to a directory, the value that is returned applies to any FIFOs that exist or that can be created within the directory. If Pathname refers to any other type of file, the pathconf service returns -1 in Return_value, and sets the Return_code to EINVAL.
4. If Name refers to PC_LINK_MAX, the following applies:
   • If File_descriptor refers to a directory, the value that is returned applies to the directory.

Related services

• fpathconf (BPX1FPC, BPX4FPC) — Determine configurable path name variables using a descriptor

Characteristics and restrictions

There are no restrictions on the use of the pathconf service.