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)

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

 int getsockopt(int socket_descriptor,
                int level,
                int option_name,
                void *option_value,
                socklen_t *option_length)

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

There are two versions of the API, as shown above. The base i5/OS API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

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.
SOL_SOCKET	Request applies to socket layer.
IPPROTO_IPV6	Request applies to IPv6 protocol layer.
IPPROTO_ICMPV6	Request applies to ICMPv6 protocol 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.

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_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 or SOCK_RAW 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.

Socket Options That Apply to the TCP Layer (IPPROTO_TCP)

Option	Description
TCP_NODELAY	Specifies whether TCP should follow the Nagle algorithm for deciding when to send data. By default TCP will follow the Nagle algorithm. To disable this behavior, applications can enable TCP_NODELAY to force TCP to always send data immediately. A non-zero option_value returned by getsockopt indicates TCP_NODELAY is enabled. For example, TCP_NODELAY should be used when there is an appliciation using TCP for a request/response. This option is only supported for sockets with an address family of AF_INET or AF_INET6 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 or AF_INET6 and type SOCK_STREAM.

Socket Options That Apply to the Socket Layer (SOL_SOCKET )

Option	Description
SO_ACCEPTCONN	Reports whether socket listening is enabled. This option stores an int value. This is a boolean option.
SO_ACCEPTECONNABORTED	Determine if the listening socket will return ECONNABORTED when a connection on the listening backlog is reset prior to a blocking accept(). The option is only valid on a socket that has successfully issued the listen() call. The option has no effect on non-blocking sockets. This option is only used by sockets with an address family of AF_INET or AF_INET6.
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. The broadcast address can be determined by issuing an ioctl() specifying the SIOCGIFBRDADDR request.
SO_DEBUG	Determine if low level-debugging is active.
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_INET6.
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 or AF_INET6 and type 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_INET or AF_INET6, the default is off (which means that the system attempts to send any queued data, with an infinite wait-time).
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_INET6.
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 a type of SOCK_STREAM.
SO_RCVTIMEO	Determine the receive timeout value. This option is not supported unless _XOPEN_SOURCE is defined to be 520 or greater.
SO_REUSEADDR	Determine if the local socket address can be reused. This option is supported by sockets with an address family of AF_INET or AF_INET6 and a type of SOCK_STREAM or SOCK_DGRAM.
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 unless _XOPEN_SOURCE is defined to be 520 or greater.
SO_TYPE	Determine the value for the socket type.
SO_USELOOPBACK	Determine if the loopback feature is being used. This option is not supported.

Socket Options That Apply to the IPv6 Layer (IPPROTO_IPV6)

Option	Description
IPV6_UNICAST_HOPS	Get the hop limit value that will be used for subsequent unicast packets sent by this socket. An option_value parameter of type int is used to retrieve the current setting. This option is only supported for sockets with an address family of AF_INET6.
IPV6_MULTICAST_IF	Get the interface over which outgoing multicast datagrams will be sent. An option_value parameter of type unsigned int is used to retrieve the interface index 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_INET6 and type of SOCK_DGRAM or SOCK_RAW.
IPV6_MULTICAST_HOPS	Get the hop limit value that will be used for subsequent multicast packets sent by this socket. An option_value parameter of type int is used to retrieve the current setting. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW.
IPV6_MULTICAST_LOOP	Determine the multicast looping mode. A value of 1 (default), 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 0, a copy of the datagram will not be delivered to the sending host. An option_value parameter of type unsigned int is used to retrieve the current setting. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW.
IPV6_V6ONLY	Determine the AF_INET6 communication restrictions. A non-zero value indicates that this AF_INET6 socket is restricted to IPv6 communications only. This option stores an int value. This is a boolean option. By default this option is turned off. This option is only supported for sockets with an address family of AF_INET6.
IPV6_CHECKSUM	Determine if the kernel will calculate and insert a checksum for output and verify the received checksum on input, discarding the packet if the checksum is in error for this socket. An option_value parameter of type int is used to retrieve the current setting. If this option is -1 (the default), this socket option is disabled. A value of 0 or greater specifies an integer offset into the user data of where the checksum is located. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_RAW with a protocol other than IPPROTO_ICMPV6. The checksum is automatically computed for protocol IPPROTO_ICMPV6.
IPV6_DONTFRAG	Determine if the kernel will not implement the automatic insertion of a fragment header in the packet if the packet is too big for the path MTU. A value of 0 disables the option meaning the default of automatic insertion will be used. A non-zero value indicates that the option is set meaning the kernel will discard the packet instead of inserting the fragment header. This option is supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW only.

Socket Options That Apply to the ICMPv6 Layer (IPPROTO_ICMPV6)

Option

Description

ICMP6_FILTER

Determine the current ICMPv6 Type Filtering. An option_value parameter of type struct icmp6_filter, defined in <netinet/icmp6.h> is used to retrieve the current setting. The following macros, defined in <netinet/icmp6.h> can be used after retrieval of the type filtering structure to determine whether or not specific ICMPv6 message types will be passed to the application or be blocked: ICMP6_FILTER_WILLPASS and ICMP6_FILTER_WILLBLOCK. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_RAW with a protocol of IPPROTO_ICMPV6.

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, and ICMP6_FILTER.

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

• SO_ACCEPTCONN
• SO_ACCEPTECONNABORTED
• SO_BROADCAST
• SO_DEBUG
• SO_DONTROUTE
• SO_KEEPALIVE
• SO_OOBINLINE
• SO_REUSEADDR
• SO_USELOOPBACK
• TCP_NODELAY
• IP_MULTICAST_LOOP
• IP_DONTFRAG
• IPV6_V6ONLY
• IPV6_MULTICAST_IF
• IPV6_MULTICAST_LOOP
• IPV6_DONTFRAG

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_INET6 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].
  
  

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 SO_RCVTIME and SO_SNDTIME options, option_value is a pointer to where the structure timeval is stored. The structure timeval is defined in <sys/time.h>.

      struct timeval {
        long  tv_sec;
        long  tv_usec;
      };

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

IP options

...

IP options

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.

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.

Authorities

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:

Error Messages

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>, IPv6 and ICMPv6 options are defined in <netinet/in.h>.
   
   
2. When a TCP connection is closed for a socket using the AF_INET or AF_INET6 address families, 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 and AF_INET6, 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 and AF_INET6, 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.
   
   
   
3. 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)
4. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the getsockopt() API is mapped to qso_getsockopt98().

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• setsockopt()--Set Socket Options