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 annex for more 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
getsockopt 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
struct linger; 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 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 may 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 specification.
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 is a get-only socket option which indicates the identifier of the group
this socket belongs to. Note that socket group IDs are unique across all
processes for a give service provider. If this socket is not a group socket, the value
is NULL.
SO_GROUP_PRIORITY
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 which 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
struct linger (pointed to by the
optval argument) with the following elements:
struct linger {
u_short l_onoff;
u_short l_linger;
}
SO_MAX_MSG_SIZE
This is a get-only socket option which indicates the maximum 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
SO_PROTOCOL_INFO
This is a get-only option which supplies the WSAPROTOCOL_INFO structure
associated with this socket. See WSAEnumProtocols for more information about this
structure.
SO_RCVBUF
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, although 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 which is already in use. On occasion, however, it may be
necessary to "re-use" an address in this way. Since 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
which 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 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 by essentially buffering send
data if there is unacknowledged data already "in flight" or until a full-size
packet can be sent. It is highly recommended that Windows Sockets implementations
enable the Nagle Algorithm by default, and 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, which need to be received by the peer with the
time delays between the messages maintained.
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 arguments is not a valid part of the user address space, or the optlen argument 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
| level is unknown or invalid
|
WSAENOPROTOOPT
| The option is unknown or unsupported by the indicated protocol family.
|
WSAENOTSOCK
| The descriptor is not a socket.
|
See Also
setsockopt,
socket,
WSAAsyncSelect,
WSAConnect,
WSAGetLastError,
WSASetLastError
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database
