Socket Options

This document provides an overview of socket options available in the Windows Sockets API. Socket options allow you to fine-tune the behavior of your sockets for various networking scenarios.

Overview

Socket options are used to retrieve or set parameters for a socket. These parameters can affect the behavior of the socket at the transport layer, the network layer, or the socket layer itself. You use the getsockopt and setsockopt functions to interact with socket options.

getsockopt

The getsockopt function retrieves the current value of a socket option.

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

setsockopt

The setsockopt function sets the current value of a socket option.

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

Common Socket Options

SOL_SOCKET Level Options

These options apply to all types of sockets.

Option Name Description Data Type
SO_BROADCAST Enables or disables the ability to send broadcast datagrams. BOOL
SO_DEBUG Enables or disables socket debugging. BOOL
SO_DONTLINGER Disables the normal process of closing a socket. BOOL
SO_ERROR Retrieves error information for a socket. int
SO_KEEPALIVE Enables or disables the periodic transmission of keep-alive messages. BOOL
SO_LINGER Specifies whether a socket should linger when closed. LINGER struct
SO_RCVBUF Sets or retrieves the size of the receive buffer. int
SO_RCVTIMEO Sets or retrieves the timeout for blocking receive operations. struct timeval
SO_REUSEADDR Enables or disables the reuse of addresses. BOOL
SO_SNDBUF Sets or retrieves the size of the send buffer. int
SO_SNDTIMEO Sets or retrieves the timeout for blocking send operations. struct timeval
SO_TYPE Retrieves the type of the socket. int

IPPROTO_TCP Level Options

These options are specific to TCP sockets.

Option Name Description Data Type
TCP_NODELAY Disables the Nagle algorithm. BOOL
TCP_MAXSEG Sets or retrieves the maximum segment size. int
TCP_KEEPIDLE Specifies the time the connection must be idle before the first keep-alive probe is sent. UINT
TCP_KEEPINTVL Specifies the interval between subsequent keep-alive probes. UINT
TCP_KEEPCNT Specifies the number of probes that must be sent before the connection is considered dead. UINT

IPPROTO_IP Level Options

These options are specific to IPv4 sockets.

Option Name Description Data Type
IP_TOS Sets or retrieves the Type of Service (ToS) field in the IP header. int
IP_TTL Sets or retrieves the Time To Live (TTL) field in the IP header. int
IP_MULTICAST_TTL Sets or retrieves the TTL for multicast datagrams. UCHAR
IP_ADD_MEMBERSHIP Joins a multicast group. struct ip_mreq
IP_DROP_MEMBERSHIP Leaves a multicast group. struct ip_mreq

Tip: When setting options that involve timeouts (e.g., SO_RCVTIMEO, SO_SNDTIMEO), ensure you use the struct timeval correctly, specifying seconds and microseconds.

Example Usage

Enabling Broadcast

To enable broadcasting on a UDP socket:

SOCKET udpSocket = socket(AF_INET, SOCK_DGRAM, 0);
BOOL broadcastEnable = TRUE;
int result = setsockopt(udpSocket, SOL_SOCKET, SO_BROADCAST, (char*)&broadcastEnable, sizeof(broadcastEnable));
if (result == SOCKET_ERROR) {
    // Handle error
}

Setting Receive Timeout

To set a 5-second receive timeout:

SOCKET tcpSocket = socket(AF_INET, SOCK_STREAM, 0);
struct timeval timeout;
timeout.tv_sec = 5;
timeout.tv_usec = 0;
int result = setsockopt(tcpSocket, SOL_SOCKET, SO_RCVTIMEO, (char*)&timeout, sizeof(timeout));
if (result == SOCKET_ERROR) {
    // Handle error
}

Note: The behavior of some options can vary depending on the Windows version and the underlying network stack implementation.

Important: Always check the return value of getsockopt and setsockopt for errors. Use WSAGetLastError() to retrieve specific error codes.

Related Topics