getsockopt

The Windows Sockets getsockopt function retrieves a socket option.

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

Parameters

s: [in] A descriptor identifying a socket.
level: [in] The level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP. See the Windows Sockets 2 Protocol-Specific Annex (a separate document included with the Platform SDK) for more information on protocol-specific levels.
optname: [in] The socket option for which the value is to be retrieved.
optval: [out] A pointer to the buffer in which the value for the requested option is to be returned.
optlen: [in/out] A pointer to the size of the optval buffer.

Remarks

The getsockopt function retrieves the current value for a socket option associated with a socket of any type, in any state, and stores the result in optval. Options can exist at multiple protocol levels, but they are always present at the uppermost "socket'' level. Options affect socket operations, such as the packet routing and out-of-band data transfer.

The value associated with the selected option is returned in the buffer optval. The integer pointed to by optlen should originally contain the size of this buffer; on return, it will be set to the size of the value returned. For SO_LINGER, this will be the size of a LINGER structure. For most other options, it will be the size of an integer.

The application is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specified.

If the option was never set with setsockopt, then getsockopt returns the default value for the option.

The following options are supported for getsockopt. The Type column identifies the type of data addressed by optval.

level = SOL_SOCKET

Value	Type	Meaning
SO_ACCEPTCONN	BOOL	Socket is listening.
SO_BROADCAST	BOOL	Socket is configured for the transmission of broadcast messages.
SO_DEBUG	BOOL	Debugging is enabled.
SO_DONTLINGER	BOOL	If true, the SO_LINGER option is disabled.
SO_DONTROUTE	BOOL	Routing is disabled.
SO_ERROR	int	Retrieve error status and clear.
SO_GROUP_ID	GROUP	The identifier of the group to which this socket belongs.
SO_GROUP_PRIORITY	int	The relative priority for sockets that are part of a socket group.
SO_KEEPALIVE	BOOL	Keepalives are being sent.
SO_LINGER	struct LINGER	Returns the current linger options.
SO_MAX_MSG_SIZE	unsigned int	Maximum size of a message for message-oriented socket types (for example, SOCK_DGRAM). Has no meaning for stream oriented sockets.
SO_OOBINLINE	BOOL	Out-of-band data is being received in the normal data stream. (See section Windows Sockets 1.1 Blocking Routines & EINPROGRESS for a discussion of this topic.)
SO_PROTOCOL_INFO	WSAPROTOCOL_INFO	Description of protocol info for protocol that is bound to this socket.
SO_RCVBUF	int	Buffer size for receives
SO_REUSEADDR	BOOL	The socket can be bound to an address which is already in use.
SO_SNDBUF	int	Buffer size for sends
SO_TYPE	int	The type of the socket (for example, SOCK_STREAM).
PVD_CONFIG	Service Provider Dependent	An "opaque" data structure object from the service provider associated with socket s. This object stores the current configuration information of the service provider. The exact format of this data structure is service provider specific.

level = IPPROTO_TCP

TCP_NODELAY

BOOL

Disables the Nagle algorithm for send coalescing.

BSD options not supported for getsockopt are:

Value	Type	Meaning
SO_RCVLOWAT	int	Receive low water mark
SO_RCVTIMEO	int	Receive time-out
SO_SNDLOWAT	int	Send low water mark
SO_SNDTIMEO	int	Send time-out
TCP_MAXSEG	int	Get TCP maximum segment size

Calling getsockopt with an unsupported option will result in an error code of WSAENOPROTOOPT being returned from WSAGetLastError.

SO_DEBUG: Windows Sockets service providers are encouraged (but not required) to supply output debug information if the SO_DEBUG option is set by an application. The mechanism for generating the debug information and the form it takes are beyond the scope of this document.
SO_ERROR: The SO_ERROR option returns and resets the per-socket based error code, which is different from the per-thread based error code that is handled using the WSAGetLastError and WSASetLastError function calls. A successful call using the socket does not reset the socket based error code returned by the SO_ERROR option.
SO_GROUP_ID: This option is reserved for future use with socket groups. This option is also exclusive to getsockopt. It indicates the identifier of the group to which this socket belongs. Socket group IDs are unique across all processes for a given service provider. If this socket is not a group socket, the value is NULL.
SO_GROUP_PRIORITY: This option is reserved for future use with socket groups. Group priority indicates the priority of the specified socket relative to other sockets within the socket group. Values are non-negative integers, with zero corresponding to the highest priority. Priority values represent a hint to the underlying service provider about how potentially scarce resources should be allocated. For example, whenever two or more sockets are both ready to transmit data, the highest priority socket (lowest value for SO_GROUP_PRIORITY) should be serviced first, with the remainder serviced in turn according to their relative priorities.
The WSAENOPROTOOPT error code is indicated for non group sockets or for service providers that do not support group sockets.
SO_KEEPALIVE: An application 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: 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-alives" the error code WSAENETRESET is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN.
SO_LINGER: SO_LINGER controls the action taken when unsent data is queued on a socket and a closesocket is performed. See closesocket for a description of the way in which the SO_LINGER settings affect the semantics of closesocket. The application gets the current behavior by retrieving a LINGER structure (pointed to by the optval parameter).
SO_MAX_MSG_SIZE: 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 meaning for byte stream oriented sockets. There is no provision to find out the maximum inbound message size
SO_PROTOCOL_INFO: This is a get-only option that supplies the WSAPROTOCOL_INFO structure associated with this socket. See WSAEnumProtocols for more information about this structure.
SO_SNDBUF: When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, an application can request different buffer sizes (larger or smaller). The call to setsockopt can succeed even if the implementation did not provide the whole amount requested. An application must call this function with the same option to check the buffer size actually provided.
SO_REUSEADDR: By default, a socket cannot be bound (see bind) to a local address that is already in use. On occasion, however, it can be necessary to "re-use" an address in this way. Because every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same local address as long as the remote addresses are different. To inform the Windows Sockets provider that a bind on a socket should not be disallowed because the desired address is already in use by another socket, the application should set the SO_REUSEADDR socket option for the socket before issuing the bind. Note that the option is interpreted only at the time of the bind: it is therefore unnecessary (but harmless) to set the option on a socket that is not to be bound to an existing address, and setting or resetting the option after the bind has no effect on this or any other socket.
PVD_CONFIG: This option retrieves an "opaque" data structure object from the service provider associated with socket s. This object stores the current configuration information of the service provider. The exact format of this data structure is service provider specific.
TCP_NODELAY: The TCP_NODELAY option is specific to TCP/IP service providers. The Nagle algorithm is disabled if the TCP_NODELAY option is enabled (and vice versa). The Nagle algorithm (described in RFC 896) is very effective in reducing the number of small packets sent by a host. The process involves buffering send data when there is unacknowledged data already "in flight" or buffering send data until a full-size packet can be sent. It is highly recommended that Windows Sockets implementations enable the Nagle Algorithm by default because,for the vast majority of application protocols, the Nagle Algorithm can deliver significant performance enhancements. However, for some applications this algorithm can impede performance, and setsockopt with the same option can be used to turn it off. These are applications where many small messages are sent, and the time delays between the messages are maintained.

Windows CE: For IrSockets implementation:

The Af_irda.h file must be explicitly included.
The WSAENETDOWN return value is not supported.

IrSockets supports several special socket options:

Value	Type	Meaning
IRLMP_ENUMDEVICES	* DEVICELIST	Describes devices in range.
IRLMP_IAS_QUERY	* IAS_QUERY	Retrieve IAS attributes.
IRLMP_SEND_PDU_LEN	* int	Retrieves max number of bytes that can be sent in any one send() call while in IRLMP_IRLPT_MODE (printing). This value should be retrieved after the connect() completes but before any data is sent.

The DEVICELIST structure is an extendible array of device descriptions. IrSockets fills in as many device descriptions as can fit in the supplied buffer and returns in the optlen result parameter the required size if the buffer is of insufficient size. The device description consists of a device identifier necessary to form a sockaddr_irda structure and a displayable string describing the device.

The IAS_QUERY structure is used to retrieve a single attribute of a single class. The application specifies the device and class to query and the attribute and attribute type. It is expected that the application allocates a buffer of the necessary size for the returned parameters.

Many SO level socket options are not meaningful to IrSockets. Only SO_LINGER and SO_DONTLINGER are specifically supported.

Return Values

If no error occurs, getsockopt returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	One of the optval or the optlen parameters is not a valid part of the user address space, or the optlen parameter is too small.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The level parameter is unknown or invalid.
WSAENOPROTOOPT	The option is unknown or unsupported by the indicated protocol family.
WSAENOTSOCK	The descriptor is not a socket.

QuickInfo