Socket Options

This section describes how to read or set various options that modify the behavior of sockets and their underlying communications protocols.

When you are manipulating a socket option, you must specify which level the option pertains to. This describes whether the option applies to the socket interface, or to a lower-level communications protocol interface.

Socket Option Functions

Here are the functions for examining and modifying socket options. They are declared in sys/socket.h.

int function>getsockopt/function> (int socket, int level, int optname, void *optval, socklen_t *optlen-ptr) The getsockopt function gets information about the value of option optname at level level for socket socket.

The option value is stored in a buffer that optval points to. Before the call, you should supply in *optlen-ptr the size of this buffer; on return, it contains the number of bytes of information actually stored in the buffer.

Most options interpret the optval buffer as a single int value.

The actual return value of getsockopt is 0 on success and -1 on failure. The following errno error conditions are defined:

EBADF

The socket argument is not a valid file descriptor.

ENOTSOCK

The descriptor socket is not a socket.

ENOPROTOOPT

The optname doesn't make sense for the given level.

int function>setsockopt/function> (int socket, int level, int optname, void *optval, socklen_t optlen) This function is used to set the socket option optname at level level for socket socket. The value of the option is passed in the buffer optval of size optlen.

The return value and error codes for setsockopt are the same as for getsockopt.

Socket-Level Options

int function>SOL_SOCKET/function> Use this constant as the level argument to getsockopt or setsockopt to manipulate the socket-level options described in this section.

Here is a table of socket-level option names; all are defined in the header file sys/socket.h.

SO_DEBUG

This option toggles recording of debugging information in the underlying protocol modules. The value has type int; a nonzero value means "yes".

SO_REUSEADDR

This option controls whether bind (the section called “Setting the Address of a Socket”) should permit reuse of local addresses for this socket. If you enable this option, you can actually have two sockets with the same Internet port number; but the system won't allow you to use the two identically-named sockets in a way that would confuse the Internet. The reason for this option is that some higher-level Internet protocols, including FTP, require you to keep reusing the same port number.

The value has type int; a nonzero value means "yes".

SO_KEEPALIVE

This option controls whether the underlying protocol should periodically transmit messages on a connected socket. If the peer fails to respond to these messages, the connection is considered broken. The value has type int; a nonzero value means "yes".

SO_DONTROUTE

This option controls whether outgoing messages bypass the normal message routing facilities. If set, messages are sent directly to the network interface instead. The value has type int; a nonzero value means "yes".

SO_LINGER

This option specifies what should happen when the socket of a type that promises reliable delivery still has untransmitted messages when it is closed; see the section called “Closing a Socket”. The value has type struct linger.

function>struct linger/function> This structure type has the following members:

int l_onoff

This field is interpreted as a boolean. If nonzero, close blocks until the data are transmitted or the timeout period has expired.

int l_linger

This specifies the timeout period, in seconds.

SO_BROADCAST

This option controls whether datagrams may be broadcast from the socket. The value has type int; a nonzero value means "yes".

SO_OOBINLINE

If this option is set, out-of-band data received on the socket is placed in the normal input queue. This permits it to be read using read or recv without specifying the MSG_OOB flag. the section called “Out-of-Band Data”. The value has type int; a nonzero value means "yes".

SO_SNDBUF

This option gets or sets the size of the output buffer. The value is a size_t, which is the size in bytes.

SO_RCVBUF

This option gets or sets the size of the input buffer. The value is a size_t, which is the size in bytes.

SO_STYLE, SO_TYPE

This option can be used with getsockopt only. It is used to get the socket's communication style. SO_TYPE is the historical name, and SO_STYLE is the preferred name in GNU. The value has type int and its value designates a communication style; see the section called “Communication Styles”.

SO_ERROR

This option can be used with getsockopt only. It is used to reset the error status of the socket. The value is an int, which represents the previous error status.