w_pioctl (BPX1PIO, BPX4PIO) — Path name I/O control
Function
The w_pioctl callable service conveys a command to the physical file system that owns the specified file.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1PIO): | 31-bit |
AMODE (BPX4PIO): | 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
CALL BPX1PIO,(Pathname_length,
Pathname,
Command,
Argument_length,
Argument,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4PIO 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 of the file.
- Pathname
- Supplied parameter
- Type:
- Character string
- Character set:
- No restriction
- Length:
- Specified by the Pathname_length parameter
The name of a field that contains the name of the file to be acted upon.
- Command
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the command to be passed to the Physical File System.
- Argument_length
- Parameter supplied and returned
- Type:
- Integer
- Length:
- Fullword
The name of a fullword containing the length of the argument. The length of the argument is specified as an integer value in the range 0–51 200.
- Argument
- Parameter supplied and returned
- Type:
- Defined by the Physical File System
- Character set:
- No restriction
- Length:
- Specified by the Argument_length parameter
Specifies the name of a buffer that contains the argument to be passed to the Physical File System.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the w_pioctl service returns
0
if the request is successful, or-1
if it is not successful. - Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the w_pioctl service stores the return code. The w_pioctl service returns Return_code only if Return_value is-1
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The w_pioctl service can return one of the following values in the Return_code parameter:Return_code Explanation EINVAL An incorrect Command or Argument_length was specified, or the function was directed against a character special file, or an invalid message queue was specified for the command of Iocc#RegFileInt. The following reason codes can accompany the return code: JRInvIoctlCmd, JRIOBufLengthInvalid, JRNotSupportedForFiletype and JRIpcBadId. EMVSPARM Incorrect parameters were passed to the service. The following reason codes can accompany the return code: JRNoStorage and JRInvParmLength. ENODEV The device is incorrect. The function is not supported for this file. The following reason code can accompany the return code: JRFuncNotSupported. EACCES The calling process does not have search permission for some component of the Pathname prefix; or does not have permission to perform the requested function against the specified file. ENOENT No file named Pathname was found; or no pathname was specified. The following reason code can accompany the return code: JrFileNotThere. 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 pathname is longer than 255 characters. Name truncation is not supported. ENOTDIR A component of the Pathname prefix is not a directory. EALREADY An attempt was made to unregister a file that is not registered. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the w_pioctl service stores the reason code. The w_pioctl service returns Reason_code only if Return_value is
-1
. Reason_code further qualifies the Return_code value.For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- This form of ioctl cannot be used with character special files. Refer to w_ioctl (BPX1IOC, BPX4IOC) — Control I/O for these files.
- One of the uses of this function is to edit the access control lists of DFS remote files, and to register interest in files by path name.
- This function can also be used to set or get the access options for z/OS UNIX files and directories. For more information, see the usage notes for w_ioctl (BPX1IOC, BPX4IOC) — Control I/O for descriptions of the SetfACL and GetfACL commands.
- For the command of Iocc#RegFileInt, see usage note 7 in w_ioctl (BPX1IOC, BPX4IOC) Control I/O.
Characteristics and restrictions
The argument is limited to 51 200 bytes.