MSDN Documentation

Socket Options

This document provides a comprehensive reference to the socket options available for Windows Sockets (Winsock). Socket options allow applications to control various aspects of socket behavior, including performance tuning, network protocol behavior, and security settings.

Introduction

Socket options are set and retrieved using the setsockopt and getsockopt functions, respectively. These functions take a socket descriptor, a level indicating the protocol or subsystem, and an option name as parameters. The optval parameter points to a buffer containing the option value or where the option value is returned.

Common Socket Option Levels

The SOL_SOCKET level provides general socket options applicable to any socket type. Other levels, such as IPPROTO_TCP and IPPROTO_UDP, are protocol-specific.

Key Socket Options

SOL_SOCKET Level Options

These options are fundamental and apply to most socket types.

Option Name Description Type
SO_BROADCAST Enables or disables the permission to send broadcast data on a socket. BOOL
SO_DEBUG Enables or disables socket debugging. BOOL
SO_DONTLINGER Disables the SO_LINGER option. None
SO_ERROR Retrieves error information for a socket. int
SO_KEEPALIVE Enables or disables keep-alive diagnostic packets for a socket. BOOL
SO_LINGER Specifies the time interval to linger on a closed socket. struct linger
SO_RCVBUF Sets or retrieves the size of the receive buffer for the socket. int
SO_RCVTIMEO Sets or retrieves the timeout value for socket receive operations. struct timeval
SO_SNDBUF Sets or retrieves the size of the send buffer for the socket. int
SO_SNDTIMEO Sets or retrieves the timeout value for socket send operations. struct timeval
SO_REUSEADDR Enables or disables the ability to reuse a local address and port. BOOL
SO_TYPE Retrieves the type of the socket. int

IPPROTO_TCP Level Options

These options are specific to TCP sockets and control aspects of TCP behavior.

Option Name Description Type
TCP_NODELAY Disables the Nagle algorithm for sending data. BOOL
TCP_MAXSEG Retrieves or sets the maximum segment size for TCP. int
TCP_KEEPIDLE Sets the time (in seconds) the connection must be idle before sending the first keep-alive probe. unsigned int
TCP_KEEPINTVL Sets the time (in seconds) between successive keep-alive probes after the first one. unsigned int
TCP_KEEPCNT Sets the number of unacknowledged probes that can be sent before the connection is considered dead. unsigned int

IPPROTO_UDP Level Options

These options are specific to UDP sockets.

Option Name Description Type
UDP_CORK A Linux-specific option, generally not applicable on Windows. N/A

Using getsockopt and setsockopt

The prototypes for these functions are:

int getsockopt(
        SOCKET s,
        int level,
        int optname,
        char FAR * optval,
        int FAR * optlen
    );

    int setsockopt(
        SOCKET s,
        int level,
        int optname,
        const char FAR * optval,
        int optlen
    );

s: A descriptor identifying a socket.

level: Specifies the protocol level at which the option is supported. To retrieve or set options for the socket itself, specify SOL_SOCKET.

optname: Specifies the socket option to retrieve or set.

optval: Pointer to a buffer in which the value for the requested option is returned, or that contains the value for the option to be set.

optlen: Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the optval parameter.

Example: Setting SO_REUSEADDR

The following code snippet demonstrates how to set the SO_REUSEADDR option on a socket:

#include <winsock2.h>
            #pragma comment(lib, "Ws2_32.lib")

            // ...

            SOCKET sock = socket(AF_INET, SOCK_STREAM, 0);
            if (sock == INVALID_SOCKET) {
                // Handle error
                return 1;
            }

            BOOL enableReuse = TRUE;
            int ret = setsockopt(sock, SOL_SOCKET, SO_REUSEADDR, (char*)&enableReuse, sizeof(enableReuse));

            if (ret == SOCKET_ERROR) {
                // Handle error
                closesocket(sock);
                return 1;
            }

            // Proceed with socket operations...

Further Reading