Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

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
OptionGetSetOptval typeDescription
PVD_CONFIGyesyeschar []An opaque data structure object containing configuration information for the service provider. This option is implementation dependent.
SO_ACCEPTCONNyesDWORD (boolean)Returns whether a socket is in listening mode. This option is only Valid for connection-oriented protocols.
SO_BROADCASTyesyesDWORD (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 yesyesDWORD (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_CONNDATAyesyeschar []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_CONNDATALENyesDWORDThe 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_TIMEyesDWORDReturns the number of seconds a socket has been connected. This option is only valid for connection-oriented protocols.
SO_CONNOPTyesyeschar []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_CONNOPTLENyesDWORDThe 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_DISCDATAyesyeschar []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_DISCDATALENyesDWORDThe 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_DISCOPTyesyeschar []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_DISCOPTLENyesDWORDThe 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_DEBUGyesyesDWORD (boolean)Enable debug output. Microsoft providers currently do not output any debug information.
SO_DONTLINGERyesyesDWORD (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_DONTROUTEyesyesDWORD (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_ERRORyesDWORDReturns the last error code on this socket. This per-socket error code is not always immediately set.
SO_EXCLUSIVEADDRUSE yesyesDWORD (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_IDyesunsigned intThis socket option is reserved and should not be used.
SO_GROUP_PRIORITYyesyesintThis socket option is reserved and should not be used.
SO_KEEPALIVE yesyesDWORD (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_LINGERyesyesstruct lingerIndicates 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_SIZEyesDWORDReturns the maximum outbound message size for message-oriented sockets supported by the protocol. Has no meaning for stream-oriented sockets.
SO_MAXDGyesDWORDReturns the maximum size, in bytes, for outbound datagrams supported by the protocol. This socket option has no meaning for stream-oriented sockets.
SO_MAXPATHDGyesDWORDReturns 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_OOBINLINEyesyesDWORD (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_OPENTYPEyesyesDWORDOnce 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_ACCEPTyesyesDWORD(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 yesyesDWORD (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_INFOyes 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_INFOAyes WSAPROTOCOL_INFOA Returns the WSAPROTOCOL_INFOA structure for the given socket
SO_PROTOCOL_INFOWyes WSAPROTOCOL_INFOW Returns the WSAPROTOCOL_INFOW structure for the given socket
SO_RANDOMIZE_PORTyesyesuint16This 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_RCVBUFyesyesDWORDThe 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_RCVLOWATyesyesDWORDA 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_RCVTIMEOyesyesDWORD

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_REUSEADDRyesyesDWORD (boolean)Allows a socket to bind to an address and port already in use. The SO_EXCLUSIVEADDRUSE option can prevent this.
SO_REUSE_UNICASTPORT yesyesDWORD (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_MULTICASTPORTyesDWORDWhen 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_SNDBUFyesyesDWORDThe 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_SNDLOWATyesyesDWORDA 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_SNDTIMEOyesyesDWORD

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_TYPEyesDWORDReturns the socket type for the given socket (SOCK_STREAM or SOCK_DGRAM, for example).
SO_UPDATE_ACCEPT_CONTEXTyesDWORD (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_CONTEXTyesDWORD (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_USELOOPBACKyesyesDWORD (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
OptionWindows 10Windows 7Windows Server 2008Windows VistaWindows Server 2003Windows XPWindows 2000Windows NT4Windows 9x/ME
PVD_CONFIG
SO_ACCEPTCONNxxxxxxxxx
SO_BROADCASTxxxxxxxxx
SO_BSP_STATE xxxx
SO_CONDITIONAL_ACCEPTxxxxxxx
SO_CONNDATAxxxxxxxx
SO_CONNDATALENxxxxxxxx
SO_CONNECT_TIMExxxxxxxxx
SO_CONNOPTxxxxxxxx
SO_CONNOPTLENxxxxxxxx
SO_DISCDATAxxxxxxxx
SO_DISCDATALENxxxxxxxx
SO_DISCOPTxxxxxxxx
SO_DISCOPTLENxxxxxxxx
SO_DEBUGxxxxxxxxx
SO_DONTLINGERxxxxxxxxx
SO_DONTROUTExxxxxxxxx
SO_ERRORxxxxxxxxx
SO_EXCLUSIVEADDRUSE xxxxxxxx SP4+
SO_GROUP_IDxxxx
SO_GROUP_PRIORITYxxxx
SO_KEEPALIVExxxxxxxxx
SO_LINGERxxxxxxxxx
SO_MAX_MSG_SIZExxxxxxxxx
SO_MAXDGxxxxxxx
SO_MAXPATHDGxxxxxxx
SO_OOBINLINExxxxxxxxx
SO_OPENTYPExxxxxxxxx
SO_PORT_SCALABILITYxxx
SO_PROTECTx
SO_PROTOCOL_INFOxxxxxxxxx
SO_PROTOCOL_INFOAxxxxxxxxx
SO_PROTOCOL_INFOWxxxxxxxxx
SO_RCVBUFxxxxxxxxx
SO_RCVLOWAT
SO_RCVTIMEOxxxxxxxxx
SO_RANDOMIZE_PORTxxxx
SO_REUSEADDRxxxxxxxxx
SO_REUSE_UNICASTPORTx
SO_REUSE_MULTICASTPORTx
SO_SNDBUFxxxxxxxxx
SO_SNDLOWAT
SO_SNDTIMEOxxxxxxxxx
SO_TYPExxxxxxxxx
SO_UPDATE_ACCEPT_CONTEXTxxxxxxxx
SO_UPDATE_CONNECT_CONTEXTxxxxxx
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

Header

Winsock2.h;
Mswsock.h;
Ws2def.h (include Winsock2.h)

 

 

Community Additions

ADD
Show:
© 2015 Microsoft