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:
- 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:
- 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.
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()