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_CONNDATALENyesULONGThe 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_TIMEyesULONGReturns 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_CONNOPTLENyesULONGThe 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_DISCDATALENyesULONGThe 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_DISCOPTLENyesULONGThe 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_SIZEyesULONGReturns the maximum outbound message size for message-oriented sockets supported by the protocol. Has no meaning for stream-oriented sockets.
SO_MAXDGyesULONGReturns the maximum size, in bytes, for outbound datagrams supported by the protocol. This socket option has no meaning for stream-oriented sockets.
SO_MAXPATHDGyesULONGReturns 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_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. 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_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 socket to bind to an address and port already in use. The SO_EXCLUSIVEADDRUSE option can prevent this. Also, if two sockets are bound to the same port the behavior is undefined as to which port will receive packets.
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 7Windows Server 2008Windows VistaWindows Server 2003Windows XPWindows 2000Windows NT4Windows 9x/ME
PVD_CONFIG
SO_ACCEPTCONNxxxxxxxx
SO_BROADCASTxxxxxxxx
SO_BSP_STATE xxx
SO_CONDITIONAL_ACCEPTxxxxxx
SO_CONNDATAxxxxxxx
SO_CONNDATALENxxxxxxx
SO_CONNECT_TIMExxxxxxxx
SO_CONNOPTxxxxxxx
SO_CONNOPTLENxxxxxxx
SO_DISCDATAxxxxxxx
SO_DISCDATALENxxxxxxx
SO_DISCOPTxxxxxxx
SO_DISCOPTLENxxxxxxx
SO_DEBUGxxxxxxxx
SO_DONTLINGERxxxxxxxx
SO_DONTROUTExxxxxxxx
SO_ERRORxxxxxxxx
SO_EXCLUSIVEADDRUSE xxxxxxx SP4+
SO_GROUP_IDxxx
SO_GROUP_PRIORITYxxx
SO_KEEPALIVExxxxxxxx
SO_LINGERxxxxxxxx
SO_MAX_MSG_SIZExxxxxxxx
SO_MAXDGxxxxxx
SO_MAXPATHDGxxxxxx
SO_OOBINLINExxxxxxxx
SO_OPENTYPExxxxxxxx
SO_PORT_SCALABILITYxx
SO_PROTECTxxxxx SP2
SO_PROTOCOL_INFOxxxxxxxx
SO_PROTOCOL_INFOAxxxxxxxx
SO_PROTOCOL_INFOWxxxxxxxx
SO_RCVBUFxxxxxxxx
SO_RCVLOWAT
SO_RCVTIMEOxxxxxxxx
SO_REUSEADDRxxxxxxxx
SO_SNDBUFxxxxxxxx
SO_SNDLOWAT
SO_SNDTIMEOxxxxxxxx
SO_TYPExxxxxxxx
SO_UPDATE_ACCEPT_CONTEXTxxxxxxx
SO_UPDATE_CONNECT_CONTEXTxxxxx
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:
© 2014 Microsoft