setsockopt
The Windows Sockets
setsockopt function sets a socket option.
int setsockopt (
SOCKET s,
|
|
int level,
|
|
int optname,
|
|
const char FAR * optval,
|
|
int 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 set.
optval
[in] A pointer to the buffer in which the value for the requested option is
supplied.
optlen
[in] The size of the
optval buffer.
Remarks
setsockopt sets the current value for a socket option associated with a socket of any
type, in any state. Although options can exist at multiple protocol levels, they
are always present at the uppermost "socket'' level. Options affect socket
operations, such as whether expedited data is received in the normal data stream,
whether broadcast messages can be sent on the socket.
There are two types of socket options: Boolean options that enable or disable
a feature or behavior, and options which require an integer value or structure.
To enable a Boolean option,
optval points to a nonzero integer. To disable the option
optval points to an integer equal to zero.
optlen should be equal to sizeof(int) for Boolean options. For other options,
optval points to the an integer or structure that contains the desired value for the
option, and
optlen is the length of the integer or structure.
The following options are supported for
setsockopt. The Type identifies the type of data addressed by
optval.
level = SOL_SOCKET
Value
| Type
| Meaning
|
SO_BROADCAST
| BOOL
| Allow transmission of broadcast messages on the socket.
|
SO_DEBUG
| BOOL
| Record debugging information.
|
SO_DONTLINGER
| BOOL
| Do not block close waiting for unsent data to be sent. Setting this option is
equivalent to setting SO_LINGER with l_onoff set to zero.
|
SO_DONTROUTE
| BOOL
| Do not route: send directly to interface.
|
SO_GROUP_PRIORITY
| int
| Specify the relative priority to be established for sockets that are part of a
socket group.
|
SO_KEEPALIVE
| BOOL
| Send keepalives
|
SO_LINGER
| struct linger
| Linger on close if unsent data is present
|
SO_OOBINLINE
| BOOL
| Receive out-of-band data in the normal data stream. (See section Out-Of-Band data for a discussion of this topic.)
|
SO_RCVBUF
| int
| Specify buffer size for receives
|
SO_REUSEADDR
| BOOL
| Allow the socket to be bound to an address which is already in use. (See bind.)
|
SO_SNDBUF
| int
| Specify buffer size for sends.
|
PVD_CONFIG
| Service Provider Dependent
| This object stores the configuration information for the service provider
associated with socket s. The exact format of this data structure is service provider specific.
|
level = IPPROTO_TCP1
TCP_NODELAY
| BOOL
| Disables the Nagle algorithm for send coalescing.
|
- included for backward compatibility with Windows Sockets 1.1
|
|
|
BSD options not supported for
setsockopt are:
Value
| Type
| Meaning
|
SO_ACCEPTCONN
| BOOL
| Socket is listening
|
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
|
SO_TYPE
| int
| Type of the socket
|
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_GROUP_PRIORITY
Group priority indicates the relative 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 is indicated for nongroup sockets or for service
providers which do not support group sockets.
SO_KEEPALIVE
An application can request that a TCP/IP 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-alives: 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
sets the desired behavior by creating a
struct linger (pointed to by the
optval argument) with the following elements:
struct linger {
u_short l_onoff;
u_short l_linger;
}
To enable SO_LINGER, the application should set
l_onoff to a nonzero value, set
l_linger to zero or the desired time-out (in seconds), and call
setsockopt. To enable SO_DONTLINGER (that is, disable SO_LINGER)
l_onoff should be set to zero and
setsockopt should be called. Note that enabling SO_LINGER with a nonzero time-out on a
nonblocking socket is not recommended.
Enabling SO_LINGER also disables SO_DONTLINGER, and vice versa. Note that if
SO_DONTLINGER is DISABLED (that is, SO_LINGER is ENABLED) then no time-out value
is specified. In this case, the time-out used is implementation dependent. If
a previous time-out has been established for a socket (by enabling SO_LINGER),
then this time-out value should be reinstated by the service provider.
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.
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
getsockopt with the same option to check the buffer size actually provided.
PVD_CONFIG
This object stores the configuration information for the service provider
associated with socket
s. The exact format of this data structure is service provider specific.
TCP_NODELAY
The TCP_NODELAY option is specific to TCP/IP service providers. Enabling the
TCP_NODELAY option disables the TCP Nagle Algorithm (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 TCP/IP service providers 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 TCP_NODELAY 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. Application writers should not set TCP_NODELAY unless the impact of doing so
is well-understood and desired, since setting TCP_NODELAY can have a
significant negative impact of network and application performance.
Return Values
If no error occurs,
setsockopt 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
| optval is not in a valid part of the process address space or 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 not valid, or the information in optval is not valid.
|
WSAENETRESET
| Connection has timed out when SO_KEEPALIVE is set.
|
WSAENOPROTOOPT
| The option is unknown or unsupported for the specified provider.
|
WSAENOTCONN
| Connection has been reset when SO_KEEPALIVE is set.
|
WSAENOTSOCK
| The descriptor is not a socket.
|
See Also
bind,
getsockopt,
ioctlsocket,
socket,
WSAAsyncSelect,
WSAEventSelect
- 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
