IOCTL

Use the IOCTL command to perform control functions on sockets.

Format


>>-SOCKET--(--"IOCTL"--,--socketid--,--icmd--+-----------+------>
                                             '-,--ivalue-'   

>--+----------+--)---------------------------------------------><
   '-,--idata-'

Parameters

socketid

The socket descriptor.

icmd

The control function. The following commands are supported:

FIONBIO

Enables or disables blocking mode. When the ivalue parameter is set to ON, the socket is set to nonblocking mode. When the ivalue parameter is set to OFF, the socket is in blocking mode. The command returns a string that contains the return code.

FIONREAD

Requests the number of bytes on the receive queue that are ready for reading. The command returns a string that contains the return code and the number of bytes that are ready for reading.

SIOCATMARK

Determines whether the current location in the input data points to out-of-band data. The command returns a string that contains the return code and YES or NO. YES indicates that there is out-of-band data.

SIOCGIFADDR

Obtains a network interface address. The ivalue parameter must specify the name of the network interface, for example, LOGETH13. The network interface name can be 1-16 characters in length. The command returns a string that contains the return code and the network interface address, which has the following format: interface domain port ipaddress.

Restriction: This function is valid only for IPv4 interfaces.

SIOCGIFBRDADDR

Obtains the network broadcast address of an interface. The ivalue parameter must specify the name of the network interface, for example, LOGETH13. The network interface name can be 1-16 characters in length. The command returns a string that contains the return code and the network broadcast address, which has the following format: Hinterface domain port ipaddress.

Restriction: This function is valid only for IPv4 interfaces.

SIOCGIFCONF

Obtains the list of the interfaces that are defined to the system. The ivalue parameter must specify the maximum number of interfaces to be returned. The command returns a string that contains the return code and a list of interfaces, which has the following format: interface domain port ipaddress

Restriction: Only IPv4 interface information is returned.

Tip: You can parse the information in the following way:

Drop st.
l_retcode = socket("IOCTL",l_sockid,"SIOCGIFCONF",10);
parse var l_retcode l_rc l_iflist
i=0;
do until l_iflist = ""
i=i+1;
parse var l_iflist st.i.interface st.i.domain st.i.port,
st.i.address l_iflist
st.i.name = st.i.domain st.i.port st.i.address;
end;
st.0 = i;

SIOCGIFDSTADDR

Obtains the network destination address of an interface. The ivalue parameter must specify the name of the network interface, for example, LOGETH13. The network interface name can be 1-16 characters in length. The command returns a string that contains the return code and the network destination address, which has the following format: interface domain port ipaddress

Restriction: This function is valid only for IPv4 interfaces.

SIOCGIFMTU

Obtains the network MTU (maximum transmission unit) of an interface. The ivalue parameter must specify the name of the network interface, for example, LOGETH13. The network interface name can be 1-16 characters in length. The command returns a string that contains the return code, the interface name, and the numeric MTU value.

Restriction: This function is valid only for IPv4 interfaces.

SIOCGIFNAMEINDEX

Obtains a list of all interface names and device indexes that are defined to the system. This list includes loopback addresses, but excludes VIPA addresses. The command returns a string that contains the return code and a list of interfaces, which have the following format: interface_index interface_name.

Tip: You can parse the information in the following way:

DROP st.
l_retcode = socket(“IOCTL”,1,”SIOCGIFNAMEINDEX”);
i = 0;
do until l_retcode = ‘'
    i=i+1;
    parse var l_retcode st.i.interfindex st.i.name l_retcode;
end;

SIOCGIFFLAGS

Obtains the network interface flags of an interface. The ivalue parameter must specify the link name of the interface, for example, LOGETH13. The command returns a string that contains the return code, the interface name, the flags in four hexadecimal digits, and the symbolic names of the flags.

The following string is an example of what is returned by the SIOCGIFFLAGS function:

0 LOOPBACK 0049 IFF_UP IFF_LOOPBACK IFF_RUNNING

Restriction: This function is valid only for IPv4 interfaces.

SIOCGIFMETRIC

Obtains the network routing metric of an interface. The ivalue parameter must specify the link name of the interface, for example, LOGETH13. The command returns a string that contains the return code, interface name, and routing metric.

Restriction: This function is valid only for IPv4 interfaces.

SIOCGIFNETMASK

Obtains the network mask of an interface. The ivalue parameter must specify the interface name, for example, LOGETH13. The command returns a string that contains the return code, interface name, and a socket NAME with the network mask, for example, 0 LOFETH13 AF_INET 0 255.255.240.0.

For more information about the format of the NAME string, see How structures are represented.

Restriction: This function is valid only for IPv4 interfaces.

SIOCGIPMSFILTER

Obtains a list of the IPv4 source addresses from the stack for a specified interface and multicast group. The ivalue parameter must be a space-delimited string that contains an IPv4 multicast address, an IPv4 interface address, and the number of addresses to be returned, for example, "224.224.224.1 176.11.16.103 5". If the number of addresses to be returned is set to 0, all source filters are returned. The command returns a string that contains the return code, filter mode (either MCAST_INCLUDE or MCAST_EXCLUDE), number of IPV4 source addresses that are returned, and the IPv4 source addresses. Depending on the filter mode, source addresses are included or excluded.

The following string is an example of what is returned by the SIOCGIPMSFILTER function:

0 MCAST_INCLUDE 2 10.11.103.1 176.11.16.103

SIOCGMSFILTER

Obtains a list of the IPv4 or IPv6 source addresses for the specified interface index and multicast group. The ivalue parameter must be a space-delimited string that contains an interface index, a socket name for the multicast address, and the number of addresses to be returned, for example, "34 AF_INET 21 224.224.224.1 5". If the number of addresses to be returned is set to 0, all source addresses are returned. The command returns a string that contains the return code, filter mode (either MCAST_INCLUDE or MCAST_EXCLUDE), the number of source addresses that are returned, and a list of the source-socket name groups.

The following string is an example of what is returned by the SIOCGMSFILTER function:

0 MCAST_INCLUDE 1 AF_INET 21 176.11.16.103

In the example, AF_INET 12 176.11.16.103 is the source-socket name.

For more information about the format of the NAME string, see How structures are represented or the BIND or CONNECT commands.

SIOCGPARTNERINFO

Provides an interface for an application to retrieve security information about its partner. The ivalue parameter must be a space-delimited string that contains a request type and a timeout value in the range 0 – 60.

The request type is one of the following values:

PI_REQTYPE_CONNTYPE, CONNTYPE, C, or 0
PI_REQTYPE_PARTNER_USERID, USERID, U, or 1

The command returns a string that contains the return code and the output data.

The return code is either 0 or -1, with 0 indicating successful completion and -1 indicating that an error occurred.

The output data includes the following information:

Status
The status indicates the type of information that is returned, which includes connection routing information that can be followed by partner user ID information. If the partner user ID information is not returned, or only the address-space user ID is returned, the appropriate user ID fields are set to 0.
Connection type (8 hexadecimal digits)
Length of the returned address-space user ID
Returned address space user ID
Length of the returned task-level user ID
Returned task-level user ID
Additional error code and the text version of the error (if the return code is -1)

The following string is an example of the output data for a successful command:

0 3 0000000E 5 USER1 0 0

In this example, 0 is the return code, 3 is the PI_STATUS (indicating that the connection routing information and the partner user ID are returned), 0000000E is the connection routing value (indicating PI_CONNTYPE_SAME_CLUSTER, PI_CONNTYPE_SAME_IMAGE, and PI_CONNTYPE_INTERNAL), 5 is the length of the returned address space user ID, USER1 is the returned address space user ID, and 0 0 indicates that there is no task-level user ID.

If an error occurs, the output data is similar to the following example:

-1 1 0000000E 0 0 0 0 ( 73 ETIME Timer expired

In this example, -1 is the return code, 1 is the PI_STATUS (indicates that the connection routing information is returned), 0000000E is the connection routing value (indicates PI_CONNTYPE_SAME_CLUSTER, PI_CONNTYPE_SAME_IMAGE, and PI_CONNTYPE_INTERNAL), 0 0 0 0 indicates that no user ID information is returned, 73 is the error code, and ETIME Timer expired is the error description.

For more information about using the SIOCGPARTNERINFO IOCTL, see z/OS Communications Server: IP Programmer's Guide and Reference.

SIOCSAPPLDATA

Associates user-defined data with a socket descriptor. This data can be used to identify socket endpoints for network-management applications or tools such as Netstat or SMF. The ivalue parameter is a string that contains the user-defined data; it can be up to 40 bytes in length. The command returns an error code.

Guideline: The content of this field is determined by the application that owns the connection. See application-specific documentation for explanations of the layout, format, and meaning of this field. Typically, the field contains printable EBCDIC characters, although some applications might include binary data.

The application data is displayed by the following items only when the TCP connection has application data associated with it:

Netstat reports. The information is displayed on the ALL/-A report. If the APPLDATA modifier is used, the information also is displayed on the ALLConn/-a and COnn/-c reports.
The SMF 119 TCP connection termination record. For more information, see z/OS Communications Server: IP Programmer's Guide and Reference.
Network management applications. For more information, see z/OS Communications Server: IP Programmer's Guide and Reference.

SIOCSIPMSFILTER

Sets the list of the IPv4 source addresses and the filter mode for an interface and multicast group. The ivalue parameter must be a space-delimited string that contains an IPv4 multicast address, an IPv4 interface address, filter mode, the number of IPv4 source addresses to be added, and the list of IPv4 source addresses, for example:

224.224.224.1 176.11.16.103 MCAST_INCLUDE 2 48.11.16.103
		176.11.16.103

The filter mode is one of the following values:

Include: MCAST_INCLUDE, INCLUDE, I, or 0
Exclude: MCAST_EXCLUDE, EXCLUDE, E, or 1

The maximum number of source addresses is 64. If the interface address is 0.0.0.0, then the stack selects the default IPv4-multicast interface address. The command returns a string that contains the return code.

SIOCSMSFILTER

Sets a list of the IPv4 or IPv6 source addresses and the filter mode for an interface and multicast group. The ivalue parameter must be a space-delimited string that contains an interface index, the socket address name for the multicast address, the filter mode, the number of source address names, and a list of the source address names, for example:

34 AF_INET6 56504 0 FF02::67:69 0 MCAST_INCLUDE 1 2001:10:11:103::1

The filter mode is one of the following values:

Include: MCAST_INCLUDE, INCLUDE, I, or 0
Exclude: MCAST_EXCLUDE, EXCLUDE, E, or 1

The maximum number of source addresses is 64. If the interface index is 0, then the stack selects an interface. The command returns a string that contains the return code.

For more information about the format of the NAME string, see How structures are represented.

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 at least minimizing the time to retrieve the information. The ivalue parameter must be set to PI_REQTYPE_SET_PARTNERDATA, PARTNERDATA, P, or 1. The command returns a string that contains the return code.

For more information about using the SIOCSPARTNERINFO IOCTL, see z/OS Communications Server: IP Programmer's Guide and Reference.

SIOCTTLSCTL

Queries or controls Application Transparent Transport Layer Security (AT-TLS) for a TCP stream socket connection. If the socket is in blocking mode, this function blocks during the initial handshake. If the socket is in nonblocking mode, it returns the 36 EWOULDBLOCK error. See the Application Transparent TLS information in z/OS Communications Server: IP Programmer's Guide and Reference for more information.

Unless the ivalue parameter is set to QUERYONLY, the application must be mapped to an AT-TLS policy and the parameter ApplicationControlled must be set to ON. The ivalue parameter can have the following values:

QUERYONLY

Requests security information about the current socket. This request can be issued by any application, regardless of the value of the ApplicationControlled parameter. If the socket is not mapped to an AT-TLS policy and the socket is in a writable state, issuing this command causes AT-TLS to try to locate and assign a policy. The command returns a string that contains status information about the security level of the connection.

QUERYHOST

Queries the partner certificate to validate that the certificate matches the host name. The idata parameter must specify the host name. This request returns one of the following values:

0: Validation status unknown. This value is returned if no partner certificate is present. This can occur for servers if client authentication is not enabled in the policy.
1: Host name validation succeeded. The host name in the partner certificate matches the value of the idata parameter.
2: Host name validation failed. The host name in the partner certificate did not match the value of the idata parameter.

QUERYRULENAME

Queries the TTLSRule name that is mapped to the connection. This request returns the TTLSRule name or *N/A*, if no mapping exists.

QUERYGROUPACTIONNAME

Queries the TTLSGroupAction name that is mapped to the connection. This request returns the TTLSGroupAction name or *N/A*, if no mapping exists.

QUERYENVIRONMENTACTIONNAME

Queries the TTLSEnvironmentAction name that is mapped to the connection. This request returns the TTLSEnvironmentAction name or *N/A*, if no mapping exists.

QUERYCONNECTIONACTIONNAME

Queries the TTLSConnectionAction name that is mapped to the connection. This request returns the TTLSConnectionAction name or *N/A*, if no mapping exists.

INITCONNECTION

Initializes a secure SSL connection using the role that is defined by the Handshake parameter in the mapped policy. When this command is successful, it returns a string that contains status information about the security level of the connection.

INITCONNHSTIMEOUT

Initializes a secure SSL connection using the role that is defined by the Handshake parameter in the mapped policy. The Handshake parameter must be set to Server or ServerWithClientAuth. If the SSL handshake times out before receiving data from the client, SSL is stopped on the connection and the TCP connection remains established. Using this command is equivalent to requesting TTLS_INIT_CONNECTION and TTLS_ALLOW_HSTIMEOUT.

RESETSESSION

Resets the session ID so that it is not reused by another connection. When this command is successful, it returns a string that contains status information about the security level of the connection.

RESETCIPHER

Resets and renegotiates the cipher that is used for the secure session. If the session ID times out or has been reset, a full handshake is performed. Otherwise, a short handshake is performed. When this command is successful, it returns a string that contains status information about the security level of the connection.

STOPCONNECTION

Stops SSL security on the connection. The TCP connection remains established. Future sends and receives are not encrypted.

If an error occurs, the SIOCTTLSCTL function returns an error code. Unless otherwise specified in the ivalue parameter, if the command is completed, the SIOCTTLSCTL function returns a string that contains the following information:

Return code
Policy status
Connection status
Security type
SSL protocol
Negotiated cipher that can be presented in 2 bytes
Client user ID if available
FIPS status
Four-byte negotiated cipher

For example, the following string is an example of what is returned by the SIOCTTLSCTL function:

0 5 2 2 0300 05 userid 01 0005

In the example, 0 is the return code, 5 is the policy status, 2 is the connection status, the second 2 is the security type, 0300 is the SSL protocol, the second 05 is the negotiated cipher, userid is the user ID that is associated with the client's certificate in the SAF database, 01 is the FIPS 140 status, and 0005 is the four-byte negotiated cipher.

The policy status is one of the following values:

1: AT-TLS function is off. The TCP/IP address space is not enabled to support AT-TLS.
2: No AT-TLS policy is defined for the connection.
3: A policy is defined for the connection, but AT-TLS is not enabled for the connection.
4: A policy is defined for the connection, and AT-TLS is enabled for the connection.
5: A policy is defined for the connection, and both AT-TLS and the ApplicationControlled parameter are enabled for this connection.

The connection status is one of the following values:

1: The connection is not secure.
2: The connection handshake is in progress.
3: The connection is secure.

The security type is one of the following values:

0: Unknown. The connection is not secure.
1: Client.
2: Server.
3: Server with client authentication and authentication type set to PASSTHRU.
4: Server with client authentication and authentication type set to FULL.
5: Server with client authentication and authentication type set to REQUIRED.
6: Server with client authentication and authentication type set to SAFCheck.

The SSL protocol is one of the following values:

0000: Unknown. The connection is not secure.
0200: SSL Version 2.
0300: SSL Version 3.
0301: TLS Version 1.0
0302: TLS Version 1.1
0303: TLS Version 1.2

The value FF indicates that the cipher has not been negotiated. SSL Version 2 cipher suites are 1 character. SSL Version 3 and TLS ciphers are 2 or 4 characters. The value 4X indicates that the cipher cannot be represented in 2 bytes. The 2-byte cipher must be obtained from the 4-byte cipher field. See the TTLSCipherParms statement description in z/OS Communications Server: IP Configuration Reference for additional cipher values.

The client user ID value is either the user ID that is associated with the client's certificate in the SAF database, or the character string **NONE** that indicates that the client ID is unknown.

The FIPS 140 status is one of the following values:

00: No FIPS 140 support
01: FIPS 140 support

If the cipher is not negotiated, the 4-byte cipher value is *NA*; otherwise, the 4-byte value of the negotiated cipher is returned. See the TTLSCipherParms statement description in z/OS Communications Server: IP Configuration Reference for additional cipher values.

Rule: When using AT-TLS application control, you must ensure that no outstanding data resides in the socket receive buffers for the application. If data exists when AT-TLS is enabled, the negotiation will fail. To flush the receive buffers, you can issue a nonblocking RECV command on the socket before you issue the IOCTL command.

Tips:

For TCP/IP socket error information concerning this command, see the Application Transparent TLS information in z/OS Communications Server: IP Programmer's Guide and Reference.
For information about SSL error numbers, see z/OS Cryptographic Services System SSL Programming.

ivalue

Additional information that is needed to run the requested command. The value of the ivalue parameter can be either input or output; it is independent of the icmd parameter.

idata

Additional information that is needed to run the requested command. The value of the idata parameter can be either input or output; it is independent of the icmd and ivalue parameter.

Returned value

The return code can be 0, a REXX socket API error number, or the REXX TCP/IP error number that is set by the socket command. The return code 0 indicates that the requested socket command was completed successfully.

See Socket call error return codes for additional information about the numeric error codes that are returned by this command.

The following REXX TCP/IP error numbers can be returned:

9 EBADF
6 ENXIO
22 EINVAL
41 EPROTOTYPE
45 EOPNOTSUPP

The following REXX socket API error numbers can be returned:

2001 EINVALIDRXSOCKETCALL
2005 ESUBTASKNOTACTIVE
2009 ESOCKETNOTDEFINED

LE C/C++ equivalent

This command has no LE C/C++ equivalent.

Code example

See the EZARXS05 REXX sample in the SBLSCLI0 file for an example of using the IOCTL command.