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