getsockopt(2)
NAME
getsockopt(), setsockopt() − get and set options on sockets
SYNOPSIS
#include <sys/socket.h>
int getsockopt(
int s,
int level,
int optname,
void *optval,
int *optlen
);
int setsockopt(
int s,
int level,
int optname,
const void *optval,
int optlen
);
_XOPEN_SOURCE_EXTENDED only
int getsockopt(
int s,
int level,
int optname,
void *optval,
size_t *optlen
);
int setsockopt(
int s,
int level,
int optname,
const void *optval,
size_t optlen
);
DESCRIPTION
The getsockopt() and setsockopt() system calls manipulate options associated with a socket. The socket is identified by the socket descriptor s. Options can 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 specify options at another level, level should be the protocol number specified in <netinet/in.h> (for example, IPPROTO_TCP).
The parameters optval and optlen specify the value of the option. optval is the address of the data structure that contains the option value, and optlen is the length of the data structure. The type and value of the data structure that optval points to depends on the option. For "boolean" options, the value may be zero (not set) or non-zero (set). The value of other options depends on the purpose of the option. Usually, neither optval nor optlen may be the NULL address or zero; see individual protocol manual entries for any exceptions, such as tcp(7P) and ip(7P).
For setsockopt(), optval and optlen are used to pass information from the application to the system. optval is the address of a location in memory that contains the option information to be passed to the system. The parameter optlen is an integer value that specifies the size, in bytes, of the data structure pointed to by optval.
For getsockopt(), optval and optlen are used to pass information from the system to the application. The parameter optlen is the address of an int variable. Before calling getsockopt(), the application should set the value of the variable to the maximum size, in bytes, of the data structure pointed to by optval. Normally, upon return, the variable pointed to by optlen is set to the actual size the data returned in the structure pointed to by optval, if getsockopt() returns without error.
The following “socket” level option names (optname) are defined in <sys/socket.h>. The type of the variable pointed to by optval is indicated in parentheses. Options for other protocol levels are described in the individual protocol manual pages, such as tcp(7P) and ip(7P).
SO_ACCEPTCONN (int; boolean ) Returns a non-zero value if socket listening is enabled, otherwise returns a zero value.
SO_BROADCAST (int; boolean; AF_INET SOCK_DGRAM sockets only) Allows the application to send messages to a broadcast address. Default: disallowed.
SO_DEBUG (int; boolean; AF_INET SOCK_STREAM sockets only) Enables or disables the recording of internal debug information. Default: disabled.
SO_DONTROUTE (int; boolean; AF_INET sockets only) Causes outbound messages to bypass normal routing facilities. Instead, messages are sent through the appropriate network interface based on the network portion of the destination address. Default: disabled.
SO_ERROR (int) Returns any pending error on the socket, and clears the error status. The value returned by SO_ERROR would be the value of errno after the next socket data transfer system call.
SO_KEEPALIVE (int; boolean; AF_INET SOCK_STREAM sockets only) If enabled, keeps an otherwise idle TCP connection active. Default: disabled.
SO_LINGER (struct linger; AF_INET SOCK_STREAM sockets only) Controls whether or not an application "lingers" (waits) if there are untransmitted data in the send socket buffer when the socket is closed. The data type struct linger is defined in <sys/socket.h>. Default: disabled, as if l_onoff had been set to zero. (See details below.)
SO_OOBINLINE (int; boolean; AF_INET SOCK_STREAM sockets only) If enabled, specifies that out-of-band data (TCP "urgent data") should be left "in-line" among the normal data stream. Otherwise, one byte of out-of-band data is pulled out of the data stream, and it is accessible only by setting MSG_OOB in the flags parameter when the application reads the data (see recv(2)). Default: disabled.
SO_PMTU (int; boolean; AF_INET sockets only) If enabled, specifies that Path MTU Discovery is to be used to determine the optimal datagram size for the route. Default: enabled for SOCK_STREAM sockets; disabled for SOCK_DGRAM sockets.
SO_RCVBUF (int) Specifies the maximum size, in bytes, of the receive socket buffer. For SOCK_DGRAM sockets, the receive buffer size may limit the maximum size of messages that the socket can receive. Default: protocol-dependent; see individual protocol manual entries, such as tcp(7P) and udp(7P).
SO_REUSEADDR (int; boolean; AF_INET sockets only) If enabled, allows a local address to be reused in subsequent calls to bind(). Default: disallowed.
SO_SNDBUF (int) Specifies the maximum size, in bytes, of the send socket buffer. For SOCK_STREAM sockets, the send buffer size limits how much data can be queued for transmission before the application is blocked. For SOCK_DGRAM sockets, the send buffer size may limit the maximum size of messages that the application can send through the socket. Default: protocol-dependent; see individual protocol manual entries, such as tcp(7P) and udp(7P).
SO_TYPE (int) Returns the socket type.
SO_USELOOPBACK (int; boolean) Not used internally; provided only for compatibility.
Setting the SO_BROADCAST option allows the application to send messages through the SOCK_DGRAM socket to a broadcast destination address.
If SO_DONTROUTE is set, the system does not use the network routing tables when determining which interface to use to send an outbound message. Instead, the system sends the message through the interface whose network address matches the network portion of the destination address. If SO_DONTROUTE is not set (default), the system uses the network routing tables.
If SO_KEEPALIVE is disabled (default), a TCP connection may remain idle until the connection is released at the protocol layer. If SO_KEEPALIVE is enabled and the connection has been idle for two hours, TCP sends a packet to the remote TCP to acknowledge that the connection is still active. If the remote TCP does not respond within 75 seconds, TCP sends another packet. If TCP sends a total of 8 packets without receiving any response from the remote TCP (that is, after 10 minutes have passed), TCP drops the connection. In that case, the next attempt to read from the socket (for example, by calling recv()) returns an error, and errno is set to ETIMEDOUT.
SO_LINGER controls the actions to be taken when there are untransmitted data in a SOCK_STREAM send socket buffer when the socket is closed, either due to an explicit call to close() or because the application terminates normally or abnormally. The action is determined by the values of members of the struct linger data structure pointed to by optval in a call to setsockopt(). The data type struct linger is defined in <sys/socket.h>. If l_onoff is zero (the default action), close() returns immediately, but the system tries to transmit any unsent data and release the protocol connection gracefully. If l_onoff is non-zero and l_linger is zero, close() returns immediately, any unsent data is discarded, and the protocol connection is aborted. If both l_onoff and l_linger are non-zero, close() does not return until the system has tried to transmit all unsent data and release the connection gracefully. In that case, close() can return an error, and errno may be set to ETIMEDOUT, if the system is unable to transmit the data after a protocol-defined time limit. Note that the value of l_linger is treated simply as a boolean; a non-zero value is not interpreted as a time limit( see _XOPEN_SOURCE_EXTENDED only below). SO_LINGER does not affect the actions taken when the function shutdown() is called.
If SO_OOBINLINE is set, out-of-band data (TCP "urgent data") is left "in-line" among the normal data stream. In that case, the SIOCATMARK ioctl() request must be used to determine if the inbound data stream has been read up to the point where the out-of-band data begins. If multiple transmissions of out-of-band data are received before the application reads them, all of the data is left in-line; however, SIOCATMARK indicates the location of only the last transmission of out-of-band data. If SO_OOBINLINE is not set (default), only one byte of out-of-band is saved. This byte is pulled out of the normal data stream, and it is accessible only by setting MSG_OOB in the flags parameter when the application reads the data (see recv(2)). In that case, if multiple transmissions of out-of-band data are received before the application reads them, previous bytes of out-of-band data are lost.
If SO_PMTU is enabled for SOCK_STREAM sockets (default), the Don’t Fragment (DF) bit in IP datagrams is set for all TCP transmissions. If a datagram is dropped by a gateway because it is too big to be forwarded without fragmenting, the originating system will receive an ICMP "Datagram Too Big" message with the new PMTU information. TCP will automatically adjust to the new datagram size, and none of the TCP applications will be notified of the ICMP "Datagram Too Big" message. The dropped data will be retransmitted when the TCP retransmission timer expires. If SO_PMTU is disabled for SOCK_STREAM sockets, the datagrams may be fragmented by intermediate gateways, which sometimes results in non-optimal network usage and lower throughput.
If SO_PMTU is enabled for SOCK_DGRAM sockets, the application is notified of any ICMP "Datagram Too Big" messages received for the UDP port. The system notifies the corresponding UDP application by returning errno set to EAGAIN for the next call to send() or recv() after the ICMP "Datagram Too Big" message is received. If the socket is using asynchronous I/O (see FIOASYNC and SIOCSPGRP in socket(7)), the system also sends a SIGIO signal to the process or process group. As usual, the UDP application is responsible for handling the retransmission of any undelivered datagrams. If SO_PMTU is disabled for SOCK_DGRAM sockets (default), UDP messages are automatically fragmented as needed.
Setting the SO_REUSEADDR option allows the local socket address to be reused in subsequent calls to bind(). This permits multiple SOCK_STREAM sockets to be bound to the same local address, as long as all existing sockets with the desired local address are in a connected state before bind() is called for a new socket. For SOCK_DGRAM sockets, SO_REUSEADDR allows multiple sockets to receive UDP multicast datagrams addressed to the bound port number. For all SOCK_DGRAM sockets bound to the same local address, SO_REUSEADDR must be set before calling bind().
SO_RCVBUF and SO_SNDBUF specify the maximum number of bytes that the system may allocate, as needed, for the receive and send buffers, respectively. These limits are merely approximate because of the way in which memory is allocated. For example, a large number of small transmissions may require more memory than the sum of the number of data bytes sent. The default receive and send buffer sizes are protocol-specific. For more information, see the appropriate manual entries, such as tcp(7P) and udp(7P).
For SOCK_STREAM sockets, larger buffer sizes can improve performance. An application can increase the size of the receive buffer at any time; however, it can decrease the receive buffer size only prior to calling connect() or listen(). An application can increase or decrease the send buffer at any time.
For SOCK_DGRAM sockets, the size of the receive and send buffers limits the size of the maximum datagram that can be received and sent, respectively. These limits include socket buffer space that is also used to save the sender’s socket address (struct sockaddr) which is associated with each datagram transmission. The sender’s socket address can be returned in the from parameter when recvfrom() is called (see recv(2)).
AF_CCITT
SO_SNDBUF and SO_RCVBUF are the only options supported for sockets of the AF_CCITT address family.
_XOPEN_SOURCE_EXTENDED only
The value of l_linger in the linger structure is interpreted as a time limit in seconds.
RETURN VALUE
getsockopt() and setsockopt() return the following values:
0 Successful completion.
-1 Failure. errno is set to indicate the error.
ERRORS
If getsockopt() or setsockopt() fails, errno is set to one of the following values:
[EBADF] The argument s is not a valid descriptor.
[EFAULT] The optval or optlen address is not valid.
[EINVAL] The level or optlen value is not valid; or optval is the NULL address; or the protocol connection has been released.
[ENOBUFS] Insufficient memory is available for internal system data structures.
[ENOPROTOOPT] The option is not recognized at the specified option level.
[ENOTSOCK] The argument s is not a socket descriptor.
[EOPNOTSUPP] The option is not supported by the socket family or socket type.
AUTHOR
getsockopt() and setsockopt() were developed by the University of California, Berkeley.
FUTURE DIRECTION
The default behavior in this release is still the classic HP-UX BSD Sockets, however it will be changed to X/Open Sockets in some future release. At that time, any HP-UX BSD Sockets behavior which is incompatible with X/Open Sockets may be obsoleted. HP customers are advised to migrate their applications to conform to X/Open specification( see xopen_networking(7) ).
SEE ALSO
socket(2), getprotoent(3N), af_ccitt(7F), tcp(7P), udp(7P), unix(7P), xopen_networking(7).
STANDARDS CONFORMANCE
getsockopt(): XPG4
Hewlett-Packard Company — HP-UX Release 10.20: July 1996