w_ioctl (BPX1IOC, BPX4IOC) — Control I/O

Function

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.

Requirements

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.

Format

CALL BPX1IOC,(File_descriptor,
              Command,
              Argument_length,
              Argument,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4IOC with the same parameters.

Parameters

File_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the file descriptor of an open file or a socket descriptor.

Command

Supplied parameter

Type:: Integer
Length:: Fullword

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.

Argument_length

Supplied parameter

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 device driver or physical file system
Character set:: No restriction
Length:: Specified by the Argument_length parameter

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

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the w_ioctl service returns one of the following values:

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

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the w_ioctl service stores the return code. The w_ioctl 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_ioctl service can return one of the following values in the Return_code parameter:

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 w_ioctl service specified an incorrect length for the argument. The correct argument length range is 0–51 200. An invalid command was encountered. The following reason codes can accompany the return code: JRInvIoctlCmd, JrNotSupportedForFileType, JrFileNotOpen, JrBadSubField.
EIO	One of the following occurred: The process group of the process that is issuing the function is an orphaned, background process group, and the process that is issuing the function is not ignoring or blocking SIGTTOU. There has been a network or transport failure. 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: JrNoCINET Common INET is not configured, or this is not a socket and the name did not match the PFS name. This error may not be critical to the application, because the imbedded ioctl can be sent directly to the one and only stack or PFS as a regular ioctl. JrCINETBadName CINET is configured, and this name does not match any stack. JrCINETNotAttached CINET is configured and this name matches a stack, but that stack is not attached to this socket.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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.

Usage notes

See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
z/OS® UNIX domain sockets support the following commands:
- FIONBIO
- FIONREAD
- FIONWRITE
- SECIGET
- SIOCATMARK
- SIOCSECENVR
Inet sockets pass the ioctl command to TCP/IP. Refer to z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference for the commands that are supported.
Pseudoterminals (ptys) and remote terminals (rtys) support TIOCGWINSZ and TIOCSWINSZ to get and set window size. Ptys also support TIOCNOTIFY begin (IOCC#PWBEGIN) and TIOCNOTIFY end (IOCC#PWEND) secure data mode.
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.
The pipe file system does not support ioctl.
The IOCC#UPDTOFTE command updates a 100-byte state area that is associated with an Open File Table Entry (OFTE). OFTEs are created by the socket, open, and pipe functions, and are shared by child processes.
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.
Three subcommands are available:
- IocUo#Write
  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.
- IocUo#Read
  The data at the specified offset in the state area is returned.
- IocUo#CS
  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 Iocc#RegFileInt command registers interest in a file and allows the program to be notified when a change to that file occurs.
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.
When a change occurs to a registered file, a message is sent on the registered IPC Message Queue. The message content is described by the Rfim structure in the BPXYRFIS macro, and contains:
- The message type specified on registration
- The user token specified on registration
- The type of change that occurred
The types of file changes that generate a message are:
- File write, including truncate and open(O_TRUNC)
- Any attribute change, such as a chmod or chown request
- Renaming, removal, or unlinking of any of the file's names
- Attempts to unmount the containing file system
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.
When an application is informed that messages have been lost, it should do the following:
- Unregister all registered files, ignoring any EALREADY return codes
- Drain the message queue, ignoring any change messages received
- Start over
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.

For file systems that support access control lists (ACLs), you can use the following commands:

GetfACL

Retrieves information from an access control list. The Argument parameter specifies the user buffer containing the following input:

A structure of type RACL_EDIT, defined in IRRPCOMP, followed by
A structure of type FACL, defined in IRRPFACL.

z/OS Security Server RACF Data Areas describes these structures.

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.

Set the RACL_EDIT and FACL fields as follows:

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')

Upon successful return, FACL_NUM_ENTRY (offset X'12') contains the number of ACL entries that the file has of the specified type (access or default). It is up to the caller to determine whether the buffer is big enough to hold that many entries. The calculation for the amount of space needed is:

(length of RACL_EDIT structure) + (FACL_NUM_ENTRY × FACL_LEN_ENTRY)

The entries start at FACL_ENTRIES and are mapped by FACL_ENTRY.

SetfACL

Sets information into an access control list. There are four types of operations you can perform on access or default ACLs:

Delete a whole ACL
Add a whole ACL
Add or change individual ACL entries
Delete individual ACL entries

The contents and length of the user buffer passed in the Argument parameter depend on the type of operation, as follows:

Deleting a whole ACL: Only a RACL_EDIT structure needs to be passed in the buffer and the buffer only needs to be as big as that structure. Set the RACL_EDIT fields as follows:
The table shows the field name and value needed when deleting a whole ACL.
Field name Value

RACL_EDIT_OPTYPE RACL_DELETE

RACL_EDIT_ACLTYPE RACL_ACCESS, RACL_FILEMOD, or RACL_DIRMOD

If the ACL is not found, the request is ignored.

Field name	Value
RACL_EDIT_OPTYPE	RACL_DELETE
RACL_EDIT_ACLTYPE	RACL_ACCESS, RACL_FILEMOD, or RACL_DIRMOD

Adding a whole ACL: A RACL_EDIT structure, FACL structure, and all FACL_ENTRY blocks to be added must be passed in the Argument buffer. Argument_length must indicate the size of the entire buffer. Set the RACL_EDIT, FACL, and FACL_ENTRY fields as follows:

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

Adding or changing individual ACL entries: A RACL_EDIT structure, FACL structure, and all FACL_ENTRY blocks to be added or modified must be passed in the Argument buffer. Argument_length must indicate the size of the entire buffer. Set the RACL_EDIT, FACL, and FACL_ENTRY fields as follows:

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

If the entry is not found in the existing ACL, it is added as a new entry. If the entry is found for the given user or group, it is modified with the specified permissions.

Deleting individual ACL entries: A RACL_EDIT structure, FACL structure, and all FACL_EDIT_ENTRY blocks to be deleted must be passed in the Argument buffer. Argument_length must indicate the size of the entire buffer. Set the RACL_EDIT, FACL, and FACL_EDIT_ENTRY fields as follows:

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

If the entry is not found in the existing ACL, it is ignored. If the entry is found for the given user or group, it is deleted. You can have entries to be deleted along with entries to be added in the same buffer.

The following FACL_ENTRY fields are useful for debugging:

FACL_RACF_RETURN_CODE: The return code from RACF®, documented in z/OS Security Server RACF Callable Services (see the return and reason codes for the makeFSP service).
FACL_RACF_REASON_CODE: The reason code from RACF, documented in z/OS Security Server RACF Callable Services (see the return and reason codes for the makeFSP service).
FACL_ERROFF: If the problem is with an entry, this field indicates the offset into the Argument buffer where the problem occurred.

Also, refer to the usage notes for the R_setfacl service in z/OS Security Server RACF Callable Services.

The IOCC#DIRIOCTL (Directed Ioctl) command sends an imbedded ioctl command and argument to a specified stack. The input argument for this command is the IocDirIoctl structure, from the BPXYIOCC macro (BPXYIOCC — Ioctl command definitions), with the following fields:
Field

Description

IocDirName

The name of the stack

IocDirCmd

The ioctl command to be sent to IocDirName

IocDirArgLen

The length of IocDirArg, which follows

IocDirArg

The ioctl argument to be sent to IocDirName

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.
The IOCC#GETSTACKS (Get TCPIP Stack Names) command returns the names of all the transport stacks that are attached to a socket, and information related to those stacks. The output argument for this command is the IocStackInfo structure, from the BPXYIOCC macro (BPXYIOCC — Ioctl command definitions), with the following fields:
Field

Description

IocStackEntries

The number of IocStackName array entries that were returned. With CINET, one or more entries may be returned, depending on how many stacks have been configured under CINET, how many are or have been active, and any stack affinity that may have been established for the socket or process.

IocStackName

The name of the stack.

IocStackCINET

Indicates that this is a CINET socket. When this bit is on, the IocStack_IPv6_Interfaces and IocStack_IPv4_Interfaces flags indicate whether the specified stack has configured interfaces of each type. Without CINET, use the SIOCGIFVERSION ioctl to obtain this information directly from the Inet stack. See SIOCGIFVERSION (determine if an IPv4 or IPv6 interface has been configured on a TCP/IP stack) in z/OS UNIX System Services File System Interface Referencefor information about the SIOCGIFVERSION ioctl command.

IocStack_IPv6_Support

Indicates that this stack supports IPv6 protocols and sockets created with AF_INET6. CINET supports IPv6 sockets over stacks that do not themselves support IPv6, as long as IPv4-mapped addresses can be used.

IocStackTdIndex

The CINET TdIndex for this stack. This value is used in the upper halfword of Interface Indices when CINET is configured.

IocStack_Active

Indicates that this stack is active. When used with this ioctl command, this bit is usually on, because inactive stacks are not usually attached to a socket, unless the stack has recently terminated.

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.
The IOCC#GRTRSELECT (Get CINET PreRouter Selections) command returns the CINET stack that would be chosen for each of a list of destination IP addresses. This ioctl is passed an array of IP addresses, and returns for each address the CINET stack that would be chosen for that destination. This is the stack over which a connect() or sendto(), for instance, would be routed if that address were specified on the call at this time. If CINET is not configured, the socket's one and only stack is returned. The input and output argument for this command is the IocRtrSelect structure, from the BPXYIOCC macro (BPXYIOCC — Ioctl command definitions), with the following fields in each array entry:
Field

Description

IocRtrIpAddr

Specifies the IP address to test. This is an IPv6 address or an IPv6-mapped IPv4 address.

IocRtrStack

Returns the name of the stack that would be chosen.

IocRtrErrTest

When equal to B'0', this indicates that there was an error with this one IP address. The following two fields are also returned: IocRtrErrno, which contains the failing return code (errno), and IocRtrRsn, which contains the failing reason code.
The SIOCGIFNAMEINDEX (Get Interface Name/Index Table) command returns the Interface Name/Index table for every stack that is attached to a socket. The output argument for this command is the If_NameIndex structure, from the BPXYIOCC macro (BPXYIOCC — Ioctl command definitions), with the following fields:
Field

Description

If_NITotalIF

Contains the total number of interfaces that have indices assigned on the stacks that are attached to this socket.

If_NIEntries

Contains the number of interfaces that have been returned. When the total is greater than the number of entries returned, the supplied buffer was not large enough to hold all of the required information. In that case, If_NITotalIF can be used to calculate the amount of space needed and the call can be repeated. When all the interfaces can be returned, the two values are equal.

If_NITable

Contains an array of If_NameIndexEntry structures.

Each interface is described by an If_NameIndexEntry structure consisting of:
Structure

Description

If_NIIndex

Contains the Interface Index, as described in this topic.

If_NIName

Contains the Interface Name, as a 1- to 16-byte character string, left-justified, and padded with blanks. When there is more than one stack, these names may not be unique, because the names are defined to each stack individually with their own configuration procedures.

If_NINameTerm

A null character supplied to terminate the name string for the convenience of C routines.

Tip: To query for the total number of interfaces, you can specify an argument length of 8, just large enough for the first two fields, and the total will be returned in If_NITotalIF, with an If_NIEntries value of 0.
This output is similar to the output of the if_nameindex() C/C++ function. For a CINET socket with more than one stack attached, the tables from each stack are concatenated into one output table. For a CINET socket, in general, a Transport Driver Index, TdIndex, value will be inserted into the Interface Indices to uniquely identify the interfaces. For example, with two stacks (1) TCPA, with interfaces IFA1 and IFA2, whose interface indices are 1 and 2, respectively, within TCPA, and (2) TCPB, with interfaces IFB1 and IFB2, whose interface indices are 1 and 3, respectively, within TCPB, the output of this ioctl would be something like:
```
('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.
Without CINET, if TCPA was configured as the only stack, and it was IPv6-enabled, the output of this ioctl would be:
```
('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 SIOCGSOCKPOEATTRS and SIOCGFDPOEATTRS commands return port of entry information for multilevel security. SIOCGSOCKPOEATTRS returns port of entry attributes for a socket resource. SIOCGFDPOEATTRS returns port of entry attributes for a non-socket resource. The port of entry information that can be returned by these commands is defined in the IocPoeAttr block in BPXYIOCC — Ioctl command definitions.
The Iocc#DevConsole command allows a program with appropriate privileges to suppress the message number and user ID that are normally prefixed to message BPXF024I when text that is written to /dev/console is sent to the system console. The Argument_length must be 4 and an Argument value of Iocc#DevConSuppress (1) enables suppression of the header on future writes. An Argument value of Iocc#DevConUnSupprs (0) cancels the suppression, so future writes will contain the header.
The SECIGET_T ioctl command returns both process-level and, if available, task-level security information of the peer for an AF_UNIX stream-connected socket. The task-level security information is from the task that issued the connect or accept call. The security information is returned in a BPXYSECT structure. The security information is not available until accept() completes. The availability of the peer's task-level security data is determined by the task-level userID length field. If the length is zero, the peer does not have task-level security data.
The SIOCTIEDESTHRD ioctl command with the SIOC#TIESD argument ties or associates a descriptor with the thread of the SIOCTIEDESTHRD caller. If that task terminates before the descriptor is closed or untied from the task, then the termination processing for the file system thread will close the descriptor.
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.
The FIONWRITE ioctl command returns the number of bytes that can be written to the connected peer AF_UNIX stream socket before the socket blocks or returns an EWOULDBLOCK return code. Note that the number of bytes returned by FIONWRITE is not guaranteed unless there is serialization among the calling applications.
The SIOCSECENVR ioctl command sets or gets the security environment of a client that is connecting to an AF_UNIX stream socket server. Arguments for the SIOCSECENVR ioctl are mapped by the BPXYSECO structure (see BPXYSECO — Map the input/output of BPX1IOC for the SIOCSECENVR request). A server must have appropriate privileges to issue this ioctl.
- The SIOCSECENVR ioctl with the SIOC#SETENVR argument is for use by an AF_UNIX stream socket server to mark the server socket as one that requires the full security environment of a connecting client to be available before a connect() will successfully complete. The connect service obtains the security environment of the connector and anchors it off of the connector's socket for use by the server. If the security environment cannot be obtained during connect processing, the connect() will fail. This ioctl is meaningful only for sockets that will become server sockets; it has no effect for all other sockets.
- The SIOCSECENVR ioctl with the SIOC#GETENVR argument is for use by an AF_UNIX stream socket server to copy the previously set security environment from the connector's address space to the server's address space so that it can be used as input on calls to the security product. This ioctl is only meaningful for server sockets that previously issued the SIOCSECENVR ioctl with the SIOC#SETENVR argument.
  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.
The SIOCGIFCONF6 (Get IPv6 Interface Configuration) command gets the name, address, and other information about the configured IPv6 network interfaces. This is similar to the SIOCGIFCONF command for IPv4.
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 Iocc#GetPathName and Iocc#GetPathNameRel (get pathname and get relative pathname) commands return the absolute or relative path name, respectively, of the file referred to by File_descriptor. The output path name is placed in the Argument buffer and is ll terminated by a null character. The length of the output path name is determined by scanning for the trailing null byte. The Argument buffer provided must be large enough to contain the output name and the trailing null byte or the call will fail with RC=ERANGE.
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.

Characteristics and restrictions

The argument is limited to 51 200 bytes.

Examples

For an example using this callable service, see BPX1IOC (w_ioctl) example.