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
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1PCF): | 31-bit |
AMODE (BPX4PCF): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
|
AMODE 64 callers use BPX4PCF with the same parameters.
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
- 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.
- 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.
- 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.
- 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
Characteristics and restrictions
There are no restrictions on the use of the pathconf service.
Examples
For an example using this callable service, see BPX1PCF (pathconf) example.