SOL_SOCKET
A version of this page is also available for
4/8/2010
The following table describes SOL_SOCKET Socket Options. See getsockopt and setsockopt for more information on getting and setting socket options. To enumerate protocols and discover supported properties for each installed protocol, use the WSAEnumProtocols function.
Some socket options require more explanation than these tables can convey; such options contain links to additional pages.
Note
All SO_* socket options apply equally to IPv4 and IPv6 (except SO_BROADCAST, since broadcast is not implemented in IPv6).
SOL_SOCKET
| Option | get/set | Optval Type | Description |
|---|---|---|---|
PVD_CONFIG |
both |
char [] |
The default is implementation dependent. This option retrieves an opaque data structure object from the service provider associated with socket s. This object stores the configured settings of the service provider. The exact format of this data structure is service provider specific. |
SO_ACCEPTCONN |
get |
BOOL |
The default is FALSE unless a WSPListen has been performed. This option indicates whether a socket is in listening mode. The socket listens through through WSPListen. Valid for connection oriented protocols only. |
SO_BROADCAST |
both |
BOOL |
The default is FALSE. This option allows transmission of broadcast messages on the socket. Valid only for protocols that support broadcasting (IPX, UDP/IPv4, and others). |
SO_CONDITIONAL_ACCEPT |
both |
BOOL |
By default, ATM sets this option to TRUE. This option indicates incoming connections will be accepted or rejected by the application and not the stack Setting the SO_CONDITIONAL_ACCEPT socket option to TRUE delays the acknowledgment of a connection until after the WSAAccept condition function is called. If FALSE, the connection may be accepted before the condition function is called, but the connection will be disconnected if the condition function rejects the call. This option must be set before calling the listen function, otherwise WSAEINVAL is returned. SO_CONDITIONAL_ACCEPT is only supported for TCP and ATM. TCP sets SO_CONDITIONAL_ACCEPT to FALSE by default, and therefore by default the connection will be accepted before WSAAccept is called. When set to TRUE, the conditional decision must be made within the TCP connection time-out. CF_DEFER connections are still subject to the time-out. |
SO_DEBUG |
both |
BOOL |
The default is FALSE. Windows Sockets service providers are encouraged, but not required, to supply output debug information if the SO_DEBUG option is set by an application or a Windows Sockets SPI client. The mechanism for generating the debug information and the form it takes are beyond the scope of this document. |
SO_DONTLINGER |
both |
BOOL |
The default is TRUE. This option indicates whether a linger value was set on a socket. If TRUE, the SO_LINGER option is disabled. Valid for reliable, connection oriented protocols only. |
SO_DONTROUTE |
both |
BOOL |
The default is FALSE. This option indicates that routing is disabled, and outgoing data should be sent on whatever interface the socket and bound to. Valid for message oriented protocols only. Microsoft providers silently ignore this option and always consult the routing table to find appropriate outgoing interface. |
SO_ERROR |
get |
int |
The default is zero (0). This option returns and resets the per socket–based error code. This is different from the per thread based–error code that is handled by using the WSAGetLastError and WSASetLastError function calls. A successful call that uses the socket does not reset the socket-based error code returned by the SO_ERROR option. |
SO_GROUP_ID |
get |
NULL |
Reserved. Do not use. This option is exclusive to getsockopt and the value should be NULL. |
SO_GROUP_PRIORITY |
get |
int |
Reserved. Do not use. The default is zero (0) |
SO_KEEPALIVE |
both |
BOOL |
The default is FALSE. An application or the Windows Sockets SPI client can request that a TCP/IP service provider enable the use of keep-alive packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets provider need not support the use of keep-alive packets. If it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: Requirements for Internet Hosts — Communication Layers. If a connection is dropped as the result of keep-alive packets, the error code WSAENETRESET is returned to any calls in progress on the socket and any subsequent calls will fail with WSAENOTCONN. SO_KEEPALIVE is not supported on ATM sockets, and requests to enable the use of keep-alive packets on an ATM socket results in an error being returned by the socket. |
SO_LINGER |
both |
linger structure |
The default is 1 (ON). This option controls the action taken when unsent data is queued on a socket and a closesocket or WSPCloseSocket is performed. See closesocket or WSPCloseSocketfor a description of the way in which the SO_LINGER settings affect the semantics of closesocket. The application or Windows Sockets SPI client gets the current behavior by retrieving a linger structure (pointed to by the optval parameter) with the l_onoff and l_linger members set appropriately. |
SO_MAX_MSG_SIZE |
get |
DWORD |
The default is implementation dependent. This is a get-only socket option that indicates the maximum outbound (send) size of a message for message-oriented socket types (for example, SOCK_DGRAM) as implemented by a particular service provider. It has no description for byte stream oriented sockets. There is no provision to find out the maximum inbound–message size. |
SO_OOBINLINE |
both |
BOOL |
The default is FALSE. This option indicates OOB data should be returned in-line with regular data. Valid for connection oriented protocols which support out-of-band data. |
SO_PROTOCOL_INFO |
get |
WSAPROTOCOL_INFO structure |
The default is Protocol dependent. This option provides protocol information for the protocol that is bound to this socket. Socket owners can use this option to determine the provider that created the socket. This option supplies the WSAPROTOCOL_INFO structure associated with this socket. See WSAEnumProtocols for more information about this structure. |
SO_PROTOCOL_INFOW |
get |
WSAPROTOCOL_INFOW |
Supplies the WSAPROTOCOL_INFO structure associated with this socket. See WSCEnumProtocols for more information about this structure. |
SO_RCVBUF |
both |
int |
The default is implementation dependent. The Windows Embedded CE TCP/UDP provider uses 32768 bytes as default. The receive buffer can be set to a maximum of 1 MB. This option specifies the total per-socket buffer space reserved for receives. When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, an application can request different buffer sizes (larger or smaller) by calling setsockopt. The call to setsockopt can succeed even when the implementation did not provide the whole amount requested. An application must call getsockopt (Windows Sockets) with the same option to check the buffer size actually provided. |
SO_REUSEADDR |
both |
BOOL |
The default is FALSE. Allows the socket to be bound to an address that is already in use. (See the bind or WSPBind functions.) By default, a socket cannot be bound to a local address that is already in use. On occasion, however, it can be necessary to reuse an address. Because every connection is uniquely identified by the combination of local and remote addresses, two sockets can be bound to the same local address as long as the remote addresses are different. SO_REUSEADDR is interpreted only at the time of the bind or WSPBind. To inform the Windows Sockets provider that a bind or WSPBind on a socket should not be disallowed because an address is already in use, the application or Windows Sockets SPI client should set SO_REUSEADDR before issuing the bind or WSPBind. REUSEADDR is not applicable for ATM sockets, and although requests to reuse and address do not result in an error, they have no affect on when an ATM socket is in use. |
SO_SNDBUF |
both |
int |
The default is implementation dependent. This option sets the per-socket buffer size for sending data. When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, an application or Windows Sockets SPI client can request different buffer sizes (larger or smaller). The call to setsockopt or WSPSetSockOpt can succeed even if the implementation did not provide the whole amount requested. This is unrelated to SO_MAX_MSG_SIZE or the size of a TCP window. Care should be taken when setting the SO_SNDBUF value as setting this value either too high or too low can have a negative effect on performance. An application must call this function with the same option to check the buffer size actually provided. A value of 0 is not supported. |
SO_TYPE |
get |
int |
The default is the socket type that was created with socket. This option returns the socket type for the given socket (e.g. SOCK_STREAM, SOCK_DGRAM, etc.) |