getsockopt()

The getsockopt() call gets options associated with a socket. It can be called only for sockets in the AF_INET domain. This call is not supported in the AF_IUCV domain. While 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 that 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 getsockopt(int s, int level, int optname, char *optval, int *optlen

Parameter: Description
s: The socket descriptor.
level: The level to which the option is set.
optname: The name of a specified socket option. See GETSOCKOPT/SETSOCKOPT command values for the numeric values of optname.
optval: Points to option data.
optlen: Points to the length of the option data.

The optval and optlen parameters are used to return data used by the particular get command. The optval parameter points to a buffer that is to receive the data requested by the get command. The optlen parameter points to the size of the buffer pointed to by the optval parameter. Initially, this size must be set to the size of that buffer before calling getsockopt(). On return it is set to the size of the data actually returned.

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. When 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:

#include <manifest.h>
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 being disabled. A nonzero value enables the option. The l_linger field specifies the amount of time to linger on close.

The following option is recognized at the TCP level (IPPROTO_TCP):

Option

Description

TCP_NODELAY

Returns the status of Nagle algorithm (RFC 896). This option is not supported for AF_IUCV sockets.

When optval is 0, Nagle algorithm is enabled and TCP will wait to send small packets of data until the acknowledgment for the previous data is received.

When optval is nonzero, Nagle algorithm is disabled and TCP will send small packets of data even before the acknowledgment for previous data sent is received.

The following options are recognized at the socket level (SOL_SOCKET):

Option

Description

SO_ACCEPTCONN

Indicates whether listen() was called for a stream socket.

SO_BROADCAST

Toggles the ability to broadcast messages. The default is disabled. When this option is enabled, it allows the application to send broadcast messages over s when the interface specified in the destination supports the broadcasting of packets. This option has no meaning for stream sockets.

SO_CLUSTERCONNTYPE

Returns a bit mapped 32–bit value. One or more than one of the following values will be returned:

No Conn means that the socket is not connected.
None means that the socket is active, but the partner is not in the same cluster. If this indicator is set, the other 3 indicators are 0.
Same cluster means that the connection partners are in the same cluster.
Same image means that the connection partners are in the same MVS™ image. SO_CLUSTERCONNTYPE_SAME_CLUSTER will also be set. If the connection partner is a distributed DVIPA, the same image bit will not be on since the exact hosting stack is not known.
Internal means that communication from this node to the stack hosting the partner application is not sent on links/interfaces exposed outside the cluster (sysplex). To determine if both ends of the connection flow over internal links/interfaces, the partner application must also issue this getsockopt() and both ends exchange their results from this socket call (through an application-dependent method).
Note: If the destination IP address for a connection (partner's IP address) is a dynamic VIPA or distributed dynamic VIPA residing in the cluster, the internal indicator will not be on because traffic for these connections can be forwarded to the target TCP/IP stacks over links or interfaces that are external to the cluster.
An internal indicator means that for this side of the connection, the link/interface type is one of the following types:
- CTC
- HiperSockets (iQDIO)
- MPCPTP (including XCF and IUTSAMEH connections)
- OSA-Express® QDIO with CHPID type OSX or OSM
- Loopback
- Or both partners are owned by the same multi-homed stack

On return, one or more of the following bits are set:

00000000  00000000 00000000 00000001'-SO_CLUSTERCONNTYPE_NONE
00000000  00000000 00000000 00000010'-SO_CLUSTERCONNTYPE_SAME_CLUSTER
00000000  00000000 00000000 00000100'-SO_CLUSTERCONNTYPE_SAME_IMAGE
00000000  00000000 00000000 00001000'-SO_CLUSTERCONNTYPE_INTERNAL
00000000  00000000 00000000 00000000'-SO_CLUSTERCONNTYPE_NOCONN

Note: A value of all zeros means that there is no active connection on the socket. This is usually the case for a listening socket. This is also true for a client socket before the client issues connect(). The caller should first check for a returned value of SO_CLUSTERCONNTYPE_NOCONN before checking for any of the other returned indicators.

If getsockopt() (SO_CLUSTERCONNTYPE) is issued before the connection has been established, it results in a return value of 0.

If the application issues getsockopt() (SO_CLUSTERCONNTYPE) on a connected socket, and has received an indication of SO_CLUSTERCONNTYPE_INTERNAL, any subsequent rerouting decisions because of current route failure will either select an alternate route, which is also SO_CLUSTERCONNTYPE_INTERNAL, or fail the connection with no route available indications. This means that when an application has received an indication of SO_CLUSTERCONNTYPE_INTERNAL on a connection, any subsequent rerouting preserves that indication on the new route, or will fail the connection. This ensures that a connection that an application relies on as being internal does not transparently become non-internal because of a routing change.

If the application never issues the new getsockopt() or if the connection was previously reported as not SO_CLUSTERCONNTYPE_INTERNAL, rerouting decisions are made as at present, and the rerouting is transparent to the application as long as any alternate route exists.

SO_DEBUG

The sock_debug() call provides the socket library tracing facility. The onoff parameter can have a value of 0 or nonzero. When onoff=0 (the default), no socket library tracing is done; when onoff=nonzero, the system traces for socket library calls and interrupts.

SO_ERROR

Returns any error pending on the socket and clears the error status. It can be used to check for asynchronous errors on connected datagram sockets and for other asynchronous errors (errors returned explicitly by one of the socket calls).

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 along an otherwise idle connection. If the remote TCP does not respond to the packet or to retransmissions of the packet, the connection is terminated 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 before trying 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 while trying to send the data. This option has meaning only for stream sockets.

SO_OOBINLINE

Toggles 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 specifying 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 only for stream sockets.

SO_RCVBUF

Returns the size of the data portion of the TCP/IP send buffer in optval. The size of the data portion of the receive buffer is protocol-specific.

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.

SO_SNDBUF

Returns 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.

SO_TYPE

Returns the type of the socket. On return, the integer pointed to by optval is set to SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW.

The following options are recognized at the IP level (IPPROTO_IP):

Option: Description
IP_MULTICAST_TTL: Gets 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: Used to determine whether outgoing multicast datagrams are looped back.
IP_MULTICAST_IF: Gets the interface for sending outbound multicast datagrams from the socket application.
Note: Multicast datagrams can be transmitted only on one interface at a time.

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.
EINVAL: The optname parameter is unrecognized, or the level parameter is not SOL_SOCKET.

Example

The following examples show the getsockopt() call. See setsockopt() to see how the setsockopt() call options are set.

Example 1

#include <manifest.h>
 
int rc;
int s;
int optval;
int optlen;
struct linger l;
int getsockopt(int s, int level, int optname, char *optval, int *optlen);
 
⋮
/* Is out of band data in the normal input queue? */
optlen = sizeof(int);
rc = getsockopt(
        s, SOL_SOCKET, SO_OOBINLINE, (char *) &optval, &optlen);
if (rc == 0)
{
    if (optlen == sizeof(int))
    {
         if (optval)
            /* yes it is in the normalqueue */
         else
            /* no it is not                  */
    }
}
 
⋮

Example 2

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

Related calls

bind(), close(), getprotobyname(), setsockopt(), socket()