The w_ioctl callable service conveys a command to a device. The specific actions that are specified by the w_ioctl callable service vary by device and physical file system, and are defined by the device driver or physical file system.
The SIOCGPARTNERINFO ioctl provides an interface for an application to retrieve information about its partner, including connection routing information, the user ID of the partner, or both. Refer to z/OS Communications Server: IP Programmer's Guide and Reference for details.
The SIOCSPARTNERINFO ioctl provides an interface for an application to set up the environment that is required to retrieve the user ID of its partner using the SIOCGPARTNERINFO ioctl. Issuing the SIOCSPARTNERINFO ioctl prior to the SIOCGPARTNERINFO ioctl can provide better performance, potentially eliminating wait time when issuing the SIOCGPARTNERINFO ioctl. Refer to z/OS Communications Server: IP Programmer's Guide and Reference for details.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task or SRB (AF_INET/AF_INET6 socket support only) |
Cross memory mode: | PASN = HASN |
AMODE (BPX1IOC): | 31-bit task or SRB mode |
AMODE (BPX4IOC): | 64-bit task mode only |
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. |
|
AMODE 64 callers use BPX4IOC with the same parameters.
The name of a fullword that contains the file descriptor of an open file or a socket descriptor.
The name of a fullword that contains the ioctl command that is to be passed to the device driver or physical file system.
See BPXYIOCC — Ioctl command definitions for a complete list of the commands that are supported.
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.
Specifies the name of a buffer, of length Argument_Length, containing the argument to be passed to the device driver or physical file system.
Return_value | Explanation |
---|---|
0 | Request was successful. For the getfacl command, return_value contains the FACL length if the request is successful. |
-1 | Request was not successful. |
1 | The SIOCSECENVR ioctl with the SIOC#GETENVR argument was issued and the buffer size specified with the SECO_BUFFERLEN argument was zero or was not large enough to contain the security object. (See usage note 18.) |
Return_code | Explanation |
---|---|
EBADF | The fildes parameter is not a valid file or socket descriptor. The following reason code can accompany the return code: JrFileNotOpen. |
EFAULT | The address is incorrect. The following reason codes can accompany the return code: JrReadUserStorageFailed, JrWriteUserStorageFailed. |
EINVAL | One of the following occurred:
The following reason codes can accompany the return code: JRInvIoctlCmd, JrNotSupportedForFileType, JrFileNotOpen, JrBadSubField. |
EIO | One of the following occurred:
The following reason codes can accompany the return code: JRSingleTDRegd, JRPrevSockError. |
EMVSPARM | Incorrect parameters were passed to the service. The following reason codes can accompany the return code: JRNoStorage and JRInvParmLength. |
ENOBUFS | Insufficient buffer space available. The following reason code can accompany the return code: JrNoArea. |
ENODEV | The device is incorrect. The function is not supported by the device driver. The following reason code can accompany the return code: JRFuncNotSupported. |
ENOTTY | The w_ioctl service specified an incorrect file descriptor. The file type was not character special. The following reason code can accompany the return code: JRNotSupportedForFileType. |
EALREADY | An attempt was made to unregister a file that is not registered. |
E2BIG | The argument_length passed on a SetfACL or GetfACL request was not large enough to contain even the minimum amount of data. The size specified must be large enough to hold a RACL_Edit, followed by an FACL and as many FACL_Entry(s) as needed. |
EIBMBADTCPNAME | The command passed was IOCC#DIRIOCTL, and the stack name was
not found attached to this socket. The specific error is determined
by the reason code that accompanies this return code:
|
The name of a fullword in which the w_ioctl service stores the reason code. The w_ioctl 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.
TIOCGWINSZ and TIOCSWINSZ retrieve and store the winsize structure (BPXYWNSZ). TIOCNOTIFY sets the TIOCXPKT_PWBEGIN and TIOCXPKT_PWEND bits on master read() when in extended packet mode.
This function is intended for use by runtime libraries.
The Argument buffer contains an UPDTOFTE subcommand and the offset, length, and value of the data to be updated. Refer to the BPXYIOCC macro for the mapping of this structure.
Data written to or read from the state area is addressed by offset and length within the state area. The state area is initialized to all zeros when it is allocated.
The specified data value is written to the specified offset in the state area. This subcommand also initially allocates the area and must be the first UPDTOFTE subcommand issued.
The data at the specified offset in the state area is returned.
This is used for a "compare and swap" type write to the state area. The specified old_value is compared to what is currently in the state area at the old_offset. If they match, the new_value is written to the new_offset. If they do not match, the current data at the old_offset in the state area is returned in the old_value along with a Return_Value of 1. The old data and the new data do not have to be at the same offset within the state area.
All of the subcommand operations are atomic with respect to other tasks attempting to access the same OFTE state area.
The program creates one or more IPC message queues and specifies a Queue Id on each registration, along with a message type and a user token that identifies the file to the program. These are specified in the Rfis structure in the BPXYRFIS macro. See BPXYRFIS — Map the register file interest structures. A Registered File Token, RfTok, is returned from the registration; this can be used later to unregister the file.
You can register files by descriptor with the w_ioctl service, or by path name with the w_pioctl service.
Because a registered file is implicitly unregistered when a message is sent, only one message is sent for any given registration.
A file can be explicitly unregistered with the w_ioctl or the w_pioctl service. An Rfis structure is passed on these calls that contains the RfTok that was returned when the file was registered. The file descriptor or path name that is used on the call is not important, but it must be valid. If the registered file is no longer open, and its file descriptor is therefore not readily available, you can use the w_pioctl service with a path name of “/”.
If you try to unregister a file that has already been implicitly or explicitly unregistered, the call fails with EALREADY. If you receive this return code, there may be a message waiting for you on the queue, so you should coordinate the freeing of any file-related control blocks that might be referenced when that message is read.
All file registrations are removed if the registering process terminates or issues an exec-type call and no messages are sent.
To receive a change message, the queue must be writable by anyone who might change the files, so we recommend that you create the queue with permission bits of 622.
The queue must be large enough to accommodate the expected number of unprocessed messages, and the messages must be processed fast enough so that the system limit on total outstanding messages is not exceeded. Messages that cannot be queued immediately are discarded, but the fact that messages were lost is remembered. This information is communicated to the application in one of two ways: (1) the Rfim_LostMsgs flag is set on subsequent change messages sent to this process until a message is successfully queued; or (2) the Rfis_LostMsgs flag is returned on the next successful registration or unregistration.
Program errors can also prevent messages from being delivered; for example, if a bad queue id is specified on registration. When a message cannot be delivered, a Ctrace entry is written for component SYSOMVS of type FILE. The trace entry contains the character string “RFIPCERR”, the returned failure codes from the msgsnd service, the queue id used, and the message that was being sent. You can use this information during program development to diagnose simple bugs.
A registered file does not have to be open to be, or to remain, registered.
A file can be registered multiple times, and by different processes. Each registration causes a separate message when the file is changed.
Any file type can be registered, but some change events only apply to regular files. In particular, writes to a directory (that is, file creation and deletion) do not generate a change message for a registered directory.
No special authority is required to register a file. Any file that the caller has open or is allowed to make stat() calls to can be registered.
Registration and file change notification are intended for use by programs that would otherwise issue periodic stat() or fstat() calls to monitor a file's time stamps in order to detect changes to the file.
Upon successful return, the buffer holds the requested ACLs. Therefore, the size of the buffer passed to BPX1IOC (specified by Argument_length) must be big enough to hold the returned ACLs. If it is not big enough, another call will be needed. The maximum number of ACL entries is 1024.
Field name | Value |
---|---|
RACL_EDIT_OPTYPE | 0 |
RACL_EDIT_ACLTYPE | The type of ACL being requested (RACL_ACCESS, for instance). You must issue separate calls for access and default ACLs. |
FACL_ID | FACL |
FACL_LEN | Size of FACL (FACL_LENGTH) |
FACL_LEN_ENTRY | FACL_ENTRY_LENGTH |
FACL_VERS | Version number (for example, X'01') |
(length of RACL_EDIT structure) + (FACL_NUM_ENTRY × FACL_LEN_ENTRY)
The
entries start at FACL_ENTRIES and are mapped by FACL_ENTRY. Field name | Value |
---|---|
RACL_EDIT_OPTYPE | RACL_DELETE |
RACL_EDIT_ACLTYPE | RACL_ACCESS, RACL_FILEMOD, or RACL_DIRMOD |
Field name | Value |
---|---|
RACL_EDIT_OPTYPE | RACL_ADD |
RACL_EDIT_ACLTYPE | RACL_ACCESS, RACL_FILEMOD, or RACL_DIRMOD |
FACL_ID | FACL |
FACL_LEN | FACL_LENGTH + (number
of FACL_ENTRYs × FACL_ENTRY_LENGTH) Note: Do not include the length
of RACL_EDIT.
|
FACL_LEN_ENTRY | FACL_ENTRY_LENGTH |
FACL_VERS | Version number (for example, X'01') |
FACL_NUM_ENTRY | Number of FACL_ENTRY blocks in the buffer |
Set the following fields for each FACL_ENTRY, as appropriate: | |
FACL_READ | 1 (to give permission) |
FACL_WRITE | 1 (to give permission) |
FACL_EXECUTE | 1 (to give permission) |
FACL_ENTRY_TYPE | X'01' for user or X'02' for group |
FACL_ENTRY_ID | UID or GID (in decimal), based on FACL_ENTRY_TYPE |
Field name | Value |
---|---|
RACL_EDIT_OPTYPE | RACL_MODIFY |
RACL_EDIT_ACLTYPE | RACL_ACCESS, RACL_FILEMOD, or RACL_DIRMOD |
FACL_ID | FACL |
FACL_LEN | FACL_LENGTH + (number
of FACL_ENTRYs × FACL_ENTRY_LENGTH) Note: Do not include the length
of RACL_EDIT.
|
FACL_LEN_ENTRY | FACL_ENTRY_LENGTH |
FACL_VERS | Version number (for example, X'01') |
FACL_NUM_ENTRY | Number of FACL_ENTRY blocks in the buffer |
Set the following fields for each FACL_ENTRY, as appropriate: | |
FACL_READ | 1 (to give permission) |
FACL_WRITE | 1 (to give permission) |
FACL_EXECUTE | 1 (to give permission) |
FACL_ENTRY_TYPE | X'01' for user or X'02' for group |
FACL_ENTRY_ID | UID or GID (in decimal), based on FACL_ENTRY_TYPE |
Field name | Value |
---|---|
RACL_EDIT_OPTYPE | RACL_MODIFY |
RACL_EDIT_ACLTYPE | RACL_ACCESS, RACL_FILEMOD, or RACL_DIRMOD |
FACL_ID | FACL |
FACL_LEN | FACL_LENGTH + (number
of FACL_EDIT_ENTRYs × FACL_ENTRY_LENGTH) Note: Do not include the
length of RACL_EDIT.
|
FACL_LEN_ENTRY | FACL_ENTRY_LENGTH |
FACL_VERS | Version number (for example, X'01') |
FACL_NUM_ENTRY | Number of FACL_EDIT_ENTRY blocks in the buffer |
Set the following fields for each FACL_EDIT_ENTRY to be deleted: | |
FACL_DEL_ENTRY | 1 |
FACL_EDIT_TYPE | X'01' for user or X'02' for group |
The imbedded ioctl is passed to the specified stack, if that stack is attached to this socket, without any examination or processing by the system. Any errors that are returned are usually returned by the stack. Directed Ioctl is not strictly restricted to socket stacks. The name should match the PFS name for the descriptor that is used.
If the imbedded ioctl generates output in its argument buffer, the output is returned in the IocDirArg buffer.
A unique error can be returned by z/OS UNIX System Services for this ioctl command, EIBMBADTCPNAME, when the stack name is not found attached to this socket.
This ioctl is not strictly restricted to socket stacks; however, with any other type of Physical File System, all of the socket-related flags would be off.
Tip: You can use the PC#TdNames pfsctl command function of the pfsctl (BPX1PCT, BPX4PCT) service to obtain a complete list of all the stack names, active or inactive, that are configured under CINET.
('00010001'x, IFA1),('00010002'x, IFA2),('00020001'x, IFB1),('00020003'x, IFB2)
The
first halfword of the index value indicates which stack under CINET
the interface belongs to. The second halfword contains that stack's
interface index for this interface.('00000001'x, IFA1),('00000002'x, IFA2)
Interface indices are used in various places in IPv6, such as for the scope_id of the IPv6 sockaddr structure and within the in6_pktinfo structure. In a CINET configuration, the first halfword of an interface index is used to route a call to the corresponding numbered stack. The upper halfword is cleared before the data is passed to the stack, so that one could use interface indices of the form X'000N0000' as a way to route a call to stack number N without actually specifying an interface index to that stack. The specified stack must be attached to the current socket. The stacks under CINET are numbered in the order of the SUBFILESYSTYPE statements in the BPXPRMxx parmlib member that defined the configuration. These values can be determined from the IocStackTdIndex field of the Iocc#GetStacks ioctl, or from the order of the names returned by the PC#TdNames pfsctl.
Refer to the C/C++ functions if_nameindex(), if_nametoindex(), and if_indextoname() for more information about interface names and indices. (See z/OS XL C/C++ Runtime Library Reference.)
The SIOCTIEDESTHRD ioctl command with the SIOC#UNTIESD argument unties a previously tied descriptor from a thread. SIOCTIEDESTHRD can be used on heavy-weight and medium-weight threads.
Servers must issue the SIOCSECENVR ioctl with the SIOC#GETENVR argument in a timely fashion. It should be issued immediately following the accept() call. If any read() calls are issued before the SIOC#GETENVR request, then the server will no longer be able to use a SIOC#GETENVR request to obtain the client's security environment.
Servers may specify the buffer in which to hold the client's security environment in the BPXYSECO structure. If the specified buffer is not large enough to contain the security environment or if SECO_BUFFERLEN is zero, the service will obtain a buffer of the correct size in the server's address space and return the security environment in that buffer. Information about the buffer and the security environment will be returned in the BPXYSECO structure and the return value will be set to 1. The server must free this buffer when it no longer needs it.
The security environment returned by a SIOC#GETENVR request can be specified as input to the RACROUTE interface using the ENVRIN keyword or to the initACEE callable service using the ENVR_in parameter.
A Net_IfConf6Header structure is passed as the argument of the ioctl. This structure specifies the buffer where the configuration information is to be written and is returned with the number of entries and entry length of the Net_IfConf6Entry structures that were written to the output buffer. These structures are defined in the BPXYIOC6 macro.
If the specified buffer address and buffer length are both zero, a Query function is performed and the header is returned with the total number of entries that would be output and the length of each individual entry for the specified version. If the specified version is zero or not supported, it is replaced with the maximum supported version and the entry length returned corresponds to that version.
If a call to get information fails with either return code ERANGE or with both return code EINVAL and the Nif6h_Version field having been changed, the call was converted into a Query function and the header has been filled. In this case, the content of the output buffer is unpredictable.
If Common INET (CINET) is configured and multiple TCP/IP stacks are attached to the socket, the output from each stack that is enabled for IPv6 will be concatenated in the output buffer and the header will contain the total number of entries returned from all the stacks. The version returned with the Query function will be the highest version supported by all the stacks.
This ioctl can be issued on an AF_INET or AF_INET6 socket.
The argument is limited to 51 200 bytes.
For an example using this callable service, see BPX1IOC (w_ioctl) example.