getsockopt()--Retrieve Information about Socket Options


  BSD 4.3 Syntax
  #include <sys/types.h>
  #include <sys/socket.h>

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

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes



  UNIX® 98 Compatible Syntax
  #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)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes


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

There are two versions of the API, as shown above. The base IBM i ® 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:


option_name
(Input) The option name for which information is to be retrieved. The following tables under option_value list the options supported for each level. Assume that the option is supported for all address families unless 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.


option_value
(Output) A pointer to the option value. The following tables list the options with details on the structure type passed for the option_value pointer.

Socket Options That Apply to the IP Layer (IPPROTO_IP)



Socket Options That Apply to the TCP Layer (IPPROTO_TCP)



Socket Options That Apply to the Socket Layer (SOL_SOCKET )



Socket Options That Apply to the IPv6 Layer (IPPROTO_IPV6)



Socket Options That Apply to the ICMPv6 Layer (IPPROTO_ICMPV6)


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

The user profile for the thread must have *IOSYSCFG special authority to set options when:

Return Value

getsockopt() returns an integer. Possible values are:


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().
  5. The following comment applies to the IPV6_RTHDR option value:
    • The following functions can be used to manipulate a routing header:
  6. The following comment applies to the IPV6_HOPOPTS, IPV6_DSTOPTS, and IPV6_RTHDRDSTOPTS option values:
    • The following functions can be used to manipulate an options header:

Related Information


API introduced: V3R1

[ Back to top | UNIX-Type APIs | APIs by category ]