SO_KEEPALIVE socket option

Article
04/19/2023

The SO_KEEPALIVE socket option is designed to allow an application to enable keep-alive packets for a socket connection.

To query the status of this socket option, call the getsockopt function. To set this option, call the setsockopt function with the following parameters.

Socket option value

The constant that represents this socket option is 0x0008.

Syntax

int setsockopt(
  (SOCKET) s,      // descriptor identifying a socket 
  (int) SOL_SOCKET,   // level
  (int) SO_KEEPALIVE, // optname
  (char *) optval, // input buffer,
  (int) optlen  // size of input buffer
);

Parameters

s [in]

A descriptor identifying the socket.

level [in]

The level at which the option is defined. Use SOL_SOCKET for this operation.

optname [in]

The socket option for which the value is to be set. Use SO_KEEPALIVE for this operation.

optval [out]

A pointer to the buffer containing the value for the option to set. This parameter should point to buffer equal to or larger than the size of a DWORD value.

This value is treated as a boolean value with 0 used to indicate FALSE (disabled) and a nonzero value to indicate TRUE (enabled).

optlen [in]

The size, in bytes, of the optval buffer. This size must be equal to or larger than the size of a DWORD value.

Return value

If the operation completes successfully, setsockopt returns zero.

If the operation fails, a value of SOCKET_ERROR is returned and a specific error code can be retrieved by calling WSAGetLastError.

Error code	Meaning
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	One of the optval or the optlen parameters point to memory that is not in a valid part of the user address space. This error is also returned if the value pointed to by the optlen parameter is less than the size of a DWORD value.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The level parameter is unknown or invalid. On Windows Vista and later, this error is also returned if the socket was in a transitional state.
WSAENOPROTOOPT	The option is unknown or unsupported by the indicated protocol family. This error is returned if the socket descriptor passed in the s parameter was for a datagram socket.
WSAENOTSOCK	The descriptor is not a socket.

Remarks

The getsockopt function called with the SO_KEEPALIVE socket option allows an application to retrieve the current state of the keepalive option, although this is feature not normally used. If an application needs to enable keepalive packets on a socket, it justs calls the setsockopt function to enable the option.

The setsockopt function called with the SO_KEEPALIVE socket option allows an application to enable keep-alive packets for a socket connection. The SO_KEEPALIVE option for a socket is disabled (set to FALSE) by default.

When this socket option is enabled, the TCP stack sends keep-alive packets when no data or acknowledgement packets have been received for the connection within an interval. For more information on the keep-alive option, see section 4.2.3.6 on the Requirements for Internet Hosts—Communication Layers specified in RFC 1122 available at the IETF website. (This resource may only be available in English.)

The SO_KEEPALIVE socket option is valid only for protocols that support the notion of keep-alive (connection-oriented protocols). For TCP, the default keep-alive timeout is 2 hours and the keep-alive interval is 1 second. The default number of keep-alive probes varies based on the version of Windows.

The SIO_KEEPALIVE_VALS control code can be used to enable or disable keep-alive, and adjust the timeout and interval, for a single connection. If keep-alive is enabled with SO_KEEPALIVE, then the default TCP settings are used for keep-alive timeout and interval unless these values have been changed using SIO_KEEPALIVE_VALS.

The default system-wide value of the keep-alive timeout is controllable through the KeepAliveTime registry setting which takes a value in milliseconds. The default system-wide value of the keep-alive interval is controllable through the KeepAliveInterval registry setting which takes a value in milliseconds.

On Windows Vista and later, the number of keep-alive probes (data retransmissions) is set to 10 and cannot be changed.

On Windows Server 2003, Windows XP, and Windows 2000, the default setting for number of keep-alive probes is 5. The number of keep-alive probes is controllable through the TcpMaxDataRetransmissions and PPTPTcpMaxDataRetransmissions registry settings. The number of keep-alive probes is set to the larger of the two registry key values. If this number is 0, then keep-alive probes will not be sent. If this number is above 255, then it is adjusted to 255.

On Windows Vista and later, the SO_KEEPALIVE socket option can only be set using the setsockopt function when the socket is in a well-known state not a transitional state. For TCP, the SO_KEEPALIVE socket option should be set either before the connect function (connect, ConnectEx, WSAConnect, WSAConnectByList, or WSAConnectByName) is called, or after the connection request is actually completed. If the connect function was called asynchronously, then this requires waiting for the connection completion before trying to set the SO_KEEPALIVE socket option. If an application attempts to set the SO_KEEPALIVE socket option when a connection request is still in process, the setsockopt function will fail and return WSAEINVAL.

On Windows Server 2003, Windows XP, and Windows 2000, the SO_KEEPALIVE socket option can be set using the setsockopt function when the socket is a transitional state (a connection request is still in progress) as well as a well-known state.

Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Ws2def.h (include Winsock2.h)