The IOCTL macro is used to control certain operating characteristics for a socket.

Keyword

Description

S

Input parameter. A value or the address of a halfword binary number specifying the socket to be controlled.

COMMAND

Input parameter. To control an operating characteristic, set this field to one of the following symbolic names. A value in a bit mask is associated with each symbolic name. By specifying one of these names, you are turning on a bit in a mask that communicates the requested operating characteristic to TCP/IP.

Value

Description

'FIONBIO'

Sets or clears blocking status.

'FIONREAD'

Returns the number of immediately readable bytes for the socket.

'SIOCATMARK'

Determines whether the current location in the data input is pointing to out-of-band data.

'SIOCGHOMEIF6'

Requests all IPv6 home interfaces.

Note: To request OSM interfaces, the application must have READ authorization to the EZB.OSM.sysname.tcpname resource.

When the SIOCGHOMEIF6 IOCTL is issued, the REQARG must contain a Network Configuration Header. The NETCONFHDR is defined in the SYS1.MACLIB(BPXYIOC6). The following fields are input fields and must be filled out:

NchEyeCatcher

Contains Eye Catcher '6NCH'.

NchIoctl

Contains the command code.

NchBufferLength

Buffer length of storage pointed to by NchBufferPTR. This buffer needs to be large enough to contain all the IPv6 interface records. Each interface record is length of HOMEIFADDRESS. If the buffer is not large enough, then errno will be set to ERANGE and the NchNumEntryRet will be set to number of interfaces. Based on NchNumEntryRet and size of HOMEIFADDRESS, calculate the necessary storage to contain the entire list.

NchBufferPtr

This is the pointer to an array of HOMEIF structures returned on a successful call. The size depends on the number of qualifying interfaces returned.

NchNumEntryRet

If return code is 0, this will be set to number of HOMEIFADDRESS returned. If errno is ERANGE, this will be set to number of qualifying interfaces. No interfaces are returned. Recalculate the NchBufferLength based on this value times the size of HOMEIFADDRESS.

'SIOCGIFADDR'

Requests the IPv4 network interface address for an interface name. For the address format, see the IOCN_SADDRIF field in the SYS1.MACLIB(BPXYIOCC) macro.

'SIOCGIFBRDADDR'

Requests the IPv4 network interface broadcast address for an interface name. For the address format, see the IOCN_SADDRIFBROADCAST field in the SYS1.MACLIB(BPXYIOCC) macro.

'SIOCGIFCONF'

Requests the IPv4 network interface configuration. The configuration consists of a variable number of 32-byte arrays. For the structure format, see the IOCN_IFREQ field in the SYS1.MACLIB(BPXYIOCC) macro.

• When IOCTL is issued, the first word in REQARG must contain the length (in bytes) of the array to be returned, and the second word in REQARG should be set to the number of interfaces requested times 32 (one address structure for each network interface). The maximum number of array elements that TCP/IP Services will return is 100.
• When IOCTL is issued, RETARG must be set to the beginning of the area in your program's storage, which is reserved for the array that is to be returned by IOCTL.
• The COMMAND 'SIOGIFCONF' returns a variable number of network interface configurations.

'SIOCGIFDSTADDR'

Requests the IPv4 network interface destination address. For the address format, see the IOCN_SADDRIFDEST field in the SYS1.MACLIB(BPXYIOCC) macro.

'SIOCGIFMTU'

Requests the IPv4 network interface MTU (maximum transmission unit). For the MTU format, see the IOCN_MTUSIZE field in the SYS1.MACLIB(BPXYIOCC) macro.

'SIOCGIFNAMEINDEX'

Requests all interface names and indexes including local loopback but excluding VIPAs. Information is returned for both IPv4 and IPv6 interfaces whether they are active or inactive. For IPv6 interfaces, information is returned to an interface only if it has at least one available IP address. See z/OS Communications Server: IPv6 Network and Application Design Guide for more information.

Note: To request OSM interfaces, the application must have READ authorization to the EZB.OSM.sysname.tcpname resource.

The configuration consists of the IF_NAMEINDEX structure which is defined in SYS1.MACLIB(BPX1IOCC).

• When the SIOCGIFNAMEINDEX IOCTL is issued, REQARG must contain the length of application storage (in bytes) being used to contain the returned IF_NAMEINDEX structure. The formula to compute this length is as follows:
  1. Determine the number of interfaces expected to be returned upon successful completion of this command.
  2. Multiply the number of interfaces by the array element (size of IF_NIINDEX, IF_NINAME, and IF_NIEXT) to determine the size of the array element.
  3. To the size of the array add the size of IF_NITOTALIF and IF_NIENTRIES to determine the total number of bytes needed to accommodate the name and index information returned.

  Upon successful completion of this call, the stack returns the number of entries required by the way of the IF_NITOTALIF field in the storage referenced by RETARG.

• When IOCTL is issued, RETARG must be set to the address of the beginning of the area in your program's storage which is reserved for the IF_NAMEINDEX structure that is to be returned by IOCTL.
• The command 'SIOCGIFNAMEINDEX' returns a variable number of all the qualifying network interfaces.

'SIOCGIPMSFILTER'

Requests a list of the IPv4 source addresses that comprise the source filter, with the current mode on a given interface and a multicast group for a socket. The source filter can include or exclude the set of source address, depending on the filter mode (MCAST_INCLUDE or MCAST_EXCLUDE). When the SIOCGIPMSFILTER IOCTL is issued, the REQARG parameters must contain an IP_MSFILTER structure, which is defined in SYS1.MACLIB(BPXYIOCC). The IP_MSFILTER option must include an interface address (input), a multicast address (input), filter mode (output), the number of source addresses in the following array (input and output), and an array of source addresses (output). On input, the number of source addresses is the number of source addresses that fit in the input array. On output, the number of source addresses contains the total number of source filters in the source filter list for the multicast group. If the application does not know the size of the source list prior to processing, it makes a reasonable guess (for example, 0), and if when the call completes the number of source addresses is a greater value, then the IOCTL can be repeated with a larger buffer. On output, the number of source addresses is always updated to be the total number of sources in the filter, but the array holds as many source addresses as will fit, up to the minimum of the array size that is passed in as the input number.

Calculate the size of IP_MSFILTER value as follows:

1. Determine the expected number of source addresses.
2. Multiply the number of source addresses by the array element (size of the IMSF_SrcEntry value) to determine the size of all array elements.
3. Add the size of all array elements to the size of the IMSF_Header value to determine the total number of bytes that are needed to accommodate the source addresses information that is returned.

'SIOCGMONDATA'

Returns TCP/IP stack IPv4 and IPv6 statistical counters. REQARG must point to a MonDataIn structure. The counters are returned in a MonDataOut structure. Both of these structures are defined in EZBZMONP in SEZANMAC.

Note: The ARP counter data provided differs depending on the type of device. See the z/OS Communications Server: IP Configuration Guide for information about devices that support ARP Offload and what is supported for each device.

'SIOCGMSFILTER'

Requests a list of the IPv4 or IPv6 source addresses that comprise the source filter, with the current mode on a given interface index and a multicast group for a socket. The source filter can include or exclude the set of source address, depending on the filter mode (MCAST_INCLUDE or MCAST_EXCLUDE). When the SIOCGMSFILTER IOCTL is issued, the REQARG parameter must contain a GROUP_FILTER structure, which is defined in SYS1.MACLIB(BPXYIOCC). The GROUP_FILTER option must include an interface index (input), a sockaddr_storage structure of the multicast address (input), filter mode (output), the number of source addresses in the following array (input and output), and an array of the sockaddr_storage structure of source addresses (output). On input, the number of source addresses is the number of source addresses that will fit in the input array. On output, the number of source addresses contains the total number of source filters in the source filter list for the multicast group. If the application does not know the size of the source list prior to processing, it can make a reasonable guess (for example, 0), and if when the call completes the number of source addresses is a greater value, the IOCTL can be repeated with a buffer that is large enough. That is, on output, the number of source addresses is always updated to be the total number of sources in the filter, but the array holds as many source addresses as will fit, up to the minimum of the array size passed in as the input number.

The application calculates the size of GROUP_FILTER value in the following way:

1. Determines the expected number of source addresses.
2. Multiplies the number of source addresses by the array element (size of the GF_SrcEntry value) to determine the size of all array elements.
3. Adds the size of all array elements to the size of the GF_Header value to determine the total number of bytes that are needed to accommodate the source-address information that is returned.

'SIOCGPARTNERINFO'

Provides an interface for an application to retrieve security credentials about its partner. When you issue the SIOCGPARTNERINFO IOCTL, the REQARG parameter must contain a PartnerInfo structure as defined by the EZBPINFA macro in SEZANMAC. For more information about using the SIOCGPARTNERINFO IOCTL, see z/OS Communications Server: IP Programmer's Guide and Reference.

'SIOCGSPLXFQDN'

Requests the fully qualified domain name for a given server and group name in a sysplex. This is a special purpose command to support applications that have registered with WorkLoad Manager (WLM) for connection optimization services by way of the DNS. When IOCTL is issued, REQARG and RETARG must use the address structure sysplexFqDn, which contains the pointer for sysplexFqDnData structure. The fully qualified domain name is returned in the domainName field of sysplexFqDnData. The group name and the server name can be passed using the groupName and serverName fields of sysplexFqDnData structure. Their structures are defined in the EZBZSDNP MACRO file.

'SIOCSAPPLDATA'

The SIOCSAPPLDATA IOCTL enables an application to set 40 bytes of user-specified application data against a socket endpoint. You can use this application data to identify socket endpoints in interfaces such as Netstat, SMF, or network management applications. When you issue the SIOCSAPPLDATA IOCTL, the REQARG parameter must contain a SetApplData structure as defined by the EZBYAPPL macro. See z/OS Communications Server: IP Programmer's Guide and Reference for more information about programming the SIOCSAPPLDATA IOCTL.

SetAD_buffer: The user-defined application data is 40 bytes of data that identifies the endpoint with the application. You can obtain this application data from the following sources:

• Netstat reports. The information is displayed in the ALL/-A report. If you use the APPLDATA modifier, then the information also is displayed on the ALLConn/-a and COnn/-c reports.
• The SMF 119 TCP connection termination record. See TCP connection termination record (subtype 2) in z/OS Communications Server: IP Programmer's Guide and Reference for more information.
• Network management interfaces. See Network management interfaces in z/OS Communications Server: IP Programmer's Guide and Reference for more information.

Consider the following guidelines:

• The application must document the content, format and meaning of the ApplData strings that it associates with the sockets that it owns.
• The application should uniquely identify itself with printable EBCDIC characters at the beginning of the string. Strings beginning with 3-character IBM® product identifiers, such as TCP/IP's EZA or EZB, are reserved for IBM use. IBM product identifiers begin with a letter in the range A-I.
• Use printable EBCDIC characters for the entire string to enable searching with Netstat filters.

Tip: Separate application data elements with a blank for easier reading.

'SIOCSIPMSFILTER'

Sets a list of the IPv4 source addresses that comprise the source filter, with the current mode on a given interface and a multicast group for a socket. The source filter can include or exclude the set of source address, depending on the filter mode (MCAST_INCLUDE or MCAST_EXCLUDE). When the SIOCSIPMSFILTER IOCTL is issued, the REQARG value must contain an IP_MSFILTER structure, which is defined in SYS1.MACLIB(BPXYIOCC). The IP_MSFILTER option must include an interface address, a multicast address, filter mode, the number of source addresses in the following array, and an array of source addresses.

Calculate the size of the IP_MSFILTER structure as follows:

1. Determine the expected number of source addresses.
2. Multiply the number of source addresses by the array element (size of IMSF_SrcEntry) to get the size of all array elements.
3. Add the size of all array elements to the size of the IMSF_Header value to get the total number of bytes needed to accommodate the source addresses information that is returned.

'SIOCSMSFILTER'

Sets a list of the IPv4 or IPv6 source addresses that comprise the source filter, with the current mode on a given interface index and a multicast group for a socket. The source filter can include or exclude the set of source address, depending on the filter mode (MCAST_INCLUDE or MCAST_EXCLUDE). When the SIOCSMSFILTER IOCTL is issued, the REQARG parameter must contain a GROUP_FILTER option structure, which is defined in SYS1.MACLIB(BPXYIOCC). The GROUP_FILTER option must include an interface index, a sockaddr_storage structure of the multicast address, filter mode, the number of source addresses in the following array, and an array of the sockaddr_storage structure of source addresses.

Calculate the size of the GROUP_FILTER value as follows:

1. Determine the expected number of source addresses.
2. Multiply the number of source addresses by the array element (size of the GF_SrcEntry value) to determine the size of all array elements.
3. Add the size of all array elements to the size of the GF_Header value to determine the total number of bytes needed to accommodate the source addresses information that is returned.

'SIOCSPARTNERINFO'

The SIOCSPARTNERINFO IOCTL sets an indicator to retrieve the partner security credentials during connection setup and saves the information. In this way, an application can issue a SIOCGPARTNERINFO IOCTL without suspending the application or can at least minimize the time it takes to retrieve the information. When you issue the SIOCSPARTNERINFO IOCTL, the REQARG parameter must contain a constant value, PI_REQTYPE_SET_PARTNERDATA, as defined by the EZBPINFA macro in SEZANMAC. For more information about using the SIOCSPARTNERINFO IOCTL, see z/OS Communications Server: IP Programmer's Guide and Reference.

SIOCTTLSCTL

Controls Application Transparent Transport Layer Security (AT-TLS) for the connection. REQARG and RETARG must contain a TTLS_IOCTL structure. If a partner certificate is requested, the TTLS_IOCTL must include a pointer to additional buffer space and the length of that buffer. Information is returned in the TTLS_IOCTL structure. If a partner certificate is requested and one is available, it is returned in the additional buffer space. The TTLS_IOCTL structure for assembler programs is defined in EZBZTLSP in SEZANMAC For details about usage, see the Application Transparent TLS information in z/OS Communications Server: IP Programmer's Guide and Reference.

Restriction: Use of this ioctl for functions other than query requires that the AT-TLS policy mapped to the connection be defined with the ApplicationControlled parameter set to On.

REQARG and RETARG

Point to arguments that are passed between the calling program and IOCTL. The length of the argument is determined by the COMMAND request. REQARG is an input parameter or an output parameter and is used to pass and receive arguments to and from IOCTL. RETARG is an output parameter and is used for arguments returned by IOCTL.

For the lengths and meanings of REQARG and RETARG for each COMMAND type, see Table 1.

Table 1. IOCTL macro arguments

COMMAND/CODE	SIZE	REQARG	SIZE	RETARG
FIONBIO X'8004A77E'	4	Set socket mode to: X'00'=blocking; X'01'=nonblocking.	0	Not used.
FIONREAD X'4004A77F'	0	Not used.	4	Number of characters available for read.
SIOCATMARK X'4004A707'	0	Not used.	4	X'00'= not at OOB data X'01'= at OOB data .
SIOCGHOMEIF6 X' C014F608'	20	NetConfHdr		See NETCONFHDR in macro BPXYIOC6.
SIOCGIFADDR X'C020A70D'	32	First 16-bytes -   interface name. Last 16-bytes -   not used.	32	Network interface address, see the IOCN_SADDRIF field in the SYS1.MACLIB (BPXYIOCC) macro for format.
SIOCGIFBRDADDR X'C020A712'	32	First 16-bytes -   interface name. Last 16-bytes -   not used.	32	Network interface address, see the IOCN_SADDRIF BROADCAST field in the SYS1.MACLIB (BPXYIOCC) macro for format.
SIOCGIFCONF X'C008A714'	8	First 4 bytes- size of return buffer. Last 4 bytes - address of return buffer.	See note1.
SIOCGIFDSTADDR X'C020A70F'	32	First 16-bytes - interface name. Last 16-bytes - not used.	32	Destination interface address, see the IOCN_SADDRIFDEST field in the SYS1.MACLIB (BPXYIOCC) macro for format.
SIOCGIFMTU X'C020A726'	32	First 16-bytes - interface name. Last 16-bytes - not used.	32	IPv4 interface MTU (maximum transmission unit), see the IOCN_MTUSIZE field in the SYS1.MACLIB (BPXYIOCC) macro for format.
SIOCGIFNAMEINDEX X'4000F603'	4	First 4 bytes size of return buffer.		See IF_NAMEINDEX in macro BPXYIOCC.
SIOCGIPMSFILTER X'C000A724'	—	See IP_MSFILTER structure in macro BPXYIOCC. See note 3.	0	Not used
SIOCGMONDATA X'C018D902'	—	See MONDATAIN structure in macro EZBZMONP.	—	See MONDATAOUT structure in macro EZBZMONP.
SIOCGMSFILTER X'C000F610'	—	See GROUP_FILTER structure in macro BPXYIOCC. See note 4.	0	Not used
SIOCGPARTNERINFO X'C000F612'	—	For the PartnerInfo structure layout, see SEZANMAC(EZBPINFA). See note 5.	0	Not used
SIOCGSPLXFQDN X'C018D905'	4082	See sysplexFqDn and sysplexFqDnData in macro EZBZSDNP.	4082	See sysplexFqDn and sysplexFqDnData in macro EZBZSDNP.
SIOCSAPPLDATA X'8018D90C'	—	See SETAPPLDATA structure in macro EZBYAPPL.	0	Not used
SIOCSIPMSFILTER X'8000A725'	—	See IP_MSFILTER structure in macro BPXYIOCC. See note 3.	0	Not used
SIOCSMSFILTER X'8000F611'	—	See GROUP_FILTER structure in macro BPXYIOCC. See note 4.	0	Not used
SIOCSPARTNERINFO X'8004F613'	4	See PI_REQTYPE_SET_PARTNERDATA in SEZANMAC(EZBPINFA).	0	Not used
SIOCTTLSCTL X'C038D90B'	56	For IOCTL structure layout, see SEZANMAC (EZBZTLSP).	56	For IOCTL structure layout, see SEZANMAC (EZBZTLSP).
Notes: The second 4-bytes in the RETARG is the address of the user buffer containing an array of 32-byte socket name structures (see IOCN_IFREQ in the SYS1.MACLIB(BPXYIOCC) macro for format). Each interface is assigned a 32-byte array element and the REQARG value should be set to the number of interfaces times 32. TCP/IP services can return up to 100 array elements. REQARG and RETARG must contain both sysplexFqDn and sysplexFqDnData. The size of the IP_MSFILTER structure must be equal to or greater than the size of the IMSF_Header. The size of the GROUP_FILTER structure must be equal to or greater than the size of the GF_Header. The size of the PartnerInfo structure must be equal to or greater than the PI_FIXED_SIZE value.

ERRNO

Output parameter. A fullword binary field. If RETCODE is negative, ERRNO contains a valid error number. Otherwise, ignore ERRNO.

See Socket call error return codes for information about ERRNO return codes.

RETCODE

Output parameter. A fullword binary field that returns one of the following values:

Value

Description

0

Successful call.

-1

Check ERRNO for an error code.

ECB or REQAREA

Input parameter. This parameter is required if you are using APITYPE=3. It points to a 104-byte field containing:

For ECB

A 4-byte ECB posted by TCP/IP when the macro completes.

For REQAREA

A 4-byte user token (set by you) that is presented to your exit when the response to this function request is complete.

For ECB/REQAREA

The last 100 bytes is a storage field used by the interface to save the state information.

Note: This storage must not be modified until the macro function has completed and the ECB has been posted, or the asynchronous exit has been driven.

ERROR

Input parameter. The location in your program to receive control when the application programming interface (API) processing module cannot be loaded.

TASK

Input parameter. The location of the task storage area in your program.