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 complete list of possible return code values, see 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. The following reason codes can accompany the return code: JRInvIoctlCmd, JRIOBufLengthInvalid and JRNotSupportedForFiletype.
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 the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

This form of ioctl may not be used with character special files. Refer to w_ioctl (BPX1IOC, BPX4IOC) 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 pathname.
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.

Characteristics and restrictions

The argument is limited to 51 200 bytes.