Socket Options
This page describes various options that control socket or protocol behavior. TargetTCP supports an assortment of standard and non-standard options. The socket option values are read using getsockopt() and set using setsockopt().
Besides a socket handle, these functions take four additional parameters: a level (socket, IPv4, IPv6, or TCP), a name, a pointer to a value, and a pointer to the value’s length. The return values are merely 0 for success and -1 for error, with errno set to the appropriate value. The pointers are used to input or output option values.
The supported options are listed in the table below, including the symbols for the level and option name parameters and information on the option value and length. Detailed descriptions follow below. Where indicated, the detailed description for some options is given in a separate manual.
| level | optname | *optval | *optlen |
|---|---|---|---|
| SOL_SOCKET | SO_BINDTODEVICE | NI name string | buffer length |
| SOL_SOCKET | SO_BROADCAST | TRUE or FALSE | sizeof(int) |
| SOL_SOCKET | SO_CHECKSUM | TRUE or FALSE | sizeof(int) |
| SOL_SOCKET | SO_CONTIMEO | ms (>= 75000) | sizeof(timeval) |
| SOL_SOCKET | SO_DONTROUTE | TRUE or FALSE | sizeof(int) |
| SOL_SOCKET | SO_ERROR | error code | sizeof(int) |
| SOL_SOCKET | SO_KEEPALIVE | TRUE or FALSE | sizeof(int) |
| SOL_SOCKET | SO_LINGER | struct linger | sizeof(int) |
| SOL_SOCKET | SO_OOBINLINE | TRUE or FALSE | sizeof(int) |
| SOL_SOCKET | SO_RCVBUF | recv buf size | sizeof(int) |
| SOL_SOCKET | SO_RCVLOWAT | 1 - 65535 | sizeof(int) |
| SOL_SOCKET | SO_RCVTIMEO | ms (>= 500) or forever | sizeof(timeval) |
| SOL_SOCKET | SO_REUSEADDR | TRUE or FALSE | sizeof(int) |
| SOL_SOCKET | SO_REUSEPORT | TRUE or FALSE | sizeof(int) |
| SOL_SOCKET | SO_SNDBUF | send buf size | sizeof(int) |
| SOL_SOCKET | SO_SNDTIMEO | ms (>= 500) | sizeof(int) |
| SOL_SOCKET | SO_TYPE | SOCK_XXXX | sizeof(int) |
| SOL_SOCKET | SO_USELOOPBACK | TRUE or FALSE | sizeof(int) |
| IPPROTO_IP | IP_ADD_MEMBERSHIP | struct ip_mreq | sizeof(struct …) |
| IPPROTO_IP | IP_ADD_SOURCE_MEMBERSHIP | struct ip_mreq_source | sizeof(struct …) |
| IPPROTO_IP | IP_BLOCK_SOURCE | struct ip_mreq_source | sizeof(struct …) |
| IPPROTO_IP | IP_DONTFRAG | TRUE or FALSE | sizeof(int) |
| IPPROTO_IP | IP_DROP_MEMBERSHIP | struct ip_mreq | sizeof(struct …) |
| IPPROTO_IP | IP_DROP_SOURCE_MEMBERSHIP | struct ip_mreq_source | sizeof(struct …) |
| IPPROTO_IP | IP_HDRINCL | TRUE or FALSE | sizeof(int) |
| IPPROTO_IP | IP_MTU | MTU value | sizeof(int) |
| IPPROTO_IP | IP_MULTICAST_IF | struct in_addr | sizeof(struct …) |
| IPPROTO_IP | IP_MULTICAST_LOOP | TRUE or FALSE | sizeof(u_char) |
| IPPROTO_IP | IP_MULTICAST_TTL | 1-255 | sizeof(u_char) |
| IPPROTO_IP | IP_TOS | IPTOS_XXXX | sizeof(int) |
| IPPROTO_IP | IP_TTL | 1-255 | sizeof(int) |
| IPPROTO_IP | IP_UNBLOCK_SOURCE | struct ip_mreq_source | sizeof(struct …) |
| IPPROTO_IP | MCAST_BLOCK_SOURCE | struct group_source_req | sizeof(struct …) |
| IPPROTO_IP | MCAST_JOIN_GROUP | struct group_req | sizeof (struct …) |
| IPPROTO_IP | MCAST_JOIN_SOURCE_GROUP | struct group_source_req | sizeof(struct …) |
| IPPROTO_IP | MCAST_LEAVE_GROUP | struct group_req | sizeof(struct …) |
| IPPROTO_IP | MCAST_LEAVE_SOURCE_GROUP | struct group_source_req | sizeof(struct …) |
| IPPROTO_IP | MCAST_UNBLOCK_SOURCE | struct group_source_req | sizeof(struct …) |
| IPPROTO_IPV6 | IPV6_ADD_MEMBERSHIP | struct ipv6_mreq | sizeof(struct …) |
| IPPROTO_IPV6 | IPV6_DONTFRAG | TRUE or FALSE | sizeof(int) |
| IPPROTO_IPV6 | IPV6_DROP_MEMBERSHIP | struct ipv6_mreq | sizeof(struct …) |
| IPPROTO_IPV6 | IPV6_MULTICAST_HOPS | 1-255 | sizeof(int) |
| IPPROTO_IPV6 | IPV6_MULTICAST_IF | interface number | sizeof(int) |
| IPPROTO_IPV6 | IPV6_MULTICAST_LOOP | TRUE or FALSE | sizeof(int) |
| IPPROTO_IPV6 | IPV6_UNICAST_HOPS | 1-255 | sizeof(int) |
| IPPROTO_IPV6 | IPV6_V6ONLY | TRUE or FALSE | sizeof(int) |
| IPPROTO_TCP | TCP_KEEPCNT | # unanswered probes | sizeof(int) |
| IPPROTO_TCP | TCP_KEEPIDLE | # secs before first | sizeof(int) |
| IPPROTO_TCP | TCP_KEEPINTVL | # secs btwn probes | sizeof(int) |
| IPPROTO_TCP | TCP_NODELAY | TRUE or FALSE | sizeof(int) |
| IPPROTO_TCP | TCP_TLS_CLIENT | TRUE or FALSE | sizeof(int) |
| IPPROTO_TCP | TCP_TLS_PEERCRT | TRUE or FALSE | sizeof(int) |
| IPPROTO_TCP | TCP_TLS_SERVER | TRUE or FALSE | sizeof(int) |
SO_BINDTODEVICE
Associates a socket with a named NI. The socket only receives packets from the specified NI and routes outbound packets through the specified NI. If used with setsockopt() and *optlen is zero or *optval is the empty string, a previously established NI binding is cleared. If used with getsockopt() and *optlen is greater than the NI name length, the name and a terminating null are copied to *optval and the name length is written to *optlen. Otherwise, zero is written to *optlen and, if the input *optlen is non-zero, the empty string is written to *optval.
SO_BROADCAST
Controls the ability to send broadcast datagrams. If set, the destination address of a datagram can be set to a broadcast address without generating an error. The default value is FALSE. Applies to datagram sockets only.
SO_CHECKSUM
Specifies whether checksums are performed on outgoing datagrams. The default value is TRUE. Applies to datagram sockets only. A non-standard option.
SO_CONTIMEO
Specifies when an incomplete connection attempt is dropped. Applies to connect() and to listening sockets, starting when the socket receives a SYN and forks a new socket that sends a SYN reply. Uses the timeval structure defined in sys_types.h and reproduced below:
struct timeval
{
long tv_sec; /* number of seconds to wait */
long tv_usec; /* number of microseconds to wait */
}
The default value is 75s. If the timeout is set to zero, the connection timer is not invoked. However, TCP will drop the connection after the maximum number of SYN retransmissions. With the default retransmit time and count settings, this takes 423s. Applies to stream sockets.
SO_DONTROUTE
Controls routing. If set, the destination IP address used with connect() and sendto() must be on a directly connected network. The default value is FALSE. Applies to stream and datagram sockets.
SO_ERROR
Reads and then clears the socket’s last error value. This is a read-only option. Applies to stream and datagram sockets.
SO_KEEPALIVE
Controls periodic probing to determine if idle connection has been dropped. If set, a timer is started when the connection is established and is restarted whenever a segment is sent. If the timer expires, the last byte sent is resent. If this byte is not acknowledged, then after multiple resends the connection is aborted. The default value is FALSE. Applies to stream sockets.
SO_LINGER
Controls the behavior of closesocket(). The optval type is struct linger, reproduced below:
struct linger
{
int l_onoff; /* linger option on/off */
int l_linger; /* linger time (secs) */
}
By default, the linger option is off and closesocket() does not block. It marks the socket as inaccessible for further application calls and returns immediately. If there is unsent or unacknowledged data, TCP waits until all data has been sent and acknowledged and then exchanges FIN flags before closing the connection and recovering socket resources. This is called a graceful close.
If the linger option is on and the linger time is non-zero, closesocket() waits up to l_linger seconds for its FIN flag to be acknowledged by the connected peer. The maximum wait is 254 seconds. If a longer timeout is requested, l_linger is set to this maximum value.
If the linger option is on and the linger time is zero, closesocket() performs a forceful close by sending the RST flag.
SO_OOBINLINE
Controls receipt of TCP urgent data within the normal stream. If set, recv() or recvfrom() can be used to access urgent data without the MSG_OOB flag. The default value is FALSE. Applies to stream sockets.
SO_RCVBUF
The socket’s receive buffer size. This is set by the compile-time setting NET_BIG_SIZE and cannot be modified by setsockopt(). Applies to stream sockets.
SO_RCVLOWAT
Specifies the number of bytes that must be waiting in the socket receive buffer before indication of received data is passed to the application via select(), recv(), etc. The default value is 1. Applies to stream sockets.
SO_RCVTIMEO
Specifies when a waiting receive call times out. Uses the timeval structure defined in sys_types.h and reproduced below:
struct timeval
{
long tv_sec; /* number of seconds to wait */
long tv_usec; /* number of microseconds to wait */
}
If the timeout is set to zero, the receive timer is not invoked and receive calls block indefinitely. This is the default value. Applies to both stream and datagram sockets.
SO_REUSEADDR and SO_REUSEPORT
Controls whether the same protocol (TCP or UDP), local IP address, and local port number can be assigned to more than one socket. See bind() for more information. The default value for both options is FALSE. Applies to both stream and datagram sockets.
SO_SNDBUF
The socket’s send buffer size. This is set by the compile-time setting NET_BIG_SIZE and cannot be modified by setsockopt(). Applies to stream sockets.
SO_SNDTIMEO
Specifies when a waiting send call times out. Uses the timeval structure defined in sys_types.h and reproduced below:
struct timeval
{
long tv_sec; /* number of seconds to wait */
long tv_usec; /* number of microseconds to wait */
}
If the timeout is set to zero, the send timer is not invoked and send calls block indefinitely. This is the default value. Applies to stream sockets only (UDP sends are non-blocking).
SO_TYPE
Outputs the socket’s type: SOCK_STREAM or SOCK_DGRAM. This is a read-only option. Applies to stream and datagram sockets.
SO_USELOOPBACK
Specifies whether outbound broadcast datagrams are also received. By default, a copy of every transmitted broadcast datagram is looped back and processed as a received datagram. Applies to IPv4 datagram sockets. This is a non-standard option.
IP_ADD_MEMBERSHIP
Creates a new exclude-mode IGMP multicast group. Applies to IPv4 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IP_ADD_SOURCE_MEMBERSHIP
Adds a source to an include-mode IGMP multicast group, potentially creating it. Applies to IPv4 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IP_BLOCK_SOURCE
Adds a source to an exclude-mode IGMP multicast group. Applies to IPv4 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IP_DONTFRAG
Specifies whether the socket’s outbound IPv4 packets may be fragmented. Set to TRUE to disable fragmentation and FALSE to enable fragmentation. The default value is FALSE. Applies to stream and datagram sockets.
IP_DROP_MEMBERSHIP
Deletes an IGPM multicast group. Applies to IPv4 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IP_DROP_SOURCE_MEMBERSHIP
Removes a source from an include-mode IGMP multicast group. Applies to IPv4 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IP_HDRINCL
Specifies whether a packet sent over a raw socket includes an IP header provided by the application. The IP layer will provide an IP header unless this option is set. The default value is FALSE. Applies to raw sockets.
IP_MTU
Outputs the current MTU of a connected socket. Applies to stream and datagram sockets.
IP_MULTICAST_IF
Specifies the IP address of the NI used by outbound multicast datagrams from this socket. The default is the last NI added to TargetTCP. If the option value is INADDR_ANY, the effect of any prior call is removed and the default NI is used for subsequent transmissions. Applies to IPv4 datagram sockets.
IP_MULTICAST_LOOP
Specifies whether outbound multicast datagrams sent by this socket are also received. By default, a copy of every transmitted multicast datagram is looped back and processed as a received datagram. Applies to IPv4 datagram sockets.
IP_MULTICAST_TTL
Specifies the hop limit for multicast packets sent by this socket. This is the number of routers the packets can cross. Routers decrement the hop limit in received packets and discard them when the limit reaches zero. Valid values are 1 to 255. The default value is 1, which restricts multicast datagrams to the local subnet. Applies to IPv4 datagram sockets.
IP_TOS
Specifies the IP type-of-service value for packets sent by this socket. The default value is 0. Applies to IPv4 stream and datagram sockets.
IP_TTL
Specifies the hop limit for unicast and broadcast packets sent by this socket. This is the number of routers the packets can cross. Routers decrement the hop limit in received packets and discard them when the limit reaches zero. Valid values are 1 to 255. The default value is 64. Applies to IPv4 stream and datagram sockets.
IP_UNBLOCK_SOURCE
Removes a source from an exclude-mode IGMP multicast group. Applies to IPv4 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
MCAST_BLOCK_SOURCE
Adds a source to an exclude-mode multicast group. Applies to datagram sockets. See the “TargetTCP Multicasting” manual for more information.
MCAST_JOIN_GROUP
Creates a new exclude-mode multicast group. Applies to datagram sockets. See the “TargetTCP Multicasting” manual for more information.
MCAST_JOIN_SOURCE_GROUP
Adds a source to an include-mode multicast group, potentially creating it. Applies to datagram sockets. See the “TargetTCP Multicasting” manual for more information.
MCAST_LEAVE_GROUP
Deletes an existing multicast group. Applies to datagram sockets. See the “TargetTCP Multicasting” manual for more information.
MCAST_LEAVE_SOURCE_GROUP
Removes a source from an include-mode multicast group. Applies to datagram sockets. See the “TargetTCP Multicasting” manual for more information.
MCAST_UNBLOCK_SOURCE
Removes a source from an exclude-mode multicast group. Applies to datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IPV6_ADD_MEMBERSHIP
Creates a new exclude-mode MLD multicast group. Applies to IPv6 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IPV6_DONTFRAG
Specifies whether the socket’s outbound IPv6 packets may be fragmented. Set to TRUE to disable fragmentation and FALSE to enable IPv6 fragmentation. The default value is FALSE. Applies to IPv6 stream and datagram sockets.
IPV6_DROP_MEMBERSHIP
Deletes an MLD multicast group. Applies to IPv6 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IPV6_MULTICAST_HOPS
Specifies the hop limit for multicast packets sent by this socket. This is the number of routers the packets can cross. Routers decrement the hop limit in received packets and discard them when the limit reaches zero. Valid values are 1 to 255. The default value is 1, which restricts multicast datagrams to the local subnet. Applies to IPv6 datagram sockets.
IPV6_MULTICAST_IF
Specifies the interface number of the NI used by outbound multicast datagrams from this socket. The default is the last NI added to TargetTCP. If the option value is 0, the effect of any prior call is removed and the default NI is used for subsequent transmissions. Applies to IPv6 datagram sockets. See the “TargetTCP Multicasting” manual for more information.
IPV6_MULTICAST_LOOP
Specifies whether outbound multicast datagrams sent by this socket are also received. By default, a copy of every transmitted multicast datagram is looped back and processed as a received datagram. Applies to IPv6 datagram sockets.
IPV6_UNICAST_HOPS
Specifies the hop limit for unicast packets sent by this socket. This is the number of routers the packets can cross. Routers decrement the hop limit in received packets and discard them when the limit reaches zero. Valid values are 1 to 255. The default value is 64. Applies to IPv6 stream and datagram sockets.
IPV6_V6ONLY
Specifies IPv6 socket behavior in dual-stack mode. If TRUE, the socket only accepts IPv6 traffic. Otherwise, the socket accepts IPv4 and IPv6 traffic. Inbound IPv4 packets are assigned an IPv4-mapped IPv6 address and handled internally as IPv6 packets. Outbound IPv6 packets that have an IPv4-mapped destination address are sent as IPv4 packets. IPV6_V6ONLY is FALSE by default. Applies to IPv6 stream and datagram sockets.
TCP_KEEPCNT
If the SO_KEEPALIVE option is set, specifies the maximum number of unanswered keepalive probes before the connection is dropped. The default value is 9. Applies to stream sockets.
TCP_KEEPIDLE
If the SO_KEEPALIVE option is set, specifies the seconds before the first keepalive probe is sent on an idle connection. The default value is two hours. Applies to stream sockets.
TCP_KEEPINTVL
If the SO_KEEPALIVE option is set, specifies the seconds between keepalive probes if the last probe was unanswered. The default value is 75 seconds. Applies to stream sockets.
TCP_NODELAY
Specifies use of the Nagle congestion avoidance algorithm. If set, the Nagle algorithm is disabled and data is sent after a send() or sendto() call without waiting until either all previously sent data is acknowledged or there is enough new data to completely fill a maximum-sized segment. The default value is FALSE. Applies to stream sockets.
TCP_TLS_CLIENT
Configures the Transport Layer Security protocol. If set, the socket behaves as a TLS client, expecting the server to respond to a TLS Client Hello message. Set at socket allocation or anytime during a TCP connection. The default value is FALSE. Applies to stream sockets. See the TargetTLS manual for more information.
TCP_TLS_PEERCRT
If TRUE, the TLS server requires a certificate from the client and the TLS client offers a certificate to the server. The default value is FALSE. Applies to stream sockets. See the TargetTLS manual for more information.
TCP_TLS_SERVER
Configures the Transport Layer Security protocol. If set, the socket behaves as a TLS server, expecting the client to follow with a TLS Client Hello message. Set at socket allocation or anytime during a TCP connection. The default value is FALSE. Applies to stream sockets. See the TargetTLS manual for more information.