getsockopt

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function retrieves a socket option.

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

Parameters

s

[in] Descriptor that identifies a socket.

level

[in] Level at which the option is defined; the supported levels include SOL_SOCKET, IPPROTO_TCP, and IPPROTO_IP.

optname

[in] Socket option for which the value is to be retrieved.

optval

[out] Pointer to the buffer in which the value for the requested option is to be returned.

optlen

[in/out] Pointer to the optvalbuffer size.

Return Values

Zero indicates no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Windows CE Remarks

For IrSockets implementation:

The Af_irda.h file must be included.

The WSAENETDOWN return value is not supported.

IrSockets supports several special socket options:

Value	Type	Description
IRLMP_ENUMDEVICES	* DEVICELIST	Describes devices in range.
IRLMP_IAS_QUERY	* IAS_QUERY	Retrieve IAS attributes.
IRLMP_SEND_PDU_LEN	* int	Retrieves the maximum 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 data is sent.

The DEVICELISTstructure 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 optlenresult parameter the required size if the buffer is of insufficient size. The device description consists of a device identifier necessary to form a sockaddr_irdastructure and a displayable string describing the device.

The IAS_QUERYstructure 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 meaningless to IrSockets. Only SO_LINGER and SO_DONTLINGER are specifically supported.

Remarks

The getsockoptfunction 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 optlenshould 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 LINGERstructure. For most other options, it will be the size of an integer.

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

If the option was never set with setsockopt, then getsockoptreturns 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	Description
SO_ACCEPTCONN	BOOL	Socket is listening.
SO_BROADCAST	BOOL	Socket is configured for the transmission of broadcast messages.
SO_DONTLINGER	BOOL	If TRUE, the SO_LINGER option is disabled.
SO_KEEPALIVE	BOOL	Keepalives are being sent.
SO_LINGER	struct LINGER	Returns the current linger options.
SO_OOBINLINE	BOOL	Out-of-band data is being received in the normal data stream.
SO_REUSEADDR	BOOL	The socket can be bound to an address which is already in use.
SO_TYPE	int	The socket type (for example, SOCK_STREAM).

level= IPPROTO_TCP

Value	Type	Description
TCP_NODELAY	BOOL	Disables the Nagle algorithm for send coalescing.

level= IPPROTO_IP

Value	Description
IP_MULTICAST_TTL	Time to Live for a multicast packet. Retrieves the number of hops for which a multicast message survives before it is discarded. Use intfor optval.
IP_MULTICAST_IF	Address of the outgoing multicast-capable interface. This address is used for subsequent multicasts. Use unsigned longfor optval.
IP_MULTICAST_LOOP	Status of the socket's loop behavior during multicast. Use unsigned longfor optval. For Windows CE, this value is always 0 and is not configurable.

BSD options not supported for getsockoptare as follows.

Value	Type	Description
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 getsockoptwith an unsupported option will result in an error value of WSAENOPROTOOPT being returned by WSAGetLastError.

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_KEEPALIVEsocket 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 Host-Communication Layers. If a connection is dropped as the result of keep-alives, the error value WSAENETRESET is returned to calls in progress on the socket, and subsequent calls will fail with WSAENOTCONN.

SO_LINGER

SO_LINGER controls the action taken when unsent data is queued on a socket and a closesocketis performed. See closesocketfor 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 LINGERstructure (pointed to by the optvalparameter).

SO_REUSEADDR

By default, a socket cannot be bound (see bind) to a local address 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 bindon a socket should not be rejected because the desired address is already in use by another socket, the application should set the SO_REUSEADDRsocket option for the socket before issuing the bind. 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 bindhas no effect on this or any other socket.

TCP_NODELAY

The TCP_NODELAYoption is specific to TCP/IP service providers. The Nagle algorithm is disabled if the TCP_NODELAYoption is enabled, and vice versa. The Nagle algorithm, as 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 route 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 majority of application protocols, the Nagle Algorithm can deliver significant performance enhancements. However, for some applications this algorithm can impede performance, and setsockoptwith 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.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	1.0 and later	Winsock.h

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

setsockopt, socket, WSAStartup