getsockopt() — Get the options associated with a socket

X/Open:

#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>

int getsockopt(int socket, int level, int option_name,
               void *__restrict__ option_value, 
               socklen_t *__restrict__ option_len);

Berkeley sockets:

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

int getsockopt(int socket, int level, int option_name,
               char *option_value,
               int *option_len);

IPv6: To include support for IPv6 socket options, add the following code:

#define _OPEN_SYS_SOCK_IPV6 1
#include <netinet/in.h>

icmp6_filter structure: To include the icmp6_filter structure in your program, add the following code:

#define _OPEN_SYS_SOCK_IPV6
#include <netinet/icmp6.h>

The getsockopt() call gets options associated with a socket. Not all options are supported by all address families. See each option for details. Options can exist at multiple protocol levels.

Parameter

Description

socket

The socket descriptor.

level

The level for which the option is set.

option_name

The name of a specified socket option.

option_value

The pointer to option data.

option_len

The pointer to the length of the option data.

All the socket level options except SO_LINGER, SO_RCVTIMEO and SO_SNDTIMEO, expect option_value to point to an integer and option_len to be set to the size of an integer. When the integer is nonzero, the option is enabled. When it is zero, the option is disabled. The SO_LINGER option expects option_value to point to a linger structure as defined in sys/socket.h. This structure is defined in the following example:

struct  linger
{
       int     l_onoff;                /* option on/off */
       int     l_linger;               /* linger time */
};

The following options are recognized at the IPv4 level:

Option

Description

IP_MULTICAST_IF

(RAW and UDP) Used to get the interface IP address used for sending outbound multicast datagrams. The IP address is passed using the in_addr structure.

IP_MULTICAST_LOOP

(RAW and UDP) Used to determine whether loopback is enabled or disabled. The loopback indicator is passed as an u_char. The value 0 indicates loopback is disabled and the value 1 indicates it is enabled.

IP_MULTICAST_TTL

(RAW and UDP) Returns the IP time-to-live of outgoing multicast datagrams. The TTL value is passed as an u_char.

IP_RECVPKINFO

(RAW and UDP) Indicates whether returning the destination IP address of an incoming packet and the interface over which the packet was received is enabled or disabled. If the setsockopt() function is used to set this option, the set value is returned. The option value is passed as an int. The value 0 indicates the option is disabled and the value 1 indicates the option is enabled. When the option is enabled, the information is returned as IP_PKTINFO ancillary data on recvmsg() function calls.

This option is protected by the _OPEN_SYS_SOCK_EXT4 feature test macro.

The following options are recognized at the socket level:

Option

Description

SO_ACCEPTCONN

The socket had a listen() call.

SO_BROADCAST

Toggles the ability to broadcast messages. If this option is enabled, it allows the application to send broadcast messages over socket, if the interface specified in the destination supports the broadcasting of packets. This option has no meaning for stream sockets. This option is valid only for the AF_INET domain.

SO_DEBUG

Reports whether debugging information is being recorded. This option stores an int value.

SO_ERROR

Returns any pending error on the socket and clears the error status. You can use SO_ERROR to check for asynchronous errors on connected datagram sockets or for other asynchronous errors (errors that are not returned explicitly by one of the socket calls).

SO_KEEPALIVE

Toggles the TCP keep-alive mechanism for a stream socket. 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. Processes writing to that socket are notified with a SIGPIPE signal. This option stores an int value. This option is valid only for the AF_INET and AF_INET6 domains.

SO_LINGER

Lingers on close if data is present. 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 TCP/IP address space 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 only a finite amount of time trying to send the data. The close() call returns without blocking the caller. This option has meaning only for stream sockets.

SO_OOBINLINE

Toggles reception of out-of-band data. When this option is enabled, out-of-band data is placed in the normal data input queue as it is received; it is then available to recv(), recvfrom(), and recvmsg() without the need to specify the MSG_OOB flag in those calls. When this option is disabled, out-of-band data is placed in the priority data input queue as it is received; it is then available to recv(), recvfrom(), and recvmsg() only if the MSG_OOB flag is specified in those calls. This option has meaning only for stream sockets.

_SO_PROPAGATEUSERID

Toggles propagating a user ID (UID) over an AF_UNIX stream socket. When enabled, user (UID) information is extracted from the system when the connect() function is invoked. Then, when the accept() function is invoked, the accepter assumes the identity of the connecter until the accepted socket is closed.

SO_RCVBUF

Reports receive buffer size information. This option stores an int value.

SO_RCVTIMEO

Reports the timeout value with the amount of time an input function waits until it completes.

If a receive operation has blocked for this much time without receiving additional data, it returns with a partial count or errno set to EWOULDBLOCK if no data is received. The default for this option is zero, which indicates that a receive operation does not time out.

SO_REUSEADDR

Toggles local address reuse. When enabled, this option allows local addresses that are already in use to be bound. SO_REUSEADDR alters the normal algorithm used in the bind() call.

The system checks at connect time to ensure that the local address and port do not have the same foreign address and port. The error EADDRINUSE is returned if the association already exists.

After the 'SO_REUSEADDR' option is active, the following situation is 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.

This option is valid only for the AF_INET and AF_INET6 domains.

SO_SECINFO

Toggles receiving security information. When enabled on an AF_UNIX UDP socket, the recvmsg() function will return security information about the sender of each datagram as ancillary data. This information contains the sender's user ID, uid, gid, and jobname and it is mapped by the secsinfo structure in sys/socket.h.

SO_SNDBUF

Reports send buffer size information. This option stores an int value.

SO_SNDTIMEO

Reports the timeout value specifying the amount of time that an output function blocks due to flow control preventing data from being sent.

If a send operation has blocked for this time, it returns with a partial count or with errno set to EWOULDBLOCK if no data is sent. The default for this option is zero, which indicates that a send operation does not time out.

SO_TYPE

This option returns the type of the socket. On return, the integer pointed to by option_value is set to SOCK_STREAM or SOCK_DGRAM. This option is valid for the AF_UNIX, AF_INET and AF_INET6 domains.

If unsuccessful, getsockopt() returns -1 and sets errno to one of the following values:

Error Code

Description

EBADF

The socket parameter is not a valid socket descriptor.

EFAULT

Using option_value and option_len parameters would result in an attempt to access storage outside the caller's address space.

EINVAL

The specified option is not valid at the specified socket level.

ENOBUFS

Buffer space is not available to send the message.

ENOPROTOOPT

The option_name parameter is unrecognized, or the level parameter is not SOL_SOCKET.

ENOSYS

The function is not implemented. You attempted to use a function that is not yet available.

ENOTSOCK

The descriptor is for a file, not for a socket.

EOPNOTSUPP

The operation is not supported by the socket protocol. At least the following options are not supported:

• IPV6_JOIN_GROUP
• IPV6_LEAVE_GROUP
• IP_ADD_SOURCE_MEMBERSHIP
• IP_DROP_SOURCE_MEMBERSHIP
• IP_DROP_MEMBERSHIP
• IP_ADD_MEMBERSHIP
• IP_BLOCK_SOURCE
• IP_UNBLOCK_SOURCE
• MCAST_JOIN_GROUP
• MCAST_LEAVE_GROUP
• MCAST_BLOCK_SOURCE
• MCAST_UNBLOCK_SOURCE
• MCAST_JOIN_SOURCE_GROUP
• MCAST_LEAVE_SOURCE_GROUP

The following are examples of the getsockopt() call. See setsockopt() — Set options associated with a socket for examples of how the setsockopt() call options are set.

int rc;
int s;
int option_value;
int option_len;
struct linger l;
int getsockopt(int s, int level, int option_name,
char *option_value,
     int *option_len);

⋮
/* Is out-of-band data in the normal input queue? */
option_len = sizeof(int);
rc = getsockopt(
        s, SOL_SOCKET, SO_OOBINLINE, (
char *) &option_value, &option_len);
if (rc == 0)
{
    if (option_len == sizeof(int))
    {
         if (option_value)
            /* yes it is in the normal queue */
         else
            /* no it is not
                  */
    }
}

⋮
/* Do I linger on close? */
option_len = sizeof(l);
rc = getsockopt(
        s, SOL_SOCKET, SO_LINGER, (char *) &l, &option_len);
if (rc == 0)
{
    if (option_len == sizeof(l))
    {
         if (l.l_onoff)
            /* yes I linger */
         else
            /* no I do not  */
    }
}