getsockopt()--Retrieve Information about Socket Options

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

int getsockopt(int socket_descriptor,
               int level,
               int option_name,
               char *option_value,
               int *option_length)

The getsockopt() function is used to retrieve information about socket options.

Parameters

socket_descriptor

(Input) The descriptor of the socket for which information is to be retrieved.

level

(Input) Value indicating whether the request applies to the socket itself or to the underlying protocol being used. Supported values are:

IPPROTO_IP

Request applies to IP protocol layer.

IPPROTO_TCP

Request applies to TCP protocol layer.

NNSPROTO_IPX

Request applies to the IPX protocol layer.

NNSPROTO_SPX

Request applies to the SPX protocol layer.

SOL_SOCKET

Request applies to socket layer.

option_name

(Input) The option name for which information is to be retrieved. The following tables list the options supported, and for which level the option applies. Assume that the option is supported for all address families unless the option is described otherwise.

Note: Options directed to a specific protocol level are only supported by that protocol. An option that is directed to level SOL_SOCKET usually completes successfully. If the underlying protocol does not provide support for the option, the socket library retrieves one of the following:

• The default value for the option.

• The value previously set with a setsockopt().

This provides compatibility with Berkeley Software Distributions implementations that also shield the application from protocols that do not support an option.

Figure 1-3. Socket Options That Apply to the IP Layer (IPPROTO_IP)

Option	Description
IP_OPTIONS	Determine what options are set in the IP header. This is only supported for sockets with an address family of AF_INET.
IP_TOS	Get Type Of Service (TOS) and Precedence in the IP header. This option is only supported for sockets with an address family of AF_INET.
IP_TTL	Get Time To Live (TTL) in the IP header. This option is only supported for sockets with an address family of AF_INET.
IP_MULTICAST_IF	Get interface over which outgoing multicast datagrams will be sent. An option_value parameter of type in_addr is used to retrieve the local IP address that is associated with the interface over which outgoing multicast datagrams will be sent. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW.
IP_MULTICAST_TTL	Get Time To Live (TTL) from the IP header for outgoing multicast datagrams. An option_value parameter of type char is used into which a value between 0 and 255 is retrieved. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW.
IP_GETPMTU	Get the discovered path MTU value. A value of 0 indicates that path MTU discovery is not enabled. A value of -1 indicates discovery is not complete; no MTU value is available. A postive value indicates the current MTU value. This option is supported for sockets with an address family of AF_INET and type of SOCK_DGRAM only.
IP_DONTFRAG	Return the current Don't fragment flag setting in the IP header. A value of 0 indicates that it is reset. A value of 1 indicates that it is set. This option is supported for sockets with an address family of AF_INET and type of SOCK_DGRAM only.
IP_PMTUAGE	Return the system setting of the path MTU discovery time out value. A value of 0 indicates infinite age; no rediscovery time is set. A positive value indicates the path MTU discovery time out value; the returned value is in minutes. This option is supported for sockets with an address family of AF_INET and type of SOCK_DGRAM only.
IP_MULTICAST_LOOP	Determine the multicast looping mode. A non-zero value indicates that multicast datagrams sent by this system should also be delivered to this system as long as it is a member of the multicast group. If this option is not set, a copy of the datagram will not be delivered to the sending host. An option_value parameter of type char is used to retrieve the current setting. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW.
IP_RECVLCLIFADDR	Determine if the local interface that a datagram was received will be returned. A value of 1 indicates the first 4 bytes of the reserved field of the sockaddr structure will contain the local interface. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM.

Figure 1-4. Socket Options That Apply to the TCP Layer (IPPROTO_TCP)

Option	Description
TCP_NODELAY	Determine if TCP is buffering data. This option is only supported for sockets with an address family of AF_INET and type SOCK_STREAM.
TCP_MAXSEG	Determine TCP maximum segment size. This option is only supported for sockets with an address family of AF_INET and type SOCK_STREAM.

Figure 1-5. Socket Options That Apply to the IPX or SPX Layer (NNSPROTO_IPX or NNSPROTO_SPX)

Option	Description
SO_HEADERS_ON_INPUT	Determine if the transport will deliver the received protocol headers with the data on input operations such as recv(). This is only supported for sockets with an address family of AF_NS and a type of SOCK_SEQPACKET or SOCK_DGRAM. If the type is SOCK_SEQPACKET, this option requests that the transport place the SPX headers received with the data packets in the first 12 bytes of the supplied user buffer on input operations. The default is that the option be set on. If the type is SOCK_DGRAM, this option requests that the transport place the IPX headers received with the data packets in the first 30 bytes of the supplied user buffer on input operations. The default is that the option be set off. Changing the setting of this option does not affect packets that have already been received by the system and are waiting to be delivered to your application.
SO_HEADERS_ON_OUTPUT	Determine if the transport will accept the protocol header as the first 12 or 30 bytes of data in the user-supplied buffer on output operations such as send(). This is only supported for sockets with an address family of AF_NS and a type of SOCK_SEQPACKET or SOCK_DGRAM. If the type is SOCK_SEQPACKET, the user must supply the SPX header as the first 12 bytes of the buffer on output operations. Only the end of message indicator and data stream type fields of the specified header are used. The default is that the option be set on. If the type is SOCK_DGRAM, the user must supply the IPX header as the first 30 bytes of the buffer on output operations. All fields of the specified header will be used except checksum and packet length. The default is that the option be set off. Changing this option does not affect packets that have been sent by your application but have not yet been transmitted because of flow control or other reasons.
SO_DEFAULT_HEADERS	Retrieve the default protocol header to be used on output operations. This is only supported for sockets with an address family of AF_NS and a type of SOCK_SEQPACKET, SOCK_STREAM, or SOCK_DGRAM. For type SOCK_SEQPACKET or SOCK_STREAM, this is a default 12-byte SPX header. Only the end of message indicator and data stream type fields of the specified header are used. For type SOCK_DGRAM, this is a default 30-byte IPX header. Only the packet type field of the specified header is used.

Figure 1-6. Socket Options That Apply to the SPX Layer Only (NNSPROTO_SPX)

Option	Description
SO_LAST_HEADER	Retrieve the last SPX header received. This is only supported for sockets with an address family of AF_NS and a type of SOCK_SEQPACKET or SOCK_STREAM.
SO_MTU	Retrieve the maximum transmission unit (MTU) size. This is only supported for sockets with an address family of AF_NS and a type of SOCK_SEQPACKET or SOCK_STREAM.

Figure 1-7. Socket Options That Apply to the Socket Layer (SOL_SOCKET )

Option	Description
SO_BROADCAST	Determine if messages can be sent to the broadcast address. This option is only supported for sockets with an address family of AF_INET and type SOCK_DGRAM or SOCK_RAW, or an address family of AF_NS and type SOCK_DGRAM. This option is only supported for sockets with an address family of AF_INET and type SOCK_DGRAM or SOCK_RAW. For sockets with an address family of AF_INET, the broadcast address can be determined by issuing an ioctl() specifying the SIOCGIFBRDADDR request. For sockets with an address family of AF_NS, a broadcast address is an address that specifies 0xFF for all six bytes of the host portion of the address.
SO_DEBUG	Determine if low level-debugging is active. This option is not supported.
SO_DONTROUTE	Determine if the normal routing mechanism is being bypassed. This option is only supported by sockets with an address family of AF_INET or AF_NS.
SO_ERROR	Return any pending errors in the socket. The value returned corresponds to the standard error codes defined in <errno.h>
SO_KEEPALIVE	Determine if the connection is being kept up by periodic transmissions. This option is only supported for sockets with an address family of AF_INET and type SOCK_STREAM, or an address family of AF_NS and a type of SOCK_SEQPACKET or SOCK_STREAM.
SO_LINGER	Determine whether the system attempts to deliver any buffered data or if the system discards it when a close() is issued. For sockets that are using a connection-oriented transport service with an address family of AF_NS or AF_INET, the default is off (which means that the system attempts to send any queued data, with an infinite wait-time). For sockets that are using a connection-oriented transport service with an address family of AF_TELEPHONY, the default is on with a linger time of 1 second (which means that the system will wait up to 1 second to send buffered data before clearing the telephone connection).
SO_OOBINLINE	Determine if out-of-band data is received inline with normal data. This option is only supported for sockets with an address family of AF_INET or AF_NS.
SO_RCVBUF	Determine the size of the receive buffer.
SO_RCVLOWAT	Determine the size of the receive low-water mark. This option is only supported for sockets with an address family of AF_INET and type of SOCK_STREAM.
SO_RCVTIMEO	Determine the receive timeout value. This option is not supported.
SO_REUSEADDR	Determine if the local socket address can be reused. This option is supported by sockets with an address family of AF_INET and a type of SOCK_STREAM or SOCK_DGRAM. It is also supported for sockets with an address family of AF_NS and a type of SOCK_SEQPACKET or SOCK_STREAM.
SO_SNDBUF	Determine the size of the send buffer.
SO_SNDLOWAT	Determine the size of the send low-water mark. This option is not supported.
SO_SNDTIMEO	Determine the send timeout value. This option is not supported.
SO_TYPE	Determine the value for the socket type.
SO_USELOOPBACK	Determine if the loopback feature is being used. This option is not supported.

option_value

(Output) A pointer to the option value. Integer flags/values are returned by getsockopt() for all the socket options except for SO_LINGER , IP_OPTIONS , IP_MULTICAST_IF , IP_MULTICAST_TTL, IP_MULTICAST_LOOP, SO_DEFAULT_HEADERS , and SO_LAST_HEADER.

The following options should be considered as set if a nonzero value for the option_value parameter is returned:

• SO_BROADCAST

• SO_DEBUG

• SO_DONTROUTE

• SO_HEADERS_ON_INPUT

• SO_HEADERS_ON_OUTPUT

• SO_KEEPALIVE

• SO_MTU

• SO_OOBINLINE

• SO_REUSEADDR

• SO_USELOOPBACK

• TCP_NODELAY

• IP_MULTICAST_LOOP

• IP_GETPMTU

• IP_DONTFRAG

• IP_PMTUAGE

For the SO_LINGER option, option_value is a pointer to where the structure linger is stored. The structure linger is defined in <sys/socket.h>.

      struct linger {
        int        l_onoff;
        int        l_linger;
      };

The l_onoff field determines if the linger option is set. A nonzero value indicates the linger option is set and is using the l_linger value. A zero value indicates that the option is not set. The l_linger field is the time to wait before any buffered data to be sent is discarded. The following occur on a close():

• For AF_INET and AF_NS sockets:

  • If the l_onoff value is zero, the system attempts to send any buffered data with an infinite wait-time.

  • If the l_onoff value is nonzero and the l_linger value is nonzero, the system attempts to send any buffered data for l_linger time. If l_linger time has elapsed and the data is still not successfully sent, it is discarded. When data is discarded, the remote program may receive a [ECONNRESET].

  • For AF_INET sockets over SNA, if the l_onoff value is nonzero and the l_linger value is zero, the system waits indefinitely (no timer is implemented). Otherwise, if the l_onoff value is nonzero and the l_linger value is zero, the system discards any buffered data. When data is discarded, the remote program may receive a [ECONNRESET] (or [ECONNABORTED] for AF_NS sockets).

• For AF_TELEPHONY sockets:

  • If the l_onoff value is zero, the system will wait until all buffered data is sent or 1 second has elapsed, whichever occurs first, before clearing the telephone connection (that is, hanging up).

  • If the l_onoff value is nonzero, the system will wait until all buffered data is sent or l_linger seconds have elapsed, whichever occurs first, before clearing the telephone connection (that is, hanging up).

Note: An application must implement an application level confirmation. Guaranteed receipt of data by the partner program is required. Setting SO_LINGER does not guarantee delivery.

For the IP_OPTIONS option, option_value is a pointer to storage in which data representing the IP options (as specified in RFC 791) is stored. getsockopt() returns the options in the following format:

IP address is a 4-byte IP address, and IP options identifies the IP options that were set using setsockopt(). If an IP option set using setsockopt() contained a source routing option (strict or loose), the first IP address in the source routing option list is removed. The IP options are adjusted accordingly. (For this adjustment, the length in the IP options portion is changed, and alignment is kept by adding no-operation option). The buffer is returned in the same format. The first 4 bytes are the IP address that was removed, and this is followed by the remaining IP options, if any. If the IP options portion does not contain a source routing option, the first 4 bytes are set to zero.

For the IP_MULTICAST_IF option, option_value is a pointer to storage in which the structure in_addr, defined in <netinet/in.h> as the following, will be stored:

    struct in_addr {
      u_long  s_addr; /* IP address  */
    };

The s_addr field that is returned will be the local IP address that is associated with the interface over which outgoing multicast datagrams are being sent.

For the SO_DEFAULT_HEADERS option where level is specified as NNSPROTO_IPX, option_value is a pointer to where the structure idp is stored. The structure idp is defined in <netns/idp.h>. For the SO_DEFAULT_HEADERS option where level is specified as NNSPROTO_SPX, option_value is a pointer to where the structure sphdr is stored. The structure sphdr is defined in <netns/sp.h>.

For the SO_LAST_HEADER option, option_value is a pointer to where the structure sphdr is stored.

Notes:

1. For sockets that use a connection-oriented transport service, IP options that are set using setsockopt() are only used if they are set prior to a connect() being issued. After the connection is established, any IP options that the user sets are ignored.

2. If the IP options portion contains a source routing option, then the address in the source routing option overrides the destination address. The destination address may have been specified on an output operation (for example, on a sendto()) or on a connect().

3. If a socket has a type of SOCK_RAW and a protocol of IPPROTO_RAW, any IP options set using setsockopt() are ignored (since the user must supply the IP header data on an output operation as part of the data that is being transmitted).

4. The structure ip_opts (defined in <netinet/in.h>) can be used to receive IP options.

option_length

(I/O) The length of the option_value. The option_length parameter must be initially set by the caller. option_length is changed on return to indicate the actual amount of storage used.

Note: For option values that are of type integer, the length of the option_value pointed to by the option_length parameter must be set to a value that is greater or equal to the size of an integer. If the length is not set correctly, a correct option value is not received.

Return Value

getsockopt() returns an integer. Possible values are:

• -1 (unsuccessful)

• 0 (successful)

Error Conditions

When getsockopt() fails, errno can be set to one of the following:

[EBADF]

Descriptor not valid.

[ECONNABORTED]

Connection ended abnormally.

This error code indicates that the transport provider ended the connection abnormally because of one of the following:

• The retransmission limit has been reached for data that was being sent on the socket.

• A protocol error was detected.

• For AF_NS sockets, a timeout occurred.

[EFAULT]

Bad address.

The system detected an address which was not valid while attempting to access the option_value or option_length parameters.

[EINVAL]

Parameter not valid.

This error code indicates one of the following:

• The level parameter specifies a level that is not supported. (except for when the socket has an address family of AF_UNIX, in which case [ENOPROTOOPT] is returned).

• The option_name parameter specifies a value that is not valid (except for when the level is SOL_SOCKET , in which case [ENOPROTOOPT] is returned).

• The option_length parameter points to an integer that has a negative value.

[EIO]

Input/output error.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOPROTOOPT]

The protocol does not support the specified option.

This error code indicates one of the following:

• The socket has an address family of AF_UNIX and the level parameter specified is not SOL_SOCKET .

• The level parameter specifies a level of SOL_SOCKET and the option_name parameter specifies a value that is not valid.

[ENOTCONN]

Requested operation requires a connection.

This error code is only returned if the level parameter specifies a level other than SOL_SOCKET and the socket_descriptor parameter points to a socket that is using a connection-oriented transport service that has had its connection broken.

[ENOTSOCK]

The specified descriptor does not reference a socket.

[EPERM]

Operation not permitted.

The executing user profile must have *IOSYSCFG special authority to get options when the level parameter specifies IPPROTO_IP and the option_value parameter is IP_OPTIONS .

[EUNKNOWN]

Unknown system state.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

Error Messages

CPE3418 E

Possible APAR condition or hardware failure.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

CPFA081 E

Unable to set return value or error code.

Usage Notes

1. Socket options are defined in <sys/socket.h>, IP options are defined in <netinet/ip.h< and <netinet/in.h>, TCP options are defined in <netinet/tcp.h>, and SPX and IPX options are defined in <netns/ns.h>.

2. The user profile for a running application must have the *IOSYSCFG special authority to specify the level parameter as IPPROTO_IP and the option_value parameter as IP_OPTIONS .

3. When a TCP connection is closed for a socket using the AF_INET address family, the port associated with that connection is not made available until twice the Maximum Segment Life (MSL) time in seconds has passed. The MSL time is approximately 2 minutes. The SO_REUSEADDR option allows a bind() to succeed when requesting a port that is being held during this time frame. This can be especially useful if a server is abruptly ended and restarted.

   Notes:

   1. For AF_INET SOCK_STREAM sockets, this option does not allow two servers to successfully issue a bind() requesting the same port number and local address combination. For AF_INET SOCK_DGRAM sockets, the SO_REUSEADDR option does allow multiple servers to successfully bind to the same port. When broadcast or multicast datagrams are received for a given port, each server that is bound to that port receives a copy of the datagram provided each server has enabled the SO_REUSEADDR option.

   2. This option does not affect unicast datagram delivery.

4. Issuing a getsockopt() with the SO_ERROR option results in the resetting of the SO_ERROR option to zero. Issuing another getsockopt() with the SO_ERROR option also returns a value of zero, assuming no errors occur on the socket. Other functions, when issued, also reset the SO_ERROR option to zero. These functions are:

   • read(), readv(), recv(), recvmsg(), recvfrom()

   • connect() (only when using a connectionless transport service)

Related Information

• setsockopt()--Set Socket Options