SOL_SOCKET Socket Options
The following tables describe SOL_SOCKET socket options. See the getsockopt and setsockopt function reference pages for more information on getting and setting socket options.
To enumerate protocols and discover supported properties for each installed protocol, use the WSAEnumProtocols, WSCEnumProtocols, or WSCEnumProtocols32 function.
Some socket options require more explanation than these tables can convey; such options contain links to additional pages.
Note
All SOL_SOCKET socket options apply equally to IPv4 and IPv6 (except SO_BROADCAST, since broadcast is not implemented in IPv6).
SOL_SOCKET Socket Options
| Option | Get | Set | Optval type | Description |
|---|---|---|---|---|
| PVD_CONFIG | yes | yes | char [] | An opaque data structure object containing configuration information for the service provider. This option is implementation dependent. |
| SO_ACCEPTCONN | yes | DWORD (boolean) | Returns whether a socket is in listening mode. This option is only Valid for connection-oriented protocols. | |
| SO_BROADCAST | yes | yes | DWORD (boolean) | Configure a socket for sending broadcast data. This option is only Valid for protocols that support broadcasting (IPX and UDP, for example). |
| SO_BSP_STATE | yes | CSADDR_INFO | Returns the local address, local port, remote address, remote port, socket type, and protocol used by a socket. See the SO_BSP_STATE reference for more information. | |
| SO_CONDITIONAL_ACCEPT | yes | yes | DWORD (boolean) | Indicates if incoming connections are to be accepted or rejected by the application, not by the protocol stack. See the SO_CONDITIONAL_ACCEPT reference for more information. |
| SO_CONNDATA | yes | yes | char [] | Additional data, not in the normal network data stream, that is sent with network requests to establish a connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others. This option is not supported by the TCP/IP protocol in Windows. |
| SO_CONNDATALEN | yes | DWORD | The length, in bytes, of additional data, not in the normal network data stream, that is sent with network requests to establish a connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others. This option is not supported by the TCP/IP protocol in Windows. | |
| SO_CONNECT_TIME | yes | DWORD | Returns the number of seconds a socket has been connected. This option is only valid for connection-oriented protocols. | |
| SO_CONNOPT | yes | yes | char [] | Additional connect option data, not in the normal network data stream, that is sent with network requests to establish a connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others. This option is not supported by the TCP/IP protocol in Windows. |
| SO_CONNOPTLEN | yes | DWORD | The length, in bytes, of connect option data, not in the normal network data stream, that is sent with network requests to establish a connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others. This option is not supported by the TCP/IP protocol in Windows. | |
| SO_DISCDATA | yes | yes | char [] | Additional data, not in the normal network data stream, that is sent with network requests to disconnect a connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others. This option is not supported by the TCP/IP protocol in Windows. |
| SO_DISCDATALEN | yes | DWORD | The length, in bytes, of additional data, not in the normal network data stream, that is sent with network requests to disconnect a connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others. This option is not supported by the TCP/IP protocol in Windows. | |
| SO_DISCOPT | yes | yes | char [] | Additional disconnect option data, not in the normal network data stream, that is sent with network requests to disconnect a connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others. This option is not supported by the TCP/IP protocol in Windows. |
| SO_DISCOPTLEN | yes | DWORD | The length, in bytes, of additional disconnect option data, not in the normal network data stream, that is sent with network requests to disconnect a connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others. This option is not supported by the TCP/IP protocol in Windows. | |
| SO_DEBUG | yes | yes | DWORD (boolean) | Enable debug output. Microsoft providers currently do not output any debug information. |
| SO_DONTLINGER | yes | yes | DWORD (boolean) | Indicates the state of the l_onoff member of the linger structure associated with a socket. If this member is nonzero, a socket remains open for a specified amount of time after a closesocket function call to enable queued data to be sent. This option is only valid for reliable, connection-oriented protocols. |
| SO_DONTROUTE | yes | yes | DWORD (boolean) | Indicates that outgoing data should be sent on whatever interface the socket is bound to and not a routed on some other interface. This option is only Valid for message-oriented protocols. Microsoft providers silently ignore this option and always consult the routing table to find the appropriate outgoing interface. |
| SO_ERROR | yes | DWORD | Returns the last error code on this socket. This per-socket error code is not always immediately set. | |
| SO_EXCLUSIVEADDRUSE | yes | yes | DWORD (boolean) | Prevents any other socket from binding to the same address and port. This option must be set before calling the bind function. See the SO_EXCLUSIVEADDRUSE reference for more information. |
| SO_GROUP_ID | yes | unsigned int | This socket option is reserved and should not be used. | |
| SO_GROUP_PRIORITY | yes | yes | int | This socket option is reserved and should not be used. |
| SO_KEEPALIVE | yes | yes | DWORD (boolean) | Enables keep-alive for a socket connection. 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. See the SO_KEEPALIVE reference for more information. |
| SO_LINGER | yes | yes | struct linger | Indicates the state of the linger structure associated with a socket. If the l_onoff member of the linger structure is nonzero, a socket remains open for a specified amount of time after a closesocket function call to enable queued data to be sent. The amount of time, in seconds, to remain open is specified in the l_linger member of the linger structure. This option is only valid for reliable, connection-oriented protocols. |
| SO_MAX_MSG_SIZE | yes | DWORD | Returns the maximum outbound message size for message-oriented sockets supported by the protocol. Has no meaning for stream-oriented sockets. | |
| SO_MAXDG | yes | DWORD | Returns the maximum size, in bytes, for outbound datagrams supported by the protocol. This socket option has no meaning for stream-oriented sockets. | |
| SO_MAXPATHDG | yes | DWORD | Returns the maximum size, in bytes, for outbound datagrams supported by the protocol to a given destination address. This socket option has no meaning for stream-oriented sockets. Microsoft providers may silently treat this as SO_MAXDG. | |
| SO_OOBINLINE | yes | yes | DWORD (boolean) | Indicates that out-of-bound data should be returned in-line with regular data. This option is only valid for connection-oriented protocols that support out-of-band data. |
| SO_OPENTYPE | yes | yes | DWORD | Once set, affects whether subsequent sockets that are created will be non-overlapped. The possible values for this option are SO_SYNCHRONOUS_ALERT and SO_SYNCHRONOUS_NONALERT. This option should not be used. Instead use the WSASocket function and leave the WSA_FLAG_OVERLAPPED bit in the dwFlags parameter turned off. |
| SO_PAUSE_ACCEPT | yes | yes | DWORD(boolean) | Use this option for listening sockets. When the option is set, the socket responds to all incoming connections with an RST rather than accepting them. |
| SO_PORT_SCALABILITY | yes | yes | DWORD (boolean) | Enables local port scalability for a socket by allowing port allocation to be maximized by allocating wildcard ports multiple times for different local address port pairs on a local machine. On platforms where both options are available, prefer SO_REUSE_UNICASTPORT instead of this option. See the SO_PORT_SCALABILITY reference for more information. |
| SO_PROTOCOL_INFO | yes | WSAPROTOCOL_INFO | This option is defined to the SO_PROTOCOL_INFOW socket option if the UNICODE macro is defined. If the UNICODE macro is not defined, then this option is defined to the SO_PROTOCOL_INFOA socket option. | |
| SO_PROTOCOL_INFOA | yes | WSAPROTOCOL_INFOA | Returns the WSAPROTOCOL_INFOA structure for the given socket | |
| SO_PROTOCOL_INFOW | yes | WSAPROTOCOL_INFOW | Returns the WSAPROTOCOL_INFOW structure for the given socket | |
| SO_RANDOMIZE_PORT | yes | yes | DWORD(boolean) | This option should be set on an unbound socket. When SO_RANDOMIZE_PORT is set and an ephemeral port is selected on the socket, a random port number is bound. Auto-reuse ports (ports selected using SO_REUSE_UNICASTPORT) also randomize the returned port, so if an application sets SO_REUSE_UNICASTPORT and then attempts to set SO_RANDOMIZE_PORT, the second setsockopt call fails. |
| SO_RCVBUF | yes | yes | DWORD | The total per-socket buffer space reserved for receives. This is unrelated to SO_MAX_MSG_SIZE and does not necessarily correspond to the size of the TCP receive window. |
| SO_RCVLOWAT | yes | yes | DWORD | A socket option from BSD UNIX included for backward compatibility. This option sets the minimum number of bytes to process for socket input operations. This option is not supported by the Windows TCP/IP provider. If this option is used on Windows Vista and later, the getsockopt and setsockopt functions fail with WSAEINVAL. On earlier versions of Windows, these functions fail with WSAENOPROTOOPT. |
| SO_RCVTIMEO | yes | yes | DWORD | The timeout, in milliseconds, for blocking receive calls. The default for this option is zero, which indicates that a receive operation will not time out. If a blocking receive call times out, the connection is in an indeterminate state and should be closed. If the socket is created using the WSASocket function, then the dwFlags parameter must have the WSA_FLAG_OVERLAPPED attribute set for the timeout to function properly. Otherwise the timeout never takes effect. |
| SO_REUSEADDR | yes | yes | DWORD (boolean) | Allows a socket to bind to an address and port already in use. The SO_EXCLUSIVEADDRUSE option can prevent this. |
| SO_REUSE_UNICASTPORT | yes | yes | DWORD (boolean) | When set, allow ephemeral port reuse for Winsock API connection functions which require an explicit bind, such as ConnectEx. Note that connection functions with an implicit bind (such as connect without an explicit bind) have this option set by default. Use this option instead of SO_PORT_SCALABILITY on platforms where both are available. |
| SO_REUSE_MULTICASTPORT | yes | DWORD | When set on a socket, this option indicates that the socket will never be used to receive unicast packets, and consequently that its port can be shared with other multicast-only applications. Setting the value to 1 enables always sharing multicast traffic on the port. Setting the value to 0 (default) disables this behavior. | |
| SO_SNDBUF | yes | yes | DWORD | The total per-socket buffer space reserved for sends. This is unrelated to SO_MAX_MSG_SIZE and does not necessarily correspond to the size of a TCP send window. |
| SO_SNDLOWAT | yes | yes | DWORD | A socket option from BSD UNIX included for backward compatibility. This option sets the minimum number of bytes to process for socket output operations. This option is not supported by the Windows TCP/IP provider. If this option is used on Windows Vista and later, the getsockopt and setsockopt functions fail with WSAEINVAL. On earlier versions of Windows, these functions fail with WSAENOPROTOOPT. |
| SO_SNDTIMEO | yes | yes | DWORD | The timeout, in milliseconds, for blocking send calls. The default for this option is zero, which indicates that a send operation will not time out. If a blocking send call times out, the connection is in an indeterminate state and should be closed. If the socket is created using the WSASocket function, then the dwFlags parameter must have the WSA_FLAG_OVERLAPPED attribute set for the timeout to function properly. Otherwise the timeout never takes effect. |
| SO_TYPE | yes | DWORD | Returns the socket type for the given socket (SOCK_STREAM or SOCK_DGRAM, for example). | |
| SO_UPDATE_ACCEPT_CONTEXT | yes | DWORD (boolean) | This option is used with the AcceptEx function. This option updates the properties of the socket which are inherited from the listening socket. This option should be set if the getpeername, getsockname, getsockopt, or setsockopt functions are to be used on the accepted socket. | |
| SO_UPDATE_CONNECT_CONTEXT | yes | DWORD (boolean) | This option is used with the ConnectEx, WSAConnectByList, and WSAConnectByName functions. This option updates the properties of the socket after the connection is established. This option should be set if the getpeername, getsockname, getsockopt, setsockopt, or shutdown functions are to be used on the connected socket. | |
| SO_USELOOPBACK | yes | yes | DWORD (boolean) | Use the local loopback address when sending data from this socket. This option should only be used when all data sent will also be received locally. This option is not supported by the Windows TCP/IP provider. If this option is used on Windows Vista and later, the getsockopt and setsockopt functions fail with WSAEINVAL. On earlier versions of Windows, these functions fail with WSAENOPROTOOPT. |
Windows Support for SOL_SOCKET Options
| Option | Windows 10 | Windows 7 | Windows Server 2008 | Windows Vista | Windows Server 2003 | Windows XP | Windows 2000 | Windows NT4 | Windows 9x/ME |
|---|---|---|---|---|---|---|---|---|---|
| PVD_CONFIG | |||||||||
| SO_ACCEPTCONN | x | x | x | x | x | x | x | x | x |
| SO_BROADCAST | x | x | x | x | x | x | x | x | x |
| SO_BSP_STATE | x | x | x | x | |||||
| SO_CONDITIONAL_ACCEPT | x | x | x | x | x | x | x | ||
| SO_CONNDATA | x | x | x | x | x | x | x | x | |
| SO_CONNDATALEN | x | x | x | x | x | x | x | x | |
| SO_CONNECT_TIME | x | x | x | x | x | x | x | x | x |
| SO_CONNOPT | x | x | x | x | x | x | x | x | |
| SO_CONNOPTLEN | x | x | x | x | x | x | x | x | |
| SO_DISCDATA | x | x | x | x | x | x | x | x | |
| SO_DISCDATALEN | x | x | x | x | x | x | x | x | |
| SO_DISCOPT | x | x | x | x | x | x | x | x | |
| SO_DISCOPTLEN | x | x | x | x | x | x | x | x | |
| SO_DEBUG | x | x | x | x | x | x | x | x | x |
| SO_DONTLINGER | x | x | x | x | x | x | x | x | x |
| SO_DONTROUTE | x | x | x | x | x | x | x | x | x |
| SO_ERROR | x | x | x | x | x | x | x | x | x |
| SO_EXCLUSIVEADDRUSE | x | x | x | x | x | x | x | x SP4+ | |
| SO_GROUP_ID | x | x | x | x | |||||
| SO_GROUP_PRIORITY | x | x | x | x | |||||
| SO_KEEPALIVE | x | x | x | x | x | x | x | x | x |
| SO_LINGER | x | x | x | x | x | x | x | x | x |
| SO_MAX_MSG_SIZE | x | x | x | x | x | x | x | x | x |
| SO_MAXDG | x | x | x | x | x | x | x | ||
| SO_MAXPATHDG | x | x | x | x | x | x | x | ||
| SO_OOBINLINE | x | x | x | x | x | x | x | x | x |
| SO_OPENTYPE | x | x | x | x | x | x | x | x | x |
| SO_PORT_SCALABILITY | x | x | x | ||||||
| SO_PROTECT | x | ||||||||
| SO_PROTOCOL_INFO | x | x | x | x | x | x | x | x | x |
| SO_PROTOCOL_INFOA | x | x | x | x | x | x | x | x | x |
| SO_PROTOCOL_INFOW | x | x | x | x | x | x | x | x | x |
| SO_RCVBUF | x | x | x | x | x | x | x | x | x |
| SO_RCVLOWAT | |||||||||
| SO_RCVTIMEO | x | x | x | x | x | x | x | x | x |
| SO_RANDOMIZE_PORT | x | x | x | x | |||||
| SO_REUSEADDR | x | x | x | x | x | x | x | x | x |
| SO_REUSE_UNICASTPORT | x | ||||||||
| SO_REUSE_MULTICASTPORT | x | ||||||||
| SO_SNDBUF | x | x | x | x | x | x | x | x | x |
| SO_SNDLOWAT | |||||||||
| SO_SNDTIMEO | x | x | x | x | x | x | x | x | x |
| SO_TYPE | x | x | x | x | x | x | x | x | x |
| SO_UPDATE_ACCEPT_CONTEXT | x | x | x | x | x | x | x | x | |
| SO_UPDATE_CONNECT_CONTEXT | x | x | x | x | x | x | |||
| SO_USELOOPBACK |
Remarks
The SOL_SOCKET socket options are defined in several Winsock header files:
- Winsock2.h
- Mswsock.h
- Ws2def.h
On the Microsoft Windows Software Development Kit (SDK) released for Windows Vista and later, the organization of header files has changed and SOL_SOCKET level is defined in the Ws2def.h header file which is automatically included in the Winsock2.h header file. Some of the SOL_SOCKET socket options are defined in the Winsock2.h and Mswsock.h header files. The remaining SOL_SOCKET socket options are defined in the Ws2def.h header file which is automatically included by the Winsock2.h header file. The Ws2def.h should never be used directly.
On the Platform Software Development Kit (SDK) released for Windows Server 2003 and Windows XP, the SOL_SOCKET level is defined in the Winsock2.h header file. The SOL_SOCKET socket options are defined in the Winsock2.h and Mswsock.h header files.
Requirements
| Requirement | Value |
|---|---|
| Header |
|
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for