ioctl: Perform special operations on socket

Use this socket function to complete special operations on socket descriptor s.

Last updated

  • Changed for PUT14 (information only; no code change).
  • Added for PUT00.

Format

#include  <sys/types.h>
#include  <sys/socket.h>
#include  <sys/ioctl.h>
int       ioctl(int s,
                int cmd,
                char *arg);
s
The socket descriptor.
cmd
Command to perform. Use one of the following values:
AOR_BALANCE
Sets TCP/IP activate on receipt load balancing on or off for a socket. If load balancing is set on, the tightly coupled scheduler selects which I-stream the ECB is created on when an activate_on_receipt, activate_on_receipt_with_length, or activate_on_receipt_of_TCP_message API is completed. If load balancing is set off, the ECB is created on the I-stream of the ECB that issued the API. The arg parameter is a pointer to an integer. If the integer is nonzero, load balancing is set on; otherwise, load balancing is set off.
Note:
  1. TCP/IP activate on receipt load balancing can be set on only for applications that run on any I-stream.
  2. The AOR_BALANCE parameter is unique to the z/TPF system.
FIONBIO
Sets or clears nonblocking input/output for a socket. The arg parameter is a pointer to an integer. If the integer is 0, nonblocking input/output on the socket is cleared. Otherwise, the socket is set for nonblocking input/output.
FIONREAD
Gets the number of immediately readable bytes for the socket. The arg parameter is a pointer to an integer. Sets the value of the integer to the number of immediately readable characters for the socket.
SIOCADDRT
Adds a routing table entry. The arg parameter is a pointer to a rtentry structure as defined in ioctl.h. The routing table entry, passed as an argument, is added to the routing tables. This option is for IBM® use only.
SIOCATMARK
Queries whether the current location in the data input is pointing to out-of-band data. The arg parameter is a pointer to an integer. Sets the argument to 1 if the socket points to a mark in the data stream for out-of-band data. Otherwise, sets the argument to 0.
SIOCDELRT
Deletes a routing table entry. The arg parameter is a pointer to a rtentry structure. If it exists, the routine table entry, passed as an argument, is deleted from the routing tables. This option is for IBM use only.
SIOCGIFADDR
Gets the network interface address. The arg parameter is a pointer to an ifreq structure, as defined in ioctl.h. The interface address is returned in the field in the ifreq structure that has the result.
SIOCGIFBRDADDR
Gets the network interface broadcast address. The arg parameter is a pointer to an ifreq structure as defined in ioctl.h. The interface broadcast address is returned in the argument.
SIOCGIFCONF
Gets the network interface configuration. The arg parameter is a pointer to an ifconf structure as defined in ioctl.h. The interface configuration is returned in the argument. The length must be at least 32 bytes. If you pass a NULL pointer for the ifcu_buf parameter in the ifconf structure, the z/TPF system returns the length that is required for the ifcu_buf buffer. The length is stored in the ifc_len parameter of the ifconf structure that is passed. Then, the application can issue the ioctl function with the SIOCGIFCONF option and a properly sized buffer that the ifcu_buf parameter in the ifconf structure points to.
SIOCGIFDSTADDR
Gets the network interface destination address. The arg parameter is a pointer to an ifreq structure as defined in ioctl.h. The interface destination (point-to-point) address is returned in the argument.
SIOCGIFFLAGS
Gets the network interface flags. The arg parameter is a pointer to an ifreq structure as defined in ioctl.h. The interface flags are returned in the argument.
SIOCGIFMETRIC
Gets the network interface routing metric. The arg parameter is a pointer to an ifreq structure as defined in ioctl.h. The interface routine metric is returned in the argument. This option is for IBM use only.
SIOGIFNETMASK
Gets the network interface network mask. The arg parameter is a pointer to an ifreq structure as defined in ioctl.h. The interface network mask is returned in the argument.
SIOCSIFDSTADDR
Sets the network interface destination address. The arg parameter is a pointer to an ifreq structure as defined in ioctl.h. Sets the interface destination (point-to-point) address to the value passed in the argument. This option is for IBM use only.
SIOCSIFFLAGS
Sets the network interface flags. The arg parameter is a pointer to an ifreq structure as defined in ioctl.h. Sets the interface flags to the values passed in the argument. This option is for IBM use only.
SIOCSIFMETRIC
Sets the network interface routing metric. The arg parameter is a pointer to an ifreq structure as defined in ioctl.h. Sets the interface routing metric to the value passed in the argument. This option is for IBM use only.
TCP_PSH_LAST
Sets the TCP push (PSH) flag in the last packet generated from a send type API call. If this option is enabled for a socket and a send type API causes multiple packets to be built, the PSH flag is set only in the last packet. If this option is disabled for a socket and a send type API causes multiple packets to be built, the PSH flag is set in every packet. The arg parameter is a pointer to an integer. If the integer is any nonzero value, the PSH flag is set only in the last packet. If the integer is 0, the PSH flag is set in every packet. This option is disabled by default, and is for TCP sockets using TCP/IP native stack support.
Note: The TCP_PSH_LAST parameter is unique to the z/TPF system.
TPF_NOSLOWSTART
Disables slow start processing for the initial start of this socket. Slow start processing is a congestion control algorithm used by TCP sockets. The arg parameter is a pointer to an integer. If the integer is any nonzero value, the socket does not perform slow start processing. If the integer is 0, the socket performs slow start processing. If the z/TPF system is the server, this option must be set before the accept function is issued. If the z/TPF system is the client, this option must be set before the connect function is issued. Slow start processing is performed automatically when congestion occurs. This option is for TCP sockets only.
Note: The TPF_NOSLOWSTART parameter is unique to the z/TPF system.
TPF_NOSWEEP
Skips the socket sweeper processing for this socket. The socket sweeper facility monitors open sockets and closes those that are idle. An idle socket is one that has had no socket application programming interfaces (APIs) issued recently by any application. The arg parameter is a pointer to an integer. If the integer is any nonzero value, the socket sweeper facility will skip monitoring the socket descriptor supplied by the s parameter for socket API activity. If the integer is any nonzero value and the SLOWSWP parameter on the SNAKEY macro is any nonzero value, the slow socket sweeper facility monitors the socket descriptor. If the integer is 0, the socket sweeper monitors the socket descriptor.
Note: The TPF_NOSWEEP parameter is unique to the z/TPF system.
TPF_RETURN_MESSAGES
Returns (via the TCP/IP native stack support socket close (UCLO) user exit) any output data sent by the application that has not been sent to the network when this socket is closed. The arg parameter is a pointer to an integer. If the integer is any nonzero value, output data that has not been sent is returned when the socket is closed. If the integer is 0, output data that has not been sent is not returned when the socket is closed. This option is for TCP sockets only.
Note: The TPF_RETURN_MESSAGES parameter is unique to the z/TPF system.
TPF_RST_IPL
Sends a TCP reset (RST) for this socket after a soft IPL. If this option is not set, the TCPRST parameter on the SNAKEY macro is used to determine whether a RST is sent. This parameter is valid only for TCP sockets. The arg parameter is a pointer to an integer. If the integer is any nonzero value, a RST is sent. If the integer is 0, a RST is not sent.
Note: The TPF_RST_IPL parameter is unique to the z/TPF system.
TPF_SURVIVE_CYCLE
Allows a socket to survive cycle down. By default, all sockets are cleaned up when the system cycles below CRAS state. The arg parameter is a pointer to an integer. If the integer is any nonzero value, the socket will not be cleaned up during cycle down processing. If the integer is 0, the socket will be cleaned up during cycle down processing.
Note: The TPF_SURVIVE_CYCLE parameter is unique to the z/TPF system.
arg
Pointer to the data associated with cmd, and its format depends on the command that is requested.

Normal return

Return code 0 indicates that the function was successful.

Error return

A return code equal to -1 indicates an error. You can get the specific error code by calling sock_errno. See z/TPF C/C++ Language Support User's Guide for more information about socket errors.
SOCOPNOTSUP
The operation is not supported on the socket.
SOCNOTCONN
The socket is not connected.
SOCINVAL
The request is not valid or not supported or the buffer passed was not the required minimum length.
SOCFAULT
Using buf and len would result in an attempt to access a protected address space.
SOCNOTSOCK
The s parameter is not a valid socket descriptor.
E1052STATE
The socket was closed because the system was in or cycling down to 1052 state.

Programming considerations

  • The operating characteristics of sockets can be controlled with the ioctl function. The operations to be controlled are determined by the cmd parameter. The arg parameter is a pointer to data associated with the particular command.
  • The TPF_NOSWEEP parameter only affects socket sweeper processing based on application idle timeouts. Sockets that issue this cmd parameter value can still be swept because of network idle timeouts.
  • TPF_NOSWEEP has no effect when the z/TPF socket sweeper facility is not active. ZNKEY SOCKSWP displays the current sweep timeout; a timeout of 0 indicates the sweeper is not active. When the socket sweeper facility is activated, the latest value for TPF_NOSWEEP determines whether the socket sweeper monitors the socket descriptor.
  • Open sockets are subject to socket sweeper monitoring by default.
  • New TCP sockets are subject to slow start processing by default.
  • If your z/TPF application passes multiple messages on a single send type API call or if the remote application is capable of processing the start of a message before the entire message has been received, TCP_PSH_LAST should not be used.
  • TPF_SURVIVE_CYCLE allows a socket to survive cycle down. If the application using the socket is a long-running ECB, the application program must allow the ECB to survive cycle down by setting bit CCE1CYC in the ECB.

Examples

The following example sets server_sock to be in nonblocking mode. 
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/ioctl.h>
⋮
int dontblock;
int rc;
int server_sock
⋮
/* Place the socket into nonblocking mode */
dontblock = 1;
rc = ioctl(server_sock, FIONBIO, (char *) &dontblock);
For more information about z/TPF TCP/IP support, see z/TPF Transmission Control Protocol/Internet Protocol.