getsockopt() — Get the options associated with a socket
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 |
both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>
int getsockopt(int socket, int level, int option_name,
void *__restrict__ option_value,
socklen_t *__restrict__ option_len);
#define _OE_SOCKETS
#include <sys/types.h>
#include <sys/socket.h>
int getsockopt(int socket, int level, int option_name,
char *option_value,
int *option_len);
#define _OPEN_SYS_SOCK_IPV6 1
#include <netinet/in.h>
#define _OPEN_SYS_SOCK_IPV6
#include <netinet/icmp6.h>
General description
- Parameter
- Description
- socket
- The socket descriptor.
- level
- The level for which the option is set.
- option_name
- The name of a specified socket option.
- option_value
- The pointer to option data.
- option_len
- The pointer to the length of the option data.
When manipulating socket options, you must specify the level at which the option resides and the name of the option. To manipulate options at the socket level, the level parameter must be set to SOL_SOCKET as defined in sys/socket.h. To manipulate options at the IPv4 or IPv6 level, the level parameter must be set to IPPROTO_IP as defined in sys/socket.h or IPPROTO_IPV6 as defined in netinet/in.h. To manipulate options at any other level, such as the TCP level, supply the appropriate protocol number for the protocol controlling the option. The getprotobyname() call can be used to return the protocol number for a named protocol.
The option_value and option_len parameters are used to return data used by the particular get command. The option_value parameter points to a buffer that is to receive the data requested by the get command. The option_len parameter points to the size of the buffer pointed to by the option_value parameter. It must be initially set to the size of the buffer before calling getsockopt(). On return it is set to the actual size of the data returned.
struct linger
{
int l_onoff; /* option on/off */
int l_linger; /* linger time */
};
The l_onoff field is set to zero 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.
- Option
- Description
- IP_MULTICAST_IF
- (RAW and UDP) Used to get the interface IP address used for sending outbound multicast datagrams. The IP address is passed using the in_addr structure.
- IP_MULTICAST_LOOP
- (RAW and UDP) Used to determine whether loopback is enabled or disabled. The loopback indicator is passed as an u_char. The value 0 indicates loopback is disabled and the value 1 indicates it is enabled.
- IP_MULTICAST_TTL
- (RAW and UDP) Returns the IP time-to-live of outgoing multicast datagrams. The TTL value is passed as an u_char.
- IP_RECVPKINFO
- (RAW and UDP) Indicates whether returning the destination IP address
of an incoming packet and the interface over which the packet was
received is enabled or disabled. If the setsockopt() function is used
to set this option, the set value is returned. The option value is
passed as an int. The value 0 indicates the option is disabled and
the value 1 indicates the option is enabled. When the option is enabled,
the information is returned as IP_PKTINFO ancillary data on recvmsg()
function calls.
This option is protected by the _OPEN_SYS_SOCK_EXT4 feature test macro.
The following options are recognized at IPv6 level:
- Option
- Description
- IPV6_ADDR_PREFERENCES
- (TCP and UDP) Used to get the source address selection preference flags for a given socket. The flags are defined as bits within the 32 bit unsigned integer returned option value. The flags returned will be either the default preference flags or will be the flags previously set by setsockopt(). The constants for the flag bit values are defined in netinet/in.h.
- IPV6_CHECKSUM
- (RAW) Used to determine if checksum processing is enabled for a RAW (non-ICMPv6) socket. The option value returned is the offset into the user data where the checksum is located. It is passed as int. A value of -1 means the function is disabled.
- IPV6_DONTFRAG
- (RAW and UDP) This option turns off the automatic inserting of a fragment header in the packet for UDP and raw sockets.
- IPV6_DSTOPTS
- (RAW and UDP) The application can remove any sticky destination options header by calling setsockopt() for this option with a zero option length.
- IPV6_HOPOPTS
- (RAW and UDP) The application can remove any sticky hop-by-hop options header by calling setsockopt() for this option with a zero option length.
- IPV6_MULTICAST_HOPS
- (RAW and UDP) Returns the hop limit value for outbound multicast datagrams. The hop limit value is passed as an int.
- IPV6_MULTICAST_IF
- (RAW and UDP) Returns the interface index for the interface used for sending outbound multicast datagrams. The interface index is passed as an u_int.
- IPV6_MULTICAST_LOOP
- (RAW and UDP) Used to determine whether loopback of outgoing multicast packets is enabled or disabled. The loopback indicator is passed as u_int. The value 0 indicates the option is disabled and the value 1 indicates it is enabled.
- IPV6_NEXTHOP
- (RAW and UDP) Specifies the next hop for the datagram as a socket address structure.
- IPV6_RECVDSTOPTS
- (RAW and UDP) To receive destination options header this option must be enabled.
- IPV6_RECVHOPLIMIT
- (RAW, TCP, and UDP) Returns the received hop limit as IPV6_HOPLIMIT ancillary data on recvmsg() function calls. The option value is passed as an int. The value 0 indicates the option is disabled and the value 1 indicates the option is enabled.
- IPV6_RECVHOPOPTS
- (RAW and UDP) To receive a hop-by-hop options header this option must be enabled.
- IPV6_RECVPATHMTU
- (RAW and UDP) Returns the path MTU as IPV6_PATHMTU ancillary data on recvmsg() function calls.
- IPV6_RECVPKTINFO
- (RAW and UDP) Indicates whether returning the destination IP address of an incoming packet and the interface over which the packet was received is enabled or disabled. The option value is passed as an int. The value 0 indicates the option is disabled and the value 1 indicates the option is enabled. When the option is enabled, the information is returned as IPV6_PKTINFO ancillary data on recvmsg() function calls.
- IPV6_RECVRTHDR
- (RAW and UDP) To receive a routing header this option must be enabled.
- IPV6_RECVTCLASS
- (RAW, TCP, and UDP) To receive the traffic class this option must be enabled.
- IPV6_RTHDR
- (RAW and UDP) The application can remove any sticky routing header by calling setsockopt() for this option with a zero option length.
- IPV6_RTHDRDSTOPTS
- (RAW and UDP) The application can remove any sticky destination options header by calling setsockopt() for this option with a zero option length.
- IPV6_TCLASS
- (RAW, TCP, and UDP) To specify the traffic class value this option must be enabled.
- IPV6_UNICAST_HOPS
- (RAW and UDP) Returns the hop limit value for outbound unicast datagrams. The hop limit value is passed as an int.
- IPV6_USE_MIN_MTU
- (RAW, TCP, and UDP) Indicates whether the IP layer will use the minimum MTU size (1280) for sending packets, bypassing path MTU discovery. The option value is passed as an int. A value of -1 causes the default values for unicast (disabled) and multicast (enabled) destinations to be used. A value of 0 disables this option for unicast and multicast destinations. A value of 1 enables this option for unicast and multicast destinations and the minimum MTU size will be used. If a setsockopt() call has not been made prior to a getsockopt() call, the default value of -1 is returned.
- IPV6_V6ONLY
- (RAW, TCP, and UDP) Used to determine whether a socket is restricted to IPv6 communications only. The option value is passed as an int. A non-zero value means the option is enabled (socket can only be used for IPv6 communications). 0 means the option is disabled.
The following option is recognized at ICMPv6 level:
- Option
- Description
- ICMP6_FILTER
- (RAW) Used to filter ICMPv6 messages. It returns the filter value being used for this socket. It is back in an icmp6_filter structure as defined in netinet/icmp6.h.
- Option
- Description
- SO_ACCEPTCONN
- The socket had a listen() call.
- SO_BROADCAST
- Toggles the ability to broadcast messages. If this option is enabled, it allows the application to send broadcast messages over socket, if the interface specified in the destination supports the broadcasting of packets. This option has no meaning for stream sockets. This option is valid only for the AF_INET domain.
- SO_DEBUG
- Reports whether debugging information is being recorded. This option stores an int value.
- SO_ERROR
- Returns any pending error on the socket and clears the error status. You can use SO_ERROR to check for asynchronous errors on connected datagram sockets or for other asynchronous errors (errors that are not returned explicitly by one of the socket calls).
- SO_KEEPALIVE
- Toggles the TCP keep-alive mechanism for a stream socket. When activated, the keep-alive mechanism periodically sends a packet on an otherwise idle connection. If the remote TCP does not respond to the packet or to retransmissions of the packet, the connection is ended with the error ETIMEDOUT. Processes writing to that socket are notified with a SIGPIPE signal. This option stores an int value. This option is valid only for the AF_INET and AF_INET6 domains.
- SO_LINGER
- Lingers on close if data is present. 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 TCP/IP address space waits to try 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 trying to send the data. The close() call returns without blocking the caller. This option has meaning only for stream sockets.
- SO_OOBINLINE
- Toggles reception of out-of-band data. When this option is enabled, out-of-band data is placed in the normal data input queue as it is received; it is then available to recv(), recvfrom(), and recvmsg() without the need to specify the MSG_OOB flag in those calls. When this option is disabled, out-of-band data is placed in the priority data input queue as it is received; it is then available to recv(), recvfrom(), and recvmsg() only if the MSG_OOB flag is specified in those calls. This option has meaning only for stream sockets.
- _SO_PROPAGATEUSERID
- Toggles propagating a user ID (UID) over an AF_UNIX stream socket. When enabled, user (UID) information is extracted from the system when the connect() function is invoked. Then, when the accept() function is invoked, the accepter assumes the identity of the connecter until the accepted socket is closed.
- SO_RCVBUF
- Reports receive buffer size information. This option stores an int value.
- SO_RCVTIMEO
-
Reports the timeout value with the amount of time an input function waits until it completes.
If a receive operation has blocked for this much time without receiving additional data, it returns with a partial count or errno set to EWOULDBLOCK if no data is received. The default for this option is zero, which indicates that a receive operation does not time out.
- SO_REUSEADDR
-
Toggles local address reuse. When enabled, this option allows local addresses that are already in use to be bound. SO_REUSEADDR alters the normal algorithm used in the bind() call.
The system checks at connect time to ensure that the local address and port do not have the same foreign address and port. The error EADDRINUSE is returned if the association already exists.
After the 'SO_REUSEADDR' option is active, the following situation is 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.
This option is valid only for the AF_INET and AF_INET6 domains.
- SO_SECINFO
- Toggles receiving security information. When enabled on an AF_UNIX UDP socket, the recvmsg() function will return security information about the sender of each datagram as ancillary data. This information contains the sender's user ID, uid, gid, and jobname and it is mapped by the secsinfo structure in sys/socket.h.
- SO_SNDBUF
- Reports send buffer size information. This option stores an int value.
- SO_SNDTIMEO
-
Reports the timeout value specifying the amount of time that an output function blocks due to flow control preventing data from being sent.
If a send operation has blocked for this time, it returns with a partial count or with errno set to EWOULDBLOCK if no data is sent. The default for this option is zero, which indicates that a send operation does not time out.
- SO_TYPE
- This option returns the type of the socket. On return, the integer pointed to by option_value is set to SOCK_STREAM or SOCK_DGRAM. This option is valid for the AF_UNIX, AF_INET and AF_INET6 domains.
Special behavior for C++: To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.
Returned value
If successful, getsockopt() returns 0.
- Error Code
- Description
- EBADF
- The socket parameter is not a valid socket descriptor.
- EFAULT
- Using option_value and option_len parameters would result in an attempt to access storage outside the caller's address space.
- EINVAL
- The specified option is not valid at the specified socket level.
- ENOBUFS
- Buffer space is not available to send the message.
- ENOPROTOOPT
- The option_name parameter is unrecognized, or the level parameter is not SOL_SOCKET.
- ENOSYS
- The function is not implemented. You attempted to use a function that is not yet available.
- ENOTSOCK
- The descriptor is for a file, not for a socket.
- EOPNOTSUPP
- The operation is not supported by the socket protocol. At least
the following options are not supported:
- IPV6_JOIN_GROUP
- IPV6_LEAVE_GROUP
- IP_ADD_SOURCE_MEMBERSHIP
- IP_DROP_SOURCE_MEMBERSHIP
- IP_DROP_MEMBERSHIP
- IP_ADD_MEMBERSHIP
- IP_BLOCK_SOURCE
- IP_UNBLOCK_SOURCE
- MCAST_JOIN_GROUP
- MCAST_LEAVE_GROUP
- MCAST_BLOCK_SOURCE
- MCAST_UNBLOCK_SOURCE
- MCAST_JOIN_SOURCE_GROUP
- MCAST_LEAVE_SOURCE_GROUP
Example
int rc;
int s;
int option_value;
int option_len;
struct linger l;
int getsockopt(int s, int level, int option_name,
char *option_value,
int *option_len);
⋮
/* Is out-of-band data in the normal input queue? */
option_len = sizeof(int);
rc = getsockopt(
s, SOL_SOCKET, SO_OOBINLINE, (
char *) &option_value, &option_len);
if (rc == 0)
{
if (option_len == sizeof(int))
{
if (option_value)
/* yes it is in the normal queue */
else
/* no it is not
*/
}
}
⋮
/* Do I linger on close? */
option_len = sizeof(l);
rc = getsockopt(
s, SOL_SOCKET, SO_LINGER, (char *) &l, &option_len);
if (rc == 0)
{
if (option_len == sizeof(l))
{
if (l.l_onoff)
/* yes I linger */
else
/* no I do not */
}
}
Related information
- netinet/in.h
- sys/socket.h
- sys/types.h
- bind() — Bind a name to a socket
- close() — Close a file
- getprotobyname() — Get a protocol entry by name
- recvmsg() — Receive messages on a socket and store in an array of message headers
- sendmsg() — Send messages on a socket
- setsockopt() — Set options associated with a socket
- socket() — Create a socket
- For more information about IPv4 socket options, see z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference.
- For more information about IPv6 socket options, see z/OS Communications Server: IPv6 Network and Appl Design Guide.