getsockopt Subroutine

Edit online

Purpose

Gets options on sockets.

Library

Standard C Library (libc.a)

Syntax

#include <sys/socket.h>
int getsockopt (Socket, Level, OptionName, OptionValue, OptionLength)
int  Socket,  Level,  OptionName;
void * OptionValue;
socklen_t * OptionLength;

Description

The getsockopt subroutine allows an application program to query socket options. The calling program specifies the name of the socket, the name of the option, and a place to store the requested information. The operating system gets the socket option information from its internal data structures and passes the requested information back to the calling program.

Options can exist at multiple protocol levels. They are always present at the uppermost socket level. When retrieving socket options, specify the level where the option resides and the name of the option.

All applications containing the getsockopt subroutine must be compiled with the _BSD macro set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

Parameters

Item Description
Socket Specifies the unique socket name.
Level Specifies the protocol level where the option resides. Options can be retrieved at the following levels:
Socket level
Specifies the Level parameter as the SOL_SOCKET option.
Other levels
Supplies the appropriate protocol number for the protocol controlling the option. For example, to indicate that an option will be interpreted by the TCP protocol, set the Level parameter to the protocol number of TCP, as defined in the netinet/in.h file.
OptionName Specifies a single option. The OptionName parameter and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The sys/socket.h file contains definitions for socket level options. The netinet/tcp.h file contains definitions for TCP protocol level options. Socket-level options can be enabled or disabled; they operate in a toggle fashion. The sys/atmsock.h file contains definitions for ATM protocol level options.

The following list defines socket protocol level options found in the sys/socket.h file:

SO_DEBUG
Specifies the recording of debugging information. This option enables or disables debugging in the underlying protocol modules.
SO_BROADCAST
Specifies whether transmission of broadcast messages is supported. The option enables or disables broadcast support.
SO_CKSUMREV
Enables performance enhancements in the protocol layers. If the protocol supports this option, enabling causes the protocol to defer checksum verification until the user's data is moved into the user's buffer (on recv, recvfrom, read, or recvmsg thread). This can cause applications to be awakened when no data is available, in the case of a checksum error. In this case, EAGAIN is returned. Applications that set this option must handle the EAGAIN error code returned from a receive call.
SO_REUSEADDR
Specifies that the rules used in validating addresses supplied by a bind subroutine should allow reuse of a local port. A particular IP address can only be bound once to the same port. This option enables or disables reuse of local ports.

SO_REUSEADDR allows an application to explicitly deny subsequent bind subroutine to the port/address of the socket with SO_REUSEADDR set. This allows an application to block other applications from binding with the bind subroutine.

SO_REUSEPORT
Specifies that the rules used in validating addresses supplied by a bind subroutine should allow reuse of a local port/address combination. Each binding of the port/address combination must specify the SO_REUSEPORT socket option. This option enables or disables the reuse of local port/address combinations.
SO_KEEPALIVE
Monitors the activity of a connection by enabling or disabling the periodic transmission of ACK messages on a connected socket. The idle interval time can be designated using the TCP/IP no command. Broken connections are discussed in "Understanding Socket Types and Protocols" in Communications Programming Concepts.
OptionName (contd)
SO_DONTROUTE
Indicates outgoing messages should bypass the standard routing facilities. Does not apply routing on outgoing messages. Directs messages to the appropriate network interface according to the network portion of the destination address. This option enables or disables routing of outgoing messages.
SO_LINGER
Lingers on a close subroutine if data is present. This option controls the action taken when an unsent messages queue exists for a socket, and a process performs a close subroutine on the socket.

If the SO_LINGER option is set, the system blocks the process during the close subroutine until it can transmit the data or until the time expires. If the SO_LINGER option is not specified, and a close subroutine is issued, the system handles the call in a way that allows the process to continue as quickly as possible.

The sys/socket.h file defines the linger structure that contains the l_linger member for specifying linger time interval. If linger time is set to anything but 0, the system tries to send any messages queued on the socket. The maximum value that the l_linger member can be set to is 65535. If the application has requested SPEC1170 compliant behavior by exporting the XPG_SUS_ENV environment variable, the linger time is n seconds; otherwise, the linger time is n/100 seconds (ticks), where n is the value of the l_linger member.

SO_OOBINLINE
Leaves received out-of-band data (data marked urgent) in line. This option enables or disables the receipt of out-of-band data.
SO_SNDBUF
Retrieves buffer size information.
SO_RCVBUF
Retrieves buffer size information.
SO_SNDLOWAT
Retrieves send buffer low-water mark information.
SO_RCVLOWAT
Retrieves receive buffer low-water mark information.
OptionName (contd)
SO_SNDTIMEO
Retrieves time-out information. This option is settable, but currently not used.
SO_RCVTIMEO
Retrieves time-out information. This option is settable, but currently not used.
SO_PEERID
Retrieves the credential information of the process associated with a peer UNIX domain socket. This information includes the process ID, effective user ID, and effective group ID. The peercred_struct structure must be used in order to get the credential information. This structure is defined in the sys/socket.h file.
SO_ERROR
Retrieves information about error status and clears.
SO_TYPE
Sets the retrieval of a socket type.

The following list defines TCP protocol level options found in the netinet/tcp.h file:

TCP_CWND_IF
Increases the factor of the TCP congestion window (cwnd) during the congestion avoidance. The value must be in the range 0 - 100 (0 is disable). The tcp_cwnd_modified network tunable option must be enabled.
TCP_CWND_DF
Decrease the factor of the TCP cwnd during the congestion avoidance. The value must be in the range 0 - 100 (0 is disable). The tcp_cwnd_modified network tunable option must be enabled.
TCP_NOTENTER_SSTART
Avoids reentering the slow start after the retransmit timeout, which might reset the cwnd to the initial window size, instead of the size of the current slow-start threshold (ss_threshold) value or half of the maximum cwnd (max cwnd/2). The values are 1 for enable and 0 for disable. The tcp_cwnd_modified network tunable option must be enabled.
TCP_ NOREDUCE_CWND_IN_FRXMT
Not decrease the cwnd size when in the fast retransmit phrase. The values are 1 for enable and 0 for disable. The tcp_cwnd_modified network tunable option must be enabled.
TCP_ NOREDUCE_CWND_EXIT_FRXMT
Not decrease the cwnd size when exits the fast retransmit phrase. The values are 1 for enable and 0 for disable. The tcp_cwnd_modified network tunable option must be enabled.
TCP_RFC1323
Indicates whether RFC 1323 is enabled or disabled on the specified socket. A non-zero OptionValue returned by the getsockopt subroutine indicates the RFC is enabled.
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 OptionValue returned by the getsockopt subroutine indicates TCP_NODELAY is enabled. For example, TCP_NODELAY should be used when there is an appliciation using TCP for a request/response.
OptionName (contd)
TCP_NODELAYACK
Specifies if TCP needs to send immediate acknowledgement packets to the sender. If this option is not set, TCP delays sending the acknowledgement packets by up to 200 ms. This allows the acknowledgements to be sent along with the data on a response and minimizes system overhead. Setting this TCP option might cause a slight increase in system overhead, but can result in higher performance for network transfers if the sender is waiting on the receiver's acknowledgements.

The following list defines ATM protocol level options found in the sys/atmsock.h file:

SO_ATM_PARM
Retrieves all ATM parameters. This socket option can be used instead of using individual sockets options described below. It uses the connect_ie structure defined in sys/call_ie.h file.
SO_ATM_AAL_PARM
Retrieves ATM AAL (Adaptation Layer) parameters. It uses the aal_parm structure defined in sys/call_ie.h file.
SO_ATM_TRAFFIC_DES
Retrieves ATM Traffic Descriptor values. It uses the traffic_desc structure defined in sys/call_ie.h file.
SO_ATM_BEARER
Retrieves ATM Bearer capability information. It uses the bearer structure defined in sys/call_ie.h file.
SO_ATM_BHLI
Retrieves ATM Broadband High Layer Information. It uses the bhli structure defined in sys/call_ie.h file.
SO_ATM_BLLI
Retrieves ATM Broadband Low Layer Information. It uses the blli structure defined in sys/call_ie.h file.
SO_ATM_QoS
Retrieves ATM Ouality Of Service values. It uses the qos_parm structure defined in sys/call_ie.h file.
SO_ATM_TRANSIT_SEL
Retrieves ATM Transit Selector Carrier. It uses the transit_sel structure defined in sys/call_ie.h file.
SO_ATM_MAX_PEND
Retrieves the number of outstanding transmit buffers that are permitted before an error indication is returned to applications as a result of a transmit operation. This option is only valid for non best effort types of virtual circuits.
SO_ATM_CAUSE
Retrieves cause for the connection failure. It uses the cause_t structure defined in the sys/call_ie.h file.
OptionValue Specifies a pointer to the address of a buffer. The OptionValue parameter takes an integer parameter. The OptionValue parameter should be set to a nonzero value to enable a Boolean option or to a value of 0 to disable the option. The following options enable and disable in the same manner:
  • SO_DEBUG
  • SO_REUSEADDR
  • SO_KEEPALIVE
  • SO_DONTROUTE
  • SO_BROADCAST
  • SO_OOBINLINE
  • TCP_RFC1323
OptionLength Specifies the length of the OptionValue parameter. The OptionLength parameter initially contains the size of the buffer pointed to by the OptionValue parameter. On return, the OptionLength parameter is modified to indicate the actual size of the value returned. If no option value is supplied or returned, the OptionValue parameter can be 0.

Options at other protocol levels vary in format and name.

Item Description
IP_DONTFRAG Get current IP_DONTFRAG option value.
IP_FINDPMTU Get current PMTU value.
IP_PMTUAGE Get current PMTU time out value.
Item Description
IP_DONTGRAG Not supported.
IP_FINDPMTU Get current PMTU value.
IP_PMTUAGE Not supported.
Item Description Value
IPV6_V6ONLY Determines whether the socket is restricted to IPv6 communications only.
Option Type:
int (Boolean interpretation)
  Allows the user to determine the outgoing hop limit value for unicast IPv6 packets.
Option Type:
int
  Allows the user to determine the outgoing hop limit value for multicast IPv6 packets.
Option Type:
int
  Allows the user to determine the interface being used for outgoing multicast packets.
Option Type:
unsigned int
  If a multicast datagram is sent to a group that the sending host belongs, a copy of the datagram is looped back by the IP layer for local delivery (if the option is set to 1). If the option is set to 0, a copy is not looped back.
Option Type:
unsigned int
  Determines whether the destination IPv6 address and arriving interface index of incoming IPv6 packets are being received as ancillary data on UDP and raw sockets.
Option Type:
int (Boolean interpretation)
  Determines whether the hop limit of incoming IPv6 packets is being received as ancillary data on UDP and raw sockets.
Option Type:
int (Boolean interpretation)
  Determines whether the traffic class of incoming IPv6 packets is being received as ancillary data on UDP and raw sockets.
Option Type:
int (Boolean interpretation)
  Determines whether the routing header of incoming IPv6 packets is being received as ancillary data on UDP and raw sockets.
Option Type:
int (Boolean interpretation)
  Determine whether the hop-by-hop options header of incoming IPv6 packets is being received as ancillary data on UDP and raw sockets.
Option Type:
int (Boolean interpretation)
  Determines whether the destination options header of incoming IPv6 packets is being received as ancillary data on UDP and raw sockets.
Option Type:
int (Boolean interpretation)
  Determines the source IPv6 address and outgoing interface index for all IPv6 packets being sent on this socket.
Option Type:
struct in6_pktinfo defined in the netinet/in.h file.
  Determines the next hop being used for outgoing IPv6 datagrams on this socket.
Option Type:
struct sockaddr_in6 defined in the netinet/in.h file.
  Determines the traffic class for outgoing IPv6 datagrams on this socket.
Option Type:
int
  Determines the routing header to be used for outgoing IPv6 datagrams on this socket.
Option Type:
struct ip6_rthdr defined in the netinet/ip6.h file.
  Determines the hop-by-hop options header to be used for outgoing IPv6 datagrams on this socket.
Option Type:
struct ip6_rthdr defined in the netinet/ip6.h file.
  Determines the destination options header to be used for outgoing IPv6 datagrams on this socket. This header will follow a routing header (if present) and will also be used when there is no routing header specified.
Option Type:
struct ip6_dest defined in the netinet/ip6.h file.
  Determines the destination options header to be used for outgoing IPv6 datagrams on this socket. This header will precede a routing header (if present). If no routing header is specified, this option will be silently ignored.
Option Type:
struct ip6_dest defined in the netinet/ip6.h file.
  Determines how IPv6 path MTU discovery is being controlled for this socket.
Option Type:
int
  Determines whether fragmentation of outgoing IPv6 packets has been disabled on this socket.
Option Type:
int (Boolean interpretation)
  Determines whether IPV6_PATHMTU messages are being received as ancillary data on this socket.
Option Type:
int (Boolean interpretation)
  Gets the address selection preferences for a socket.
Option Type:
int (Boolean interpretation)
  Determines the current Path MTU for a connected socket.
Option Type:
struct ip6_mtuinfo defined in the netinet/in.h file.
Item Description Value
IPPROTO_ICMPV6 Allows the user to filter ICMPV6 messages by the ICMPV6 type field. If no filter was set, the default kernel filter will be returned.
Option Type:
The icmp6_filter structure defined in the netinet/icmp6.h file.

Return Values

Upon successful completion, the getsockopt subroutine returns a value of 0.

If the getsockopt subroutine is unsuccessful, the subroutine handler performs the following actions:

  • Returns a value of -1 to the calling program.
  • Moves an error code, indicating the specific error, into the errno global variable.

Upon successful completion of the IPPROTO_IP option IP_PMTUAGE the returns are:

With AIX® Version 6.1:

  • Positive non-zero OptionValue.

Upon successful completion of TCP protocol sockets option IP_FINDPMTU the returns are:

With AIX Version 6.1:

  • OptionValue 0 if PMTU discovery (tcp_pmtu_discover) is not enabled/not available.
  • Positive non-zero OptionValue if PMTU is available.

Error Codes

Item Description
EBADF The Socket parameter is not valid.
EFAULT The address pointed to by the OptionValue parameter is not in a valid (writable) part of the process space, or the OptionLength parameter is not in a valid part of the process address space.
EINVAL The Level, OptionName, or OptionLength is invalid.
ENOBUF Insufficient resources are available in the system to complete the call.
ENOTSOCK The Socket parameter refers to a file, not a socket.
ENOPROTOOPT The option is unknown.
EOPNOTSUPP The option is not supported by the socket family or socket type.
EPERM The user application does not have the permission to get or to set this socket option. Check the network tunable option.

Examples

The following program fragment illustrates the use of the getsockopt subroutine to determine an existing socket type:

#include <sys/types.h>
#include <sys/socket.h>
int type;
socklen_t size = sizeof(int);
if(getsockopt(s, SOL_SOCKET, SO_TYPE, (void*)&type,&size)<0){
.
.
.
}