setsockopt: Set options associated with a socket

The setsockopt socket function sets options associated with a socket.

Last updated

  • Changed for PUT15.
  • Changed for PUT14.
  • Changed for PUT04.
  • Added for PUT00.

Format

#include  <sys/socket.h>
int       setsockopt(int s,
                     int level,
                     int optname,
                     char *optval,
                     int optlen);
s
The socket descriptor.
level
The level that the option is set for. Specify the value SOL_SOCKET.
optname
The name of a specified socket option. Use one of the following values:
SO_BROADCAST
Toggles the ability to broadcast messages. Enabling this option lets the application send broadcast messages over s if the interface specified in the destination supports broadcasting of packets. This option has no meaning for stream sockets.
SO_KEEPALIVE
Toggles the ability to send probes on idle sockets to verify that the socket is still active. This option has meaning only for stream sockets.
SO_LINGER
Waits to complete the close function if data is present. When this option is enabled and there is unsent data present when the close function is called, the calling application is blocked during the close function until the data is transmitted or the connection has timed out. The close function returns without blocking the caller. This option has meaning only for stream sockets.
SO_OOBINLINE
Toggles reception of out-of-band data. Enabling this option causes out-of-band data to be placed in the normal data input queue as it is received, making it available to recvfrom without having to specify the MSG_OOB flag in those calls. Disabling this option causes out-of-band data to be placed in the priority data input queue as it is received, making it available to recvfrom only by specifying the MSG_OOB flag in these calls. This option has meaning only for stream sockets.
SO_INPUT_PRIORITY
Allows you to set the input message priority for this socket. Valid values for this parameter are 0-9. If you set the priority to 0, the application's priority defined in the network services database is used. For sockets with a priority value of 1, traffic is read in and processed even during input list shutdown and if traffic limiting is enabled for this server, traffic limiting checks are bypassed. When there are resource constraints, packets with the largest priority values are discarded first. The priority for an individual socket overrides the application's priority defined in the network services database. This option is valid only for TCP and UDP sockets and is unique to the z/TPF system. Input message priority has meaning only for sockets using OSA-Express.

See z/TPF Transmission Control Protocol/Internet Protocol for information about input message priority.

SO_RCVBUF
Allows you to set the size of the receive buffer to a value to suit your application needs. The minimum size is 512 bytes. The maximum size is 1048576 bytes.
SO_RCVLOWAT
This option has meaning only for TCP sockets. With this option, you can set the receive buffer low-water mark, which is the minimum amount of data that must be received before a read, recv, recvfrom, activate_on_receipt, or activate_on_receipt_with_length function will be completed. Specify a value in the range of 0 - 1048576.
SO_RCVTIMEO
Defines the receive timeout value, which is how long the system will wait for a read, recv, recvfrom, tpf_read_TCP_message, activate_on_receipt, activate_on_receipt_with_length, activate_on_receipt_of_TCP_message, accept, activate_on_accept, or connect function to be completed before timing out the operation. A returned value of 0 indicates the system will not time out. The maximum value is 32767 seconds.
SO_REUSEADDR
Toggles local address reuse. Enabling this option lets local addresses that are already in use to be bound. This changes the normal algorithm used in the bind function. At connect time, the system checks that no local address and port have the same remote address and port and returns error code SOCADDRINUSE if the association already exists.
SO_DONTROUTE
Toggles the routine bypass for outgoing messages. When you enable this option, outgoing messages bypass the standard routing algorithm and are directed to the appropriate network interface according to the network portion of the destination address. When enabled, this option lets you send packets only to directly connected networks (networks for which the host has an interface). This option has no meaning for stream sockets.
SO_SNDBUF
Allows you to set the size of the send buffer to a value to suit your application needs. The minimum size is 512 bytes and the maximum size is 1048576 bytes.
SO_SNDLOWAT
Allows you to set the send buffer low-water mark, which is the minimum amount of space that must be available in the send buffer to allow a select for write function to be processed. Specify a value in the range of 0 - 32767.
SO_SNDTIMEO
Defines the send timeout value, which is how long the system will wait for a send, sendto, write, or writev function to be completed before timing out the operation. A returned value of 0 indicates the system will not time out. The maximum value is 32767 seconds.
SO_TCPDELAY
Defines the TCP delayed acknowledgment timer value, which is the amount of time that the z/TPF system waits before sending a stand-alone acknowledgment (ACK) to acknowledge data on this TCP socket. Values are specified in tens of milliseconds, ranging from 1 (10 ms) to 50 (500 ms). If you do not specify this option for this socket, the system default value (the value of the TCPDELAY parameter in CTK2) is used. This option is valid only for TCP sockets that are using TCP/IP native stack support.
Note: The SO_TCPDELAY socket option is unique to the z/TPF system.
SO_TCPDUACK
Defines the duplicate acknowledgment (ACK) for fast retransmit value, which is the number of duplicate standalone ACKs that the z/TPF system receives for a given socket before generating a fast retransmit. A value of 0 means that fast retransmits will not happen for the socket. If you do not specify this option for this socket, the system default value (the value of the TCPDUACK parameter in CTK2) is used. This option is valid only for TCP sockets that are using TCP/IP native stack support. Specify a value in the range of 0 - 5.
Note: The SO_TCPDUACK socket option is unique to the z/TPF system.
SO_UDPMPSIZ
Defines the maximum packet size for the socket. The minimum size is 576 bytes and the maximum is 3840. If you do not specify this option for this socket, the system default value (the value of the UDPMPSIZ parameter in CTK2) is used. This option is valid only for UDP sockets.
Note:
  1. The maximum packet size used for the socket is the smaller value of SO_UDPMPSIZ and the maximum transmission unit (MTU) of the link over which the packet is to be sent.
  2. The SO_UDPMPSIZ socket option is unique to the z/TPF system.
optval
A pointer to option data. The optval and optlen parameters are used to pass data used by a particular command. The optval parameter points to a buffer containing the data needed by the command. The optval parameter is optional and can be set to the NULL pointer if data is not needed by the command.
optlen
The length of the option data. The optlen parameter must be set to the size of the data pointed to by optval.

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. For more information about socket errors, see Socket error return codes.
E1052STATE
The socket was closed because the system was in or cycling down to 1052 state.
SOCFAULT
The pointer to the optval parameter is NULL.
SOCINVAL
The value of the optlen parameter is not a valid size.
SOCNOPROTOOPT
The optname parameter is not recognized, or the level parameter is not valid.
SOCNOTSOCK
The s parameter is not a valid socket descriptor.

Programming considerations

  • The setsockopt function sets options associated with a socket.
  • When specifying socket options, you must specify the name of the option and the level at which the option resides.
  • The length passed must be a minimum of 4 bytes.
  • When you use socket level options other than SO_LINGER, optval points to an integer and optlen is set to the size of the integer. When the integer is nonzero, the option is enabled. When the integer is 0, the option is disabled. The SO_LINGER option expects optval to point to a linger structure. This structure is defined in the following example: 
    struct linger
      int     l_onoff;              /* option on/off */
      int     l_linger;             /* linger time   */
⋮
  • The l_onoff is set to 0 if the SO_LINGER option is being disabled. A nonzero value enables the option. The l_linger field specifies the amount of time to wait before completing a close when there is still data to be sent. The units of l_linger are seconds.

Examples

In the following example, out-of-band data is set in the normal input queue. 
#include <sys/socket.h>
⋮
int rc;
int server_sock;
int optval;
⋮
optval = 1;
rc = setsockopt(server_sock, SOL_SOCKET, SO_OOBINLINE,
                (char *)&optval, sizeof(int));
⋮