GETSOCKOPT(2) — Series 300 and 800 Only

NAME

getsockopt, setsockopt − get and set options on sockets

SYNOPSIS

#include <sys/types.h>
#include <sys/socket.h>

getsockopt(s, level, optname, optval, optlen)
int s, level, optname;
char *optval;
int *optlen;

setsockopt(s, level, optname, optval, optlen)
int s, level, optname;
char *optval;
int optlen;

DESCRIPTION

Getsockopt and setsockopt manipulate options associated with a socket. The socket is identified by the socket descriptor s. Options may exist at multiple protocol levels, and they are always present at the uppermost “socket” level. (See socket(2).)

When manipulating socket options, the level at which the option resides (level) and the name of the option (optname) must be specified. To manipulate options at the “socket” level, level is specified as SOL_SOCKET. To manipulate options at any other level, the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP (See getprotoent(3N).)

The parameters optval and optlen are used to access option values for setsockopt. For getsockopt, the parameters identify a buffer in which the value for the requested option is to be returned. For getsockopt, optlen is a value-result parameter, initially containing the size of the buffer pointed to by optval, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, optval can be supplied as 0. If optval is not 0 and the named option does not have a value associated with it, then optlen is returned as 0. If the memory pointed to by optval is not large enough to contain the entire option value, then only the first optlen bytes of the value are returned.

To determine whether or not an option is set, the return value of getsockopt must be examined.

Optname and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file <sys/socket.h> contains definitions for “socket” level options. (See socket(2).) Options at other protocol levels vary in format and name. Consult the appropriate entries in Section 7P, such as tcp(7P).

The “socket” level options defined in the include file <sys/socket.h> are explained below:

SO_DEBUG no functionality; included only for compatibility.

SO_DONTROUTE causes outgoing messages to bypass standard routing facilities and to be routed by the network portion of the internet address.

SO_REUSEADDR allows local address reuse.

SO_KEEPALIVE keeps otherwise idle connected sockets active by forcing transmissions every 45 seconds, for up to 6 minutes without a response.

SO_LINGER lingers on close if data present.

SO_DONTLINGER does not linger on close.

SO_RCVBUF for stream sockets, changes the buffer size of a socket’s receive socket buffer. You can increase a stream socket’s buffer size at any time but decrease it only prior to establishing a connection.

SO_SNDBUF for stream sockets, changes the buffer size of a socket’s send socket buffer. You can increase a stream socket’s buffer size at any time but decrease it only prior to establishing a connection.

Setsockopt(2) and getsockopt(2) are used to set and get options, respectively. None of these options are supported for SOCK_DGRAM sockets. When a socket is created, none of the options are enabled except SO_DONTLINGER.

SO_REUSEADDR indicates the rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. This allows multiple SOCK_STREAM sockets to be bound to the same local address, as long as all existing sockets at the desired address are in a connected state before the bind(2) is done on the new socket. The SO_REUSEADDR option has no effect on SOCK_DGRAM sockets.

The SO_KEEPALIVE option defaults to off.

SO_LINGER and SO_DONTLINGER control the actions taken when unsent messages are queued on a SOCK_STREAM socket and a close(2) is performed. If SO_LINGER is set with a non-zero linger interval, the system blocks the process on the close(2) attempt until it is able to transmit the data or until it decides it is unable to deliver the information. If SO_LINGER is set with a linger interval of zero, the connection is immediately terminated on the close(2) of the socket, and any unsent data that are queued on the connection are lost. The linger interval is an integer value whose address is specified in optval. If SO_DONTLINGER is specified (which is the default upon socket creation) and a close(2) is issued, the call returns immediately. The system still gracefully brings down the connection by transmitting any queued data, if possible. The setting of SO_LINGER and SO_DONTLINGER are mutually exclusive. Setting one unsets the other. You can set either any time during the life of an established connection. The setting of SO_LINGER and SO_DONTLINGER have no effect upon the action of shutdown(2).

SO_RCVBUF and SO_SNDBUF change the buffer size of a stream socket. You can increase a stream socket’s buffer size at any time but decrease it only prior to establishing a connection. The maximum buffer size is 65535 bytes. The buffer sizes are integer values whose addresses are specified in optval. The default buffer size is 4096 bytes.

RETURN VALUE

If the call is successful, 0 is returned. If it fails, −1 is returned and an error code is stored in errno.

DIAGNOSTICS

If the option is set, getsockopt returns without error and any option value is returned as described above. If the option is not set, getsockopt returns −1, and errno is set to the ENOPROTOOPT error.

The call to getsockopt or setsockopt fails if:

[EBADF] The argument s is not a valid descriptor.

[ENOBUFS] No buffer space is available.

[ENOTSOCK] The argument s is a file, not a socket.

[ENOPROTOOPT] In getsockopt, the requested option is currently not set.

[EINVAL] The option is unknown at the specified protocol level, or the socket has been shut down.

[EFAULT] The optval or, in the case of getsockopt, optlen parameters are not valid pointers.

DEPENDENCIES

Implemented on the Series 300 and 800 only.

“socket” level options are supported only for TCP SOCK_STREAM sockets, not UDP SOCK_DGRAM sockets.

AUTHOR

UCB (University of California at Berkeley)

Museum

Related Articles