# Compaq TCP/IP Services for OpenVMS
Sockets API and System Services Programming

Previous | Contents | Index

# Appendix A
Socket Options

This appendix describes the socket options that you can set with the Sockets API `setsockopt()` function and the $QIO system service IO$_SETMODE and IO$_SETCHAR I/O function codes. You can query the value of these socket options using the Sockets API `getstockopt()` function or the $QIO system service IO$_SENSEMODE or IO$_SENSECHAR I/O function code.

The following tables list:

- Socket Options
- TCP Protocol Options
- IP Protocol Options

Table A-1 lists the socket options that are set at the SOL_SOCKET level and their Sockets API and system service symbol names.

Table A-1 Socket Options
Sockets API Symbol | System Service Symbol | Description
--- | --- | ---
SO_BROADCAST | TCPIP$C_BROADCAST | Permits the sending of broadcast messages. Takes an integer parameter and requires a system user identification code (UIC) or SYSPRV, BYPASS, or OPER privilege. Optional for a connectionless datagram.
SO_DONTROUTE | TCPIP$C_DONTROUTE | Indicates that outgoing messages should bypass the standard routing facilities. Instead, the messages are directed to the appropriate network interface according to the network portion of the destination address.
SO_ERROR | TCPIP$C_ERROR | Obtains the socket error status and clears the error on the socket.
SO_FULL_DUPLEX_CLOSE | TCPIP$C_FULL_DUPLEX_CLOSE | When set before a close operation, the receive and transmit sides of the communications are closed.
SO_KEEPALIVE | TCPIP$C_KEEPALIVE | Keeps connections active. Enables the periodic transmission of keepalive probes to the remote system. If the remote system fails to respond to the keepalive probes, the connection is broken. If the SO_KEEPALIVE option is enabled, the values of TCP_KEEPCNT, TCP_KEEPINTVL and TCP_KEEPIDLE affect TCP behavior on the socket.
SO_LINGER | TCPIP$C_LINGER | Lingers on a `close()` function if data is present. Controls the action taken when unsent messages queue on a socket and a `close()` function is performed. Uses a `linger` structure parameter defined in SOCKET.H to specify the state of the option and the linger interval. If SO_LINGER is specified, the system blocks the process during the `close()` function until it can transmit the data or until the time expires. If the option is not specified and a `close()` function is issued, the system allows the process to resume as soon as possible.
SO_OOBINLINE | TCPIP$C_OOBINLINE | When this option is set, out-of-band data is placed in the normal input queue. When `SO_OOBINLINE` is set, the `MSG_OOB` flag to the receive functions cannot be used to read the out-of-band data. A value of 0 disables the option, and a nonzero value enables the option.
SO_RCVBUF | TCPIP$C_RCVBUF | Sets the receive buffer size, in bytes. Takes an integer parameter and requires a system UIC or SYSPRV, BYPASS, or OPER privilege.
SO_RCVTIMEO | TCPIP$C_RCVTIMEO | For Compaq use only. Sets the timeout value for a `recv()` operation. The argument to the two `sockopt` functions is a pointer to a `timeval` structure containing an integer value specified in seconds.
SO_REUSEADDR | TCPIP$C_REUSEADDR | Specifies that the rules used in validating addresses supplied by a `bind()` function should allow reuse of local addresses. A value of 0 disables the option, and a non-zero value enables the option. The SO_REUSEPORT option is automatically set when an application sets SO_REUSEADDR
SO_REUSEPORT | TCPIP$C_REUSEPORT | Allows more than one process to receive UDP datagrams destined for the same port. The `bind()` call that binds a process to the port must be preceded by a `setsockopt()` call specifying this option. SO_REUSEPORT is automatically set when an application sets the SO_REUSEADDR option.
SO_SHARE | TCPIP$C_SHARE | Allows multiple processes to share the socket.
SO_SNDBUF | TCPIP$C_SNDBUF | Sets the send buffer size in bytes. Takes an integer parameter and requires a system UIC or SYSPRV, BYPASS, or OPER privilege. Optional for a connectionless datagram.
SO_SNDLOWAT | TCPIP$C_SNDLOWAT | Sets the low-water mark for a `send()` operation. The send low-water mark is the amount of space that must exist in the socket send buffer for `select()` to return writeable. Takes an integer value specified in bytes.
SO_SNDTIMEO | TCPIP$C_SNDTIMEO | For Compaq use only. Sets the timeout value for a `send()` operation. The argument to the two `sockopt()` functions is a pointer to a `timeval` structure containing an integer value specified in seconds.
SO_TYPE | TCPIP$C_TYPE | Obtains the socket type.
SO_USELOOPBACK | TCPIP$C_USELOOPBACK | For Compaq use only. This option applies only to sockets in the routing domain (AF_ROUTE), When you enable this option, the socket receives a copy of everything sent on the socket.

Table A-2 lists the TCP protocol options that are set at the IPPROTO_TCP level and their Sockets API and system service symbol names.

Table A-2 TCP Protocol Options
Sockets API Symbol | System Service Symbol | Description
--- | --- | ---
TCP_KEEPCNT | TCPIP$C_TCP_KEEPCNT | When the SO_KEEPALIVE option is enabled, TCP sends a keepalive probe to the remote system of a connection that has been idle for a period of time. If the remote system does not respond to the keepalive probe, TCP retransmits a keepalive probe for a certain number of times before a connection is considered to be broken. The TCP_KEEPCNT option specifies the maximum number of keepalive probes to be sent. The value of TCP_KEEPCNT is an integer value between 1 and n, where n is the value of the systemwide `tcp_keepcnt` parameter. The default value for for the systemwide parameter, `tcp_keepcnt` , is 8. To display the values of the systemwide parameters, enter the following command at the system prompt: `$ sysconfig -q inet` The default value for TCP_KEEPCNT is 8.
TCP_KEEPIDLE | TCPIP$C_TCP_KEEPIDLE | When the SO_KEEPALIVE option is enabled, TCP sends a keepalive probe to the remote system of a connection that has been idle for a period of time. If the remote system does not respond to the keepalive probe, TCP retransmits a keepalive probe for a certain number of times before a connection is considered to be broken. TCP_KEEPIDLE specifies the number of seconds before TCP will send the initial keepalive probe. The default value for TCP_KEEPIDLE is an integer value between 1 and n, where n is the value for the systemwide parameter `tcp_keepidle` . The default value for `tcp_keepidle` , specified in half-second units, is 150 (75 seconds). To display the values of the systemwide parameters, enter the following command at the system prompt: `$ sysconfig -q inet` The default value for TCP_KEEPIDLE is 75 seconds.
TCP_KEEPINIT | TCPIP$C_TCP_KEEPINIT | If a TCP connection cannot be established within a period of time, TCP will time out the connection attempt. The default timeout value for this initial connection establishment is 75 seconds. The TCP_KEEPINIT option specifies the number of seconds to wait before the connection attempt times out. For passive connections, the TCP_KEEPINIT option value is inherited from the listening socket. The value of TCP_KEEPINIT is an integer between 1 and n, where n is the value for the systemwide parameter `tcp_keepinit` . The default value of the systemwide parameter `tcp_keepinit` , specified in half-second units, is 150 (75 seconds). To display the values of the systemwide parameters, enter the following command at the system prompt: `$ sysconfig -q inet` The TCP_KEEPINIT option does not require the SO_KEEPALIVE option to be enabled.
TCP_KEEPINTVL | TCPIP$C_TCP_KEEPINTVL | When the SO_KEEPALIVE option is enabled, TCP sends a keepalive probe to the remote system on a connection that has been idle for a period of time. If the remote system does not respond to a keepalive probe, TCP retransmits the keepalive probe after a period of time. The default value for this retransmit interval is 75 seconds. The TCP_KEEPINTVL option specifies the number of seconds to wait before retransmitting a keepalive probe. The value of the TCP_KEEPINTVL option is an integer between 1 and n, where n is the value of the systemwide parameter `tcp_keepintvl` which is specified in half-second units. The default value for the systemwide parameter `tcp_keepintvl` is 150 (75 seconds). To display the values of the systemwide parameters, enter the following command at the system prompt: `$ sysconfig -q inet`
TCP_NODELAY | TCPIP$C_TCP_NODELAY | Specifies that the `send()` operation not be delayed to merge packets. Under most circumstances, TCP sends data when it is presented. When outstanding data has not yet been acknowledged, TCP gathers small amounts of the data into a single packet and sends it when an acknowledgment is received. This functionality can cause significant delays for some clients that do not expect replies (such as windowing systems that send a stream of events from the mouse). The TCP_NODELAY disables the Nagle algorithm, which reduces the number of small packets on a wide area network.
TCP_MAXSEG | TCPIP$C_TCP_MAXSEG | Sets the maximum transmission unit (MTU) of a TCP segment to a specified integer value from 1 to 65535. The default is 576 bytes. Can only be set before a `listen()` or `connect()` operation on the socket. For passive connections, the value is obtained from the listening socket. Note that TCP does not use an MTU value that is less than 32 or greater than the local network's MTU. Setting the option to zero results in the default behavior.
TCP_NODELACK | TCPIP$C_TCP_NODELACK | When specified, disables the algorithm that gathers outstanding data that has not been acknowledged and sends it in a single packet when acknowledgment is received. Takes an integer value.
TCP protocol options that are obsolete but provided for backward compatibility
TCP_DROP_IDLE | TCPIP$C_TCP_DROP_IDLE | When the TCP_KEEPALIVE option is enabled, the TCP_DROP_IDLE option specifies the time interval after which a connection is dropped. The value of TCP_DROP_IDLE is an integer specified in seconds. The default value is 600 seconds. When the TCP_DROP_IDLE option is set, the value of the TCP_KEEPCNT option is calculated as the value of TCP_DROP_IDLE divided by the value of TCP_KEEPINTVL. A call to `getsockopt()` function specifying the TCP_DROP_IDLE option returns the result of multiplying the values of TCP_KEEPCNT and TCP_KEEPINTVL.
TCP_PROBE_IDLE | TCPIP$C_TCP_PROBE_IDLE | When the TCP_KEEPALIVE option is enabled, the TCP_PROBE_IDLE option specifies the time interval between the keepalive probes and for the connections establishing the timeout. The default value for TCP_PROBE_IDLE is 75 seconds. The value of TCP_PROBE_IDLE is an integer specified in seconds. When this option is set, TCP_KEEPINTVL, TCP_KEEPIDLE and TCP_KEEPINIT are set to the value specified for TCP_PROBE_IDLE. A call to the `getsockopt()` function specifying the TCP_PROBE_IDLE option returns the value of TCP_KEEPINTVL.

Table A-3 lists options that are set at the IPPROTO_IP level and their Sockets API and system service symbol names.

Table A-3 IP Protocol Options
Sockets API Symbol | System Service Symbol | Description
--- | --- | ---
IP_ADD_MEMBERSHIP | TCPIP$C_IP_ADD_MEMBERSHIP | Adds the host to the membership of a multicast group. A host must become a member of a multicast group before it can receive datagrams sent to the group. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. Up to IP_MAX_MEMBERSHIPS (currently 20) memberships may be added on a single socket.
IP_DROP_MEMBERSHIP | TCPIP$C_IP_DROP_MEMBERSHIP | Removes the host from the membership of a multicast group.
IP_HDRINCL | TCPIP$C_IP_HDRINCL | If specified for a raw IP socket, you must build the IP header for all datagrams sent on the raw socket.
IP_MULTICAST_IF | TCPIP$C_IP_MULTICAST_IF | Specifies the interface for outgoing multicast datagrams sent on this socket. The interface is specified as an `in_addr` structure.
IP_MULTICAST_LOOP | TCPIP$C_IP_MULTICAST_LOOP | Disables loopback of local delivery. If a multicast datagram is sent to a group which the sending host is a member, a copy of the datagram is looped back by the IP layer for local delivery (the default). To disable the loopback delivery, specify a value of 0.
IP_MULTICAST_TTL | TCPIP$C_IP_MULTICAST_TTL | Specifies the time-to-live (TTL) value for outgoing multicast datagrams. Takes an integer value between 0 and 255:
Value | Action
--- | ---
0 | Restricts distribution to applications running on the local host.
1 | Forwards the multicast datagram to hosts on the local subnet.
2 - 255 | With a multicast router attached to the sending host's network, forwards multicast datagrams beyond the local subnet. Multicast routers forward the datagram to known networks that have hosts belonging to the specified multicast group. The TTL value is decremented by each multicast router in the path. When the TTL value is decremented to zero, the datagram is no longer forwarded.
IP_OPTIONS | TCPIP$C_IP_OPTIONS | Provides IP options to be transmitted in the IP header of each outgoing packet.
IP_RECVDSTADDR | TCPIP$C_IP_RECVDSTADDR | Enables a SOCK_DGRAM socket to receive the destination IP address for a UDP datagram.
IP_RECVOPTS | TCPIP$C_IP_RECVOPTS | Enables a SOCK_DGRAM socket to receive IP options.
IP_TTL | TCPIP$C_IP_TTL | Time to live (TTL) for a datagram.
IP_TOS | TCPIP$C_IP_TOS | Type of service (1-byte value).

Previous | Next | Contents | Index