setsockopt()

The setsockopt() call sets options associated with a socket. It can be called only for sockets in the AF_INET domain. Options can exist at multiple protocol levels; they are always present at the highest socket level.

When manipulating socket options, you must specify the level at which the option resides and the name of the option. To manipulate options at the socket level, the level parameter must be set to SOL_SOCKET, as defined in SOCKET.H. To manipulate options at the TCP level, the level parameter must be set to IPPROTO_TCP, as defined in SOCKET.H. To manipulate options at any other level, such as the IP level, supply the appropriate protocol number for the protocol controlling the option. Currently, the SOL_SOCKET, IPPROTO_TCP, and IPPROTO_IP levels are supported. The getprotobyname() call can be used to return the protocol number for a named protocol.

#include <manifest.h>
#include <bsdtypes.h>
#include <socket.h>
 
int setsockopt(int s, int level, int optname, char *optval, int optlen)

Parameter: Description
s: The socket descriptor
level: The level for which the option is being set
optname: The name of a specified socket option. See GETSOCKOPT/SETSOCKOPT command values for the numeric values of optname.
optval: The pointer to option data
optlen: The length of the option data

The optval and optlen parameters are used to pass data used by the particular set command. The optval parameter points to a buffer containing the data needed by the set command. The optlen parameter must be set to the size of the data pointed to by optval.

All of the socket level options except SO_LINGER expect optval to point to an integer and optlen to be set to the size of an integer. When the integer is nonzero, the option is enabled. For toggle type options, if the integer is nonzero, the option is enabled. If it is 0, the option is disabled. The SO_LINGER option expects optval to point to a linger structure, as defined in SOCKET.H. This structure is defined in the following example:

struct  linger
{
        int     l_onoff;                /* option on/off */
        int     l_linger;               /* linger time */
};

The l_onoff field is set to 0 if the SO_LINGER option is disabled. A nonzero value enables the option. The l_linger field specifies the amount of time to wait on close. The units of l_linger are seconds.

The following option is recognized at the TCP level:

Option

Description

TCP_NODELAY

Toggles the use of Nagle algorithm (RFC 896) for all data sent over the socket. This option is not supported for AF_IUCV sockets. Under most circumstances, TCP sends data when it is presented from the application.

However, when outstanding data has not yet been acknowledged, TCP will defer the transmission of any new data from the application until all of the outstanding data has been acknowledged. The Nagle algorithm enforces this deferral, even in cases where the receiver's window is sufficiently open to accept the new data. For interactive applications, such as ones that send a stream of mouse events which receive no replies, this deferral of transmission might result in significant delays. For these types of applications, disabling Nagle algorithm would improve response time.

Notes:

When Nagle algorithm is enabled, TCP will wait to send small amounts of data until the acknowledgment for the previous data is received.
When Nagle algorithm is disabled, TCP will send small amounts of data even before the acknowledgment for previous data sent is received.

The following keywords are recognized at the socket level:

Keyword

Description

SO_RCVBUF

Sets the size of the data portion of the TCP/IP receive buffer in OPTVAL. The size of the data portion of the receive buffer is protocol-specific. If the requested size exceeds the allowed size, the following situation occurs:

If the protocol is TCP, a return value of -1 and errno of ENOBUFS is set. The receive buffer size is unchanged.
For maximum values for the TCP protocol, see the TCPCONFIG TCPRCVBUFRSIZE and TCPMAXRCVBUFSIZE parameters in the z/OS Communications Server: IP Configuration Reference.
If the protocol is UDP or RAW, a return value of 0 is returned and the buffer size is set to 65535.

SO_SNDBUF

Sets the size of the data portion of the TCP/IP send buffer in OPTVAL. The size of the data portion of the send buffer is protocol-specific. If the requested size exceeds the allowed size, the following situation occurs:

If the protocol is TCP, a return value of -1 and errno of ENOBUFS is set. The send buffer size for the TCP connection is set to the maximum size. The value of the send buffer size can be retrieved by issuing GETSOCKOPT for SO_SNDBUF.
For maximum values for the TCP protocol, see the TCPCONFIG TCPSENDBUFRSIZE parameters in the z/OS Communications Server: IP Configuration Reference.
If the protocol is UDP or RAW, a return value of 0 is returned and the buffer size is set to 65535.

SO_BROADCAST

Toggles the ability to broadcast messages. The default is disabled. If this option is enabled, it allows the application to send broadcast messages over s when the interface specified in the destination supports broadcasting of packets. This option has no meaning for stream sockets.

SO_KEEPALIVE

Toggles the TCP keep alive mechanism for a stream socket. The default is disabled. When activated, the keep alive mechanism periodically sends a packet on an otherwise idle connection. If the remote TCP does not respond to the packet, or to retransmissions of the packet, the connection is ended with the error ETIMEDOUT.

SO_LINGER

Lingers on close if data is present. The default is disabled. When this option is enabled and there is unsent data present when close() is called, the calling application is blocked during the close() call until the data is transmitted, or the connection has timed out. If this option is disabled, the close() call returns without blocking the caller, and the TCP/IP address space still waits to try to send the data. Although the data transfer is usually successful, it cannot be guaranteed, because the TCP/IP address space waits a finite amount of time while trying to send the data. This option has meaning for stream sockets only.

SO_OOBINLINE

Toggles the reception of out-of-band data. The default is disabled. When this option is enabled, it causes out-of-band data to be placed in the normal data input queue as it is received, making it available to recv(), recvfrom(), and recvmsg() without having to specify the MSG_OOB flag in those calls. When this option is disabled, it causes out-of-band data to be placed in the priority data input queue as it is received, making it available to recv(), recvfrom(), and recvmsg() only by specifying the MSG_OOB flag in those calls. This option has meaning for stream sockets only.

SO_REUSEADDR

Toggles local address reuse. The default is disabled. This alters the normal algorithm used in the bind() call.

The normal bind() call algorithm allows each internet address and port combination to be bound only once. If the address and port have been bound already, a subsequent bind() will fail and return error EADDRINUSE.

After the 'SO_REUSEADDR' option is active, the following situations are supported:

A server can bind() the same port multiple times as long as every invocation uses a different local IP address and the wildcard address INADDR_ANY is used only one time per port.
A server with active client connections can be restarted and can bind to its port without having to close all of the client connections.
For datagram sockets, multicasting is supported so multiple bind() calls can be made to the same class D address and port number.

The following options are recognized at the IP level (IPPROTO_IP):

Option: Description
IP_MULTICAST_TTL: Sets the IP time to live of outgoing multicast datagrams. The default value is 1 (multicast is available only to the local subnet).
IP_MULTICAST_LOOP: Enables or disables the loopback of outgoing multicast datagrams. The default value is enabled.
IP_MULTICAST_IF: Sets the interface for sending outbound multicast datagrams from the socket application.
Note: Multicast datagrams can be transmitted only on one interface at a time.
IP_ADD_MEMBERSHIP: Joins a multicast group on a specific interface. An interface has to be specified with this option. Only applications that want to receive multicast datagrams need to join multicast groups.
IP_DROP_MEMBERSHIP: Exits a multicast group.

Return values

The value 0 indicates success; the value -1 indicates an error. Errno identifies the specific error.

Errno: Description
EBADF: The s parameter is not a valid socket descriptor.
EFAULT: Using optval and optlen parameters would result in an attempt to access storage outside the caller address space.
ENOBUFS: No buffer space is available.
ENOPROTOOPT: The optname parameter is unrecognized, or the level parameter is not SOL_SOCKET.

Example

See getsockopt() to see how the getsockopt() options set is queried.

int rc;
int s;
int optval;
struct linger l;
int setsockopt(int s, int level, int optname,char *optval, int optlen);
⋮
/* I want out of band data in the normal inputqueue */
optval = 1;
rc = setsockopt(s, SOL_SOCKET, SO_OOBINLINE, (char *) &optval, sizeof(int));
 
⋮
/* I want to linger on close */
l.l_onoff  = 1;
l.l_linger = 100;
rc = setsockopt(s, SOL_SOCKET, SO_LINGER, (char *) &l, sizeof(l));

Related calls

fcntl(), getprotobyname(), getsockopt(), ioctl(), socket()