Windows Sockets

An Open Interface for Network Programming under Microsoft Windows

Version 1.1

20 January 1993

Table of Contents


4. SOCKET LIBRARY REFERENCE

4.1 Socket Routines

This chapter presents the socket library routines in alphabetical order, and describes each routine in detail.

In each routine it is indicated that the header file winsock.h must be included. Appendix A.2 lists the Berkeley-compatible header files which are supported. These are provided for compatibility purposes only, and each of them will simply include winsock.h. The Windows header file windows.h is also needed, but winsock.h will include it if necessary.

4.1.1 accept()

Description
Accept a connection on a socket.
#include <winsock.h>

SOCKET PASCAL FAR accept ( SOCKET s, struct sockaddr FAR * addr,
int FAR * addrlen );
s
A descriptor identifying a socket which is listening for connections after a listen().

addr
An optional pointer to a buffer which receives the address of the connecting entity, as known to the communications layer. The exact format of the addr argument is determined by the address family established when the socket was created.

addrlen
An optional pointer to an integer which contains the length of the address addr.

Remarks
This routine extracts the first connection on the queue of pending connections on s, creates a new socket with the same properties as s and returns a handle to the new socket. If no pending connections are present on the queue, and the socket is not marked as non- blocking, accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, accept() returns an error as described below. The accepted socket may not be used to accept more connections. The original socket remains open.

The argument addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the address family in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types such as SOCK_STREAM. If addr and/or addrlen are equal to NULL, then no information about the remote address of the accepted socket is returned.

Return Value
If no error occurs, accept() returns a value of type SOCKET which is a descriptor for the accepted packet. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling WSAGetLastError().

The integer referred to by addrlen initially contains the amount of space pointed to by addr. On return it will contain the actual length in bytes of the address returned.

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULT
The addrlen argument is too small (less than the sizeof a struct sockaddr).

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

WSAEINPROGRESS
A blocking Windows Sockets call is in progress.

WSAEINVAL
listen() was not invoked prior to accept().

WSAEMFILE
The queue is empty upon entry to accept() and there are no descriptors available.

WSAENOBUFS
No buffer space is available.

WSAENOTSOCK
The descriptor is not a socket.

WSAEOPNOTSUPP
The referenced socket is not a type that supports connection-oriented service.

WSAEWOULDBLOCK
The socket is marked as non-blocking and no connections are present to be accepted.

See Also
bind(), connect(), listen(), select(), socket(), WSAAsyncSelect()

4.1.2 bind()

Description
Associate a local address with a socket.
#include <winsock.h>

int PASCAL FAR bind ( SOCKET s, const struct sockaddr FAR * name, int namelen );
s
A descriptor identifying an unbound socket.

name
The address to assign to the socket. The sockaddr structure is defined as follows:
struct sockaddr {
    u_short        sa_family;
    char        sa_data[14];
};
namelen
The length of the name.

Remarks
This routine is used on an unconnected datagram or stream socket, before subsequent connect()s or listen()s. When a socket is created with socket(), it exists in a name space (address family), but it has no name assigned. bind() establishes the local association (host address/port number) of the socket by assigning a local name to an unnamed socket.

In the Internet address family, a name consists of several components. For SOCK_DGRAM and SOCK_STREAM, the name consists of three parts: a host address, the protocol number (set implicitly to UDP or TCP, respectively), and a port number which identifies the application. If an application does not care what address is assigned to it, it may specify an Internet address equal to INADDR_ANY, a port equal to 0, or both. If the Internet address is equal to INADDR_ANY, any appropriate network interface will be used; this simplifies application programming in the presence of multi- homed hosts. If the port is specified as 0, the Windows Sockets implementation will assign a unique port to the application with a value between 1024 and 5000. The application may use getsockname() after bind() to learn the address that has been assigned to it, but note that getsockname() will not necessarily fill in the Internet address until the socket is connected, since several Internet addresses may be valid if the host is multi-homed.

If an application desires to bind to an arbitrary port outside of the range 1024 to 5000, such as the case of rsh which must bind to any reserved port, code similar to the following may be used:

SOCKADDR_IN sin;
SOCKET s;
u_short alport = IPPORT_RESERVED;

sin.sin_family = AF_INET;
sin.sin_addr.s_addr = 0;
for (;;) {
    sin.sin_port = htons(alport);
    if (bind(s, (LPSOCKADDR)&sin, sizeof (sin)) == 0) {
        /* it worked */
    }
    if ( GetLastError() != WSAEADDRINUSE) {
        /* fail */
    }
    alport--;
    if (alport == IPPORT_RESERVED/2 ) {
        /* fail--all unassigned reserved ports are */
        /* in use. */
    }
}
Return Value
If no error occurs, bind() returns 0. Otherwise, it returns SOCKET_ERROR, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEADDRINUSE
The specified address is already in use. (See the SO_REUSEADDR socket option under setsockopt().)

WSAEFAULT
The namelen argument is too small (less than the size of a struct sockaddr).

WSAEINPROGRESS
A blocking Windows Sockets call is in progress.

WSAEAFNOSUPPORT
The specified address family is not supported by this protocol.

WSAEINVAL
The socket is already bound to an address.

WSAENOBUFS
Not enough buffers available, too many connections.

WSAENOTSOCK
The descriptor is not a socket.

See Also
connect(), listen(), getsockname(), setsockopt(), socket(), WSACancelBlockingCall().

4.1.3 closesocket()

Description
Close a socket.
#include <winsock.h>

int PASCAL FAR closesocket ( SOCKET s );
s
A descriptor identifying a socket.

Remarks
This function closes a socket. More precisely, it releases the socket descriptor s, so that further references to s will fail with the error WSAENOTSOCK. If this is the last reference to the underlying socket, the associated naming information and queued data are discarded.

The semantics of closesocket() are affected by the socket options SO_LINGER and SO_DONTLINGER as follows:

    Option          Interval    Type of close   Wait for close? 
    SO_DONTLINGER   Don't care  Graceful        No
    SO_LINGER       Zero        Hard            No
    SO_LINGER       Non-zero    Graceful        Yes
If SO_LINGER is set (i.e. the l_onoff field of the linger structure is non-zero; see sections 2.4, 4.1.7 and 4.1.21) with a zero timeout interval (l_linger is zero), closesocket() is not blocked even if queued data has not yet been sent or acknowledged. This is called a "hard" or "abortive" close, because the socket's virtual circuit is reset immediately, and any unsent data is lost. Any recv() call on the remote side of the circuit will fail with WSAECONNRESET.

If SO_LINGER is set with a non-zero timeout interval, the closesocket() call blocks until the remaining data has been sent or until the timeout expires. This is called a graceful disconnect. Note that if the socket is set to non-blocking and SO_LINGER is set to a non-zero timeout, the call to closesocket() will fail with an error of WSAEWOULDBLOCK.

If SO_DONTLINGER is set on a stream socket (i.e. the l_onoff field of the linger structure is zero; see sections 2.4, 4.1.7 and 4.1.21), the closesocket() call will return immediately. However, any data queued for transmission will be sent if possible before the underlying socket is closed. This is also called a graceful disconnect. Note that in this case the Windows Sockets implementation may not release the socket and other resources for an arbitrary period, which may affect applications which expect to use all available sockets.

Return Value
If no error occurs, closesocket() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOTSOCK
The descriptor is not a socket.

WSAEINPROGRESS
A blocking Windows Sockets call is in progress.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

WSAEWOULDBLOCK
The socket is marked as nonblocking and SO_LINGER is set to a nonzero timeout value.

See Also
accept(), socket(), ioctlsocket(), setsockopt(), WSAAsyncSelect().

4.1.4 connect()

Description
Establish a connection to a peer.
#include <winsock.h>

int PASCAL FAR connect ( SOCKET s, const struct sockaddr FAR * name,
                         int namelen );
s
A descriptor identifying an unconnected socket.

name
The name of the peer to which the socket is to be connected.

namelen
The length of the name.

Remarks
This function is used to create a connection to the specified foreign association. The parameter s specifies an unconnected datagram or stream socket If the socket is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound. Note that if the address field of the name structure is all zeroes, connect() will return the error WSAEADDRNOTAVAIL.

For stream sockets (type SOCK_STREAM), an active connection is initiated to the foreign host using name (an address in the name space of the socket). When the socket call completes successfully, the socket is ready to send/receive data.

For a datagram socket (type SOCK_DGRAM), a default destination is set, which will be used on subsequent send() and recv() calls.

Return Value
If no error occurs, connect() returns 0. Otherwise, it returns SOCKET_ERROR, and a specific error code may be retrieved by calling WSAGetLastError().

On a blocking socket, the return value indicates success or failure of the connection attempt.

On a non-blocking socket, if the return value is SOCKET_ERROR an application should call WSAGetLastError(). If this indicates an error code of WSAEWOULDBLOCK, then your application can either:

  1. Use select() to determine the completion of the connection request by checking if the socket is writeable, or

  2. If your application is using the message-based WSAAsyncSelect() to indicate interest in connection events, then your application will receive an FD_CONNECT message when the connect operation is complete.

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEADDRINUSE
The specified address is already in use.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

WSAEINPROGRESS
A blocking Windows Sockets call is in progress.

WSAEADDRNOTAVAIL
The specified address is not available from the local machine.

WSAEAFNOSUPPORT
Addresses in the specified family cannot be used with this socket.

WSAECONNREFUSED
The attempt to connect was forcefully rejected.

WSAEDESTADDREQ
A destination address is required.

WSAEFAULT
The namelen argument is incorrect.

WSAEINVAL
The socket is not already bound to an address.

WSAEISCONN
The socket is already connected.

WSAEMFILE
No more file descriptors are available.

WSAENETUNREACH
The network can't be reached from this host at this time.

WSAENOBUFS
No buffer space is available. The socket cannot be connected.

WSAENOTSOCK
The descriptor is not a socket.

WSAETIMEDOUT
Attempt to connect timed out without establishing a connection

WSAEWOULDBLOCK
The socket is marked as non-blocking and the connection cannot be completed immediately. It is possible to select() the socket while it is connecting by select()ing it for writing.

See Also
accept(), bind(), getsockname(), socket(), select() and WSAAsyncSelect()..

4.1.5 getpeername()

Description
Get the address of the peer to which a socket is connected.
#include <winsock.h>

int PASCAL FAR getpeername ( SOCKET s, struct sockaddr FAR * name,
                             int FAR * namelen );
s
A descriptor identifying a connected socket.

name
The structure which is to receive the name of the peer.

namelen
A pointer to the size of the name structure.

Remarks
getpeername() retrieves the name of the peer connected to the socket s and stores it in the struct sockaddr identified by name. It is used on a connected datagram or stream socket.

On return, the namelen argument contains the actual size of the name returned in bytes.

Return Value
If no error occurs, getpeername() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULT
The namelen argument is not large enough.

WSAEINPROGRESS
A blocking Windows Sockets call is in progress.

WSAENOTCONN
The socket is not connected.

WSAENOTSOCK
The descriptor is not a socket.

See Also
bind(), socket(), getsockname().

4.1.6 getsockname()

Description
Get the local name for a socket.
#include <winsock.h>

int PASCAL FAR getsockname ( SOCKET s, struct sockaddr FAR * name,
                             int FAR * namelen );
s
A descriptor identifying a bound socket.

name
Receives the address (name) of the socket.

namelen
The size of the name buffer.

Remarks
getsockname() retrieves the current name for the specified socket descriptor in name. It is used on a bound and/or connected socket specified by the s parameter. The local association is returned. This call is especially useful when a connect() call has been made without doing a bind() first; this call provides the only means by which you can determine the local association which has been set by the system.

On return, the namelen argument contains the actual size of the name returned in bytes.

If a socket was bound to INADDR_ANY, indicating that any of the host's IP addresses should be used for the socket, getsockname() will not necessarily return information about the host IP address, unless the socket has been connected with connect() or accept(). A Windows Sockets application must not assume that the IP address will be changed from INADDR_ANY unless the socket is connected. This is because for a multi-homed host the IP address that will be used for the socket is unknown unless the socket is connected.

Return Value
If no error occurs, getsockname() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULT
The namelen argument is not large enough.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAENOTSOCK
The descriptor is not a socket.

WSAEINVAL
The socket has not been bound to an address with bind().

See Also
bind(), socket(), getpeername().

4.1.7 getsockopt()

Description
Retrieve a socket option.
#include <winsock.h>

int PASCAL FAR getsockopt ( SOCKET s, int level, int optname,
                            char FAR * optval, int FAR * optlen );
s
A descriptor identifying a socket.

level
The level at which the option is defined; the only supported levels are SOL_SOCKET and IPPROTO_TCP.

optname
The socket option for which the value is to be retrieved.

optval
A pointer to the buffer in which the value for the requested option is to be returned.

optlen
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 may exist at multiple protocol levels, but they are always present at the uppermost "socket'' level. Options affect socket operations, such as whether an operation blocks or not, the routing of packets, out-of-band data transfer, etc.

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 all other options it will be the size of an integer.

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. The TCP_NODELAY option uses level IPPROTO_TCP; all other options use level SOL_SOCKET.

Value           Type            Meaning
SO_ACCEPTCONN   BOOL            Socket is listen()ing.
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_KEEPALIVE    BOOL            Keepalives are being sent.
SO_LINGER       struct linger   Returns the current linger options.
                FAR *
SO_OOBINLINE    BOOL            Out-of-band data is being received in the
                                normal data stream.
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 (e.g. SOCK_STREAM).
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 timeout
SO_SNDLOWAT     int             Send low water mark
SO_SNDTIMEO     int             Send timeout
IP_OPTIONS                      Get options in IP header.
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().

Return Value
If no error occurs, getsockopt() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULT
The optlen argument was invalid.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAENOPROTOOPT
The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_ACCEPTCONN, SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM.

WSAENOTSOCK
The descriptor is not a socket.

See Also
setsockopt(), WSAAsyncSelect(), socket().

4.1.8 htonl()

Description
Convert a u_long from host to network byte order.
#include <winsock.h>

u_long PASCAL FAR htonl ( u_long hostlong );
hostlong
A 32-bit number in host byte order.

Remarks
This routine takes a 32-bit number in host byte order and returns a 32-bit number in network byte order.

Return Value
htonl() returns the value in network byte order.

See Also
htons(), ntohl(), ntohs().

4.1.9 htons()

Description
Convert a u_short from host to network byte order.
#include <winsock.h>

u_short PASCAL FAR htons ( u_short hostshort );
hostshort
A 16-bit number in host byte order.

Remarks
This routine takes a 16-bit number in host byte order and returns a 16-bit number in network byte order.

Return Value
htons() returns the value in network byte order.

See Also
htonl(), ntohl(), ntohs().

4.1.10 inet_addr()

Description
Convert a string containing a dotted address into an in_addr.
#include <winsock.h>

unsigned long PASCAL FAR inet_addr ( const char FAR * cp );
cp
A character string representing a number expressed in the Internet standard ".'' notation.

Remarks
This function interprets the character string specified by the cp parameter. This string represents a numeric Internet address expressed in the Internet standard ".'' notation. The value returned is a number suitable for use as an Internet address. All Internet addresses are returned in network order (bytes ordered from left to right).

Internet Addresses

Values specified using the ".'' notation take one of the following forms:

        a.b.c.d     a.b.c     a.b     a
When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. Note that when an Internet address is viewed as a 32-bit integer quantity on the Intel architecture, the bytes referred to above appear as "d.c.b.a''. That is, the bytes on an Intel processor are ordered from right to left.

Note: The following notations are only used by Berkeley, and nowhere else on the Internet. In the interests of compatibility with their software, they are supported as specified.

When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as "128.net.host''.

When a two part address is specified, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as "net.host''.

When only one part is given, the value is stored directly in the network address without any byte rearrangement.

Return Value
If no error occurs, inet_addr() returns an unsigned long containing a suitable binary representation of the Internet address given. If the passed-in string does not contain a legitimate Internet address, for example if a portion of an "a.b.c.d" address exceeds 255, inet_addr() returns the value INADDR_NONE.

See Also
inet_ntoa()

4.1.11 inet_ntoa()

Description
Convert a network address into a string in dotted format.
#include <winsock.h>

char FAR * PASCAL FAR inet_ntoa ( struct in_addr in );
in
A structure which represents an Internet host address.

Remarks
This function takes an Internet address structure specified by the in parameter. It returns an ASCII string representing the address in ".'' notation as "a.b.c.d''. Note that the string returned by inet_ntoa() resides in memory which is allocated by the Windows Sockets implementation. The application should not make any assumptions about the way in which the memory is allocated. The data is guaranteed to be valid until the next Windows Sockets API call within the same thread, but no longer.

Return Value
If no error occurs, inet_ntoa() returns a char pointer to a static buffer containing the text address in standard ".'' notation. Otherwise, it returns NULL. The data should be copied before another Windows Sockets call is made.

See Also
inet_addr().

4.1.12 ioctlsocket()

Description
Control the mode of a socket.
#include <winsock.h>

int PASCAL FAR ioctlsocket ( SOCKET s, long cmd, u_long FAR * argp );
s
A descriptor identifying a socket.

cmd
The command to perform on the socket s.

argp
A pointer to a parameter for cmd.

Remarks
This routine may be used on any socket in any state. It is used to get or retrieve operating parameters associated with the socket, independent of the protocol and communications subsystem. The following commands are supported:

FIONBIO
Enable or disable non-blocking mode on the socket s. argp points at an unsigned long, which is non-zero if non-blocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (i.e. non-blocking mode is disabled). This is consistent with BSD sockets.

The WSAAsyncSelect() routine automatically sets a socket to nonblocking mode. If WSAAsyncSelect() has been issued on a socket, then any attempt to use ioctlsocket() to set the socket back to blocking mode will fail with WSAEINVAL. To set the socket back to blocking mode, an application must first disable WSAAsyncSelect() by calling WSAAsyncSelect() with the lEvent parameter equal to 0.

FIONREAD
Determine the amount of data which can be read atomically from socket s. argp points at an unsigned long in which ioctlsocket() stores the result. If s is of type SOCK_STREAM, FIONREAD returns the total amount of data which may be read in a single recv(); this is normally the same as the total amount of data queued on the socket. If s is of type SOCK_DGRAM, FIONREAD returns the size of the first datagram queued on the socket.

SIOCATMARK
Determine whether or not all out-of-band data has been read. This applies only to a socket of type SOCK_STREAM which has been configured for in-line reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, the operation returns TRUE. Otherwise it returns FALSE, and the next recv() or recvfrom() performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the "urgent" (out of band) data, it will be received in order. (Note that a recv() or recvfrom() will never mix out-of-band and normal data in the same call.) argp points at a BOOL in which ioctlsocket() stores the result.

Compatibility
This function is a subset of ioctl() as used in Berkeley sockets. In particular, there is no command which is equivalent to FIOASYNC, while SIOCATMARK is the only socket- level command which is supported.

Return Value
Upon successful completion, the ioctlsocket() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVAL
cmd is not a valid command, or argp is not an acceptable parameter for cmd, or the command is not applicable to the type of socket supplied

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAENOTSOCK
The descriptor s is not a socket.

See Also
socket(), setsockopt(), getsockopt(), WSAAsyncSelect().

4.1.13 listen()

Description
Establish a socket to listen for incoming connection.
#include <winsock.h>

int PASCAL FAR listen ( SOCKET s, int backlog );
s
A descriptor identifying a bound, unconnected socket.

backlog
The maximum length to which the queue of pending connections may grow.

Remarks
To accept connections, a socket is first created with socket(), a backlog for incoming connections is specified with listen(), and then the connections are accepted with accept(). listen() applies only to sockets that support connections, i.e. those of type SOCK_STREAM. The socket s is put into "passive'' mode where incoming connections are acknowledged and queued pending acceptance by the process.

This function is typically used by servers that could have more than one connection request at a time: if a connection request arrives with the queue full, the client will receive an error with an indication of WSAECONNREFUSED.

listen() attempts to continue to function rationally when there are no available descriptors. It will accept connections until the queue is emptied. If descriptors become available, a later call to listen() or accept() will re-fill the queue to the current or most recent "backlog'', if possible, and resume listening for incoming connections.

Compatibility
backlog is currently limited (silently) to 5. As in 4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest legal value.

Return Value
If no error occurs, listen() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEADDRINUSE
An attempt has been made to listen() on an address in use.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEINVAL
The socket has not been bound with bind() or is already connected.

WSAEISCONN
The socket is already connected.

WSAEMFILE
No more file descriptors are available.

WSAENOBUFS
No buffer space is available.

WSAENOTSOCK
The descriptor is not a socket.

WSAEOPNOTSUPP
The referenced socket is not of a type that supports the listen() operation.

See Also
accept(), connect(), socket().

4.1.14 ntohl()

Description
Convert a u_long from network to host byte order.
#include <winsock.h>

u_long PASCAL FAR ntohl ( u_long netlong );
netlong
A 32-bit number in network byte order.

Remarks
This routine takes a 32-bit number in network byte order and returns a 32-bit number in host byte order.

Return Value
ntohl() returns the value in host byte order.

See Also
htonl(), htons(), ntohs().

4.1.15 ntohs()

Description
Convert a u_short from network to host byte order.
#include <winsock.h>

u_short PASCAL FAR ntohs ( u_short netshort );
netshort
A 16-bit number in network byte order.

Remarks
This routine takes a 16-bit number in network byte order and returns a 16-bit number in host byte order.

Return Value
ntohs() returns the value in host byte order.

See Also
htonl(), htons(), ntohl().

4.1.16 recv()

Description
Receive data from a socket.
#include <winsock.h>

int PASCAL FAR recv ( SOCKET s, char FAR * buf, int len, int flags );
s
A descriptor identifying a connected socket.

buf
A buffer for the incoming data.

len
The length of buf.

flags
Specifies the way in which the call is made.

Remarks
This function is used on connected datagram or stream sockets specified by the s parameter and is used to read incoming data.

For sockets of type SOCK_STREAM, as much information as is currently available up to the size of the buffer supplied is returned. If the socket has been configured for in- line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data will be returned. The application may use the ioctlsocket() SIOCATMARK to determine whether any more out-of-band data remains to be read.

For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the datagram, the excess data is lost, and recv() returns the error WSAEMSGSIZE.

If no incoming data is available at the socket, the recv() call waits for data to arrive unless the socket is non-blocking. In this case a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select() or WSAAsyncSelect() calls may be used to determine when more data arrives.

If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a recv() will complete immediately with 0 bytes received. If the connection has been reset, a recv() will fail with the error WSAECONNRESET.

Flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

    Value       Meaning
    MSG_PEEK    Peek at the incoming data.  The data is copied into the
                buffer but is not removed from the input queue.
    MSG_OOB     Process out-of-band data (See section 2.2.3 for a discussion
                of this topic.)
Return Value
If no error occurs, recv() returns the number of bytes received. If the connection has been closed, it returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOTCONN
The socket is not connected.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAENOTSOCK
The descriptor is not a socket.

WSAEOPNOTSUPP
MSG_OOB was specified, but the socket is not of type SOCK_STREAM.

WSAESHUTDOWN
The socket has been shutdown; it is not possible to recv() on a socket after shutdown() has been invoked with how set to 0 or 2.

WSAEWOULDBLOCK
The socket is marked as non-blocking and the receive operation would block.

WSAEMSGSIZE
The datagram was too large to fit into the specified buffer and was truncated.

WSAEINVAL
The socket has not been bound with bind().

WSAECONNABORTED
The virtual circuit was aborted due to timeout or other failure.

WSAECONNRESET
The virtual circuit was reset by the remote side.

See Also
recvfrom(), read(), recv(), send(), select(), WSAAsyncSelect(), socket()

4.1.17 recvfrom()

Description
Receive a datagram and store the source address.
#include <winsock.h>

int PASCAL FAR recvfrom ( SOCKET s, char FAR * buf, int len, int flags,
                          struct sockaddr FAR * from, int FAR * fromlen );
s
A descriptor identifying a bound socket.

buf
A buffer for the incoming data.

len
The length of buf.

flags
Specifies the way in which the call is made.

from
An optional pointer to a buffer which will hold the source address upon return.

fromlen
An optional pointer to the size of the from buffer.

Remarks
This function is used to read incoming data on a (possibly connected) socket and capture the address from which the data was sent.

For sockets of type SOCK_STREAM, as much information as is currently available up to the size of the buffer supplied is returned. If the socket has been configured for in- line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data will be returned. The application may use the ioctlsocket() SIOCATMARK to determine whether any more out-of-band data remains to be read. The from and fromlen parameters are ignored for SOCK_STREAM sockets.

For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the message, the excess data is lost, and recvfrom() returns the error code WSAEMSGSIZE.

If from is non-zero, and the socket is of type SOCK_DGRAM, the network address of the peer which sent the data is copied to the corresponding struct sockaddr. The value pointed to by fromlen is initialized to the size of this structure, and is modified on return to indicate the actual size of the address stored there.

If no incoming data is available at the socket, the recvfrom() call waits for data to arrive unless the socket is non-blocking. In this case a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select() or WSAAsyncSelect() calls may be used to determine when more data arrives.

If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a recvfrom() will complete immediately with 0 bytes received. If the connection has been reset recv() will fail with the error WSAECONNRESET.

Flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

    Value       Meaning
    MSG_PEEK    Peek at the incoming data.  The data is copied into the
                buffer but is not removed from the input queue.
    MSG_OOB     Process out-of-band data (See section 2.2.3 for a discussion
                of this topic.)
Return Value
If no error occurs, recvfrom() returns the number of bytes received. If the connection has been closed, it returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULT
The fromlen argument was invalid: the from buffer was too small to accommodate the peer address.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEINVAL
The socket has not been bound with bind().

WSAENOTCONN
The socket is not connected (SOCK_STREAM only).

WSAENOTSOCK
The descriptor is not a socket.

WSAEOPNOTSUPP
MSG_OOB was specified, but the socket is not of type SOCK_STREAM.

WSAESHUTDOWN
The socket has been shutdown; it is not possible to recvfrom() on a socket after shutdown() has been invoked with how set to 0 or 2.

WSAEWOULDBLOCK
The socket is marked as non-blocking and the recvfrom() operation would block.

WSAEMSGSIZE
The datagram was too large to fit into the specified buffer and was truncated.

WSAECONNABORTED
The virtual circuit was aborted due to timeout or other failure.

WSAECONNRESET
The virtual circuit was reset by the remote side.

See Also
recv(), send(), socket(), WSAAsyncSelect().

4.1.18 select()

Description
Determine the status of one or more sockets, waiting if necessary.
#include <winsock.h>

int PASCAL FAR select ( int nfds, fd_set FAR * readfds, fd_set FAR * writefds,
                        fd_set FAR * exceptfds, const struct timeval FAR * timeout );
nfds
This argument is ignored and included only for the sake of compatibility.

readfds
An optional pointer to a set of sockets to be checked for readability.

writefds
An optional pointer to a set of sockets to be checked for writability

exceptfds
An optional pointer to a set of sockets to be checked for errors.

timeout
The maximum time for select() to wait, or NULL for blocking operation.

Remarks
This function is used to determine the status of one or more sockets. For each socket, the caller may request information on read, write or error status. The set of sockets for which a given status is requested is indicated by an fd_set structure. Upon return, the structure is updated to reflect the subset of these sockets which meet the specified condition, and select() returns the number of sockets meeting the conditions. A set of macros is provided for manipulating an fd_set. These macros are compatible with those used in the Berkeley software, but the underlying representation is completely different.

The parameter readfds identifies those sockets which are to be checked for readability. If the socket is currently listen()ing, it will be marked as readable if an incoming connection request has been received, so that an accept() is guaranteed to complete without blocking. For other sockets, readability means that queued data is available for reading or, for sockets of type SOCK_STREAM, that the virtual socket corresponding to the socket has been closed, so that a recv() or recvfrom() is guaranteed to complete without blocking. If the virtual circuit was closed gracefully, then a recv() will return immediately with 0 bytes read; if the virtual circuit was reset, then a recv() will complete immediately with the error code WSAECONNRESET. The presence of out-of- band data will be checked if the socket option SO_OOBINLINE has been enabled (see setsockopt()).

The parameter writefds identifies those sockets which are to be checked for writability. If a socket is connect()ing (non-blocking), writability means that the connection establishment successfully completed. If the socket is not in the process of connect()ing, writability means that a send() or sendto() will complete without blocking. [It is not specified how long this guarantee can be assumed to be valid, particularly in a multithreaded environment.]

The parameter exceptfds identifies those sockets which are to be checked for the presence of out-of-band data or any exceptional error conditions. Note that out-of-band data will only be reported in this way if the option SO_OOBINLINE is FALSE. For a SOCK_STREAM, the breaking of the connection by the peer or due to KEEPALIVE failure will be indicated as an exception. This specification does not define which other errors will be included. If a socket is connect()ing (non-blocking), failure of the connect attempt is indicated in exceptfds.

Any of readfds, writefds, or exceptfds may be given as NULL if no descriptors are of interest.

Four macros are defined in the header file winsock.h for manipulating the descriptor sets. The variable FD_SETSIZE determines the maximum number of descriptors in a set. (The default value of FD_SETSIZE is 64, which may be modified by #defining FD_SETSIZE to another value before #including winsock.h.) Internally, an fd_set is represented as an array of SOCKETs; the last valid entry is followed by an element set to INVALID_SOCKET. The macros are:

    FD_CLR(s, *set)     Removes the descriptor s from set.
    FD_ISSET(s, *set)   Nonzero if s is a member of the set, zero otherwise.
    FD_SET(s, *set)     Adds descriptor s to set.
    FD_ZERO(*set)       Initializes the set to the NULL set.
The parameter timeout controls how long the select() may take to complete. If timeout is a null pointer, select() will block indefinitely until at least one descriptor meets the specified criteria. Otherwise, timeout points to a struct timeval which specifies the maximum time that select() should wait before returning. If the timeval is initialized to {0, 0}, select() will return immediately; this is used to "poll" the state of the selected sockets. If this is the case, then the select() call is considered nonblocking and the standard assumptions for nonblocking calls apply. For example, the blocking hook must not be called, and the Windows Sockets implementation must not yield.

Return Value
select() returns the total number of descriptors which are ready and contained in the fd_set structures, 0 if the time limit expired, or SOCKET_ERROR if an error occurred. If the return value is SOCKET_ERROR, WSAGetLastError() may be used to retrieve a specific error code.

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVAL
The timeout value is not valid.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAENOTSOCK
One of the descriptor sets contains an entry which is not a socket.

See Also
WSAAsyncSelect(), accept(), connect(), recv(), recvfrom(), send().

4.1.19 send()

Description
Send data on a connected socket.
#include <winsock.h>

int PASCAL FAR send ( SOCKET s, const char FAR * buf, int len, int flags );
s
A descriptor identifying a connected socket.

buf
A buffer containing the data to be transmitted.

len
The length of the data in buf.

flags
Specifies the way in which the call is made.

Remarks
send() is used on connected datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the iMaxUdpDg element in the WSAData structure returned by WSAStartup(). If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted.

Note that the successful completion of a send() does not indicate that the data was successfully delivered.

If no buffer space is available within the transport system to hold the data to be transmitted, send() will block unless the socket has been placed in a non-blocking I/O mode. On non-blocking SOCK_STREAM sockets, the number of bytes written may be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts. The select() call may be used to determine when it is possible to send more data.

Flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

    Value           Meaning
    MSG_DONTROUTE   Specifies that the data should not be subject to
                    routing.  A Windows Sockets supplier may choose
                    to ignore this flag; see also the discussion of
                    the SO_DONTROUTE option in section 2.4.
    MSG_OOB         Send out-of-band data (SOCK_STREAM only; see also
                    section 2.2.3)
Return Value
If no error occurs, send() returns the total number of characters sent. (Note that this may be less than the number indicated by len.) Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEACCES
The requested address is a broadcast address, but the appropriate flag was not set.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEFAULT
The buf argument is not in a valid part of the user address space.

WSAENETRESET
The connection must be reset because the Windows Sockets implementation dropped it.

WSAENOBUFS
The Windows Sockets implementation reports a buffer deadlock.

WSAENOTCONN
The socket is not connected.

WSAENOTSOCK
The descriptor is not a socket.

WSAEOPNOTSUPP
MSG_OOB was specified, but the socket is not of type SOCK_STREAM.

WSAESHUTDOWN
The socket has been shutdown; it is not possible to send() on a socket after shutdown() has been invoked with how set to 1 or 2.

WSAEWOULDBLOCK
The socket is marked as non-blocking and the requested operation would block.

WSAEMSGSIZE
The socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation.

WSAEINVAL
The socket has not been bound with bind().

WSAECONNABORTED
The virtual circuit was aborted due to timeout or other failure.

WSAECONNRESET
The virtual circuit was reset by the remote side.

See Also
recv(), recvfrom(), socket(), sendto(), WSAStartup().

4.1.20 sendto()

Description
Send data to a specific destination.
#include <winsock.h>

int PASCAL FAR sendto ( SOCKET s, const char FAR * buf, int len, int flags,
                        const struct sockaddr FAR * to, int tolen );
s
A descriptor identifying a socket.

buf
A buffer containing the data to be transmitted.

len
The length of the data in buf.

flags
Specifies the way in which the call is made.

to
An optional pointer to the address of the target socket.

tolen
The size of the address in to.

Remarks
sendto() is used on datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the iMaxUdpDg element in the WSAData structure returned by WSAStartup(). If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted.

Note that the successful completion of a sendto() does not indicate that the data was successfully delivered.

sendto() is normally used on a SOCK_DGRAM socket to send a datagram to a specific peer socket identified by the to parameter. On a SOCK_STREAM socket, the to and tolen parameters are ignored; in this case the sendto() is equivalent to send().

To send a broadcast (on a SOCK_DGRAM only), the address in the to parameter should be constructed using the special IP address INADDR_BROADCAST (defined in winsock.h) together with the intended port number. It is generally inadvisable for a broadcast datagram to exceed the size at which fragmentation may occur, which implies that the data portion of the datagram (excluding headers) should not exceed 512 bytes.

If no buffer space is available within the transport system to hold the data to be transmitted, sendto() will block unless the socket has been placed in a non-blocking I/O mode. On non-blocking SOCK_STREAM sockets, the number of bytes written may be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts. The select() call may be used to determine when it is possible to send more data.

Flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

    Value           Meaning
    MSG_DONTROUTE   Specifies that the data should not be subject to
                    routing.  A Windows Sockets supplier may choose
                    to ignore this flag; see also the discussion of
                    the SO_DONTROUTE option in section 2.4.
    MSG_OOB         Send out-of-band data (SOCK_STREAM only; see also
                    section 2.2.3)
Return Value
If no error occurs, sendto() returns the total number of characters sent. (Note that this may be less than the number indicated by len.) Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEACCES
The requested address is a broadcast address, but the appropriate flag was not set.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEFAULT
The buf or to parameters are not part of the user address space, or the to argument is too small (less than the sizeof a struct sockaddr).

WSAENETRESET
The connection must be reset because the Windows Sockets implementation dropped it.

WSAENOBUFS
The Windows Sockets implementation reports a buffer deadlock.

WSAENOTCONN
The socket is not connected (SOCK_STREAM only).

WSAENOTSOCK
The descriptor is not a socket.

WSAEOPNOTSUPP
MSG_OOB was specified, but the socket is not of type SOCK_STREAM.

WSAESHUTDOWN
The socket has been shutdown; it is not possible to sendto() on a socket after shutdown() has been invoked with how set to 1 or 2.

WSAEWOULDBLOCK
The socket is marked as non-blocking and the requested operation would block.

WSAEMSGSIZE
The socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation.

WSAECONNABORTED
The virtual circuit was aborted due to timeout or other failure.

WSAECONNRESET
The virtual circuit was reset by the remote side.

WSAEADDRNOTAVAIL
The specified address is not available from the local machine.

WSAEAFNOSUPPORT
Addresses in the specified family cannot be used with this socket.

WSAEDESTADDRREQ
A destination address is required.

WSAENETUNREACH
The network can't be reached from this host at this time.

See Also
recv(), recvfrom(), socket(), send(), WSAStartup().

4.1.21 setsockopt()

Description
Set a socket option.
#include <winsock.h>

int PASCAL FAR setsockopt ( SOCKET s, int level, int optname,
                            const char FAR * optval, int optlen );
s
A descriptor identifying a socket.

level
The level at which the option is defined; the only supported levels are SOL_SOCKET and IPPROTO_TCP.

optname
The socket option for which the value is to be set.

optval
A pointer to the buffer in which the value for the requested option is supplied.

optlen
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 may exist at multiple protocol levels, this specification only defines options that exist at the uppermost "socket'' level. Options affect socket operations, such as whether expedited data is received in the normal data stream, whether broadcast messages may be sent on the socket, etc.

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.

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 {
    int        l_onoff;
    int        l_linger;
}
To enable SO_LINGER, the application should set l_onoff to a non-zero value, set l_linger to 0 or the desired timeout (in seconds), and call setsockopt(). To enable SO_DONTLINGER (i.e. disable SO_LINGER) l_onoff should be set to zero and setsockopt() should be called.

By default, a socket may not be bound (see bind()) to a local address which is already in use. On occasions, however, it may be desirable 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 implementation 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.

An application may request that the Windows Sockets implementation enable the use of "keep-alive" packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets implementation 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.

The TCP_NODELAY option disables the Nagle algorithm. The Nagle algorithm is used to reduce the number of small packets sent by a host by buffering unacknowledged send data until a full-size packet can be sent. However, for some applications this algorithm can impede performance, and TCP_NODELAY may be used to turn it off. 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 performance. TCP_NODELAY is the only supported socket option which uses level IPPROTO_TCP; all other options use level SOL_SOCKET.

Windows Sockets suppliers 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.

The following options are supported for setsockopt(). The Type identifies the type of data addressed by optval.

Value           Type            Meaning
SO_BROADCAST    BOOL            Allow transmission of broadcast messages
                                on the socket.
SO_DEBUG        BOOL            Record debugging information.
SO_DONTLINGER   BOOL            Don't 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            Don't route: send directly to interface.
SO_KEEPALIVE    BOOL            Send keepalives
SO_LINGER       struct linger   Linger on close if unsent data is present
                FAR *
SO_OOBINLINE    BOOL            Receive out-of-band data in the normal data
                                stream.
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.
TCP_NODELAY     BOOL            Disables the Nagle algorithm for send
                                coalescing.
BSD options not supported for setsockopt() are:
Value           Type            Meaning
SO_ACCEPTCONN   BOOL            Socket is listening
SO_ERROR        int             Get error status and clear
SO_RCVLOWAT     int             Receive low water mark
SO_RCVTIMEO     int             Receive timeout
SO_SNDLOWAT     int             Send low water mark
SO_SNDTIMEO     int             Send timeout
SO_TYPE         int             Type of the socket
IP_OPTIONS                      Set options field in IP header.
Return Value
If no error occurs, setsockopt() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULT
optval is not in a valid part of the process address space.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

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. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM.

WSAENOTCONN
Connection has been reset when SO_KEEPALIVE is set.

WSAENOTSOCK
The descriptor is not a socket.

See Also
bind(), getsockopt(), ioctlsocket(), socket(), WSAAsyncSelect().

4.1.22 shutdown()

Description
Disable sends and/or receives on a socket.
#include <winsock.h>

int PASCAL FAR shutdown ( SOCKET s, int how );
s
A descriptor identifying a socket.

how
A flag that describes what types of operation will no longer be allowed.

Remarks
shutdown() is used on all types of sockets to disable reception, transmission, or both.

If how is 0, subsequent receives on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP, the TCP window is not changed and incoming data will be accepted (but not acknowledged) until the window is exhausted. For UDP, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated.

If how is 1, subsequent sends are disallowed. For TCP sockets, a FIN will be sent.

Setting how to 2 disables both sends and receives as described above.

Note that shutdown() does not close the socket, and resources attached to the socket will not be freed until closesocket() is invoked.

Comments
shutdown() does not block regardless of the SO_LINGER setting on the socket.

An application should not rely on being able to re-use a socket after it has been shut down. In particular, a Windows Sockets implementation is not required to support the use of connect() on such a socket.

Return Value
If no error occurs, shutdown() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVAL
how is not valid.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAENOTCONN
The socket is not connected (SOCK_STREAM only).

WSAENOTSOCK
The descriptor is not a socket.

See Also
connect(), socket().

4.1.23 socket()

Description
Create a socket.
#include <winsock.h>

SOCKET PASCAL FAR socket ( int af, int type, int protocol );
af
An address format specification. The only format currently supported is PF_INET, which is the ARPA Internet address format.

type
A type specification for the new socket.

protocol
A particular protocol to be used with the socket, or 0 if the caller does not wish to specify a protocol.

Remarks
socket() allocates a socket descriptor of the specified address family, data type and protocol, as well as related resources. If a protocol is not specified (i.e. equal to 0), the default for the specified connection mode is used.

Only a single protocol exists to support a particular socket type using a given address format. However, the address family may be given as AF_UNSPEC (unspecified), in which case the protocol parameter must be specified. The protocol number to use is particular to the "communication domain'' in which communication is to take place.

The following type specifications are supported:

Type            Explanation
SOCK_STREAM     Provides sequenced, reliable, two-way, connection-based
                byte streams with an out-of-band data transmission
                mechanism.  Uses TCP for the Internet address family.
SOCK_DGRAM      Supports datagrams, which are connectionless,
                unreliable buffers of a fixed (typically small)
                maximum length.  Uses UDP for the Internet address
                family.
Sockets of type SOCK_STREAM are full-duplex byte streams. A stream socket must be in a connected state before any data may be sent or received on it. A connection to another socket is created with a connect() call. Once connected, data may be transferred using send() and recv() calls. When a session has been completed, a closesocket() must be performed. Out-of-band data may also be transmitted as described in send() and received as described in recv().

The communications protocols used to implement a SOCK_STREAM ensure that data is not lost or duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls will fail with the error code set to WSAETIMEDOUT.

SOCK_DGRAM sockets allow sending and receiving of datagrams to and from arbitrary peers using sendto() and recvfrom(). If such a socket is connect()ed to a specific peer, datagrams may be send to that peer send() and may be received from (only) this peer using recv().

Return Value
If no error occurs, socket() returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEAFNOSUPPORT
The specified address family is not supported.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEMFILE
No more file descriptors are available.

WSAENOBUFS
No buffer space is available. The socket cannot be created.

WSAEPROTONOSUPPORT
The specified protocol is not supported.

WSAEPROTOTYPE
The specified protocol is the wrong type for this socket.

WSAESOCKTNOSUPPORT
The specified socket type is not supported in this address family.

See Also
accept(), bind(), connect(), getsockname(), getsockopt(), setsockopt(), listen(), recv(), recvfrom(), select(), send(), sendto(), shutdown(), ioctlsocket().

4.2 Database Routines

4.2.1 gethostbyaddr()

Description
Get host information corresponding to an address.
#include <winsock.h>

struct hostent FAR * PASCAL FAR gethostbyaddr ( const char FAR * addr,
                                                int len, int type );
addr
A pointer to an address in network byte order.

len
The length of the address, which must be 4 for PF_INET addresses.

type
The type of the address, which must be PF_INET.

Remarks
gethostbyaddr() returns a pointer to the following structure which contains the name(s) and address which correspond to the given address.
struct hostent {
    char FAR *        h_name;
    char FAR * FAR *        h_aliases;
    short        h_addrtype;
    short        h_length;
    char FAR * FAR *        h_addr_list;
};
The members of this structure are:
Element       Usage
h_name        Official name of the host (PC).
h_aliases     A NULL-terminated array of alternate names.
h_addrtype    The type of address being returned; for Windows Sockets this
              is always PF_INET.
h_length      The length, in bytes, of each address; for PF_INET, this is
              always 4.
h_addr_list   A NULL-terminated list of addresses for the host.  Addresses
              are returned in network byte order.
The macro h_addr is defined to be h_addr_list[0] for compatibility with older software.

The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value
If no error occurs, gethostbyaddr() returns a pointer to the hostent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAHOST_NOT_FOUND
Authoritative Answer Host not found.

WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

See Also
WSAAsyncGetHostByAddr(), gethostbyname(),

4.2.2 gethostbyname()

Description
Get host information corresponding to a hostname.
#include <winsock.h>

struct hostent FAR * PASCAL FAR gethostbyname ( const char FAR * name );
name
A pointer to the name of the host.

Remarks
gethostbyname() returns a pointer to a hostent structure as described under gethostbyaddr(). The contents of this structure correspond to the hostname name.

The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

A gethostbyname() implementation must not resolve IP address strings passed to it. Such a request should be treated exactly as if an unknown host name were passed. An application with an IP address string to resolve should use inet_addr() to convert the string to an IP address, then gethostbyaddr() to obtain the hostent structure.

Return Value
If no error occurs, gethostbyname() returns a pointer to the hostent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAHOST_NOT_FOUND
Authoritative Answer Host not found.

WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

See Also
WSAAsyncGetHostByName(), gethostbyaddr(

4.2.3 gethostname()

Description
Return the standard host name for the local machine.
#include <winsock.h>

int PASCAL FAR gethostname ( char FAR * name, int namelen );
name
A pointer to a buffer that will receive the host name.

namelen
The length of the buffer.

Remarks
This routine returns the name of the local host into the buffer specified by the name parameter. The host name is returned as a null-terminated string. The form of the host name is dependent on the Windows Sockets implementation--it may be a simple host name, or it may be a fully qualified domain name. However, it is guaranteed that the name returned will be successfully parsed by gethostbyname() and WSAAsyncGetHostByName().

Return Value
If no error occurs, gethostname() returns 0, otherwise it returns SOCKET_ERROR and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes
WSAEFAULT
The namelen parameter is too small

WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

See Also
gethostbyname(), WSAAsyncGetHostByName().

4.2.4 getprotobyname()

Description
Get protocol information corresponding to a protocol name.
#include <winsock.h>

struct protoent FAR * PASCAL FAR getprotobyname ( const char FAR * name );
name
A pointer to a protocol name.

Remarks
getprotobyname() returns a pointer to the following structure which contains the name(s) and protocol number which correspond to the given protocol name.
struct protoent {
    char FAR *        p_name;
    char FAR * FAR *        p_aliases;
    short        p_proto;
};
The members of this structure are:
    Element     Usage
    p_name      Official name of the protocol.
    p_aliases   A NULL-terminated array of alternate names.
    p_proto     The protocol number, in host byte order.
The pointer which is returned points to a structure which is allocated by the Windows Sockets library. The application must never attempt to modify this structure or to free any of its components. Furthermore only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value
If no error occurs, getprotobyname() returns a pointer to the protoent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

See Also
WSAAsyncGetProtoByName(), getprotobynumber()

4.2.5 getprotobynumber()

Description
Get protocol information corresponding to a protocol number.
#include <winsock.h>

struct protoent FAR * PASCAL FAR getprotobynumber ( int number );
number
A protocol number, in host byte order.

Remarks
This function returns a pointer to a protoent structure as described above in getprotobyname(). The contents of the structure correspond to the given protocol number.

The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value
If no error occurs, getprotobynumber() returns a pointer to the protoent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

See Also
WSAAsyncGetProtoByNumber(), getprotobyname()

4.2.6 getservbyname()

Description
Get service information corresponding to a service name and protocol.
#include <winsock.h>

struct servent FAR * PASCAL FAR getservbyname ( const char FAR * name,
                                                const char FAR * proto );
name
A pointer to a service name.

proto
An optional pointer to a protocol name. If this is NULL, getservbyname() returns the first service entry for which the name matches the s_name or one of the s_aliases. Otherwise getservbyname() matches both the name and the proto.

Remarks
getservbyname() returns a pointer to the following structure which contains the name(s) and service number which correspond to the given service name.
struct servent {
    char FAR *        s_name;
    char FAR * FAR *        s_aliases;
    short        s_port;
    char FAR *        s_proto;
};
The members of this structure are:
    Element     Usage
    s_name      Official name of the service.
    s_aliases   A NULL-terminated array of alternate names.
    s_port      The port number at which the service may be contacted.
                Port numbers are returned in network byte order.
    s_proto     The name of the protocol to use when contacting the service.
The pointer which is returned points to a structure which is allocated by the Windows Sockets library. The application must never attempt to modify this structure or to free any of its components. Furthermore only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value
If no error occurs, getservbyname() returns a pointer to the servent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

See Also
WSAAsyncGetServByName(), getservbyport()

4.2.7 getservbyport()

Description
Get service information corresponding to a port and protocol.
#include <winsock.h>

struct servent FAR * PASCAL FAR getservbyport ( int port,
                                                const char FAR * proto );
port
The port for a service, in network byte order.

proto
An optional pointer to a protocol name. If this is NULL, getservbyport() returns the first service entry for which the port matches the s_port. Otherwise getservbyport() matches both the port and the proto.

Remarks
getservbyport() returns a pointer a servent structure as described above for getservbyname().

The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value
If no error occurs, getservbyport() returns a pointer to the servent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall().

See Also
WSAAsyncGetServByPort(), getservbyname()

4.3 Microsoft Windows-specific Extensions

4.3.1 WSAAsyncGetHostByAddr()

Description
Get host information corresponding to an address - asynchronous version.
#include <winsock.h>

HANDLE PASCAL FAR WSAAsyncGetHostByAddr ( HWND hWnd, unsigned int wMsg,
                                          const char FAR * addr, int len,
                                          int type, char FAR * buf,
                                          int buflen );
hWnd
The handle of the window which should receive a message when the asynchronous request completes.

wMsg
The message to be received when the asynchronous request completes.

addr
A pointer to the network address for the host. Host addresses are stored in network byte order.

len
The length of the address, which must be 4 for PF_INET.

type
The type of the address, which must be PF_INET.

buf
A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a hostent structure but any and all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen
The size of data area buf above.

Remarks
This function is an asynchronous version of gethostbyaddr(), and is used to retrieve host name and address information corresponding to a network address. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetHostByAddr() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
The use of these macros will maximize the portability of the source code for the application.

Return Value
The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetHostByAddr() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetHostByAddr() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
The buffer supplied to this function is used by the Windows Sockets implementation to construct a hostent structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).

Notes For Windows Sockets Suppliers
It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

Error Codes
The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFS
No/insufficient buffer space is available

WSAHOST_NOT_FOUND
Authoritative Answer Host not found.

WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEWOULDBLOCK
The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also
gethostbyaddr(), WSACancelAsyncRequest()

4.3.2 WSAAsyncGetHostByName()

Description
Get host information corresponding to a hostname - asynchronous version.
#include <winsock.h>

HANDLE PASCAL FAR WSAAsyncGetHostByName ( HWND hWnd, unsigned int wMsg,
                                          const char FAR * name,
                                          char FAR * buf, int buflen );
hWnd
The handle of the window which should receive a message when the asynchronous request completes.

wMsg
The message to be received when the asynchronous request completes.

name
A pointer to the name of the host.

buf
A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a hostent structure but any and all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen
The size of data area buf above.

Remarks
This function is an asynchronous version of gethostbyname(), and is used to retrieve host name and address information corresponding to a hostname. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetHostByName() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
The use of these macros will maximize the portability of the source code for the application.

Return Value
The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetHostByName() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetHostByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
The buffer supplied to this function is used by the Windows Sockets implementation to construct a hostent structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).

Notes For Windows Sockets Suppliers
It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

Error Codes
The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFS
No/insufficient buffer space is available

WSAHOST_NOT_FOUND
Authoritative Answer Host not found.

WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEWOULDBLOCK
The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also
gethostbyname(), WSACancelAsyncRequest()

4.3.3 WSAAsyncGetProtoByName()

Description
Get protocol information corresponding to a protocol name - asynchronous version.
#include <winsock.h>

HANDLE PASCAL FAR WSAAsyncGetProtoByName ( HWND hWnd, unsigned int wMsg,
                                           const char FAR * name,
                                           char FAR * buf, int buflen );
hWnd
The handle of the window which should receive a message when the asynchronous request completes.

wMsg
The message to be received when the asynchronous request completes.

name
A pointer to the protocol name to be resolved.

buf
A pointer to the data area to receive the protoent data. Note that this must be larger than the size of a protoent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a protoent structure but any and all of the data which is referenced by members of the protoent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen
The size of data area buf above.

Remarks
This function is an asynchronous version of getprotobyname(), and is used to retrieve the protocol name and number corresponding to a protocol name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetProtoByName() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
The use of these macros will maximize the portability of the source code for the application.

Return Value
The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetProtoByName() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetProtoByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
The buffer supplied to this function is used by the Windows Sockets implementation to construct a protoent structure together with the contents of data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).

Notes For Windows Sockets Suppliers
It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

Error Codes
The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFS
No/insufficient buffer space is available

WSAHOST_NOT_FOUND
Authoritative Answer Host not found.

WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEWOULDBLOCK
The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also
getprotobyname(), WSACancelAsyncRequest()

4.3.4 WSAAsyncGetProtoByNumber()

Description
Get protocol information corresponding to a protocol number - asynchronous version.
#include <winsock.h>

HANDLE PASCAL FAR WSAAsyncGetProtoByNumber ( HWND hWnd, unsigned int wMsg,
                                             int number, char FAR * buf,
                                             int buflen );
hWnd
The handle of the window which should receive a message when the asynchronous request completes.

wMsg
The message to be received when the asynchronous request completes.

number
The protocol number to be resolved, in host byte order.

buf
A pointer to the data area to receive the protoent data. Note that this must be larger than the size of a protoent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a protoent structure but any and all of the data which is referenced by members of the protoent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen
The size of data area buf above.

Remarks
This function is an asynchronous version of getprotobynumber(), and is used to retrieve the protocol name and number corresponding to a protocol number. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetProtoByNumber() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
The use of these macros will maximize the portability of the source code for the application.

Return Value
The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetProtoByNumber() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetProtoByNumber() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
The buffer supplied to this function is used by the Windows Sockets implementation to construct a protoent structure together with the contents of data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).

Notes For Windows Sockets Suppliers
It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

Error Codes
The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFS
No/insufficient buffer space is available

WSAHOST_NOT_FOUND
Authoritative Answer Host not found.

WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEWOULDBLOCK
The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also
getprotobynumber(), WSACancelAsyncRequest()

4.3.5 WSAAsyncGetServByName()

Description
Get service information corresponding to a service name and port - asynchronous version.
#include <winsock.h>

HANDLE PASCAL FAR WSAAsyncGetServByName ( HWND hWnd, unsigned int wMsg,
                                          const char FAR * name,
                                          const char FAR * proto,
                                          char FAR * buf, int buflen );
hWnd
The handle of the window which should receive a message when the asynchronous request completes.

wMsg
The message to be received when the asynchronous request completes.

name
A pointer to a service name.

proto
A pointer to a protocol name. This may be NULL, in which case WSAAsyncGetServByName() will search for the first service entry for which s_name or one of the s_aliases matches the given name. Otherwise WSAAsyncGetServByName() matches both name and proto.

buf
A pointer to the data area to receive the servent data. Note that this must be larger than the size of a servent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a servent structure but any and all of the data which is referenced by members of the servent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen
The size of data area buf above.

Remarks
This function is an asynchronous version of getservbyname(), and is used to retrieve service information corresponding to a service name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetServByName() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
The use of these macros will maximize the portability of the source code for the application.

Return Value
The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetServByName() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncServByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
The buffer supplied to this function is used by the Windows Sockets implementation to construct a hostent structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).

Notes For Windows Sockets Suppliers
It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

Error Codes
The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFS
No/insufficient buffer space is available

WSAHOST_NOT_FOUND
Authoritative Answer Host not found.

WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEWOULDBLOCK
The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also
getservbyname(), WSACancelAsyncRequest()

4.3.6 WSAAsyncGetServByPort()

Description
Get service information corresponding to a port and protocol - asynchronous version.
#include <winsock.h>

HANDLE PASCAL FAR WSAAsyncGetServByPort ( HWND hWnd, unsigned int wMsg,
                                          int port, const char FAR * proto,
                                          char FAR * buf, int buflen );
hWnd
The handle of the window which should receive a message when the asynchronous request completes.

wMsg
The message to be received when the asynchronous request completes.

port
The port for the service, in network byte order.

proto
A pointer to a protocol name. This may be NULL, in which case WSAAsyncGetServByPort() will search for the first service entry for which s_port match the given port. Otherwise WSAAsyncGetServByPort() matches both port and proto.

buf
A pointer to the data area to receive the servent data. Note that this must be larger than the size of a servent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a servent structure but any and all of the data which is referenced by members of the servent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.

buflen
The size of data area buf above.

Remarks
This function is an asynchronous version of getservbyport(), and is used to retrieve service information corresponding to a port number. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a servent structure. To access the elements of this structure, the original buffer address should be cast to a servent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetServByPort() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
The use of these macros will maximize the portability of the source code for the application.

Return Value
The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.

If the operation was successfully initiated, WSAAsyncGetServByPort() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetServByPort() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
The buffer supplied to this function is used by the Windows Sockets implementation to construct a servent structure together with the contents of data areas referenced by members of the same servent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).

Notes For Windows Sockets Suppliers
It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

Error Codes
The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFS
No/insufficient buffer space is available

WSAHOST_NOT_FOUND
Authoritative Answer Host not found.

WSATRY_AGAIN
Non-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERY
Non recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATA
Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEWOULDBLOCK
The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also
getservbyport(), WSACancelAsyncRequest()

4.3.7 WSAAsyncSelect()

Description
Request event notification for a socket.
#include <winsock.h>

int PASCAL FAR WSAAsyncSelect ( SOCKET s, HWND hWnd,
                                unsigned int wMsg, long lEvent );
s
A descriptor identifying the socket for which event notification is required.

hWnd
A handle identifying the window which should receive a message when a network event occurs.

wMsg
The message to be received when a network event occurs.

lEvent
A bitmask which specifies a combination of network events in which the application is interested.

Remarks
This function is used to request that the Windows Sockets DLL should send a message to the window hWnd whenever it detects any of the network events specified by the lEvent parameter. The message which should be sent is specified by the wMsg parameter. The socket for which notification is required is identified by s.

This function automatically sets socket s to non-blocking mode.

The lEvent parameter is constructed by or'ing any of the values specified in the following list.

    Value       Meaning
    FD_READ     Want to receive notification of readiness for reading
    FD_WRITE    Want to receive notification of readiness for writing
    FD_OOB      Want to receive notification of the arrival of out-of-band
                data
    FD_ACCEPT   Want to receive notification of incoming connections
    FD_CONNECT  Want to receive notification of completed connection
    FD_CLOSE    Want to receive notification of socket closure
Issuing a WSAAsyncSelect() for a socket cancels any previous WSAAsyncSelect() for the same socket. For example, to receive notification for both reading and writing, the application must call WSAAsyncSelect() with both FD_READ and FD_WRITE, as follows:
    rc = WSAAsyncSelect(s, hWnd, wMsg, FD_READ|FD_WRITE);
It is not possible to specify different messages for different events. The following code will not work; the second call will cancel the effects of the first, and only FD_WRITE events will be reported with message wMsg2:
    rc = WSAAsyncSelect(s, hWnd, wMsg1, FD_READ);
    rc = WSAAsyncSelect(s, hWnd, wMsg2, FD_WRITE);
To cancel all notification - i.e., to indicate that the Windows Sockets implementation should send no further messages related to network events on the socket - lEvent should be set to zero.
    rc = WSAAsyncSelect(s, hWnd, 0, 0);
Although in this instance WSAAsyncSelect() immediately disables event message posting for the socket, it is possible that messages may be waiting in the application's message queue. The application must therefore be prepared to receive network event messages even after cancellation. Closing a socket with closesocket() also cancels WSAAsyncSelect() message sending, but the same caveat about messages in the queue prior to the closesocket() still applies.

Since an accept()'ed socket has the same properties as the listening socket used to accept it, any WSAAsyncSelect() events set for the listening socket apply to the accepted socket. For example, if a listening socket has WSAAsyncSelect() events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE events with the same wMsg value used for messages. If a different wMsg or events are desired, the application should call WSAAsyncSelect(), passing the accepted socket and the desired new information. [7]

When one of the nominated network events occurs on the specified socket s, the application's window hWnd receives message wMsg. The wParam argument identifies the socket on which a network event has occurred. The low word of lParam specifies the network event that has occurred. The high word of lParam contains any error code. The error code be any error as defined in winsock.h.

The error and event codes may be extracted from the lParam using the macros WSAGETSELECTERROR and WSAGETSELECTEVENT, defined in winsock.h as:

#define WSAGETSELECTERROR(lParam)            HIWORD(lParam)
#define WSAGETSELECTEVENT(lParam)            LOWORD(lParam)
The use of these macros will maximize the portability of the source code for the application.

The possible network event codes which may be returned are as follows:

    Value       Meaning
    FD_READ     Socket s ready for reading
    FD_WRITE    Socket s ready for writing
    FD_OOB      Out-of-band data ready for reading on socket s.
    FD_ACCEPT   Socket s ready for accepting a new incoming connection
    FD_CONNECT  Connection on socket s completed
    FD_CLOSE    Connection identified by socket s has been closed
Return Value
The return value is 0 if the application's declaration of interest in the network event set was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
Although WSAAsyncSelect() can be called with interest in multiple events, the application window will receive a single message for each network event.

As in the case of the select() function, WSAAsyncSelect() will frequently be used to determine when a data transfer operation (send() or recv()) can be issued with the expectation of immediate success. Nevertheless, a robust application must be prepared for the possibility that it may receive a message and issue a Windows Sockets API call which returns WSAEWOULDBLOCK immediately. For example, the following sequence of events is possible:

  1. Data arrives on socket s; Windows Sockets posts WSAAsyncSelect message
  2. Application processes some other message
  3. While processing, application issues an ioctlsocket(s, FIONREAD...) and notices that there is data ready to be read
  4. Application issues a recv(s,...) to read the data
  5. Application loops to process next message, eventually reaching the WSAAsyncSelect message indicating that data is ready to read
  6. Application issues recv(s,...), which fails with the error WSAEWOULDBLOCK.

Other sequences are possible.

The Windows Sockets DLL will not continually flood an application with messages for a particular network event. Having successfully posted notification of a particular event to an application window, no further message(s) for that network event will be posted to the application window until the application makes the function call which implicitly reenables notification of that network event.

    Event       Re-enabling function
    FD_READ     recv() or recvfrom()
    FD_WRITE    send() or sendto()
    FD_OOB      recv()
    FD_ACCEPT   accept()
    FD_CONNECT  NONE
    FD_CLOSE    NONE
Any call to the reenabling routine, even one which fails, results in reenabling of message posting for the relevant event.

For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is "level-triggered." This means that if the reenabling routine is called and the relevant event is still valid after the call, a WSAAsyncSelect() message is posted to the application. This allows an application to be event-driven and not concern itself with the amount of data that arrives at any one time. Consider the following sequence:

  1. Windows Sockets DLL receives 100 bytes of data on socket s and posts an FD_READ message.
  2. The application issues recv( s, buffptr, 50, 0) to read 50 bytes.
  3. The Windows Sockets DLL posts another FD_READ message since there is still data to be read.

With these semantics, an application need not read all available data in response to an FD_READ message--a single recv() in response to each FD_READ message is appropriate. If an application issues multiple recv() calls in response to a single FD_READ, it may receive multiple FD_READ messages. Such an application may wish to disable FD_READ messages before starting the recv() calls by calling WSAAsyncSelect() with the FD_READ event not set.

If an event is true when the application initially calls WSAAsyncSelect() or when the reenabling function is called, then a message is posted as appropriate. For example, if an application calls listen(), a connect attempt is made, then the application calls WSAAsyncSelect() specifying that it wants to receive FD_ACCEPT messages for the socket, the Windows Sockets implementation posts an FD_ACCEPT message immediately.

The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted when a socket is first connected with connect() or accepted with accept(), and then after a send() or sendto() fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application can assume that sends are possible starting from the first FD_WRITE message and lasting until a send returns WSAEWOULDBLOCK. After such a failure the application will be notified that sends are again possible with an FD_WRITE message.

The FD_OOB event is used only when a socket is configured to receive out-of-band data separately. If the socket is configured to receive out-of-band data in-line, the out-of- band (expedited) data is treated as normal data and the application should register an interest in, and will receive, FD_READ events, not FD_OOB events. An application may set or inspect the way in which out-of-band data is to be handled by using setsockopt() or getsockopt() for the SO_OOBINLINE option.

The error code in an FD_CLOSE message indicates whether the socket close was graceful or abortive. If the error code is 0, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual socket was reset. This only applies to sockets of type SOCK_STREAM.

The FD_CLOSE message is posted when a close indication is received for the virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is posted when the connection goes into the FIN WAIT or CLOSE WAIT states. This results from the remote end performing a shutdown() on the send side or a closesocket().

Please note your application will receive ONLY an FD_CLOSE message to indicate closure of a virtual circuit. It will NOT receive an FD_READ message to indicate this condition.

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVAL
Indicates that one of the specified parameters was invalid

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

Additional error codes may be set when an application window receives a message. This error code is extracted from the lParam in the reply message using the WSAGETSELECTERROR macro. Possible error codes for each network event are:

Event: FD_CONNECT
Error Code          Meaning 
WSAEADDRINUSE       The specified address is already in use.
WSAEADDRNOTAVAIL    The specified address is not available from the
                    local machine.
WSAEAFNOSUPPORT     Addresses in the specified family cannot be used
                    with this socket.
WSAECONNREFUSED     The attempt to connect was forcefully rejected.
WSAEDESTADDRREQ     A destination address is required.
WSAEFAULT           The namelen argument is incorrect.
WSAEINVAL           The socket is already bound to an address.
WSAEISCONN          The socket is already connected.
WSAEMFILE           No more file descriptors are available.
WSAENETUNREACH      The network can't be reached from this host at this
                    time.
WSAENOBUFS          No buffer space is available.  The socket cannot be
                    connected.
WSAENOTCONN         The socket is not connected.
WSAENOTSOCK         The descriptor is a file, not a socket.
WSAETIMEDOUT        Attempt to connect timed out without establishing a
                    connection.
Event: FD_CLOSE
Error Code          Meaning
WSAENETDOWN         The Windows Sockets implementation has detected
                    that the network subsystem has failed.
WSAECONNRESET       The connection was reset by the remote side.
WSAECONNABORTED     The connection was aborted due to timeout or other
                    failure.
Event: FD_READ
Event: FD_WRITE
Event: FD_OOB
Event: FD_ACCEPT
Error Code          Meaning
WSAENETDOWN         The Windows Sockets implementation has detected
                    that the network subsystem has failed.
Notes For Windows Sockets Suppliers
It is the responsibility of the Windows Sockets Supplier to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation MUST re-post that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKESELECTREPLY macro when constructing the lParam in the message.

When a socket is closed, the Windows Sockets Supplier should purge any messages remaining for posting to the application window. However the application must be prepared to receive, and discard, any messages which may have been posted prior to the closesocket().

See Also
select()

4.3.8 WSACancelAsyncRequest()

Description
Cancel an incomplete asynchronous operation.
#include <winsock.h>

int PASCAL FAR WSACancelAsyncRequest ( HANDLE hAsyncTaskHandle );
hAsyncTaskHandle
Specifies the asynchronous operation to be canceled.

Remarks
The WSACancelAsyncRequest() function is used to cancel an asynchronous operation which was initiated by one of the WSAAsyncGetXByY() functions such as WSAAsyncGetHostByName(). The operation to be canceled is identified by the hAsyncTaskHandle parameter, which should be set to the asynchronous task handle as returned by the initiating function.

Return Value
The value returned by WSACancelAsyncRequest() is 0 if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
An attempt to cancel an existing asynchronous WSAAsyncGetXByY() operation can fail with an error code of WSAEALREADY for two reasons. First, the original operation has already completed and the application has dealt with the resultant message. Second, the original operation has already completed but the resultant message is still waiting in the application window queue.

Notes For Windows Sockets Suppliers
It is unclear whether the application can usefully distinguish between WSAEINVAL and WSAEALREADY, since in both cases the error indicates that there is no asynchronous operation in progress with the indicated handle. [Trivial exception: 0 is always an invalid asynchronous task handle.] The Windows Sockets specification does not prescribe how a conformant Windows Sockets implementation should distinguish between the two cases. For maximum portability, a Windows Sockets application should treat the two errors as equivalent.

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVAL
Indicates that the specified asynchronous task handle was invalid

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

WSAEALREADY
The asynchronous routine being canceled has already completed.

See Also
WSAAsyncGetHostByAddr(), WSAAsyncGetHostByName(), WSAAsyncGetProtoByNumber(), WSAAsyncGetProtoByName(), WSAAsyncGetServByPort(), WSAAsyncGetServByName().

4.3.9 WSACancelBlockingCall()

Description
Cancel a blocking call which is currently in progress.
#include <winsock.h>

int PASCAL FAR WSACancelBlockingCall ( void );
Remarks
This function cancels any outstanding blocking operation for this task. It is normally used in two situations:

  1. An application is processing a message which has been received while a blocking call is in progress. In this case, WSAIsBlocking() will be true.

  2. A blocking call is in progress, and Windows Sockets has called back to the application's "blocking hook" function (as established by WSASetBlockingHook()).

In each case, the original blocking call will terminate as soon as possible with the error WSAEINTR. (In (1), the termination will not take place until Windows message scheduling has caused control to revert to the blocking routine in Windows Sockets. In (2), the blocking call will be terminated as soon as the blocking hook function completes.)

In the case of a blocking connect() operation, the Windows Sockets implementation will terminate the blocking call as soon as possible, but it may not be possible for the socket resources to be released until the connection has completed (and then been reset) or timed out. This is likely to be noticeable only if the application immediately tries to open a new socket (if no sockets are available), or to connect() to the same peer.

Cancelling an accept() or a select() call does not adversely impact the sockets passed to these calls. Only the particular call fails; any operation that was legal before the cancel is legal after the cancel, and the state of the socket is not affected in any way.

Cancelling any operation other than accept() and select() can leave the socket in an indeterminate state. If an application cancels a blocking operation on a socket, the only operation that the application can depend on being able to perform on the socket is a call to closesocket(), although other operations may work on some Windows Sockets implementations. If an application desires maximum portability, it must be careful not to depend on performing operations after a cancel. An application may reset the connection by setting the timeout on SO_LINGER to 0.

If a cancel operation compromised the integrity of a SOCK_STREAM's data stream in any way, the Windows Sockets implementation must reset the connection and fail all future operations other than closesocket() with WSAECONNABORTED.

Return Value
The value returned by WSACancelBlockingCall() is 0 if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
Note that it is possible that the network operation completes before the WSACancelBlockingCall() is processed, for example if data is received into the user buffer at interrupt time while the application is in a blocking hook. In this case, the blocking operation will return successfully as if WSACancelBlockingCall() had never been called. Note that the WSACancelBlockingCall() still succeeds in this case; the only way to know with certainty that an operation was actually canceled is to check for a return code of WSAEINTR from the blocking call.

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVAL
Indicates that there is no outstanding blocking call.

4.3.10 WSACleanup()

Description
Terminate use of the Windows Sockets DLL.
#include <winsock.h>

int PASCAL FAR WSACleanup ( void );
Remarks
An application or DLL is required to perform a (successful) WSAStartup() call before it can use Windows Sockets services. When it has completed the use of Windows Sockets, the application or DLL must call WSACleanup() to deregister itself from a Windows Sockets implementation and allow the implementation to free any resources allocated on behalf of the application or DLL. Any open SOCK_STREAM sockets that are connected when WSACleanup() is called are reset; sockets which have been closed with closesocket() but which still have pending data to be sent are not affected--the pending data is still sent.

There must be a call to WSACleanup() for every call to WSAStartup() made by a task. Only the final WSACleanup() for that task does the actual cleanup; the preceding calls simply decrement an internal reference count in the Windows Sockets DLL. A naive application may ensure that WSACleanup() was called enough times by calling WSACleanup() in a loop until it returns WSANOTINITIALISED.

Return Value
The return value is 0 if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Comments
Attempting to call WSACleanup() from within a blocking hook and then failing to check the return code is a common Windows Sockets programming error. If an application needs to quit while a blocking call is outstanding, the application must first cancel the blocking call with WSACancelBlockingCall() then issue the WSACleanup() call once control has been returned to the application.

Notes For Windows Sockets Suppliers
Well-behaved Windows Sockets applications will make a WSACleanup() call to indicate deregistration from a Windows Sockets implementation. This function can thus, for example, be utilized to free up resources allocated to the specific application.

A Windows Sockets implementation must be prepared to deal with an application which terminates without invoking WSACleanup() - for example, as a result of an error.

In a multithreaded environment, WSACleanup() terminates Windows Sockets operations for all threads.

A Windows Sockets implementation must ensure that WSACleanup() leaves things in a state in which the application can invoke WSAStartup() to re-establish Windows Sockets usage.

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

See Also
WSAStartup()

4.3.11 WSAGetLastError()

Description
Get the error status for the last operation which failed.
#include <winsock.h>

int PASCAL FAR WSAGetLastError ( void );
Remarks
This function returns the last network error that occurred. When a particular Windows Sockets API function indicates that an error has occurred, this function should be called to retrieve the appropriate error code.

Return Value
The return value indicates the error code for the last Windows Sockets API routine performed by this thread.

Notes For Windows Sockets Suppliers
The use of the WSAGetLastError() function to retrieve the last error code, rather than relying on a global error variable (cf. errno), is required in order to provide compatibility with future multi-threaded environments.

Note that in a nonpreemptive Windows environment WSAGetLastError() is used to retrieve only Windows Sockets API errors. In a preemptive environment, WSAGetLastError() will invoke GetLastError(), which is used to retrieve the error status for all Win32 API functions on a per-thread basis. For portability, an application should use WSAGetLastError() immediately after the Windows Sockets API function which failed.

See Also
WSASetLastError()

4.3.12 WSAIsBlocking()

Description
Determine if a blocking call is in progress.
#include <winsock.h>

BOOL PASCAL FAR WSAIsBlocking ( void );
Remarks
This function allows a task to determine if it is executing while waiting for a previous blocking call to complete.

Return Value
The return value is TRUE if there is an outstanding blocking function awaiting completion. Otherwise, it is FALSE.

Comments
Although a call issued on a blocking socket appears to an application program as though it "blocks", the Windows Sockets DLL has to relinquish the processor to allow other applications to run. This means that it is possible for the application which issued the blocking call to be re-entered, depending on the message(s) it receives. In this instance, the WSAIsBlocking() function can be used to ascertain whether the task has been re- entered while waiting for an outstanding blocking call to complete. Note that Windows Sockets prohibits more than one outstanding call per thread.

Notes For Windows Sockets Suppliers
A Windows Sockets implementation must prohibit more than one outstanding blocking call per thread.

4.3.13 WSASetBlockingHook()

Description
Establish an application-specific blocking hook function.
#include <winsock.h>

FARPROC PASCAL FAR WSASetBlockingHook ( FARPROC lpBlockFunc );
lpBlockFunc
A pointer to the procedure instance address of the blocking function to be installed.

Remarks
This function installs a new function which a Windows Sockets implementation should use to implement blocking socket function calls.

A Windows Sockets implementation includes a default mechanism by which blocking socket functions are implemented. The function WSASetBlockingHook() gives the application the ability to execute its own function at "blocking" time in place of the default function.

When an application invokes a blocking Windows Sockets API operation, the Windows Sockets implementation initiates the operation and then enters a loop which is similar to the following pseudocode:

for(;;) {
    /* flush messages for good user response */
    while(BlockingHook())
        ;
    /* check for WSACancelBlockingCall() */
    if(operation_cancelled())
        break;
    /* check to see if operation completed */
    if(operation_complete())
        break;     /* normal completion */
}
Note that Windows Sockets implementations may perform the above steps in a different order; for example, the check for operation complete may occur before calling the blocking hook. The default BlockingHook() function is equivalent to:
BOOL DefaultBlockingHook(void) {
    MSG msg;
    BOOL ret;
    /* get the next message if any */
    ret = (BOOL)PeekMessage(&msg,NULL,0,0,PM_REMOVE);
    /* if we got one, process it */
    if (ret) {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }
    /* TRUE if we got a message */
    return ret;
}
The WSASetBlockingHook() function is provided to support those applications which require more complex message processing - for example, those employing the MDI (multiple document interface) model. It is not intended as a mechanism for performing general applications functions. In particular, the only Windows Sockets API function which may be issued from a custom blocking hook function is WSACancelBlockingCall(), which will cause the blocking loop to terminate.

This function must be implemented on a per-task basis for non-multithreaded versions of Windows and on a per-thread basis for multithreaded versions of Windows such as Windows NT. It thus provides for a particular task or thread to replace the blocking mechanism without affecting other tasks or threads.

In multithreaded versions of Windows, there is no default blocking hook--blocking calls block the thread that makes the call. However, an application may install a specific blocking hook by calling WSASetBlockingHook(). This allows easy portability of applications that depend on the blocking hook behavior.

Return Value
The return value is a pointer to the procedure-instance of the previously installed blocking function. The application or library that calls the WSASetBlockingHook () function should save this return value so that it can be restored if necessary. (If "nesting" is not important, the application may simply discard the value returned by WSASetBlockingHook() and eventually use WSAUnhookBlockingHook() to restore the default mechanism.) If the operation fails, a NULL pointer is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.

See Also
WSAUnhookBlockingHook()

4.3.14 WSASetLastError()

Description
Set the error code which can be retrieved by WSAGetLastError().
#include <winsock.h>

void PASCAL FAR WSASetLastError ( int iError );
iError
Specifies the error code to be returned by a subsequent WSAGetLastError() call.

Remarks
This function allows an application to set the error code to be returned by a subsequent WSAGetLastError() call for the current thread. Note that any subsequent Windows Sockets routine called by the application will override the error code as set by this routine.

Notes For Windows Sockets Suppliers
In a Win32 environment, this function will invoke SetLastError().

Return Value
None.

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

See Also
WSAGetLastError()

4.3.15 WSAStartup()

Description
#include <winsock.h>

int PASCAL FAR WSAStartup ( WORD wVersionRequested,
                            LPWSADATA lpWSAData );
wVersionRequested
The highest version of Windows Sockets API support that the caller can use. The high order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

lpWSAData
A pointer to the WSADATA data structure that is to receive details of the Windows Sockets implementation.

Remarks
This function MUST be the first Windows Sockets function called by an application or DLL. It allows an application or DLL to specify the version of Windows Sockets API required and to retrieve details of the specific Windows Sockets implementation. The application or DLL may only issue further Windows Sockets API functions after a successful WSAStartup() invocation.

In order to support future Windows Sockets implementations and applications which may have functionality differences from Windows Sockets 1.1, a negotiation takes place in WSAStartup(). The caller of WSAStartup() and the Windows Sockets DLL indicate to each other the highest version that they can support, and each confirms that the other's highest version is acceptable. Upon entry to WSAStartup(), the Windows Sockets DLL examines the version requested by the application. If this version is higher than the lowest version supported by the DLL, the call succeeds and the DLL returns in wHighVersion the highest version it supports and in wVersion the minimum of its high version and wVersionRequested. The Windows Sockets DLL then assumes that the application will use wVersion. If the wVersion field of the WSADATA structure is unacceptable to the caller, it should call WSACleanup() and either search for another Windows Sockets DLL or fail to initialize.

This negotiation allows both a Windows Sockets DLL and a Windows Sockets application to support a range of Windows Sockets versions. An application can successfully utilize a Windows Sockets DLL if there is any overlap in the version ranges. The following chart gives examples of how WSAStartup() works in conjunction with different application and Windows Sockets DLL versions:

App       DLL       wVersion   wVersion  wHighVersion  End Result
versions  versions  Requested
1.1       1.1       1.1        1.1       1.1           use 1.1
1.0, 1.1  1.0       1.1        1.0       1.0           use 1.0
1.0       1.0, 1.1  1.0        1.0       1.1           use 1.0
1.1       1.0, 1.1  1.1        1.1       1.1           use 1.1
1.1       1.0       1.1        1.0       1.0           Application fails
1.0       1.1       1.0        ---       ---           WSAVERNOTSUPPORTED
1.0, 1.1  1.0, 1.1  1.1        1.1       1.1           use 1.1
1.1, 2.0  1.1       2.0        1.1       1.1           use 1.1
2.0       1.1       2.0        1.1       1.1           Application fails
The following code fragment demonstrates how an application which supports only version 1.1 of Windows Sockets makes a WSAStartup() call:
    WORD wVersionRequested;
    WSADATA wsaData;
    int err;

    wVersionRequested = MAKEWORD( 1, 1 );

    err = WSAStartup( wVersionRequested, &wsaData );
    if ( err != 0 ) {
        /* Tell the user that we couldn't find a useable */
        /* winsock.dll.                                  */
        return;
    }

    /* Confirm that the Windows Sockets DLL supports 1.1.*/
    /* Note that if the DLL supports versions greater    */
    /* than 1.1 in addition to 1.1, it will still return */
    /* 1.1 in wVersion since that is the version we      */
    /* requested.                                        */

    if ( LOBYTE( wsaData.wVersion ) != 1 ||
            HIBYTE( wsaData.wVersion ) != 1 ) {
        /* Tell the user that we couldn't find a useable */
        /* winsock.dll.                                  */
        WSACleanup( );
        return;
    }

    /* The Windows Sockets DLL is acceptable.  Proceed.  */
And this code fragment demonstrates how a Windows Sockets DLL which supports only version 1.1 performs the WSAStartup() negotiation:
    /* Make sure that the version requested is >= 1.1.   */
    /* The low byte is the major version and the high    */
    /* byte is the minor version.                        */

    if ( LOBYTE( wVersionRequested ) < 1 ||
        ( LOBYTE( wVersionRequested ) == 1 &&
        HIBYTE( wVersionRequested ) < 1 ) {
        return WSAVERNOTSUPPORTED;
    }

    /* Since we only support 1.1, set both wVersion and  */
    /* wHighVersion to 1.1.                              */

    lpWsaData->wVersion = MAKEWORD( 1, 1 );
    lpWsaData->wHighVersion = MAKEWORD( 1, 1 );
Once an application or DLL has made a successful WSAStartup() call, it may proceed to make other Windows Sockets API calls as needed. When it has finished using the services of the Windows Sockets DLL, the application or DLL must call WSACleanup() in order to allow the Windows Sockets DLL to free any resources for the application.

Details of the actual Windows Sockets implementation are described in the WSAData structure defined as follows:

struct WSAData {
    WORD            wVersion;
    WORD            wHighVersion;
    char            szDescription[WSADESCRIPTION_LEN+1];
    char            szSystemStatus[WSASYSSTATUS_LEN+1];
    unsigned short  iMaxSockets;
    unsigned short  iMaxUdpDg;
    char FAR *      lpVendorInfo;
};
The members of this structure are:

wVersion
The version of the Windows Sockets specification that the Windows Sockets DLL expects the caller to use.

wHighVersion
The highest version of the Windows Sockets specification that this DLL can support (also encoded as above). Normally this will be the same as wVersion.

szDescription
A null-terminated ASCII string into which the Windows Sockets DLL copies a description of the Windows Sockets implementation, including vendor identification. The text (up to 256 characters in length) may contain any characters, but vendors are cautioned against including control and formatting characters: the most likely use that an application will put this to is to display it (possibly truncated) in a status message.

szSystemStatus
A null-terminated ASCII string into which the Windows Sockets DLL copies relevant status or configuration information. The Windows Sockets DLL should use this field only if the information might be useful to the user or support staff: it should not be considered as an extension of the szDescription field.

iMaxSockets
The maximum number of sockets which a single process can potentially open. A Windows Sockets implementation may provide a global pool of sockets for allocation to any process; alternatively it may allocate per-process resources for sockets. The number may well reflect the way in which the Windows Sockets DLL or the networking software was configured. Application writers may use this number as a crude indication of whether the Windows Sockets implementation is usable by the application. For example, an X Windows server might check iMaxSockets when first started: if it is less than 8, the application would display an error message instructing the user to reconfigure the networking software. (This is a situation in which the szSystemStatus text might be used.) Obviously there is no guarantee that a particular application can actually allocate iMaxSockets sockets, since there may be other Windows Sockets applications in use.

iMaxUdpDg
The size in bytes of the largest UDP datagram that can be sent or received by a Windows Sockets application. If the implementation imposes no limit, iMaxUdpDg is zero. In many implementations of Berkeley sockets, there is an implicit limit of 8192 bytes on UDP datagrams (which are fragmented if necessary). A Windows Sockets implementation may impose a limit based, for instance, on the allocation of fragment reassembly buffers. The minimum value of iMaxUdpDg for a compliant Windows Sockets implementation is 512. Note that regardless of the value of iMaxUdpDg, it is inadvisable to attempt to send a broadcast datagram which is larger than the Maximum Transmission Unit (MTU) for the network. (The Windows Sockets API does not provide a mechanism to discover the MTU, but it must be no less than 512 bytes.)

lpVendorInfo
A far pointer to a vendor-specific data structure. The definition of this structure (if supplied) is beyond the scope of this specification.

An application or DLL may call WSAStartup() more than once if it needs to obtain the WSAData structure information more than once. However, the wVersionRequired parameter is assumed to be the same on all calls to WSAStartup(); that is, an application or DLL cannot change the version of Windows Sockets it expects after the initial call to WSAStartup().

There must be one WSACleanup() call corresponding to every WSAStartup() call to allow third-party DLLs to make use of a Windows Sockets DLL on behalf of an application. This means, for example, that if an application calls WSAStartup() three times, it must call WSACleanup() three times. The first two calls to WSACleanup() do nothing except decrement an internal counter; the final WSACleanup() call for the task does all necessary resource deallocation for the task.

Return Value
WSAStartup() returns zero if successful. Otherwise it returns one of the error codes listed below. Note that the normal mechanism whereby the application calls WSAGetLastError() to determine the error code cannot be used, since the Windows Sockets DLL may not have established the client data area where the "last error" information is stored.

Notes For Windows Sockets Suppliers
Each Windows Sockets application MUST make a WSAStartup() call before issuing any other Windows Sockets API calls. This function can thus be utilized for initialization purposes.

Further issues are discussed in the notes for WSACleanup().

Error Codes
WSASYSNOTREADY
Indicates that the underlying network subsystem is not ready for network communication.

WSAVERNOTSUPPORTED The version of Windows Sockets API support requested is not provided by this particular Windows Sockets implementation.

WSAEINVAL
The Windows Sockets version specified by the application is not supported by this DLL.

See Also
send(), sendto(), WSACleanup()

4.3.16 WSAUnhookBlockingHook()

Description
Restore the default blocking hook function.
#include <winsock.h>

int PASCAL FAR WSAUnhookBlockingHook ( void );
Remarks
This function removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

WSAUnhookBlockingHook() will always install the default mechanism, not the previous mechanism. If an application wish to nest blocking hooks - i.e. to establish a temporary blocking hook function and then revert to the previous mechanism (whether the default or one established by an earlier WSASetBlockingHook()) - it must save and restore the value returned by WSASetBlockingHook(); it cannot use WSAUnhookBlockingHook().

In multithreaded versions of Windows such as Windows NT, there is no default blocking hook. Calling WSAUnhookBlockingHook() disables any blocking hook installed by the application and any blocking calls made block the thread which made the call.

Return Value
The return value is 0 if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes
WSANOTINITIALISED
A successful WSAStartup() must occur before using this API.

See Also
WSASetBlockingHook()


NEXT PREVIOUS CONTENTS