-x@-Cw;g*111(Y EEE*o;;;;/;g\Lzzzz,$4Yy.K




EMBED PBrush \s \* mergeformatWindows
Sockets


Windows Sockets
An Open Interface for
Network Programming under
MicrosoftSYMBOL 226 \f "Symbol" WindowsSYMBOL 228 \f "Symbol"

Version 1.0 Rev.A


date \@ "d MMMM, yyyy"11 June, 1992


Martin Hall
JSB Corporation

Mark Towfiq
FTP Software, Inc.

Geoff Arnold
Sun Microsystems, Inc.

David Treadwell
Microsoft Corporation

Henry Sanders
Microsoft Corporation













Copyright SYMBOL 211 \f "Symbol" 1992 by Martin Hall, Mark Towfiq
Geoff Arnold, David Treadwell and Henry Sanders

All rights reserved.

This document may be freely redistributed in any form, electronic or otherwise, provided that it is distributed in its entirety and that the copyright and this notice are included. Comments or questions may be submitted via electronic mail to [email protected]. Requests to be added to the Windows Sockets mailing list should be addressed to [email protected]. Questions about products conforming to this specification should be addressed to the vendors of the products.
Windows Sockets
Version 1.0
CONTENTS
1. INTRODUCTION
1.1 What is Windows Sockets?
1.2 Berkeley Sockets
1.3 Microsoft Windows and Windows-specific extensions
1.4 The Status of this Specification

2. PROGRAMMING WITH SOCKETS
2.1 Windows Sockets Stack Installation checking
2.2 Sockets
2.2.1 Basic concepts
2.2.2 Client-server model
2.2.3 Out-of-band data
2.2.4 Broadcasting
2.3 Byte Ordering
2.4 Socket Options
2.5 Database Files
2.6 Deviation from Berkeley Sockets
2.6.1 socket data type and error values
2.6.2 select() and FD_*
2.6.3 Error codes - errno & WSAGetLastError()
2.6.4 Pointers
2.6.5 Renamed functions
2.6.5.1close() & closesocket()
2.6.5.2ioctl() & ioctlsocket()
2.6.6 Blocking routines & EINPROGRESS
2.6.7 Maximum number of sockets supported
2.6.8 Include files
2.6.9 Return values on API failure

3. SOCKET LIBRARY OVERVIEW
3.1 Socket Functions
3.1.1 Blocking/Non blocking & Data Volatility
3.2 Database Functions
3.3 Microsoft Windows Extension Functions
3.3.1 Asynchronous select() Mechanism
3.3.2 Asynchronous Support Routines
3.3.3 Hooking Blocking Methods
3.3.4 Error Handling

4. SOCKET LIBRARY REFERENCE
4.1 Socket Routines
4.1.1 accept()
4.1.2 bind()
4.1.3 closesocket()
4.1.4 connect()
4.1.5 getpeername()
4.1.6 getsockname()
4.1.7 getsockopt()
4.1.8 htonl()
4.1.9 htons()
4.1.10 inet_addr()
4.1.11 inet_ntoa()
4.1.12 ioctlsocket()
4.1.13 listen()
4.1.14 ntohl()
4.1.15 ntohs()
4.1.16 recv()
4.1.17 recvfrom()
4.1.18 select()
4.1.18 send()
4.1.19 sendto()
4.1.20 setsockopt()
4.1.21 shutdown()
4.1.22 socket()

4.2 Database Routines
4.2.1 gethostbyname()
4.2.2 gethostbyaddr()
4.2.3 getprotobyname()
4.2.4 getprotobynumber()
4.2.5 getservbyname()
4.2.6 getservbyport()

4.3 Microsoft Windows-specific Extensions
4.3.1 WSAAsyncGetHostByAddr()
4.3.2 WSAAsyncGetHostByName()
4.3.3 WSAAsyncGetProtoByName()
4.3.4 WSAAsyncGetProtoByNumber()
4.3.5 WSAAsyncGetServByName()
4.3.6 WSAAsyncGetServByPort()
4.3.7 WSAAsyncSelect()
4.3.8 WSACancelAsyncRequest()
4.3.9 WSACancelBlockingCall()
4.3.10 WSACleanup()
4.3.11 WSAGetLastError()
4.3.12 WSAIsBlocking()
4.3.13 WSASetBlockingHook()
4.3.14 WSASetLastError()
4.3.15 WSAStartup()
4.3.16 WSAUnhookBlockingHook()

APPENDICES
AError Codes and Header Files
A.1 Error Codes
A.2 Header Files
A.2.1 Berkeley Header Files
A.2.2 Windows Sockets Header File - winsock.h

BNotes for Windows Sockets Suppliers
B.1 Introduction
B.2 Windows Sockets Components
B.2.1 Development Components
B.2.2 Run Time Components
B.3 Multithreadedness and blocking routines
B.4 Database Files
B.5 FD_ISSET
B.6 Error Codes
B.7 DLL Ordinal Numbers
B.8 Validation Suite

CBackground Information
C.1 Origins of Windows Sockets
C.2 Roadmap
1. INTRODUCTION
1.1 What is Windows Sockets?
The Windows Sockets specification defines a network programming interface for Microsoft Windows which is based on the "socket" paradigm popularized in the Berkeley Software Distribution (BSD) from the University of California at Berkeley. It encompasses both familiar Berkeley socket style routines and a set of Windows-specific extensions designed to allow the programmer to take advantage of the message-driven nature of Windows.

The Windows Sockets Specification is intended to provide a single API to which application developers can program and multiple network software vendors can conform. Furthermore, in the context of a particular version of Microsoft Windows, it defines a binary interface (ABI) such that an application written to the Windows Sockets API can work with a conformant protocol implementation from any network software vendor. This specification thus defines the library calls and associated semantics to which an application developer can program and which a network software vendor can implement.

Network software which conforms to this Windows Sockets specification will be considered "Windows Sockets Compliant". Suppliers of interfaces which are "Windows Sockets Compliant" shall be referred to as "Windows Sockets Suppliers". To be Windows Sockets Compliant, a vendor must implement 100% of this Windows Sockets specification.

Applications which are capable of operating with any "Windows Sockets Compliant" protocol implementation will be considered as having a "Windows Sockets Interface" and will be referred to as "Windows Sockets Applications".

This version of the Windows Sockets specification defines and documents the use of the API in conjunction with the Internet Protocol Suite (IPS, generally referred to as TCP/IP). Specifically, all Windows Sockets implementations support both stream (TCP) and datagram (UDP) sockets.

While the use of this API with alternative protocol stacks is not precluded (and is expected to be the subject of future revisions of the specification), such usage is beyond the scope of this version of the specification.

1.2 Berkeley Sockets
The Windows Sockets Specification has been built upon the Berkeley Sockets programming model which is the de facto standard for TCP/IP networking. It is intended to provide a high degree of familiarity for programmers who are used to programming with sockets in UNIX and other environments, and to simplify the task of porting existing sockets-based source code. The Windows Sockets API is consistent with release 4.3 of the Berkeley Software Distribution (4.3BSD).

Portions of the Windows Sockets specification are derived from material which is Copyright (c) 1982-1986 by the Regents of the University of California. All rights are reserved. The Berkeley Software License Agreement specifies the terms and conditions for redistribution.

1.3 Microsoft Windows and Windows-specific extensions
This API is intended to be usable within all implementations and versions of Microsoft Windows from Microsoft Windows Version 3.0 onwards. It thus provides for Windows Sockets implementations and Windows Sockets applications in both 16 and 32 bit operating environments.

Windows Sockets makes provisions for multithreaded Windows processes. A process contains one or more threads of execution. In the Win16 non-multithreaded world, a task corresponds to a process with a single thread. All references to threads in this document refer to actual "threads" in multithreaded Windows environments. In non multithreaded environments (such as Windows 3.0), use of the term thread refers to a Windows process.

The Microsoft Windows extensions included in Windows Sockets are provided to allow application developers to create software which conforms to the Windows programming model. It is expected that this will facilitate the creation of robust and high-performance applications, and will improve the cooperative multitasking of applications within non-preemptive versions of Windows. With the exception of WSAStartup() and WSACleanup() their use is not mandatory.

1.4 The Status of this Specification
This document is version 1.0 of the Windows Sockets Specification. It represents the results of considerable work within the vendor and user community, as described in Appendix C. This version of the specification has been released in order that network software suppliers and applications developers can begin to construct implementations and applications which conform to the standard. As with any specification, we anticipate that changes will be necessary, as the users of the standard gain experience with it, and Appendix C describes the way in which this change is expected to occur.
2. PROGRAMMING WITH SOCKETS
2.1 Windows Sockets Stack Installation Checking
To detect the presence of one (or many) Windows Sockets implementations on a system, an application which has been linked with the Windows Sockets Import Library may simply call the WSAStartup() routine. If an application wishes to be a little more sophisticated it can examine the $PATH environment variable and search for instances of Windows Sockets implementations (WINSOCK.DLL). For each instance it can issue a LoadLibrary() call and use the WSAStartup() routine to discover implementation specific data.

This version of the Windows Sockets specification does not attempt to address explicitly the issue of multiple concurrent Windows Sockets implementations. Nothing in the specification should be interpreted as restricting multiple Windows Sockets DLLs from being present and used concurrently by one or more Windows Sockets applications.

2.2 Sockets
The following material is derived from the document "An Advanced 4.3BSD Interprocess Communication Tutorial" by Samuel J. Leffler, Robert S. Fabry, William N. Joy, Phil Lapsley, Steve Miller, and Chris Torek.

2.2.1 Basic concepts
The basic building block for communication is the socket. A socket is an endpoint of communication to which a name may be bound. Each socket in use has a type and an associated process. Sockets exist within communication domains. A communication domain is an abstraction introduced to bundle common properties of threads communicating through sockets. Sockets normally exchange data only with sockets in the same domain (it may be possible to cross domain boundaries, but only if some translation process is performed). The Windows Sockets facilities support a single communication domain: the Internet domain, which is used by processes which communicate using the Internet Protocol Suite. (Future versions of this specification may include additional domains.)

Sockets are typed according to the communication properties visible to a user. Applications are presumed to communicate only between sockets of the same type, although there is nothing that prevents communication between sockets of different types should the underlying communication protocols support this.

Two types of sockets currently are available to a user. A stream socket provides for the bi-directional, reliable, sequenced, and unduplicated flow of data without record boundaries.

A datagram socket supports bi-directional flow of data which is not promised to be sequenced, reliable, or unduplicated. That is, a process receiving messages on a datagram socket may find messages duplicated, and, possibly, in an order different from the order in which it was sent. An important characteristic of a datagram socket is that record boundaries in data are preserved. Datagram sockets closely model the facilities found in many contemporary packet switched networks such as Ethernet.

2.2.2 Client-server model
The most commonly used paradigm in constructing distributed applications is the client/server model. In this scheme client applications request services from a server application. This implies an asymmetry in establishing communication between the client and server.

The client and server require a well-known set of conventions before service may be rendered (and accepted). This set of conventions comprises a protocol which must be implemented at both ends of a connection. Depending on the situation, the protocol may be symmetric or asymmetric. In a symmetric protocol, either side may play the master or slave roles. In an asymmetric protocol, one side is immutably recognized as the master, with the other as the slave. An example of a symmetric protocol is the TELNET protocol used in the Internet for remote terminal emulation. An example of an asymmetric protocol is the Internet file transfer protocol, FTP. No matter whether the specific protocol used in obtaining a service is symmetric or asymmetric, when accessing a service there is a "client process'' and a "server process''.

A server application normally listens at a well-known address for service requests. That is, the server process remains dormant until a connection is requested by a client's connection to the server's address. At such a time the server process "wakes up'' and services the client, performing whatever appropriate actions the client requests of it. While connection-based services are the norm, some services are based on the use of datagram sockets.

2.2.3 Out-of-band data
Note: The following discussion of out-of-band data, also referred to as TCP Urgent data, follows the model used in the Berkeley software distribution. Users and implementors should be aware of the fact that there are at present two conflicting interpretations of RFC 793 (in which the concept is introduced), and that the implementation of out-of-band data in the Berkeley Software Distribution does not conform to the Host Requirements laid down in RFC 1122. To minimize interoperability problems, applications writers are advised not to use out-of-band data unless this is required in order to interoperate with an existing service. Windows Sockets suppliers are urged to document the out-of-band semantics (BSD or RFC 1122) which their product implements. It is beyond the scope of this specification to mandate a particular set of semantics for out-of-band data handling.

The stream socket abstraction includes the notion of "out of band'' data. Out-of-band data is a logically independent transmission channel associated with each pair of connected stream sockets. Out-of-band data is delivered to the user independently of normal data. The abstraction defines that the out-of-band data facilities must support the reliable delivery of at least one out-of-band message at a time. This message may contain at least one byte of data, and at least one message may be pending delivery to the user at any one time. For communications protocols which support only in-band signaling (i.e. the urgent data is delivered in sequence with the normal data), the system normally extracts the data from the normal data stream and stores it separately. This allows users to choose between receiving the urgent data in order and receiving it out of sequence without having to buffer all the intervening data. It is possible to "peek'' at out-of-band data.

An application may prefer to process out-of-band data "in-line", as part of the normal data stream. This is achieved by setting the socket option SO_OOBINLINE (see section 4.1.20, setsockopt()). In this case, the application may wish to determine whether any of the unread data is "urgent" (the term usually applied to in-line out-of-band data). To facilitate this, the Windows Sockets implementation will maintain a logical "mark" in the data stream indicate the point at which the out-of-band data was sent. An application can use the SIOCATMARK ioctlsocket() command (see 4.1.12) to determine whether there is any unread data preceding the mark. For example, it might use this to resynchronize with its peer by ensuring that all data up to the mark in the data stream is discarded when appropriate.

The WSAAsyncSelect() routine is particularly well suited to handling notification of the presence of out-of-band-data.

2.2.4 Broadcasting
By using a datagram socket, it is possible to send broadcast packets on many networks supported by the system. The network itself must support broadcast: the system provides no simulation of broadcast in software. Broadcast messages can place a high load on a network, since they force every host on the network to service them. Consequently, the ability to send broadcast packets has been limited to sockets which are explicitly marked as allowing broadcasting. Broadcast is typically used for one of two reasons: it is desired to find a resource on a local network without prior knowledge of its address, or important functions such as routing require that information be sent to all accessible neighbors.

The destination address of the message to be broadcast depends on the network(s) on which the message is to be broadcast. The Internet domain supports a shorthand notation for broadcast on the local network, the address INADDR_BROADCAST. Received broadcast messages contain the senders address and port, as datagram sockets must be bound before use.

Some types of network support the notion of different types of broadcast. For example, the IEEE 802.5 token ring architecture supports the use of link-level broadcast indicators, which control whether broadcasts are forwarded by bridges. The Windows Sockets specification does not provide any mechanism whereby an application can determine the type of underlying network, nor any way to control the semantics of broadcasting.

2.3 Byte Ordering
The Intel byte ordering is like that of the DEC VAX, and therefore differs from the Internet and 68000-type processor byte ordering. Thus care must be taken to ensure correct orientation.

Consider an application which normally contacts a server on the TCP port corresponding to the "time" service, but which provides a mechanism for the user to specify that an alternative port is to be used. The port number returned by getservbyname() is already in network order, which is the format required constructing an address, so no translation is required. However if the user elects to use a different port, entered as an integer, the application must convert this from host to network order (using the htons() function) before using it to construct an address. Conversely, if the application wishes to display the number of the port within an address (returned via, e.g., getpeername()), the port number must be converted from network to host order (using ntohs()) before it can be displayed.

Since the Intel and Internet byte orders are different, the conversions described above are unavoidable. Application writers are cautioned that they should use the standard conversion functions provided as part of the Windows Sockets API rather than writing their own conversion code, since future implementations of Windows Sockets are likely to run on systems for which the host order is identical to the network byte order. Only applications which use the standard conversion functions are likely to be portable.

2.4 Socket Options
The socket options supported by Windows Sockets are listed in the pages describing setsockopt() and getsockopt(). A Windows Sockets implementation must recognize all of these options, and (for getsockopt()) return plausible values for each. The default value for each option is shown in the following table.

Value
Type
Meaning
Default
Note

SO_ACCEPTCON
BOOL
Socket is listen()ing.
FALSE unless a listen() has been performed


SO_BROADCAST
BOOL
Socket is configured for the transmission of broadcast messages.
FALSE


SO_DEBUG
BOOL
Debugging is enabled.
FALSE
(i)

SO_DONTLINGER
BOOL
If true, the SO_LINGER option is disabled..
TRUE


SO_DONTROUTE
BOOL
Routing is disabled.
FALSE
(i)

SO_ERROR
int
Retrieve error status and clear.
0


SO_KEEPALIVE
BOOL
Keepalives are being sent.
FALSE


SO_LINGER
struct linger FAR *
Returns the current linger options.
l_onoff is 0


SO_OOBINLINE
BOOL
Out-of-band data is being received in the normal data stream.
FALSE


SO_RCVBUF
int
Buffer size for receives
Implementation dependent
(i)

SO_REUSEADDR
BOOL
The address to which this socket is bound can be used by others.
FALSE


SO_SNDBUF
int
Buffer size for sends
Implementation dependent
(i)

SO_TYPE
int
The type of the socket (e.g. SOCK_STREAM).
As created via socket()



Notes:
(i)An implementation may silently ignore this option on setsockopt() and return a constant value for getsockopt(), or it may accept a value for setsockopt() and return the corresponding value in getsockopt() without using the value in any way.


2.5 Database Files
The getXbyY() and WSAAsyncGetXByY() classes of routines are provided for retrieving network specific information. The getXbyY() routines were originally designed (in the first Berkeley UNIX releases) as mechanisms for looking up information in text databases. Although the information may be retrieved by the Windows Sockets implementation in different ways, a Windows Sockets application requests such information in a consistent manner through either the getXbyY() or the WSAAsyncGetXByY() class of routines.

2.6 Deviation from Berkeley Sockets
There are a few limited instances where the Windows Sockets API has had to divert from strict adherence to the Berkeley conventions, usually because of difficulties of implementation in a Windows environment.

2.6.1 socket data type and error values
A new data type, SOCKET, has been defined. The definition of this type was necessary for future enhancements to the Windows Sockets specification, such as being able to use sockets as file handles in Windows/NT. Definition of this type also facilitates porting of applications to a Win/32 environment, as the type will automatically be promoted from 16 to 32 bits.

Because the SOCKET type is unsigned, compiling existing source code from, for example, a UNIX environment may lead to compiler warnings about signed/unsigned data type mismatches.

This means, for example, that checking for errors when the socket() and accept() routines return should not be done by comparing the return value with -1, or seeing if the value is negative (both common, and legal, approaches in BSD). Instead, an application should use the manifest constant INVALID_SOCKET as defined in winsock.h. For example:
TYPICAL BSD STYLE:
s = socket(...);
if (s == -1)/* or s < 0 */
{...}

PREFERRED STYLE:
s = socket(...);
if (s == INVALID_SOCKET)
{...}

2.6.2 select() and FD_*
Because a SOCKET is no longer represented by the UNIX-style "small non-negative integer", the implementation of the select() function was changed in the Windows Sockets API. Each set of descriptors is still represented by the fd_set type, but instead of being stored as a bitmask the set is implemented as an array of SOCKETs.. To avoid potential problems, applications must adhere to the use of the FD_XXX macros to set, initialize, clear, and check the fd_set structures.

2.6.3 Error codes - errno, h_errno & WSAGetLastError()
Error codes set by the Windows Sockets implementation are NOT made available via the errno variable. Additionally, for the getXbyY() class of functions, error codes are NOT made available via the h_errno variable. Instead, error codes are accessed by using the WSAGetLastError() API described in 4.3.11. This function is provided in Windows Sockets as a precursor (and eventually an alias) for the Win32 function GetLastError(). This is intended to provide a reliable way for a thread in a multi-threaded process to obtain per-thread error information.

For compatibility with BSD, an application may choose to include a line of the form:

#define errno WSAGetLastError()

This will allow networking code which was written to use the global errno to work correctly in a single-threaded environment. There are, obviously, some drawbacks. If a source file includes code which inspects errno for both socket and non-socket functions, this mechanism cannot be used. Furthermore, it is not possible for an application to assign a new value to errno. (In Windows Sockets the function WSASetLastError() may be used for this purpose.)

TYPICAL BSD STYLE:
r = recv(...);
if (r == -1
&& errno == EWOULDBLOCK)
{...}

PREFERRED STYLE:
r = recv(...);
if (r == -1 /* (but see below) */
&& WSAGetLastError() == EWOULDBLOCK)
{...}

Although error constants consistent with 4.3 Berkeley Sockets are provided for compatibility purposes, applications should, where possible, use the "WSA" error code definitions. For example, a more accurate version of the above source code fragment is:

r = recv(...);
if (r == -1
&& WSAGetLastError() == WSAEWOULDBLOCK)
{...}

2.6.4 Pointers
All pointers used by applications with Windows Sockets should be FAR. To facilitate this, data type definitions such as LPHOSTENT are provided.

2.6.5 Renamed functions
In two cases it was necessary to rename functions which are used in Berkeley Sockets in order to avoid clashes with other APIs.

2.6.5.1 close() & closesocket()
In Berkeley Sockets, sockets are represented by standard file descriptors, and so the close() function can be used to close sockets as well as regular files. While nothing in the Windows Sockets API prevents an implementation from using regular file handles to identify sockets, nothing requires it either. Socket descriptors are not presumed to correspond to regular file handles, and file operations such as read(), write(), and close() cannot be assumed to work correctly when applied to socket descriptors.. Sockets must be closed by using the closesocket() routine. Using the close() routine to close a socket is incorrect and the effects of doing so are undefined by this specification.

2.6.5.1 ioctl() & ioctlsocket()
Various C language run-time systems use the ioctl() routine for purposes unrelated to Windows Sockets. For this reason we have defined the routine ioctlsocket() which is used to handle socket functions which in the Berkeley Software Distribution are performed using ioctl() and fcntl().

2.6.6 Blocking routines & EINPROGRESS
Although blocking operations on sockets are supported under Windows Sockets, their use is strongly discouraged. Programmers who are constrained to use blocking mode - for example, as part of an existing application which is to be ported - should be aware of the semantics of blocking operations in Windows Sockets. See Section 3.1.1 for more details.

2.6.7 Maximum number of sockets supported
The maximum number of sockets supported by a particular Windows Sockets supplier is implementation specific. An application should make no assumptions about the availability of a certain number of sockets. This topic is addressed further in section 4.3.15, WSAStartup(). However, independent of the number of sockets supported by a particular implementation is the issue of the maximum number of sockets which an application can actually make use of.

The maximum number of sockets which a Windows Sockets application can make use of is determined at compile time by the manifest constant FD_SETSIZE. This value is used in constructing the fd_set structures used in select() (see section 4.1.18). The default value in winsock.h is 64. If an application is designed to be capable of working with more than 64 sockets, the implementor should define the manifest FD_SETSIZE in every source file before including winsock.h. One way of doing this may be to include the definition within the compiler options in the makefile. It must be emphasized that defining FD_SETSIZE as a particular value has no effect on the actual number of sockets provided by a Windows Sockets implementation.

2.6.8 Include files
For ease of portability of existing Berkeley sockets based source code, a number of standard Berkeley include files are supported. However, these Berkeley header files merely include the winsock.h include file, and it is therefore sufficient (and recommended) that Windows Sockets application source files should simply include winsock.h.

2.6.9 Return values on API failure
The manifest constant SOCKET_ERROR is provided for checking API failure. Although use of this constant is not mandatory, it is recommended. The following example illustrates the use of the SOCKET_ERROR constant:

TYPICAL BSD STYLE:
r = recv(...);
if (r == -1 /* or r < 0 */
&& errno == EWOULDBLOCK)
{...}
PREFERRED STYLE:
r = recv(...);
if (r == SOCKET_ERROR
&& WSAGetLastError() == WSAEWOULDBLOCK)
{...}
3. SOCKET LIBRARY OVERVIEW
3.1 Socket Functions
The Windows Sockets specification includes the following Berkeley-style socket routines:

accept()
An incoming connection is acknowledged and associated with an immediately created socket. The original socket is returned to the listening state.

bind()
Assign a local name to an unnamed socket.

closesocket()
Remove a socket descriptor from the per-process object reference table.

connect()
Initiate a connection on the specified socket.

getpeername()
Retrieve the name of the peer connected to the specified socket descriptor.

getsockname()
Retrieve the current name for the specified socket

getsockopt()
Retrieve options associated with the specified socket descriptor.

htonl()
Convert a 32-bit quantity from host byte order to network byte order.

htons()
Convert a 16-bit quantity from host byte order to network byte order.

inet_addr()
Converts a character string representing a number in the Internet standard ".'' notation to an Internet address value.

inet_ntoa()
Converts an Internet address value to an ASCII string in ".'' notation i.e. "a.b.c.d''.

ioctlsocket()
Provide control for descriptors.

listen()
Listen for incoming connections on a specified socket.

ntohl()
Convert a 32-bit quantity from network byte order to host byte order.

ntohs()
Convert a 16-bit quantity from network byte order to host byte order.

recv()
Receive data from a connected socket.

recvfrom()
Receive data from either a connected or unconnected socket.

select()
Perform synchronous I/O multiplexing.

send()
Send data to a connected socket.

sendto()
Send data to either a connected or unconnected socket.

setsockopt()
Store options associated with the specified socket descriptor.

shutdown()
Shut down part of a full-duplex connection.

socket()
Create an endpoint for communication and return a socket descriptor.


3.1.1 Blocking/Non blocking & Data Volatility
One major issue in porting applications from a Berkeley sockets environment to a Windows environment involves "blocking"; that is, invoking a function which does not return until the associated operation is completed. The problem arises when the operation may take an arbitrarily long time to complete: an obvious example is a recv() which may block until data has been received from the peer system. The default behavior within the Berkeley sockets model is for a socket to operate in a blocking mode unless the programmer explicitly requests that operations be treated as non-blocking.

Even on a blocking socket, some operations (e.g. bind(), getsockopt(), getpeername()) can be completed immediately. For such operations there is no difference between blocking and non-blocking operation. Other operations (e.g. recv()) may be completed immediately or may take an arbitrary time to complete, depending on various transport conditions. When applied to a blocking socket, these operations are referred to as blocking operations.

Within a Windows Sockets implementation, a blocking operation which cannot be completed immediately is handled as follows. The DLL initiates the operation, and then enters a loop in which it dispatches any Windows messages (yielding the processor to another thread if necessary) and then checks for the completion of the Windows Sockets function. If the function has completed, or if WSACancelBlockingCall() has been invoked, the blocking function completes with an appropriate result. Refer to section 4.3.13, WSASetBlockingHook(), for a complete description of this mechanism, including pseudocode for the various functions.

If a Windows message is received for a process for which a blocking operation is in progress, there is a risk that the application will attempt to issue another Windows Sockets call. Because of the difficulty of managing this condition safely, the Windows Sockets specification does not support such application behavior. Two functions are provided to assist the programmer in this situation. WSAIsBlocking() may be called to determine whether or not a blocking Windows Sockets call is in progress. WSACancelBlockingCall() may be called to cancel an in-progress blocking call, if any. Any other Windows Sockets function which is called in this situation will fail with the error WSAEINPROGRESS. It should be emphasized that this restriction applies to both blocking and non-blocking operations.

Although this mechanism is sufficient for simple applications, it cannot support the complex message-dispatching requirements of more advanced applications (for example, those using the MDI model). For such applications, the Windows Sockets API includes the function WSASetBlockingHook(), which allows the programmer to define a special routine which will be called instead of the default message dispatch routine described above.

If an application invokes an asynchronous or non-blocking operation which takes a pointer to a memory object (e.g. a buffer, or a global variable) as an argument, it is the responsibility of the application to ensure that the object is available to the Windows Sockets implementation throughout the operation. The application must not invoke any Windows function which might affect the mapping or addressability of the memory involved. In a multithreaded system, the application is also responsible for coordinating access to the object using appropriate synchronization mechanisms. A Windows Sockets implementation cannot, and will not, address these issues. The possible consequences of failing to observe these rules are beyond the scope of this specification.

3.2 Database Functions
The Windows Sockets specification defines the following "database" routines. As noted earlier, a Windows Sockets supplier may choose to implement these in a manner which does not depend on local database files. The pointer returned by certain database routines such as gethostbyname() points to a structure which is allocated by the Windows Sockets library. The data which is pointed to is volatile and is good only until the next Windows Sockets API call from that thread. Additionally, the application must never attempt to modify this structure or to free any of its components. Only one copy of this structure is allocated for a thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.


gethostbyaddr()
Retrieve the name(s) and address corresponding to a network address.

gethostbyname()
Retrieve the name(s) and address corresponding to a host name.

getprotobyname()
Retrieve the protocol name and number corresponding to a protocol name.

getprotobynumber()
Retrieve the protocol name and number corresponding to a protocol number.

getservbyname()
Retrieve the service name and port corresponding to a service name.

getservbyport()
Retrieve the service name and port corresponding to a port.


3.3 Microsoft Windows-specific Extension Functions
The Windows Sockets specification provides a number of extensions to the standard set of Berkeley Sockets routines. Principally, these extended APIs allow message-based, asynchronous access to network events. While use of this extended API set is not mandatory for socket-based programming, it is recommended for conformance with the Microsoft Windows programming paradigm.


WSAAsyncGetHostByAddr()
A set of functions which provide asynchronous

WSAAsyncGetHostByName()
versions of the standard Berkeley

WSAAsyncGetProtoByName()
getXbyY() functions. For example, the

WSAAsyncGetProtoByNumber()
WSAAsyncGetHostByName() function provides an

WSAAsyncGetServByName()
asynchronous message based implementation of

WSAAsyncGetServByPort()
the standard Berkeley gethostbyname() function.

WSAAsyncSelect()
Perform asynchronous version of select()

WSACancelAsyncRequest()
Cancel an outstanding instance of a WSAAsyncGetXByY() function.

WSACancelBlockingCall()
Cancel an outstanding "blocking" API call

WSACleanup()
Sign off from the underlying Windows Sockets DLL.

WSAGetLastError()
Obtain details of last Windows Sockets API error

WSAIsBlocking()
Determine if the underlying Windows Sockets DLL is already blocking an existing call for this thread

WSASetBlockingHook()
"Hook" the blocking method used by the underlying Windows Sockets implementation

WSASetLastError()
Set the error to be returned by a subsequent WSAGetLastError()

WSAStartup()
Initialize the underlying Windows Sockets DLL.

WSAUnhookBlockingHook()
Restore the original blocking function


3.3.1 Asynchronous select() Mechanism
The WSAAsyncSelect() API allows an application to register an interest in one or many network events. This API is provided to supersede the need to do polled network I/O. Any situation in which select() or non-blocking I/O routines (such as send() and recv()) are either already used or are being considered is usually a candidate for the WSAAsyncSelect() API. When declaring interest in such condition(s), you supply a window handle to be used for notification. The corresponding window then receives message-based notification of the conditions in which you declared an interest.

WSAAsyncSelect() allows interest to be declared in the following conditions for a particular socket:
Socket readiness for reading
Socket readiness for writing
Out-of-band data ready for reading
Socket readiness for accepting incoming connection
Completion of non-blocking connect()
Connection closure

3.3.2 Asynchronous Support Routines
The asynchronous "database" functions allow applications to request information in an asynchronous manner. Some network implementations and/or configurations perform network based operations to resolve such requests. The WSAAsyncGetXByY() functions allow application developers to request services which would otherwise block the operation of the whole Windows environment if the standard Berkeley function were used. The WSACancelAsyncRequest() function allows an application to cancel any outstanding asynchronous request.

3.3.3 Hooking Blocking Methods
As noted in Section 3.1.1 above, Windows Sockets implements blocking operations in such a way that Windows message processing can continue, which may result in the application which issued the call receiving a Windows message. In certain situations an application may want to influence or change the way in which this pseudo-blocking process is implemented. The WSASetBlockingHook() provides the ability to substitute a named routine which the Windows Sockets implementation is to use when relinquishing the processor during a "blocking" operation.

3.3.4 Error Handling
For compatibility with thread-based environments, details of API errors are obtained through the WSAGetLastError() API. Although the accepted "Berkeley-Style" mechanism for obtaining socket-based network errors is via "errno", this mechanism cannot guarantee the integrity of an error ID in a multi-threaded environment. WSAGetLastError() allows you to retrieve an error code on a per thread basis.

WSAGetLastError() returns error codes which avoid conflict with standard Microsoft C error codes. Certain error codes returned by certain Windows Sockets routines fall into the standard range of error codes as defined by Microsoft C. If you are NOT using an application development environment which defines error codes consistent with Microsoft C, you are advised to use the Windows Sockets error codes prefixed by "WSA" to ensure accurate error code detection.

Note that this specification defines a recommended set of error codes, and lists the possible errors which may be returned as a result of each function. It may be the case in some implementations that other Windows Sockets error codes will be returned in addition to those listed, and applications should be prepared to handle errors other than those enumerated under each API description. However a Windows Sockets implementation must not return any value which is not enumerated in the table of legal Windows Sockets errors given in Appendix A.1.
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()
DescriptionAccept a connection on a socket.

#include

SOCKET accept ( SOCKET s, struct sockaddr FAR * addr, int FAR * addrlen );


sA descriptor identifying a socket which is listening for connections after a listen().

addrThe 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.

addrlenA pointer to an integer which contains the length of the address addr.

RemarksThis 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.


Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULTThe address in the addr argument is the wrong size.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets call is in progress.

WSAEINVALlisten() was not invoked prior to accept().

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

WSAENOBUFSNo buffer space is available.

WSAENOTSOCKThe descriptor is not a socket.

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

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

See Alsobind(), connect(), listen(), select(), socket(), WSAAsyncSelect()
4.1.2 bind()
DescriptionAssociate a local address with a socket.

#include

int bind ( SOCKET s, struct sockaddr FAR * name, int namelen );


sA descriptor identifying an unbound socket.

nameThe address to assign to the socket. The sockaddr structure is defined as follows:

struct sockaddr {
u_shortsa_family;
charsa_data[14];
};

namelenThe length of the name.

RemarksThis 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.

If an application does not care what address is assigned to it, it may specify an Internet address and port equal to 0. If this is the case, the Windows Sockets implementation will assign a unique address to the application. The application may use getsockname() after bind() to learn the address that has been assigned to it.

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.


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

Error CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe 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().)

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

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets call is in progress.

WSAEAFNOSUPPORTThe specified address family is not supported by this protocol.

WSAEINVALThe socket is already bound to an address.

WSAENOBUFSNot enough buffers available, too many connections.

WSAENOTSOCKThe descriptor is not a socket.

See Alsoconnect(), listen(), getsockname(), setsockopt(), socket(), WSACancelBlockingCall().
4.1.3 closesocket()
DescriptionClose a socket.

#include

int closesocket ( SOCKET s );


sA descriptor identifying a socket.

RemarksThis 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:

OptionIntervalType of closeWait for close?
SO_DONTLINGERDon't careGracefulNo
SO_LINGERZeroHardNo
SO_LINGERNon-zeroGracefulYes

If SO_LINGER is set (i.e. the l_onoff field of the linger structure is non-zero; see sections 2.4, 4.1.8 and 4.1.20) 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" close, because the socket is closed immediately, and any unsent data is lost.

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.

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.8 and 4.1.20), 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOTSOCKThe descriptor is not a socket.

WSAEINPROGRESSA blocking Windows Sockets call is in progress.


See Alsoaccept(), socket(), ioctlsocket(), setsockopt(), WSAAsyncSelect().
4.1.4 connect()
DescriptionEstablish a connection to a peer.

#include

int connect ( SOCKET s, struct sockaddr FAR * name, int namelen );


sA descriptor identifying an unconnected socket.

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

namelenThe length of the name.

RemarksThis 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 ValueIf no error occurs, connect() returns 0. Otherwise, it returns SOCKET_ERROR, and a specific error code may be retrieved by calling WSAGetLastError().

Error CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEADDRINUSEThe specified address is already in use.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets call is in progress.

WSAEADDRNOTAVAILThe specified address is not available from the local machine.

WSAEAFNOSUPPORTAddresses in the specified family cannot be used with this socket.

WSAECONNREFUSEDThe attempt to connect was forcefully rejected.

WSAEDESTADDREQA destination address is required.

WSAEFAULTThe namelen argument is incorrect.

WSAEINVALThe socket is not already bound to an address.

WSAEISCONNThe socket is already connected.

WSAEMFILENo more file descriptors are available.

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

WSAENOBUFSNo buffer space is available. The socket cannot be connected.

WSAENOTSOCKThe descriptor is not a socket.

WSAETIMEDOUTAttempt to connect timed out without establishing a connection

WSAEINPROGRESSThe 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 Alsoaccept(), bind(), getsockname(), socket().
4.1.5 getpeername()
DescriptionGet the address of the peer to which a socket is connected.

#include

int getpeername ( SOCKET s, struct sockaddr FAR * name, int FAR * namelen );


sA descriptor identifying a connected socket.

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

namelenA pointer to the size of the name structure.

Remarksgetpeername() 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULTThe namelen argument is not large enough.

WSAEINPROGRESSA blocking Windows Sockets call is in progress.

WSAENOTCONNThe socket is not connected.

WSAENOTSOCKThe descriptor is not a socket.

See Alsobind(), socket(), getsockname().
4.1.6 getsockname()
DescriptionGet the local name for a socket.

#include

int getsockname ( SOCKET s, struct sockaddr FAR * name, int FAR * namelen );


sA descriptor identifying a bound socket.

nameThe name of the socket.

namelen The size of the name array.

Remarksgetsockname() 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.


Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULTThe namelen argument is not large enough.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAENOTSOCKThe descriptor is not a socket.

See Alsobind(), socket().
4.1.7 getsockopt()
DescriptionRetrieve a socket option.

#include

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


sA descriptor identifying a socket.

levelThe level at which the option is defined; the only supported level is SOL_SOCKET.

optnameThe socket option for which the value is to be retrieved.

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

optlenA pointer to the size of the optval buffer.

Remarksgetsockopt() 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.

Value
Type
Meaning

SO_ACCEPTCON
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 FAR *
Returns the current linger options.

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).


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



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



Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEFAULTThe optlen argument was invalid.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

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

WSAENOTSOCKThe descriptor is not a socket.

See Alsosetsockopt(), WSAAsyncSelect(), socket().
4.1.8 htonl()
DescriptionConvert a u_long from host to network byte order.

#include

u_long htonl ( u_long hostlong );


hostlongA 32-bit number in host byte order.

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


Return Valuehtonl() returns the value in network byte order.

See Alsohtons(), ntohl(), ntohs().
4.1.9 htons()
DescriptionConvert a u_short from host to network byte order.

#include

u_short htons ( u_short hostshort );


hostshortA 16-bit number in host byte order.

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


Return Valuehtons() returns the value in network byte order.

See Alsohtonl(), ntohl(), ntohs().
4.1.10 inet_addr()
DescriptionConvert a string containing a dotted address into an in_addr.

#include

struct in_addr inet_addr ( char FAR * cp );


cpA character string representing a number expressed in the Internet standard ".'' notation.

RemarksThis 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.da.b.ca.ba

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 ValueIf no error occurs, inet_addr() returns an in_addr structure containing a suitable binary representation of the Internet address given. Otherwise, it returns the value INADDR_NONE.

See Alsoinet_ntoa()
4.1.11 inet_ntoa()
DescriptionConvert a network address into a string in dotted format.

#include

char FAR * inet_ntoa ( struct in_addr in );


inA structure which represents an Internet host address.

RemarksThis 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 ValueIf 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 Alsoinet_addr().
4.1.12 ioctlsocket()
DescriptionControl the mode of a socket.

#include

int ioctlsocket ( SOCKET s, long cmd, u_long FAR * argp );


sA descriptor identifying a socket.

cmdThe command to perform on the socket s.

argpA pointer to a parameter for cmd.

RemarksThis 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:

CommandSemantics
FIONBIOEnable 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.
FIONREADDetermine 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.
SIOCATMARKDetermine 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.

CompatibilityThis 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 ValueUpon 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

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

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAENOTSOCKThe descriptor s is not a socket.


See Alsosocket(), setsockopt(), getsockopt().
4.1.13 listen()
DescriptionEstablish a socket to listen for incoming connection.

#include

int listen ( SOCKET s, int backlog );

sA descriptor identifying a bound, unconnected socket.

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

RemarksTo 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.

Compatibilitybacklog 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

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

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEFAULTAn invalid argument was given.

WSAEINVALThe socket has not been bound with bind().

WSAEISCONNThe socket is already connected.

WSAEMFILENo more file descriptors are available.

WSAENOBUFSNo buffer space is available.

WSAENOTSOCKThe descriptor is not a socket.

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

See Alsoaccept(), connect(), socket().
4.1.14 ntohl()
DescriptionConvert a u_long from network to host byte order.

#include

u_long ntohl ( u_long netlong );


netlongA 32-bit number in network byte order.

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


Return Valuentohl() returns the value in host byte order.

See Alsohtonl(), htons(), ntohs().
4.1.15 ntohs()
DescriptionConvert a u_short from network to host byte order.

#include

u_short ntohs ( u_short netshort );


netshortA 16-bit number in network byte order.

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


Return Valuentohs() returns the value in host byte order.

See Alsohtonl(), htons(), ntohl().
4.1.15 recv()
DescriptionReceive data from a socket.

#include

int recv ( int s, char FAR * buf, int len, int flags );


sA descriptor identifying a connected socket.

bufA buffer for the incoming data.

lenThe length of buf.

flagsSpecifies the way in which the call is made.

RemarksThis 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 size of the buffer supplied. If the datagram is larger than the buffer supplied, the excess data is lost.

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.

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:

ValueMeaning
MSG_PEEKPeek at the incoming data. The data is copied into the buffer but is not removed from the input queue.

MSG_OOBProcess out-of-band data (See section 2.2.3 for a discussion of this topic.)



Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOTCONNThe socket is not connected.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAENOTSOCKThe descriptor is not a socket.

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

WSAESHUTDOWNThe 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.

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

See Alsorecvfrom(), read(), send(), select(), WSAAsyncSelect(), socket()
4.1.16 recvfrom()
DescriptionReceive a datagram and store the source address.

#include

int recvfrom ( int s, char FAR * buf, int len, int flags, struct sockaddr FAR * from, int FAR * fromlen );


sA descriptor identifying a bound socket.

bufA buffer for the incoming data.

lenThe length of buf.

flagsSpecifies the way in which the call is made.

fromPoints to a buffer which will hold the source address upon return.

fromlenA pointer to the size of the from buffer.

RemarksThis 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.

For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the size of the buffer supplied. If the datagram is larger than the buffer supplied, the excess data is lost.

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.

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:

ValueMeaning
MSG_PEEKPeek at the incoming data. The data is copied into the buffer but is not removed from the input queue.

MSG_OOBProcess out-of-band data (See section 2.2.3 for a discussion of this topic.)



Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

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

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEINVALThe socket has not been bound with bind().

WSAENOTCONNThe socket is not connected (SOCK_STREAM only).

WSAENOTSOCKThe descriptor is not a socket.

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

WSAESHUTDOWNThe 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.

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

See Alsorecv(), send(), socket(), WSAAsyncSelect().
4.1.17 select()
DescriptionDetermine the status of one or more sockets, waiting if necessary.

#include

long select ( int nfds, fd_set FAR * readfds, fd_set FAR * writefds, fd_set FAR * exceptfds, struct timeval FAR * timeout );


nfdsThis argument is ignored and included only for the sake of compatibility.

readfdsA set of sockets to be checked for readability.

writefdsA set of sockets to be checked for writeability

exceptfdsA set of sockets to be checked for errors.

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

RemarksThis 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, so that a recv() or recvfrom() is guaranteed to complete without blocking. 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 writeability. If a socket is connect()ing (non-blocking), writeability means that the connection establishment is complete. For other sockets, writeability 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.

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.


Return Valueselect() returns the total number of descriptors which are ready and contained in the fd_set structures, or 0 if the time limit expired.

Error CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVALThe timeout value is not valid.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

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

See AlsoWSAAsyncSelect(), accept(), connect(), read(), write(), recv(), recvfrom(), send().
4.1.18 send()
DescriptionSend data on a connected socket.

#include

int send ( SOCKET s, char FAR * buf, int len, int flags );


sA descriptor identifying a connected socket.

bufA buffer containing the data to be transmitted.

lenThe length of the data in buf.

flagsSpecifies the way in which the call is made.

Remarkssend() 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 the (truncated) 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:

ValueMeaning
MSG_DONTROUTESpecifies 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_OOBSend out-of-band data (SOCK_STREAM only; see also section 2.2.3)


Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

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

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEFAULTThe buf is not in a valid part of the user address space.

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

WSAENOBUFSThe Windows Sockets implementation reports a buffer deadlock.

WSAENOTCONNThe socket is not connected.

WSAENOTSOCKThe descriptor is not a socket.

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

WSAESHUTDOWNThe 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.

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

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

See Alsorecv(), recvfrom(), socket(), sendto(), WSAStartup().
4.1.19 sendto()
DescriptionSend data to a specific destination.

#include

int sendto ( SOCKET s, char FAR * buf, int len, int flags, struct sockaddr FAR * to, int tolen );


sA descriptor identifying a socket.

bufA buffer containing the data to be transmitted.

lenThe length of the data in buf.

flagsSpecifies the way in which the call is made.

toA pointer to the address of the target socket.

tolenThe size of the address in to.

Remarkssendto() 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 the (truncated) 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 connection-oriented socket, the to parameter is 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:

ValueMeaning
MSG_DONTROUTESpecifies 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_OOBSend out-of-band data (SOCK_STREAM only; see also section 2.2.3)


Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

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

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEFAULTThe buf or to are not in a valid part of the user address space.

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

WSAENOBUFSThe Windows Sockets implementation reports a buffer deadlock.

WSAENOTCONNThe socket is not connected (SOCK_STREAM only).

WSAENOTSOCKThe descriptor is not a socket.

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

WSAESHUTDOWNThe 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.

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

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

See Alsorecv(), recvfrom(), socket(), send(), WSAStartup().
4.1.20 setsockopt()
DescriptionSet a socket option.

#include

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


sA descriptor identifying a socket.

levelThe level at which the option is defined; the only supported level is SOL_SOCKET.

optnameThe socket option for which the value is to be set.

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

optlenA pointer to the size of the optval buffer.

Remarkssetsockopt() 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 {
intl_onoff;
intl_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 of address re-use, 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 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 FAR *
Linger on close if unsent data is present

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


BSD options not supported for setsockopt() are:

Value
Type
Meaning

SO_ACCEPTCON
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


Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

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

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEINVALlevel is not valid.

WSAENETRESETConnection has timed out when SO_KEEPALIVE is set.

WSAENOPROTOOPTThe 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.

WSAENOTCONNConnection has been reset when SO_KEEPALIVE is set.

WSAENOTSOCKThe descriptor is not a socket.

See Alsobind(), getsockopt(), ioctlsocket(), socket(), WSAAsyncSelect().
4.1.21 shutdown()
DescriptionDisable sends and/or receives on a socket.

#include

int shutdown ( SOCKET s, int how );


sA descriptor identifying a socket.

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

Remarksshutdown() 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.


Commentsshutdown() 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVALhow is not valid.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAENOTCONNThe socket is not connected (SOCK_STREAM only).

WSAENOTSOCKThe descriptor is not a socket.

See Alsoconnect(), socket().

4.1.22 socket()
DescriptionCreate a socket.

#include

SOCKET socket ( int af, int type, int protocol );


afAn address format specification. The only format currently supported is PF_INET, which is the ARPA Internet address format.

typeA type specification for the new socket.

protocolA particular protocol to be used with the socket.

Remarkssocket() allocates a socket descriptor of the specified address family, data type and protocol, as well as related resources. If a protocol is not specified, 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:

TypeExplanation
SOCK_STREAMProvides sequenced, reliable, two-way, connection-based byte streams with an out-of-band data transmission mechanism. Uses TCP for the Internet address family.

SOCK_DGRAMSupports 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEAFNOSUPPORTThe specified address family is not supported..

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEMFILENo more file descriptors are available.

WSAENOBUFSNo buffer space is available. The socket cannot be created.

WSAEPROTONOSUPPORTThe specified protocol is not supported.

WSAEPROTOTYPEThe specified protocol is the wrong type for this socket.

WSAESOCKTNOSUPPORTThe specified socket type is not supported in this address family.

See Alsoaccept(), bind(), connect(), getsockname(), getsockopt(), setsockopt(), listen(), recv(), recvfrom(), select(), send(), sendto(), shutdown(), ioctlsocket().
4.2 Database Routines
4.2.1 gethostbyaddr()
DescriptionGet host information corresponding to an address.

#include

struct hostent FAR * gethostbyaddr ( char FAR * addr, int len, int type );


addrA pointer to an address in network byte order.
lenThe length of the address, which must be 4 for PF_INET addresses.
typeThe type of the address, which must be PF_INET.

Remarksgethostbyaddr() 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;
inth_addrtype;
inth_length;
char FAR * FAR *h_addr_list;
};

The members of this structure are:
ElementUsage
h_nameOfficial name of the host (PC).
h_aliasesA NULL-terminated array of alternate names.
h_addrtypeThe type of address being returned; for Windows Sockets this is always PF_INET.
h_lengthThe length, in bytes, of each address; for PF_INET, this is always 4.
h_addr_listA 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAHOST_NOT_FOUNDAuthoritative Answer Host not found.

WSATRY_AGAINNon-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid name, no data record of requested type.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

See AlsoWSAAsyncGetHostByAddr(), gethostbyname(),
4.2.2 gethostbyname()
DescriptionGet host information corresponding to a hostname.

#include

struct hostent FAR * gethostbyname ( char FAR * name );


nameA pointer to the name of the host.

Remarksgethostbyname() 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.


Return ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAHOST_NOT_FOUNDAuthoritative Answer Host not found.

WSATRY_AGAINNon-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid name, no data record of requested type.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()


See AlsoWSAAsyncGetHostByName(), gethostbyaddr()
4.2.3 getprotobyname()
DescriptionGet protocol information corresponding to a protocol name.

#include

struct protoent FAR * getprotobyname ( char FAR * name );


nameA pointer to a protocol name.

Remarksgetprotobyname() 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;
intp_proto;
};

The members of this structure are:
ElementUsage
p_nameOfficial name of the protocol.
p_aliasesA NULL-terminated array of alternate names.
p_protoThe 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid name, no data record of requested type.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()


See AlsoWSAAsyncGetProtoByName(), getprotobynumber()
4.2.4 getprotobynumber()
DescriptionGet protocol information corresponding to a protocol number.

#include

struct protoent FAR * getprotobynumber ( int number );


numberA protocol number, in host byte order.

RemarksThis 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid name, no data record of requested type.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()

See AlsoWSAAsyncGetProtoByNumber(), getprotobyname()
4.2.5 getservbyname()
DescriptionGet service information corresponding to a service name and protocol.

#include

struct servent FAR * getservbyname ( char FAR * name, char FAR * proto );


nameA pointer to a service name.
protoA 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.

Remarksgetservbyname() 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;
ints_port;
char FAR *s_proto;
};

The members of this structure are:
ElementUsage
s_nameOfficial name of the service.
s_aliasesA NULL-terminated array of alternate names.
s_portThe port number at which the service may be contacted. Port numbers are returned in network byte order.
s_protoThe 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid name, no data record of requested type.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()


See AlsoWSAAsyncGetServByName(), getservbyport()
4.2.6 getservbyport()
DescriptionGet service information corresponding to a port and protocol.

#include

struct servent FAR * getservbyport ( int port, char FAR * proto );


portThe port for a service, in network byte order.
protoA 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.

Remarksgetservbyport() 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 ValueIf 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid name, no data record of requested type.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEINTRThe (blocking) call was canceled via WSACancelBlockingCall()


See AlsoWSAAsyncGetServByPort(), getservbyname()
4.3 Microsoft Windows-specific Extensions
4.3.1 WSAAsyncGetHostByAddr()
DescriptionGet host information corresponding to an address - asynchronous version.

#include

HANDLE WSAAsyncGetHostByAddr ( HWND hWnd, unsigned int wMsg, char FAR * addr, int len, int type, char FAR * buf, int buflen );


hWndThe handle of the window which should receive a message when the asynchronous request completes.

wMsgThe message to be received when the asynchronous request completes.

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

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

typeThe type of the address, which must be PF_INET.

bufA 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.

buflenThe size of data area buf above.

RemarksThis 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 ValueThe 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().

CommentsThe 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
SuppliersIt 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.

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

Error CodesThe 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.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFSNo/insufficient buffer space is available

WSAHOST_NOT_FOUNDAuthoritative Answer Host not found.

WSATRY_AGAINNon-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid 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.

WSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

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

See Alsogethostbyaddr(), WSACancelAsyncRequest()
4.3.2 WSAAsyncGetHostByName()
DescriptionGet host information corresponding to a hostname - asynchronous version.

#include

HANDLE WSAAsyncGetHostByName ( HWND hWnd, unsigned int wMsg, char FAR * name, char FAR * buf, int buflen );


hWndThe handle of the window which should receive a message when the asynchronous request completes.

wMsgThe message to be received when the asynchronous request completes.

nameA pointer to the name of the host.

bufA 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.

buflenThe size of data area buf above.

RemarksThis 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 ValueThe 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().

CommentsThe 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
SuppliersIt 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.

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

Error CodesThe 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.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFSNo/insufficient buffer space is available

WSAHOST_NOT_FOUNDAuthoritative Answer Host not found.

WSATRY_AGAINNon-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid 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.

WSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

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

See Alsogethostbyname(), WSACancelAsyncRequest()
4.3.3 WSAAsyncGetProtoByName()
DescriptionGet protocol information corresponding to a protocol name - asynchronous version.

#include

HANDLE WSAAsyncGetProtoByName ( HWND hWnd, unsigned int wMsg, char FAR * name, char FAR * buf, int buflen );


hWndThe handle of the window which should receive a message when the asynchronous request completes.

wMsgThe message to be received when the asynchronous request completes.

nameA pointer to the protocol name to be resolved.

bufA 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.

buflenThe size of data area buf above.

RemarksThis 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 ValueThe 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().

CommentsThe 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
SuppliersIt 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.

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

Error CodesThe 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.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFSNo/insufficient buffer space is available

WSAHOST_NOT_FOUNDAuthoritative Answer Host not found.

WSATRY_AGAINNon-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid 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.

WSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

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

See Alsogetprotobyname(), WSACancelAsyncRequest()
4.3.4 WSAAsyncGetProtoByNumber()
DescriptionGet protocol information corresponding to a protocol number - asynchronous version.

#include

HANDLE WSAAsyncGetProtoByNumber ( HWND hWnd, unsigned int wMsg, int number, char FAR * buf, int buflen );


hWndThe handle of the window which should receive a message when the asynchronous request completes.

wMsgThe message to be received when the asynchronous request completes.

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

bufA 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.

buflenThe size of data area buf above.

RemarksThis 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 ValueThe 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().

CommentsThe 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
SuppliersIt 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.

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

Error CodesThe 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.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFSNo/insufficient buffer space is available

WSAHOST_NOT_FOUNDAuthoritative Answer Host not found.

WSATRY_AGAINNon-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid 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.

WSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEWOULDBLOCKThe asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
See Alsogetprotobynumber(), WSACancelAsyncRequest()
4.3.5 WSAAsyncGetServByName()
DescriptionGet service information corresponding to a service name and port - asynchronous version.

#include

HANDLE WSAAsyncGetServByName ( HWND hWnd, unsigned int wMsg, char FAR * name, char FAR * proto, char FAR * buf, int buflen );


hWndThe handle of the window which should receive a message when the asynchronous request completes.

wMsgThe message to be received when the asynchronous request completes.

nameA pointer to a service name.

protoA 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.

bufA 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.

buflenThe size of data area buf above.

RemarksThis 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 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 ValueThe 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().

CommentsThe 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
SuppliersIt 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.

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

Error CodesThe 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.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFSNo/insufficient buffer space is available

WSAHOST_NOT_FOUNDAuthoritative Answer Host not found.

WSATRY_AGAINNon-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid 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.

WSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

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

See Alsogetservbyname(), WSACancelAsyncRequest()
4.3.6 WSAAsyncGetServByPort()
DescriptionGet service information corresponding to a port and protocol - asynchronous version.

#include

HANDLE WSAAsyncGetServByPort ( HWND hWnd, unsigned int wMsg, int port, char FAR * proto, char FAR * buf, int buflen );


hWndThe handle of the window which should receive a message when the asynchronous request completes.

wMsgThe message to be received when the asynchronous request completes.

portThe port for the service, in network byte order.

protoA 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.

bufA 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.

buflenThe size of data area buf above.

RemarksThis 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 ValueThe 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().

CommentsThe 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
SuppliersIt 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.

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

Error CodesThe 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.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAENOBUFSNo/insufficient buffer space is available

WSAHOST_NOT_FOUNDAuthoritative Answer Host not found.

WSATRY_AGAINNon-Authoritative Host not found, or SERVERFAIL.

WSANO_RECOVERYNon recoverable errors, FORMERR, REFUSED, NOTIMP.

WSANO_DATAValid 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.

WSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

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

See Alsogetservbyport(), WSACancelAsyncRequest()
4.3.7 WSAAsyncSelect()
DescriptionRequest event notification for a socket.

#include

int WSAAsyncSelect ( SOCKET s, HWND hWnd, unsigned int wMsg, long lEvent );


sA descriptor identifying the socket for which event notification is required.

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

wMsgThe message to be received when a network event occurs.

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

RemarksThis 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.

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

ValueMeaning
FD_READWant to receive notification of readiness for reading
FD_WRITEWant to receive notification of readiness for writing
FD_OOBWant to receive notification of the arrival of out-of-band data
FD_ACCEPTWant to receive notification of incoming connections
FD_CONNECTWant to receive notification of completed connection
FD_CLOSEWant 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 the WSAAsyncSelect() takes effect immediately, 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.

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

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:

ValueMeaning
FD_READSocket s ready for reading
FD_WRITESocket s ready for writing
FD_OOBOut-of-band data ready for reading on socket s.
FD_ACCEPTSocket s ready for accepting a new incoming connection
FD_CONNECTConnection on socket s completed
FD_CLOSEConnection identified by socket s has been closed


Return ValueThe 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().

CommentsAlthough 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:

(i)data arrives on socket s; Windows Sockets posts WSAAsyncSelect message
(ii)application processes some other message
(iii)while processing, application issues an ioctlsocket(s, FIONREAD...) and notices that there is data ready to be read
(iv)application issues a recv(s,...) to read the data
(v)application loops to process next message, eventually reaching the WSAAsyncSelect message indicating that data is ready to read
(vi)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 re-enables notification of that network event.

EventRe-enabling function
FD_READrecv() or recvfrom()
FD_WRITEsend() or sendto()
FD_OOBrecv()
FD_ACCEPTaccept()
FD_CONNECTNONE
FD_CLOSENONE

There is an intrinsic race condition in the message-based model that application developers should be aware of in their programming. Consider the following sequence:

(i)Windows Sockets DLL receives 100 bytes of data on socket s and sends a message to the application
(ii)application begins processing the message
(iii)application issues ioctlsocket(s, FIONREAD,...) and learns that there are 100 bytes of data ready
(iv)Windows Sockets DLL receives another 50 bytes of data. Since the application has not issued the re-enabling function (see below), no new message is sent
(v)application performs a recv(s, bufptr, 100, 0) to read 100 bytes of data (as indicated by the FIONREAD)
(vi)application yields, and unless more data is sent it never knows that there are 50 bytes of unread data

There are three obvious solutions to this. First, the application can issue another FIONREAD ioctlsocket() after the recv() to determine whether more data is available, Secondly, the application can perform repeated recv()'s until it encounters WSAEWOULDBLOCK. Finally, the application can issue a single recv() with a len which it can be certain is sufficient to gather all of the waiting data. (This last method is obviously risky unless the pattern of data transmission is well understood.)

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.

Error CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVALIndicates that one of the specified parameters was invalid

WSAEINPROGRESSA 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 CodeMeaning
WSAEADDRINUSEThe specified address is already in use.

WSAEADDRNOTAVAILThe specified address is not available from the local machine.

WSAEAFNOSUPPORTAddresses in the specified family cannot be used with this socket.

WSAECONNREFUSEDThe attempt to connect was forcefully rejected.

WSAEDESTADDRREQA destination address is required.

WSAEFAULTThe namelen argument is incorrect.

WSAEINVALThe socket is already bound to an address.

WSAEISCONNThe socket is already connected.

WSAEMFILENo more file descriptors are available.

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

WSAENOBUFSNo buffer space is available. The socket cannot be connected.

WSAENOTCONNThe socket is not connected.

WSAENOTSOCKThe descriptor is a file, not a socket.

WSAETIMEDOUTAttempt to connect timed out without establishing a connection

Event: FD_CLOSE
Event: FD_READ
Event: FD_WRITE
Event: FD_OOB
Event: FD_ACCEPT
Error CodeMeaning
WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

Notes For
Windows Sockets
SuppliersIt 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.

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 Alsoselect()
4.3.8 WSACancelAsyncRequest()
DescriptionCancel an incomplete asynchronous operation.

#include

int WSACancelAsyncRequest ( HANDLE hAsyncTaskHandle );


hAsyncTaskHandleSpecifies the asynchronous operation to be canceled.

RemarksThe 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 ValueThe 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().

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

Notes For
Windows Sockets
SuppliersIt 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVALIndicates that the specified asynchronous task handle was invalid

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

WSAEALREADYThe asynchronous routine being canceled has already completed.


See AlsoWSAAsyncGetHostByAddr(), WSAAsyncGetHostByName(), WSAAsyncGetProtoByNumber(), WSAAsyncGetProtoByName(), WSAAsyncGetHostByName(), WSAAsyncGetServByPort(), WSAAsyncGetServByName()
4.3.9 WSACancelBlockingCall()
DescriptionCancel a blocking call which is currently in progress.

#include

int WSACancelBlockingCall ( void );

RemarksThis 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.

Return ValueThe 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().

Error CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINVALIndicates that there is no outstanding blocking call.
4.3.10 WSACleanup()
DescriptionTerminate use of the Windows Sockets DLL.

#include

int WSACleanup ( void );

RemarksAn application 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 may call WSACleanup() to deregister itself from a Windows Sockets implementation.

Return ValueThe 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().

Notes For
Windows Sockets
SuppliersWell-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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

See AlsoWSAStartup()
4.3.11 WSAGetLastError()
DescriptionGet the error status for the last operation which failed.

#include

int WSAGetLastError ( void );

RemarksThis 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 ValueThe return value indicates the error code for the last Windows Sockets API routine performed by this thread.

Notes For
Windows Sockets
SuppliersThe 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 Win16 environment WSAGetLastError() is used to retrieve only Windows Sockets API errors. In a Win32 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 AlsoWSASetLastError()
4.3.12 WSAIsBlocking()
DescriptionDetermine if a blocking call is in progress.

#include

BOOL WSAIsBlocking ( void );

RemarksThis function allows a task to determine if it is executing while waiting for a previous blocking call to complete.

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

CommentsAlthough 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
SuppliersA Windows Sockets implementation must prohibit more than one outstanding blocking call per thread.
4.3.13 WSASetBlockingHook()
DescriptionEstablish an application-specific blocking hook function.

#include

FARPROC WSASetBlockingHook ( FARPROC lpBlockFunc );


lpBlockFuncA pointer to the procedure instance address of the blocking function to be installed.

RemarksThis 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 equivalent 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 */
}

The default BlockingHook() function is equivalent to:

BOOL DefaultBlockingHook(void) {
MSG msg;
BOOL ret;
/* get the next message if any */
ret = (BOOL)PeekMessage(&msg,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.

Return ValueThe 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 WSAUnsetBlockingHook() 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().

Notes For
Windows Sockets
SuppliersThis function must be implemented on a per-thread basis. It thus provides for a particular thread to replace the blocking mechanism without affecting other threads.

Error CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

WSAENETDOWNThe Windows Sockets implementation has detected that the network subsystem has failed.

WSAEINPROGRESSA blocking Windows Sockets operation is in progress.

See AlsoWSAUnhookBlockingHook()
4.3.14 WSASetLastError()
DescriptionSet the error code which can be retrieved by WSAGetLastError().

#include

void WSASetLastError ( int iError );

RemarksThis 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.


iErrorSpecifies the error code to be returned by a subsequent WSAGetLastError() call.

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

Return ValueNone.

Error CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

See AlsoWSAGetLastError()
4.3.15 WSAStartup()
Description

#include

int WSAStartup ( WORD wVersionRequired, LPWSADATA lpWSAData );


wVersionRequiredThe highest version of Windows Sockets API support required. The high order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

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

RemarksThis function MUST be the first Windows Sockets function called by an application. It allows an application to specify the version of Windows Sockets API required and to retrieve details of the specific Windows Sockets implementation. The application 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.0, a negotiation takes place in WSAStartup(). An application passes to WSAStartup() the highest Windows Sockets version that it can take advantage of. If this version is lower than the lowest version supported by the Windows Sockets DLL, the DLL cannot support the application and WSAStartup() returns WSAVERNOTSUPPORTED. Otherwise, the DLL will attempt to register the application as a client: if this fails, WSAStartup() fails and returns WSASYSNOTREADY. If the DLL can support the application and the registration process succeeds, .the function stores the highest version of Windows Sockets supported by the DLL in the wHighVersion element of the WSAData structure and returns 0. If wHighVersion is lower than the lowest version supported by the application, the application either fails its initialization or attempts to find another Windows Sockets DLL on the system.

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 DLL if there is any overlap in the versions. The following chart gives examples of how WSAStartup() works in conjunction with different application and DLL versions:

App versions
DLL Versions
wVersionRequired
wHighVersion
Result

1.0
1.0
1.0
1.0
use 1.0

1.0 2.0
1.0
2.0
1.0
use 1.0

1.0
1.0 2.0
1.0
2.0
use 1.0

1.0
2.0 3.0
1.0
(failure)
fail

2.0 3.0
1.0
3.0
1.0
fail

1.0 2.0 3.0
1.0 2.0 3.0
3.0
3.0
use 3.0


Once an application 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 should call WSACleanup().

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

struct WSAData {
WORDwVersion;
WORDwHighVersion;
char szDescription[WSADESCRIPTION_LEN+1];
charszSystemStatus[WSASYSSTATUS_LEN+1];
intiMaxSockets;
intiMaxUdpDg;
char FAR *lpVendorInfo
};

The members of this structure are:
ElementUsage
wVersionThe version of the Windows Sockets DLL, encoded as for wVersionRequired.
wHighVersionThe highest version of the Windows Sockets specification that this DLL can support (also encoded as above). Normally this will be the same as wVersion.
szDescriptionA 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.
szSystemStatusA 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.
iMaxSocketsThe 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.
iMaxUdpDgThe 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.)
lpVendorInfoA far pointer to a vendor-specific data structure. The definition of this structure (if supplied) is beyond the scope of this specification.


Return ValueWSAStartup() 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
SuppliersEach 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 CodesWSASYSNOTREADYIndicates that the underlying network subsystem is not ready for network communication.

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

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

See Alsosend(), sendto(), WSACleanup()
4.3.16 WSAUnhookBlockingHook()
DescriptionRestore the default blocking hook function.

#include

int WSAUnhookBlockingHook ( void );

RemarksThis 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().

Return ValueThe 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 CodesWSANOTINITIALISEDA successful WSAStartup() must occur before using this API.

See AlsoWSASetBlockingHook()
APPENDIX AError Codes and Header Files
A.1 Error Codes
The following is a list of possible error codes returned by the WSAGetLastError() call, along with their explanations. The error numbers are consistently set across all Windows Sockets-compliant implementations.

Windows Sockets code
Berkeley equivalent
Error
Interpretation

WSAEINTR
EINTR
10004
As in standard C

WSAEBADF
EBADF
10009
As in standard C

WSAEINVAL
EINVAL
10022
As in standard C

WSAEMFILE
EMFILE
10024
As in standard C

WSAEWOULDBLOCK
EWOULDBLOCK
10035
As in BSD

WSAEINPROGRESS
EINPROGRESS
10036
This error is returned if anyWindows Sockets API function is called while a blocking function isin progress.

WSAEALREADY
EALREADY
10037
As in BSD

WSAENOTSOCK
ENOTSOCK
10038
As in BSD

WSAEDESTADDRREQ
EDESTADDRREQ
10039
As in BSD

WSAEMSGSIZE
EMSGSIZE
10040
As in BSD

WSAEPROTOTYPE
EPROTOTYPE
10041
As in BSD

WSAENOPROTOOPT
ENOPROTOOPT
10042
As in BSD

WSAEPROTONOSUPPORT
EPROTONOSUPPORT
10043
As in BSD

WSAESOCKTNOSUPPORT
ESOCKTNOSUPPORT
10044
As in BSD

WSAEOPNOTSUPP
EOPNOTSUPP
10045
As in BSD

WSAEPFNOSUPPORT
EPFNOSUPPORT
10046
As in BSD

WSAEAFNOSUPPORT
EAFNOSUPPORT
10047
As in BSD

WSAEADDRINUSE
EADDRINUSE
10048
As in BSD

WSAEADDRNOTAVAIL
EADDRNOTAVAIL
10049
As in BSD

WSAENETDOWN
ENETDOWN
10050
As in BSD. This error may be reported at any time if the Windows Sockets implementation detects an underlying failure.

WSAENETUNREACH
ENETUNREACH
10051
As in BSD

WSAENETRESET
ENETRESET
10052
As in BSD

WSAECONNABORTED
ECONNABORTED
10053
As in BSD

WSAECONNRESET
ECONNRESET
10054
As in BSD

WSAENOBUFS
ENOBUFS
10055
As in BSD

WSAEISCONN
EISCONN
10056
As in BSD

WSAENOTCONN
ENOTCONN
10057
As in BSD

WSAESHUTDOWN
ESHUTDOWN
10058
As in BSD

WSAETOOMANYREFS
ETOOMANYREFS
10059
As in BSD

WSAETIMEDOUT
ETIMEDOUT
10060
As in BSD

WSAECONNREFUSED
ECONNREFUSED
10061
As in BSD

WSAELOOP
ELOOP
10062
As in BSD

WSAENAMETOOLONG
ENAMETOOLONG
10063
As in BSD

WSAEHOSTDOWN
EHOSTDOWN
10064
As in BSD

WSAEHOSTUNREACH
EHOSTUNREACH
10065
As in BSD

WSASYSNOTREADY

10091
Returned by WSAStartup() indicating that the network subsystem is unusable.

WSAVERNOTSUPPORTED

10092
Returned by WSAStartup() indicating that the Windows SocketsDLL cannot support this app.

WSANOTINITIALISED

10093
Returned by any function except WSAStartup() indicating that a successful WSAStartup() has not yet been performed.

WSAHOST_NOT_FOUND
HOST_NOT_FOUND
11001
As in BSD.

WSATRY_AGAIN
TRY_AGAIN
11002
As in BSD

WSANO_RECOVERY
NO_RECOVERY
11003
As in BSD

WSANO_DATA
NO_DATA
11004
As in BSD



The first set of definitions is present to resolve contentions between standard C error codes which may be defined inconsistently between various C compilers.

The second set of definitions provides Windows Sockets versions of regular Berkeley Sockets error codes.

The third set of definitions consists of extended Windows Sockets-specific error codes.

The fourth set of errors are returned by Windows Sockets getXbyY() and WSAAsyncGetXByY() functions, and correspond to the errors which in Berkeley software would be returned in the h_errno variable. They correspond to various failures which may be returned by the Domain Name Service. If the Windows Sockets implementation does not use the DNS, it will use the most appropriate code. In general, a Windows Sockets application should interpret WSAHOST_NOT_FOUND and WSANO_DATA as indicating that the key (name, address, etc.) was not found,, while WSATRY_AGAIN and WSANO_RECOVERY suggest that the name service itself is non-operational.

The error numbers are derived from the winsock.h header file listed in section A.2.2, and are based on the fact that Windows Sockets error numbers are computed by adding 10000 to the "normal" Berkeley error number.

Note that this table does not include all of the error codes defined in winsock.h. This is because it includes only errors which might reasonably be returned by a Windows Sockets implementation: winsock.h, on the other hand, includes a full set of BSD definitions to ensure compatibility with ported software.


A.2 Header Files
A.2.1 Berkeley Header Files
A Windows Sockets supplier who provides a development kit to support the development of Windows Sockets applications must supply a set of vestigial header files with names that match a number of the header files in the Berkeley software distribution. These files are provided for source code compatibility only, and each consists of three lines:

#ifndef _WINSOCK API_
#include
#endif

The header files provided for compatibility are:
netdb.h
arpa/inet.h
sys/time.h
sys/socket.h
netinet/in.h

The file winsock.h contains all of the type and structure definitions, constants, macros, and function prototypes used by the Windows Sockets specification. An application writer may choose to ignore the compatibility headers and include winsock.h in each source file.


A.2.2 Windows Sockets Header File - winsock.h

The winsock.h header file includes a number of types and definitions from the standard Windows header file windows.h. The windows.h in the Windows 3.0 SDK (Software Developer's Kit) lacks a #include guard, so if you need to include windows.h as well as winsock.h, you should define the symbol _INC_WINDOWS before #including winsock.h, as follows:
#include
#define _INC_WINDOWS
#include
Users of the SDK for Windows 3.1 and later need not do this.

/* WINSOCK.H--definitions to be used with the WINSOCK.DLL
*
* This file includes parts which are Copyright (c) 1982-1986 Regents
* of the University of California. All rights reserved. The
* Berkeley Software License Agreement specifies the terms and
* conditions for redistribution.
*/

#ifndef _WINSOCKAPI_
#define _WINSOCKAPI_

/*
* Pull in WINDOWS.H if necessary
*/
#ifndef _INC_WINDOWS
#include
#endif /* _INC_WINDOWS */

/*
* Basic system type definitions, taken from the BSD file sys/types.h.
*/
typedef unsigned char u_char;
typedef unsigned short u_short;
typedef unsigned int u_int;
typedef unsigned long u_long;

/*
* The new type to be used in all
* instances which refer to sockets.
*/
typedef unsigned int SOCKET;

/*
* Select uses arrays of SOCKETs. These macros manipulate such
* arrays. FD_SETSIZE may be defined by the user before including
* this file, but the default here should be >= 64.
*
* CAVEAT IMPLEMENTOR and USER: THESE MACROS AND TYPES MUST BE
* INCLUDED IN WINSOCK.H EXACTLY AS SHOWN HERE.
*/
#ifndef FD_SETSIZE
#define FD_SETSIZE 64
#endif /* FD_SETSIZE */

typedef struct fd_set {
u_short fd_count; /* how many are SET? */
SOCKET fd_array[FD_SETSIZE]; /* an array of SOCKETs */
} fd_set;

extern int FAR __WSAFDIsSet(SOCKET, fd_set FAR *);

#define FD_CLR(fd, set) { \
int __i; \
for (__i = 0; __i < ((fd_set FAR *)(set))->fd_count ; __i++) { \
if (((fd_set FAR *)(set))->fd_array[__i] == fd) { \
while (__i < ((fd_set FAR *)(set))->fd_count-1) { \
((fd_set FAR *)(set))->fd_array[__i] = \
((fd_set FAR*)(set))->fd_array[__i+1]; \
__i++; \
} \
((fd_set FAR *)(set))->fd_count--; \
break; \
} \
} \
}

#define FD_SET(fd, set) { \
if (((fd_set FAR *)(set))->fd_count < FD_SETSIZE) \
((fd_set FAR *)(set))->fd_array[((fd_set FAR *)(set))->fd_count++]=fd;\
}

#define FD_ZERO(set) ((fd_set FAR *)(set))->fd_count=0

#define FD_ISSET(fd, set) __WSAFDIsSet((int)fd, (fd_set FAR *)set)

/*
* Structure used in select() call, taken from the BSD file sys/time.h.
*/
struct timeval {
long tv_sec; /* seconds */
long tv_usec; /* and microseconds */
};

/*
* Operations on timevals.
*
* NB: timercmp does not work for >= or <=.
*/
#define timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec)
#define timercmp(tvp, uvp, cmp) \
((tvp)->tv_sec cmp (uvp)->tv_sec || \
(tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec)
#define timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0

/*
* Commands for ioctlsocket(), taken from the BSD file fcntl.h.
*
*
* Ioctl's have the command encoded in the lower word,
* and the size of any in or out parameters in the upper
* word. The high 2 bits of the upper word are used
* to encode the in/out status of the parameter; for now
* we restrict parameters to at most 128 bytes.
*/
#define IOCPARM_MASK 0x7f /* parameters must be < 128 bytes */
#define IOC_VOID 0x20000000 /* no parameters */
#define IOC_OUT 0x40000000 /* copy out parameters */
#define IOC_IN 0x80000000 /* copy in parameters */
#define IOC_INOUT (IOC_IN|IOC_OUT)
/* 0x20000000 distinguishes new &
old ioctl's */
#define _IO(x,y) (IOC_VOID|('x'<<8)|y)

#define _IOR(x,y,t) (IOC_OUT|((sizeof(t)&IOCPARM_MASK)<<16)|('x'<<8)|y)

#define _IOW(x,y,t) (IOC_IN|((sizeof(t)&IOCPARM_MASK)<<16)|('x'<<8)|y)

#define FIONREAD _IOR(f, 127, int) /* get # bytes to read */
#define FIONBIO _IOW(f, 126, int) /* set/clear non-blocking i/o */
#define FIOASYNC _IOW(f, 125, int) /* set/clear async i/o */

/* Socket I/O Controls */
#define SIOCSHIWAT _IOW(s, 0, int) /* set high watermark */
#define SIOCGHIWAT _IOR(s, 1, int) /* get high watermark */
#define SIOCSLOWAT _IOW(s, 2, int) /* set low watermark */
#define SIOCGLOWAT _IOR(s, 3, int) /* get low watermark */
#define SIOCATMARK _IOR(s, 7, int) /* at oob mark? */

/*
* Structures returned by network data base library, taken from the
* BSD file netdb.h. All addresses are supplied in host order, and
* returned in network order (suitable for use in system calls).
*/

struct hostent {
char FAR * h_name; /* official name of host */
char FAR * FAR * h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char FAR * FAR * h_addr_list; /* list of addresses */
#define h_addr h_addr_list[0] /* address, for backward compat */
};

/*
* It is assumed here that a network number
* fits in 32 bits.
*/
struct netent {
char FAR * n_name; /* official name of net */
char FAR * FAR * n_aliases; /* alias list */
int n_addrtype; /* net address type */
u_long n_net; /* network # */
};

struct servent {
char FAR * s_name; /* official service name */
char FAR * FAR * s_aliases; /* alias list */
int s_port; /* port # */
char FAR * s_proto; /* protocol to use */
};

struct protoent {
char FAR * p_name; /* official protocol name */
char FAR * FAR * p_aliases; /* alias list */
int p_proto; /* protocol # */
};

/*
* Constants and structures defined by the internet system,
* Per RFC 790, September 1981, taken from the BSD file netinet/in.h.
*/

/*
* Protocols
*/
#define IPPROTO_IP 0 /* dummy for IP */
#define IPPROTO_ICMP 1 /* control message protocol */
#define IPPROTO_GGP 2 /* gateway^2 (deprecated) */
#define IPPROTO_TCP 6 /* tcp */
#define IPPROTO_PUP 12 /* pup */
#define IPPROTO_UDP 17 /* user datagram protocol */
#define IPPROTO_IDP 22 /* xns idp */
#define IPPROTO_ND 77 /* UNOFFICIAL net disk proto */

#define IPPROTO_RAW 255 /* raw IP packet */
#define IPPROTO_MAX 256

/*
* Port/socket numbers: network standard functions
*/
#define IPPORT_ECHO 7
#define IPPORT_DISCARD 9
#define IPPORT_SYSTAT 11
#define IPPORT_DAYTIME 13
#define IPPORT_NETSTAT 15
#define IPPORT_FTP 21
#define IPPORT_TELNET 23
#define IPPORT_SMTP 25
#define IPPORT_TIMESERVER 37
#define IPPORT_NAMESERVER 42
#define IPPORT_WHOIS 43
#define IPPORT_MTP 57

/*
* Port/socket numbers: host specific functions
*/
#define IPPORT_TFTP 69
#define IPPORT_RJE 77
#define IPPORT_FINGER 79
#define IPPORT_TTYLINK 87
#define IPPORT_SUPDUP 95

/*
* UNIX TCP sockets
*/
#define IPPORT_EXECSERVER 512
#define IPPORT_LOGINSERVER 513
#define IPPORT_CMDSERVER 514
#define IPPORT_EFSSERVER 520

/*
* UNIX UDP sockets
*/
#define IPPORT_BIFFUDP 512
#define IPPORT_WHOSERVER 513
#define IPPORT_ROUTESERVER 520
/* 520+1 also used */

/*
* Ports < IPPORT_RESERVED are reserved for
* privileged processes (e.g. root).
*/
#define IPPORT_RESERVED 1024

/*
* Link numbers
*/
#define IMPLINK_IP 155
#define IMPLINK_LOWEXPER 156
#define IMPLINK_HIGHEXPER 158

/*
* Internet address (old style... should be updated)
*/
struct in_addr {
union {
struct { u_char s_b1,s_b2,s_b3,s_b4; } S_un_b;
struct { u_short s_w1,s_w2; } S_un_w;
u_long S_addr;
} S_un;
#define s_addr S_un.S_addr
/* can be used for most tcp & ip code */
#define s_host S_un.S_un_b.s_b2
/* host on imp */
#define s_net S_un.S_un_b.s_b1
/* network */
#define s_imp S_un.S_un_w.s_w2
/* imp */
#define s_impno S_un.S_un_b.s_b4
/* imp # */
#define s_lh S_un.S_un_b.s_b3
/* logical host */
};

/*
* Definitions of bits in internet address integers.
* On subnets, the decomposition of addresses to host and net parts
* is done according to subnet mask, not the masks here.
*/
#define IN_CLASSA(i) (((long)(i) & 0x80000000) == 0)
#define IN_CLASSA_NET 0xff000000
#define IN_CLASSA_NSHIFT 24
#define IN_CLASSA_HOST 0x00ffffff
#define IN_CLASSA_MAX 128

#define IN_CLASSB(i) (((long)(i) & 0xc0000000) == 0x80000000)
#define IN_CLASSB_NET 0xffff0000
#define IN_CLASSB_NSHIFT 16
#define IN_CLASSB_HOST 0x0000ffff
#define IN_CLASSB_MAX 65536

#define IN_CLASSC(i) (((long)(i) & 0xc0000000) == 0xc0000000)
#define IN_CLASSC_NET 0xffffff00
#define IN_CLASSC_NSHIFT 8
#define IN_CLASSC_HOST 0x000000ff

#define INADDR_ANY (u_long)0x00000000
#define INADDR_LOOPBACK 0x7f000001
#define INADDR_BROADCAST (u_long)0xffffffff /* must be masked */
#define INADDR_NONE 0xffffffff /* -1 return */

/*
* Socket address, internet style.
*/
struct sockaddr_in {
short sin_family;
u_short sin_port;
struct in_addr sin_addr;
char sin_zero[8];
};

#define WSADESCRIPTION_LEN 256
#define WSASYS_STATUS_LEN 128

typedef struct WSAData {
WORD wVersion;
WORD wHighVersion;
char szDescription[WSADESCRIPTION_LEN+1];
char szSystemStatus[WSASYS_STATUS_LEN+1];
int iMaxSockets;
int iMaxUdpDg;
char FAR * lpVendorInfo;
} WSADATA;

typedef WSADATA FAR *LPWSADATA;

/*
* Options for use with [gs]etsockopt at the IP level.
*/
#define IP_OPTIONS 1 /* set/get IP per-packet options */

/*
* Definitions related to sockets: types, address families, options,
* taken from the BSD file sys/socket.h.
*/

/*
* This is used instead of -1, since the
* SOCKET type is unsigned.
*/
#define INVALID_SOCKET (SOCKET)(~0)
#define SOCKET_ERROR (-1)

/*
* Types
*/
#define SOCK_STREAM 1 /* stream socket */
#define SOCK_DGRAM 2 /* datagram socket */
#define SOCK_RAW 3 /* raw-protocol interface */
#define SOCK_RDM 4 /* reliably-delivered message */
#define SOCK_SEQPACKET 5 /* sequenced packet stream */

/*
* Option flags per-socket.
*/
#define SO_DEBUG 0x0001 /* turn on debugging info recording */
#define SO_ACCEPTCONN 0x0002 /* socket has had listen() */
#define SO_REUSEADDR 0x0004 /* allow local address reuse */
#define SO_KEEPALIVE 0x0008 /* keep connections alive */
#define SO_DONTROUTE 0x0010 /* just use interface addresses */
#define SO_BROADCAST 0x0020 /* permit sending of broadcast msgs */
#define SO_USELOOPBACK 0x0040 /* bypass hardware when possible */
#define SO_LINGER 0x0080 /* linger on close if data present */
#define SO_OOBINLINE 0x0100 /* leave received OOB data in line */

#define SO_DONTLINGER (u_int)(~SO_LINGER)

/*
* Additional options.
*/
#define SO_SNDBUF 0x1001 /* send buffer size */
#define SO_RCVBUF 0x1002 /* receive buffer size */
#define SO_SNDLOWAT 0x1003 /* send low-water mark */
#define SO_RCVLOWAT 0x1004 /* receive low-water mark */
#define SO_SNDTIMEO 0x1005 /* send timeout */
#define SO_RCVTIMEO 0x1006 /* receive timeout */
#define SO_ERROR 0x1007 /* get error status and clear */
#define SO_TYPE 0x1008 /* get socket type */

/*
* Address families.
*/
#define AF_UNSPEC 0 /* unspecified */
#define AF_UNIX 1 /* local to host (pipes, portals) */
#define AF_INET 2 /* internetwork: UDP, TCP, etc. */
#define AF_IMPLINK 3 /* arpanet imp addresses */
#define AF_PUP 4 /* pup protocols: e.g. BSP */
#define AF_CHAOS 5 /* mit CHAOS protocols */
#define AF_NS 6 /* XEROX NS protocols */
#define AF_NBS 7 /* nbs protocols */
#define AF_ECMA 8 /* european computer manufacturers */
#define AF_DATAKIT 9 /* datakit protocols */
#define AF_CCITT 10 /* CCITT protocols, X.25 etc */
#define AF_SNA 11 /* IBM SNA */
#define AF_DECnet 12 /* DECnet */
#define AF_DLI 13 /* Direct data link interface */
#define AF_LAT 14 /* LAT */
#define AF_HYLINK 15 /* NSC Hyperchannel */
#define AF_APPLETALK 16 /* AppleTalk */

#define AF_MAX 17

/*
* Structure used by kernel to store most
* addresses.
*/
struct sockaddr {
u_short sa_family; /* address family */
char sa_data[14]; /* up to 14 bytes of direct address */
};

/*
* Structure used by kernel to pass protocol
* information in raw sockets.
*/
struct sockproto {
u_short sp_family; /* address family */
u_short sp_protocol; /* protocol */
};

/*
* Protocol families, same as address families for now.
*/
#define PF_UNSPEC AF_UNSPEC
#define PF_UNIX AF_UNIX
#define PF_INET AF_INET
#define PF_IMPLINK AF_IMPLINK
#define PF_PUP AF_PUP
#define PF_CHAOS AF_CHAOS
#define PF_NS AF_NS
#define PF_NBS AF_NBS
#define PF_ECMA AF_ECMA
#define PF_DATAKIT AF_DATAKIT
#define PF_CCITT AF_CCITT
#define PF_SNA AF_SNA
#define PF_DECnet AF_DECnet
#define PF_DLI AF_DLI
#define PF_LAT AF_LAT
#define PF_HYLINK AF_HYLINK
#define PF_APPLETALK AF_APPLETALK

#define PF_MAX AF_MAX

/*
* Structure used for manipulating linger option.
*/
struct linger {
u_short l_onoff; /* option on/off */
u_short l_linger; /* linger time */
};

/*
* Level number for (get/set)sockopt() to apply to socket itself.
*/
#define SOL_SOCKET 0xffff /* options for socket level */

/*
* Maximum queue length specifiable by listen.
*/
#define SOMAXCONN 5

#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_PEEK 0x2 /* peek at incoming message */
#define MSG_DONTROUTE 0x4 /* send without using routing tables */

#define MSG_MAXIOVLEN 16

/*
* Define constant based on rfc883, used by gethostbyxxxx() calls.
*/
#define MAXGETHOSTSTRUCT 1024

/*
* All Windows Sockets error constants are biased by WSABASEERR from the "normal"
*/
#define WSABASEERR 10000
/*
* Windows Sockets definitions of regular Microsoft C error constants
*/
#define WSAEINTR (WSABASEERR+4)
#define WSAEBADF (WSABASEERR+9)
#define WSAEFAULT (WSABASEERR+14)
#define WSAEINVAL (WSABASEERR+22)
#define WSAEMFILE (WSABASEERR+24)

/*
* Windows Sockets definitions of regular Berkeley error constants
*/
#define WSAEWOULDBLOCK (WSABASEERR+35)
#define WSAEINPROGRESS (WSABASEERR+36)
#define WSAEALREADY (WSABASEERR+37)
#define WSAENOTSOCK (WSABASEERR+38)
#define WSAEDESTADDRREQ (WSABASEERR+39)
#define WSAEMSGSIZE (WSABASEERR+40)
#define WSAEPROTOTYPE (WSABASEERR+41)
#define WSAENOPROTOOPT (WSABASEERR+42)
#define WSAEPROTONOSUPPORT (WSABASEERR+43)
#define WSAESOCKTNOSUPPORT (WSABASEERR+44)
#define WSAEOPNOTSUPP (WSABASEERR+45)
#define WSAEPFNOSUPPORT (WSABASEERR+46)
#define WSAEAFNOSUPPORT (WSABASEERR+47)
#define WSAEADDRINUSE (WSABASEERR+48)
#define WSAEADDRNOTAVAIL (WSABASEERR+49)
#define WSAENETDOWN (WSABASEERR+50)
#define WSAENETUNREACH (WSABASEERR+51)
#define WSAENETRESET (WSABASEERR+52)
#define WSAECONNABORTED (WSABASEERR+53)
#define WSAECONNRESET (WSABASEERR+54)
#define WSAENOBUFS (WSABASEERR+55)
#define WSAEISCONN (WSABASEERR+56)
#define WSAENOTCONN (WSABASEERR+57)
#define WSAESHUTDOWN (WSABASEERR+58)
#define WSAETOOMANYREFS (WSABASEERR+59)
#define WSAETIMEDOUT (WSABASEERR+60)
#define WSAECONNREFUSED (WSABASEERR+61)
#define WSAELOOP (WSABASEERR+62)
#define WSAENAMETOOLONG (WSABASEERR+63)
#define WSAEHOSTDOWN (WSABASEERR+64)
#define WSAEHOSTUNREACH (WSABASEERR+65)
#define WSAENOTEMPTY (WSABASEERR+66)
#define WSAEPROCLIM (WSABASEERR+67)
#define WSAEUSERS (WSABASEERR+68)
#define WSAEDQUOT (WSABASEERR+69)
#define WSAESTALE (WSABASEERR+70)
#define WSAEREMOTE (WSABASEERR+71)

/*
* Extended Windows Sockets error constant definitions
*/
#define WSASYSNOTREADY (WSABASEERR+91)
#define WSAVERNOTSUPPORTED (WSABASEERR+92)
#define WSANOTINITIALISED (WSABASEERR+93)

/*
* Error return codes from gethostbyname() and gethostbyaddr()
* (when using the resolver). Note that these errors are
* retrieved via WSAGetLastError() and must therefore follow
* the rules for avoiding clashes with error numbers from
* specific implementations or language run-time systems.
* For this reason the codes are based at WSABASEERR+1001.
* Note also that [WSA]NO_ADDRESS is defined only for
* compatibility purposes.
*/

#define h_errno WSAGetLastError()

/* Authoritative Answer: Host not found */
#define WSAHOST_NOT_FOUND (WSABASEERR+1001)
#define HOST_NOT_FOUND WSAHOST_NOT_FOUND

/* Non-Authoritative: Host not found, or SERVERFAIL */
#define WSATRY_AGAIN (WSABASEERR+1002)
#define TRY_AGAIN WSATRY_AGAIN

/* Non recoverable errors, FORMERR, REFUSED, NOTIMP */
#define WSANO_RECOVERY (WSABASEERR+1003)
#define NO_RECOVERY WSANO_RECOVERY

/* Valid name, no data record of requested type */
#define WSANO_DATA (WSABASEERR+1004)
#define NO_DATA WSANO_DATA

/* no address, look for MX record */
#define WSANO_ADDRESS WSANO_DATA
#define NO_ADDRESS WSANO_ADDRESS

/*
* Windows Sockets errors redefined as regular Berkeley error constants
*/
#define EWOULDBLOCK WSAEWOULDBLOCK
#define EINPROGRESS WSAEINPROGRESS
#define EALREADY WSAEALREADY
#define ENOTSOCK WSAENOTSOCK
#define EDESTADDRREQ WSAEDESTADDRREQ
#define EMSGSIZE WSAEMSGSIZE
#define EPROTOTYPE WSAEPROTOTYPE
#define ENOPROTOOPT WSAENOPROTOOPT
#define EPROTONOSUPPORT WSAEPROTONOSUPPORT
#define ESOCKTNOSUPPORT WSAESOCKTNOSUPPORT
#define EOPNOTSUPP WSAEOPNOTSUPP
#define EPFNOSUPPORT WSAEPFNOSUPPORT
#define EAFNOSUPPORT WSAEAFNOSUPPORT
#define EADDRINUSE WSAEADDRINUSE
#define EADDRNOTAVAIL WSAEADDRNOTAVAIL
#define ENETDOWN WSAENETDOWN
#define ENETUNREACH WSAENETUNREACH
#define ENETRESET WSAENETRESET
#define ECONNABORTED WSAECONNABORTED
#define ECONNRESET WSAECONNRESET
#define ENOBUFS WSAENOBUFS
#define EISCONN WSAEISCONN
#define ENOTCONN WSAENOTCONN
#define ESHUTDOWN WSAESHUTDOWN
#define ETOOMANYREFS WSAETOOMANYREFS
#define ETIMEDOUT WSAETIMEDOUT
#define ECONNREFUSED WSAECONNREFUSED
#define ELOOP WSAELOOP
#define ENAMETOOLONG WSAENAMETOOLONG
#define EHOSTDOWN WSAEHOSTDOWN
#define EHOSTUNREACH WSAEHOSTUNREACH
#define ENOTEMPTY WSAENOTEMPTY
#define EPROCLIM WSAEPROCLIM
#define EUSERS WSAEUSERS
#define EDQUOT WSAEDQUOT
#define ESTALE WSAESTALE
#define EREMOTE WSAEREMOTE

/* Socket function prototypes */

SOCKET PASCAL FAR accept (SOCKET s, struct sockaddr FAR *addr,
int FAR *addrlen);

int PASCAL FAR bind (SOCKET s, struct sockaddr FAR *addr, int namelen);

int PASCAL FAR closesocket (SOCKET s);

int PASCAL FAR connect (SOCKET s, struct sockaddr FAR *name, int namelen);

int PASCAL FAR ioctlsocket (SOCKET s, long cmd, int arg);

int PASCAL FAR getpeername (SOCKET s, struct sockaddr FAR *name,
int FAR * namelen);

int PASCAL FAR getsockname (SOCKET s, struct sockaddr FAR *name,
int FAR * namelen);

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

u_long PASCAL FAR htonl (u_long hostlong);

u_short PASCAL FAR htons (u_short hostshort);

struct in_addr PASCAL FAR inet_addr (char FAR * cp);

char FAR * PASCAL FAR inet_ntoa (struct in_addr in);

int PASCAL FAR listen (SOCKET s, int backlog);

u_long PASCAL FAR ntohl (u_long netlong);

u_short PASCAL FAR ntohs (u_short netshort);

int PASCAL FAR recv (SOCKET s, char FAR * buf, int len, int flags);

int PASCAL FAR recvfrom (SOCKET s, char FAR * buf, int len, int flags,
struct sockaddr FAR *from, int FAR * fromlen);

long PASCAL FAR select (int nfds, fd_set FAR *readfds, fd_set far *writefds,
fd_set FAR *exceptfds, struct timeval far *timeout);

int PASCAL FAR send (SOCKET s, char FAR * buf, int len, int flags);

int PASCAL FAR sendto (SOCKET s, char FAR * buf, int len, int flags,
struct sockaddr FAR *to, int tolen);

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

int PASCAL FAR shutdown (SOCKET s, int how);

SOCKET PASCAL FAR socket (int af, int type, int protocol);

/* Database function prototypes */

struct hostent FAR * PASCAL FAR gethostbyaddr(char FAR * addr,
int len, int type);

struct hostent FAR * PASCAL FAR gethostbyname(char FAR * name);

struct servent FAR * PASCAL FAR getservbyport(int port, char FAR * proto);

struct servent FAR * PASCAL FAR getservbyname(char FAR * name,
char FAR * proto);

struct protoent FAR * PASCAL FAR getprotobynumber(int proto);

struct protoent FAR * PASCAL FAR getprotobyname(char FAR * name);

/* Microsoft Windows Extension function prototypes */

int PASCAL FAR WSAStartup(WORD wVersionRequired, LPWSADATA lpWSAData);

int PASCAL FAR WSACleanup(void);

void PASCAL FAR WSASetLastError(int iError);

int PASCAL FAR WSAGetLastError(void);

BOOL PASCAL FAR WSAIsBlocking(void);

int PASCAL FAR WSAUnhookBlockingHook(void);

FARPROC PASCAL FAR WSASetBlockingHook(FARPROC lpBlockFunc);

int PASCAL FAR WSACancelBlockingCall(void);

HANDLE PASCAL FAR WSAAsyncGetServByName(HWND hWnd, u_int wMsg,
char FAR * name, char FAR * proto,
char FAR * buf, int buflen);

HANDLE PASCAL FAR WSAAsyncGetServByPort(HWND hWnd, u_int wMsg, int port,
char FAR * proto, char FAR * buf,
int buflen);

HANDLE PASCAL FAR WSAAsyncGetProtoByName(HWND hWnd, u_int wMsg,
char FAR * name, char FAR * buf,
int buflen);

HANDLE PASCAL FAR WSAAsyncGetProtoByNumber(HWND hWnd, u_int wMsg,
int number, char FAR * buf,
int buflen);

HANDLE PASCAL FAR WSAAsyncGetHostByName(HWND hWnd, u_int wMsg,
char FAR * name, char FAR * buf,
int buflen);

HANDLE PASCAL FAR WSAAsyncGetHostByAddr(HWND hWnd, u_int wMsg,
char FAR * addr, int len, int type,
char FAR * buf, int buflen);

int PASCAL FAR WSACancelAsyncRequest(HANDLE hAsyncTaskHandle);

int PASCAL FAR WSAAsyncSelect(SOCKET s, HWND hWnd, u_int wMsg,
long lEvent);

/* Microsoft Windows Extended data types */
typedef struct sockaddr SOCKADDR;
typedef struct sockaddr *PSOCKADDR;
typedef struct sockaddr FAR *LPSOCKADDR;

typedef struct sockaddr_in SOCKADDR_IN;
typedef struct sockaddr_in *PSOCKADDR_IN;
typedef struct sockaddr_in FAR *LPSOCKADDR_IN;

typedef struct linger LINGER;
typedef struct linger *PLINGER;
typedef struct linger FAR *LPLINGER;

typedef struct in_addr IN_ADDR;
typedef struct in_addr *PIN_ADDR;
typedef struct in_addr FAR *LPIN_ADDR;

typedef struct fd_set FD_SET;
typedef struct fd_set *PFD_SET;
typedef struct fd_set FAR *LPFD_SET;

typedef struct hostent HOSTENT;
typedef struct hostent *PHOSTENT;
typedef struct hostent FAR *LPHOSTENT;

typedef struct servent SERVENT;
typedef struct servent *PSERVENT;
typedef struct servent FAR *LPSERVENT;

typedef struct protoent PROTOENT;
typedef struct protoent *PPROTOENT;
typedef struct protoent FAR *LPPROTOENT;

/*
* Windows message parameter composition and decomposition
* macros.
*
* WSAMAKEASYNCREPLY is intended for use by the Windows Sockets implementation
* when constructing the response to a WSAGetXByY()
*/
#define WSAMAKEASYNCREPLY(buflen,error) MAKELONG(buflen,error)
/*
* WSAMAKESELECTREPLY is intended for use by the Windows Sockets implementation
* when constructing the response to WSAAsyncSelect()
*/
#define WSAMAKESELECTREPLY(event,error) MAKELONG(event,error)
/*
* WSAGETASYNCBUFLEN is intended for use by the Windows Sockets application
* to extract the buffer length from the lParam in the response
* to a WSAGetXByY().
*/
#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
/*
* WSAGETASYNCERROR is intended for use by the Windows Sockets application
* to extract the error code from the lParam in the response
* to a WSAGetXByY().
*/
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)
/*
* WSAGETSELECTEVENT is intended for use by the Windows Sockets application
* to extract the event code from the lParam in the response
* to a WSAAsyncSelect().
*/
#define WSAGETSELECTEVENT(lParam) LOWORD(lParam)
/*
* WSAGETSELECTERROR is intended for use by the Windows Sockets application
* to extract the error code from the lParam in the response
* to a WSAAsyncSelect().
*/
#define WSAGETSELECTERROR(lParam) HIWORD(lParam)

#endif /* _WINSOCKAPI_ */



APPENDIX B Notes for Windows Sockets Suppliers
B.1 Introduction
A Windows Sockets implementation must implement ALL the functionality described in the Windows Sockets documentation. Validation of compliance is discussed in Appendix B, Section B.8.

Windows Sockets Version 1.0 implementations must support both TCP and UDP type sockets. An implementation may support raw sockets (of type SOCK_RAW), but their use is deprecated.

Certain APIs documented above have special notes for Windows Sockets implementors. A Windows Sockets implementation should pay special attention to conforming to the API as documented. The Special Notes are provided for assistance and clarification.

B.2 Windows Sockets Components
B.2.1 Development Components
The Windows Sockets development components for use by Windows Sockets application developers will be provided by each Windows Sockets supplier. These Windows Sockets development components are:

ComponentDescription
Windows Sockets DocumentationThis document
WINSOCK.LIB fileWindows Sockets API Import Library
WINSOCK.H fileWindows Sockets Header File
NETDB.H fileBerkeley Compatible Header File
ARPA/INET.H fileBerkeley Compatible Header File
SYS/TIME.H fileBerkeley Compatible Header File
SYS/SOCKET.H fileBerkeley Compatible Header File
NETINET/IN.H fileBerkeley Compatible Header File

B.2.2 Run Time Components
The run time component provided by each Windows Sockets supplier is:

ComponentDescription
WINSOCK.DLLThe Windows Sockets API implementation DLL

B.3 Multithreadedness and blocking routines.
Data areas returned by, for example, the getXbyY() routines MUST be on a per thread basis.

Note that an application MUST be prevented from making multiple nested Windows Sockets function calls. Only one outstanding function call will be allowed for a particular task. Any Windows Sockets call performed when an existing blocking call is already outstanding will fail with an error code of WSAEINPROGRESS. There are two exceptions to this restriction: WSACancelBlockingCall() and WSAIsBlocking() may be called at any time. Windows Sockets suppliers should note that although preliminary drafts of this specification indicated that the restriction only applied to blocking function calls, and that it would be permissible to make non-blocking calls while a blocking call was in progress, this is no longer true.

Regarding the implementation of blocking routines, the solution in Windows Sockets is to simulate the blocking mechanism by having each routine call PeekMessage() as it waits for the completion of its operation. In anticipation of this, the function WSASetBlockingHook() is provided to allow the programmer to define a special routine to be called instead of the default PeekMessage() loop. The blocking hook functions are discussed in more detail in 4.3.13, WSASetBlockingHook().

B.4 Database Files
The database routines in the getXbyY() family (gethostbyaddr(), etc.) were originally designed (in the first Berkeley UNIX releases) as mechanisms for looking up information in text databases. A Windows Sockets supplier may choose to employ local files OR a name service to provide some or all of this information. If local files exist, the format of the files must be identical to that used in BSD UNIX, allowing for the differences in text file formats.

B.5 FD_ISSET
It is necessary to implement the FD_ISSET Berkeley macro using a supporting function: __WSAFDIsSet(). It is the responsibility of a Windows Sockets implementation to make this available as part of the Windows Sockets API. Unlike the other functions exported by a Windows Sockets DLL, however, this function is not intended to be invoked directly by Windows Sockets applications: it should be used only to support the FD_ISSET macro. The source code for this function is listed below:

int FAR
__WSAFDIsSet(SOCKET fd, fd_set FAR *set)
{
int i = set->count;

while (i--)
if (set->fd_array[i] == fd)
return 1;

return 0;
}

B.6 Error Codes
In order to avoid conflict between various compiler environments Windows Sockets implementations MUST return the error codes listed in the API specification, using the manifest constants beginning with "WSA". The Berkeley-compatible error code definitions are provided solely for compatibility purposes for applications which are being ported from other platforms.

B.7 DLL Ordinal Numbers
The winsock.def file for use by every Windows Sockets implementation is as follows.

;
; File: winsock.def
; System: MS-Windows 3.x
; Summary: Module definition file for Windows Sockets DLL.
;

LIBRARY WINSOCK ; Application's module name

DESCRIPTION 'BSD Socket API for Windows'

EXETYPE WINDOWS ; required for all windows applications

STUB 'WINSTUB.EXE' ; generates error message if application
; is run without Windows

;CODE can be FIXED in memory because of potential upcalls
CODE PRELOAD FIXED

;DATA must be SINGLE and at a FIXED location since this is a DLL
DATA PRELOAD FIXED SINGLE

HEAPSIZE 1024
STACKSIZE 16384

; All functions that will be called by any Windows routine
; must be exported

EXPORTS
accept @1
bind @2
closesocket @3
connect @4
getpeername @5
getsockname @6
getsockopt @7
htonl @8
htons @9
inet_addr @10
inet_ntoa @11
ioctlsocket @12
listen @13
ntohl @14
ntohs @15
recv @16
recvfrom @17
select @18
send @19
sendto @20
setsockopt @21
shutdown @22
socket @23

gethostbyaddr @51
gethostbyname @52
getprotobyname @53
getprotobynumber @54
getservbyname @55
getservbyport @56

WSAAsyncSelect @101
WSAAsyncGetHostByAddr @102
WSAAsyncGetHostByName @103
WSAAsyncGetProtoByNumber @104
WSAAsyncGetProtoByName @105
WSAAsyncGetServByPort @106
WSAAsyncGetServByName @107
WSACancelAsyncRequest @108
WSASetBlockingHook @109
WSAUnhookBlockingHook @110
WSAGetLastError @111
WSASetLastError @112
WSACancelBlockingCall @113
WSAIsBlocking @114
WSAStartup @115
WSACleanup @116

__WSAFDIsSet @151

WEP @500 RESIDENTNAME

;eof

B.8 Validation Suite
The Windows Sockets Test and Validation suite to ensure Windows Sockets compliance is expected to be available from Microsoft from September 1992. To be made available under the "Windows Sockets compliant" banner, a Windows Sockets implementation must meet the conformance criteria laid down for this suite.
Appendix C Background Information
C.1 Origins of Windows Sockets
The Windows Sockets project had its origins in a Birds Of A Feather session held at Interop '91 in San Jose on October 10, 1991. A committee was established, and an intensive debate via email resulted in the creation of a first draft specification, which was largely based on submissions from JSB and NetManage. This draft, and issues arising from it, were debated at a committee meeting hosted by Microsoft in Redmond, WA on December 9, 1991. Following further email discussions, a working group was established to develop the specification into its current form.

The following people participated in the process as committee members, in working meetings, or in email review. The authors would like to thank everyone who participated in any way, and apologize in advance if we have omitted anyone.

Martin Hall (Moderator)
JSB Corporation
[email protected]

Mark Towfiq (Coordinator)
FTP Software
[email protected]

Geoff Arnold
Sun Microsystems, Inc.
[email protected]

Alistair Banks
Microsoft
[email protected]

Carl Beame
Beame & Whiteside
beame@mcmaster,ca

David Beaver
Microsoft
[email protected]

Amatzia BenArtzi
NetManage, Inc.
[email protected]

Mark Beyer
Ungermann-Bass
[email protected]

James Van Bokkelen
FTP Software
[email protected]

Nelson Bolyard
Silicon Graphics, Inc.
[email protected]

Pat Bonner
Hewlett-Packard
[email protected]

Isaac Chan
Microsoft
[email protected]

Nestor Fesas
Hughes LAN Systems
[email protected]

Gary Gere
Gupta
[email protected]

Bill Hayes
Hewlett-Packard
[email protected]

Hoek Law
Citicorp
[email protected]

Paul Hill
MIT
[email protected]

Graeme Le Roux
Moresdawn P/L
-

Terry Lister
Hewlett-Packard
[email protected]

Lee Murach
Network Research
[email protected]

David Pool
Spry, Inc.
[email protected]

Brad Rice
Age
[email protected]

Allen Rochkind
3Com
-

Henry Sanders
Microsoft
[email protected]

David Treadwell
Microsoft
[email protected]

Miles Wu
Wollongong
[email protected]

Boris Yanovsky
NetManage, Inc.
[email protected]



C.2 Roadmap

There are two ways to develop a standard specification. One can wait until there are one or two proven implementations in the marketplace, and embody the de facto standard as a formal specification. Alternatively one can develop a largely original specification, publish it, and wait for implementations and applications to emerge. The Windows Sockets effort has followed the second of these approaches. Compared with the first, this approach has a number of drawbacks which must be carefully managed. The principal problem is a classic chicken-and-egg: in the absence of a proven implementation, vendors and developers are concerned that there may be one or more problems within the specification which are not immediately obvious, will only emerge as people start to implement, and will require revisions which will obsolete some of the implementation work. Thus they are tempted to hold off on implementing to the first version of the specification, preferring to wait until a more stable draft emerges. Naturally if everybody follows this cautious approach, the process will never get anywhere.

We are publishing this version of the specification as version 1.0, and will make it widely available. During the summer of 1992, we expect a number of vendors to implement this specification. Those that do so will meet a few days before the Interop show which will take place in San Francisco in October, and will review the results of their work. A revised version of the specification will then be published at the Interop conference. There are three possibilities:
(1)No change is necessary: the current version is reissued as is, as version 1.0.
(2)The API is unchanged, but clarifications or corrections to the text of the specification are necessary. The new version will be issued as version 1.1.
(3)Additions or revisions to the API itself are required. The new version of the specification will be issued as version 2.0.

Our current expectation is that the second of these will occur, and that version 1.1 of the Windows Sockets specification will be published at Interop in October (one year after the process began). This will be the definitive Windows Sockets specification, and we will seek to publish it under the auspices of a standards organization which will allow us to formalize the process of future revision. At the present time, we expect that this publication will take the form of an informational Request For Comments (RFC).

Given that we do not anticipate any significant changes to the API, we expect that commercial implementations based on the present specification, and fully interoperable with versions built to the revised specification, will be commercially available at or soon after Interop.

Windows is a trademark of Microsoft Corporation.
UNIX is a trademark of Unix System Laboratories, Inc.
VAX is a trademark of Digital Equipment Corporation.
68000 is a trademark of Motorola, Inc.
This specification uses the function name getXbyY() to represent the set of routines gethostbyaddr(), gethostbyname(), etc. Similarly WSAAsyncGetXByY() represents WSAAsyncGetHostByAddr(), etc.
NT and Windows/NT are trademarks of Microsoft Corporation.



PAGEiv

PAGE13



PAGE2 Introduction

Introduction PAGE1



PAGE8 Programming with Sockets

Programming with Sockets PAGE9

PAGE12 Socket Library Overview

Socket Library Overview PAGE13


PAGE14 Socket Library Reference

Socket Library Reference PAGE14



PAGE16 accept

accept PAGE15

PAGE18 bind

bind PAGE17

PAGE20 closesocket

closesocket PAGE19

PAGE22 connect

connect PAGE21

PAGE23 getpeername

getpeername PAGE23

PAGE24 getsockname

getsockname PAGE24

PAGE26 getsockopt

getsockopt PAGE25

PAGE27 htonl

htonl PAGE27

PAGE28 htons

htons PAGE28

PAGE29 inet_addr

inet_addr PAGE29

PAGE30 inet_ntoa

inet_ntoa PAGE30

PAGE32 ioctlsocket

ioctlsocket PAGE31

PAGE34 listen

listen PAGE33

PAGE35 ntohl

ntohl PAGE35

PAGE36 ntohs

ntohs PAGE36

PAGE38 recv

recv PAGE37

PAGE40 recvfrom

recvfrom PAGE39

PAGE42 select

select PAGE41

PAGE44 send

send PAGE43

PAGE46 sendto

sendto PAGE47

PAGE50 setsockopt

setsockopt PAGE49

PAGE52 shutdown

shutdown PAGE51

PAGE54 socket

socket PAGE53

PAGE56 gethostbyaddr

gethostbyaddr PAGE55

PAGE57 gethostbyname

gethostbyname PAGE57

PAGE58 getprotobyname

getprotobyname PAGE59

PAGE60 getprotobynumber

getprotobynumber PAGE60

PAGE62 getservbyname

getservbyname PAGE61

PAGE63 getservbyport

getservbyport PAGE63

PAGE66 WSAAsyncGetHostByAddr

WSAAsyncGetHostByAddr PAGE65

PAGE68 WSAAsyncGetHostByName

WSAAsyncGetHostByName PAGE69

PAGE72 WSAAsyncGetProtoByName

WSAAsyncGetProtoByName PAGE71

PAGE74 WSAAsyncGetProtoByNumber

WSAAsyncGetProtoByNumber PAGE75

PAGE78 WSAAsyncGetServByName

WSAAsyncGetServByName PAGE77

PAGE80 WSAAsyncGetServByPort

WSAAsyncGetServByPort PAGE81

PAGE86 WSAAsyncSelect

WSAAsyncSelect PAGE85

PAGE88 WSACancelAsyncRequest

WSACancelAsyncRequest PAGE87

PAGE88 WSACancelBlockingCall

WSACancelBlockingCall PAGE89

PAGE90 WSACleanup

WSACleanup PAGE89

PAGE90 WSAGetLastError

WSAGetLastError PAGE91

PAGE92 WSAIsBlocking

WSAIsBlocking PAGE91

PAGE94 WSASetBlockingHook

WSASetBlockingHook PAGE93

PAGE94 WSASetLastError

WSASetLastError PAGE95

PAGE98 WSAStartup

WSAStartup PAGE97

PAGE98 WSAUnhookBlockingHook

WSAUnhookBlockingHook PAGE99

PAGE100 Appendix A1: Error Codes

Appendix A1: Error Codes PAGE101

PAGE102 Appendix A2: Header Files

Appendix A2: Header Files PAGE101

PAGE112 winsock.h

winsock.h PAGE113

PAGE116 Appendix B: Notes for Windows Sockets Suppliers

Appendix B: Notes for Windows Sockets Suppliers PAGE115

PAGE118 Appendix C: Background Information

Appendix C: Background Information PAGE117

WinSockAPIPAGE8







vz}u}::$.g_I&7],@@@@@@45IA &7&7(7&@@@@@@-4#PBrush&WordDocument%WINSOCKG.DOC%WordObject
0 0 55 38BMv(7&(ttwwwwwxwwwwwwwwwwwwwwwwwwwpwwwwxxwwxwwxwwxwwxwwwxwwwxwwxwx
METAFILEPICT$v-I&7],@@@@@@45IA &7&7(7&@@@@@@-4&'/0FGIK\^`bcyzKdnoJat#




"H(0w
B45!(!-!9!##$$%%%%'\(==1?>?7@G@FFGGsGGGGGHH1H4H>HAH]HlHHHHHI!IsIzIIIJJ+J,JCJFJMJOJrJyJJKKKDLLL
MMM'MyMM5N=NRNZNGPNPUPWPQRIRURvRRRRRR"S+S,S
\,S1SBSSSTTTU!U#UWWXXXXXXYYYYZ*ZZZ[[]]]]2^@^``aaeauaaa/c7cwdyddd6ffEfKfRfffffgghhhhhhgihiiill%m.mmmmmooXpapcqxqqq5r;r=r[rqrr

\rrmsssssst9tFttttt/u6uuuuuZvevvvvv:wAwwwwwxxZxbxxxxxxyMyWyyyyzS{Y{||||||A}G}2!0Oo2BHWKb13
b3Jcz
*26Ms,bqEVJZ
9?DJDEFZ^_`vwxvz!b!&-AIx|pwyZi +KWRihpqwy)*+ABFGKLTV\]/6IMRY:>
RbRU".CI
"$;T_stu45UV$_fLXmz.:9ABJLTVceqsb%'-.bf45/8n;B'2rstRYw{ZacI[_j7Bghi}#*+,<@KRS`AJntR^s4@y
-39=@GIOcOPw|x~@F1=DHrx}$9E8@AMO_ai|07
`'29^_`txyzKWX_)-./UXZ`b
!5T`u"#.EPce&;F
`$>Iklm"@CHOPo+,&*4ATVXe8Der&2bWXYmqrs)0gmMNCFw}
!FIN_doQY$
,
;
C
D
L
O
X
Z
b
v













`


+2 +2WXYmqrsE
Q
R
Y


















$%(-.46<=nq<= &!&LaL[+7LRwz#&(3S_E\jp !+-35;=EGWYaw"#'23;=CDqt3:X\hoGTtw{
^,34f !!"+""### #$#&#K#N#}##########$'$3$$$$$[%r%%%&'''5'8'''''''''''''''F(G(H(\(`(a(b(s(t(x((((((((((((5)7)>)
^>)r)z)))))**8*?*++,,#-+---.$.(.2.....E/N/////00G2N2P2X2]2f22233k4r4s4v4y4z4444444444444444444445
5555"5%5&585;5^5e5|555555#6*6l6t6667*7+7377c777788889999999999999999999:(:):*:>:B:C:D:U:V:W:d:g:l:m:p:u:v:|:~:::::::;;;;I;P;Q;U;<>D?I?@@o@~@AAAA%B(BBBBBBBCDiDlDAFGFZFdF
`dFGGGGGGGGGGGGGGHHHHH H!H4H5H6HCHFHKHLHOHTHUHZHrHtHyHzHHHHHHHHHII
IICIEIxI}IIIIIIIJJJJKKKKLLNLLLLLLLMMkMtMNNOO,P1PQQWQfQ~RRRRSS{SS
`SSSSSTTSUVUZU\UEWMW`WjWXXXXXXXXXXXXXXXXXYYYY0Y1Y2Y7Y8Y=YBYCYJYWY]YbYcYjYlYrYsYYYYYYY4Z:ZZZZZZZZZ+]1]f]l]]]]]B^H^^^^^L_Y_____K`R`l`t`````
aaWacWa]abbccccdd!fXfGgSgZg^ggggggggghh`jfjjjjjjjjjll&l2lllllllmmnnooooooopppp"p9pDpsptpupppppppppppppppp0q7q8q@qqqrrUsXssstt"t
`"t*t+t5t/u8uNuZuouyuuuv
v-v9vw)wwwwwwwxx3x4x5xIxMxNxOxbxcxexjxkxoxtxux~xxxxy
y:yByxyyyy{{{{~~S~W~^~b~~~~~r@AEx|I[_ja "(*35BDPR^`hkpr|~%&';=>?nosxy|=DER

-/>Wb+jwLXmcm|'*5UaYpt|}
!"TY[_c#Xos{|%'()UV]_cii%&';=>?c?os"&^m-1ht2DFQq}68G_j@Ev%cr%4
/:c: "(,FI[ax{ioy*0tz/2^u,C24=
`=
~,2(01@BY{%&*8>M1OSeipv4=lr, `!&.ER!)5[\]quvwSWx~
DJ
@]KN{Ia)28])-LRHPQaczDEIWX\bciuvy~CI'-DGRYf~39EK
`c~BH~e1Hhy~V\p{




2
T
_









!%27CDGLMTV\`6;{,05:?
`?B%CGY]dj(1`f 09 ,LR"{9F{
#)#$$$$$$$$Q%R%S%g%k%l%m%%%%%%%%%%%%%%%%%
`%%%%%S&W&&&&&'4'g'm'~''''''''''e)k)))))))**++++++a,g,,,q.w...//!0'0k0q00011(2+222W3n333%4<44444666666677w7}777%8+8::!<)<*<9<; `x<<<<<<<<<<<<<<<<<======g=k===>>w>~>>>%?+?m?q?????AAABzBBSCVCPDQDDDDD-E=E _KKLLLLLLLLGNHN`NnNNNRRRR)R/R3R;RDRJRVR^RiSjSSSTTVVV$VVVVVVVXXDYPYTY`YYYYYK[Q[[[X__&`K```aabbbbbbbbccc1c5c6c7cYcZckcmcrcccccc
`c6dGdZdqddd#e/eFe]eefffCfTfggiiijxkkkkkkkkkkkllll2lTl_lllllllllllmmznnppqqqqqq}rrrrrrssssssttttt%t[tgttt1u=uuuuvNvZvwwwwUxaxxcxxxxy
yyyyyzz[z\z]zqzuzvzwzzzz|{{{|.|?|||#}4}}}}};~L~M~X~~~~~~~:>EAI>IAHQe
RU&\h
`ozy "<=DFJQ`f %1;Ffr'(124:J!(}^np|
`JV\hiu%JRSY[ceq'>CO/;aij~EQ@Ljvw~lugpWQ

^QAJQZ$-7^7p7*8,89 :::<<<<8=f=@@~BBBBBBaDqDDD[FFFGxHHHHTTUV*Vk^w^DiEixiyiiiiijj?jHjjjyj{jjjjjjjjkkk k!k#k

[#k$k(k)k-k.k0k1k9k:k>k?k@kAk_k`kdkekfkgkokpktkukvkwkkkkkkkkkkkkkkkkkkkllllllBlClGlHlJlKlSlTlXlYl[l\lolpltlulwlxl|l}lllllllllllllllllllllllllllllllldllllllmmmm"m#m'm(m*m+m/m0m4m5m7m8mTmUmYmZm\m]mambmfmgmimjmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmnnnnnnnnnn,n-n1n2n4n5n9n:n>n?nAnBn^n_ncndnfngnkndknlnpnqnsntnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnoooooo"o#o'o(o*o+o/o0o4o5o7o8oJoKoOoPoRoSoWoXo\o]o_o`onooosotovowo{o|oooooooooooooooodooooooooooooooooooooopppppppp p"p#p'p(p,p-p/p0pPpQpUpVpXpYp]p^pbpcpepfppppppppppppppppppppppppppppqqqqqq
qqq0q1q5q6q8q9q=q>qBqCqEqFqfqgqkqdkqlqnqoqsqtqxqyq{q|qqqqqqqqqqqqqqqqqqqqrrrrr:r;r?r@rBrCrGrHrLrMrOrPrrrrrrrrrrrrrrrrrrrrrrrrrsssssss s$s%s's(sJsKsOsPsRsSsWsXs\s]s_s`ssssssssdsssssssssssssssssstttttttttttt@tAtEtFtHtItMtNtRtStUtVtvtwt{t|t~ttttttttttttttttttttttttttttuuuu u!u%u&u(u)u-u.u2u3u5u6ufugukulunuousutuxuyu|ud|u}uuuuuuuuuuuuuvvvvv
vvvvvvv3v4v8v9v!#2IKNPRTVXZ\^`bd!lz
/p!h!!!!C!!@@&2'2(2)2!
@@&2'2(2)2!!@0-Cz2K`s4E_
24Qg
)
J
a
c








/?Ti"6H!!%!!%!!%!!!h!!HHJax
=
]
~




:Pk"4Gf1_t%CKMoq!!!!!!!%h!%h!%!!!%!HW!Y!!###"$$&&&y'{''Z(\(r(v+x+,,m-o-g/i//00335551939==1@3@@@@CCDDFFFqGsGJJLLLMM!!!!!!
!
!0&*'*(*)*!!!!!!!!!!!!:MMMNNNN%N+NCNoNqNsNNNNNNNNNNOOOO O~vMM(l?B!

h
(l?B!

xh
(l?B!






h
x OMOSOUOWOeOkOOOOOOOOOOOOOOOPP
P"PGPUPWPYPgPmPPPPPPPPPQQQQZQaQcQeQpQuQQQQQQQQxh
xh
(l?B!

xh
7QRRRRRSS
SS!U#UHUVVEVWWmXoXYYYZZZ,Z>ZXZ`ZbZ{ZX\Z\\^^__;_=_a
aa/a





x-r[rqrrrrks!!!!!!!!!!!!!!!!;ksmsusssssst7t9tHttttttt-u/u8uuuuuuuXvZvgvvvvvvw8w:wCwwwwwww
xxxXxZxdxxxxxxxxxyKyMyYyyyyyl

l



ByyyzZ|\|~~jlmo02DFHYGIKd{s!!l

l



!!!!!!!!!l



+d3ac|
46O.`bsCEXl

l

l

l



.F7\'OQg+BD\^
zup
!
!!!`!!`!`!!!!!!!!!!!!!l



*$&ikuwynp {}"$kmEGqsfhXZ\( !
!!!!!!!!!!!!!!!!!!`
!
!
!4(-/PR
"!#VX46ln>?Tqseg!!!!!!!!!!!!!!!!!!!!`
!
! !2eg(*HJL^`579)+-`bbdUWEG!!!!
!!!!!!!!!!!!!!!!
!7
]_+-[]GI'prPRIK]_ "WY!!!!!
!
!!x!!!!!!!!!@!"7eg!#IKNPRdfHJwyKMOuwvx>@!!
!!!!!!!!!!
!
!!!!!!!7{}%+DFU[&;`bpv9;FKbdmr!p



l
a#%


&p
!!!!>$):l
n%

B
&p!p!p1.0
\^vxGIK+-\^`!57PRT01E!!!!!!!
!!!!!!
!!!!?E'(>ikFH79LEVX468VXTV!!!!!!!`
!X
!
!!!
!!!!
!!!!!!4UWoq')
bd%'qsKM9
;
e
f
v






!!!!!!!!!!!!
!
!
!!!!!!7

)+UWoqA
C
E









8:!!!!!!!!
!!!!!!!!
!!<+&(^`')cdw?ACoq13fhrt ""!!!!!!!
!
!!!!!!!!!!!!!6"+"""""""##W$Y$$$+%-%t%v%%%%%2&4&a&c&&&I'K''''''D(F(^(`((((5)7)p)r)))))6*8*,,!!
!
!!!!!!!!!!!!!!!
!
!
!5,..~00>2@222i4k4444455N5P57777788x8z88888597999999&:(:@:B::::::::;;!!!!!!!!!!!!!!!
!
!!!!!!!3;G;I;====B?D?m@o@~@FAHAAAABBCChCjCCCDDYD[DDDEEPERE|E~EEEEFFFFF}GGGGGHHHHHH!!!!!!!!!!!!
!
!!!!!!!
!7HHHHHHI
IAICIvIxIIIiKkKKKLLoNqN*P,PUQWQfQ.R0RzR|R~RSSSSRTTTTTTTCUEUUUUUAVCVVVVVWWWWWWXX!!!!!!!!
!!!!!!!!!
!
!!=XXXXXXYYnYpYrYYYYY2Z4ZZZZZn\p\u^w^___````*a,addggggggggggs
l
a#%


&p!!!h
!!!!!!
!
!
!!!!!!!-gggh
h+h-hii!i2i4i?iTiiiiiiiiijjjjkjmjxj}jjjjjjjjjjjjkk k%kAkCkPkUkmk
l
n%
B!p!p





&p
l
a#%
8mkok|kkkkkkkkkkkkkklllllmm|m~mmm
nn.n0nqnsnfohooooo%p&p9pqpsppppppp
!!!!!!!!!!!!!!!

B
&p
l
n%1pp.q0qqqrrKsMssst t"tyt{tLuNuvv]v_vvvvv+w-wrwtwwwwwxxx1x3xKxMxxxxyy8y:yvyxyWzYz!
!!!!!!!!!!!!!!!!!!!
!
!4Yz{{{{{||G}I}K}pr]_ "ce*,ik
#%<=<=
!!!!!!!!!!!!!!!!!!!!4='6UXY}CXY!CD~
@AW!
!!!!!!!!!!!!
!
!!!!!!!7IKL)*%&ef)+rst \^_'(:Nky|}=>df(*
!!!!
!!!!!!!!!!!!!?*qrs
&'`bcBDuw9;#%<=56G[x!!!!
!!!!!!
!!!!!!!!!9,eghEFKLHI_@
tv=?!"gi!!
!
!!!!!!!!!!!!
!
!!;/$&(DFY[46
IKfh#4%'~!!!!!!!!!! !!!!!!
!
!
!
!!!!!!!1kmCDAC&([\{]_a?A

KM!!!!!
!
!
!
!!!!!!!!!!!!!!5M(*,rt$&OQDE
Y[Y[su!!!!!!!!!!!!!!!!!!!!!! !3uQSvx/1NP'ce68CTEG)+~yyy!!!!!!!!!!!!!! !!!!!!
!
!
!
!!!!/+cd!#acFH|}AC%'PRUWz|~! !!!!!!
!
!
!
!!!!!!!!!!!!4~68|~npCE

[
\




bd`b4
5
T




XZ\~!!!!!!!!!!!!!!!!!!!!!!!!/\46=??A} fh
C!E!{!}!!!!~~~~~!!!!!!!!!!!!!! !!!!!!!
!
!
!
!
!1!!8"9"s"u"""M#O#####$$$$$O%Q%i%k%%%%Q&S&&&&&''c)e)))++..+0-0001@1B11~! !!!!!!
!
!
!
!
!!!!!!!!!!!!!1111_2a23344666-67 777d8f88899<9=9|9}99999:::::;<;;;>u>w>??%@'@6@u@@@=A~AAABBBBCCD3D5DDDE EFFUFWFGGjHlHHHHIIKIIIIII%JgJJJ!!!!!!!!! !!!!!!!@`!!
!
!
!!8JJJKKkLmL*N,NxNN"OZOO1P3PTPVPQQR R=RLR`RqRRR*S,SSS,TT9UUUWWYYYYBZDZZZZZ[[!!!!!!!
!
!!!!!!
!
!
!!!!!!!2[[\\p\r\\\]]?]A]o]q]]]]]^
^W^Y^^^^^__V_X_i_y_____$`&`1`B`-a/aaabbbbbcc3c5cocqcrccc
!!!!!!!!!!!
!@`@!!!!!!,9ce!e#e
ffggggii*j,jjjjj&k(ktkvkxk4l5lTlllllllVmXmmmnnooqqrrrrTsVssssssstt!!!!!!!!!!!!!!!!
!!!7tt/u1uuuuvwwww!x#xxx1y3yyyyyyyzYz[zszuzzzz{|{{{||}}~~~~~<>?A!!!!!!!!!!!!!!!!!!!!!!5A !>?A<\n')KZjAInZ\mo!!!!!!!!!!
!!!!!!!!!;02wyHJ\^`#%9;68:{}|w!>!!
!
!
!!!!!!!
!!!!!!!!!!!,@BP^p~^XXRLF^X(l?4
t4d

(l?4
t4d

(l?4
t4d






X!!! %*/68ERW\fhjY[0Zm~~ytojyeeeeeeeeey`[!!!!!!!(l?4
t4d






X(l?4
t4d

X#"XZ\VXHJstAC_a~yto!!!!!!!!!!!!!!!!!!!!
!

!
!
!
!
!
!*
-/:BI[]hpwQS`jq|~vp8
"l3tDT!

"l3tDT!

"l3tDT!





8
!!!,~")46FSZeg{'.9;LZaln}ik{8
"l3tDT!

8
N)+7@GRT`ip{}!(35FT[fhry 029"l3tDT!

"l3tDT!

8
A9 *,8AHSUWYegytojojooo!!!"l3tDT!





8
"l3tDT!

8
"l3tDT!

8
(CEWY[\nQZgs3I_u;{:?Uk<]_cZ
:SU !!!!!!!!!!OUn35Rb&`'*,IVX\#')-IMzc/i
].y*,tvFHc(i5w|~Q $&!c&*WlqAz~H![_aeK$_=?.Rv*Nr>b:<@UZ
;af!cSXj{#@0R}"&(,b'Sw@d/R~.wy}59;`A?AE}EJLPz:yP!cPRVsxX:%'TVZrw=H1}L[[%'+Vej}Cch|5:]~$De.Qwy&ae!cegk16QS46RTX %LP-^@q
5
f



*[P
E
v


:k/`16gI9pR!cRT'Z!Gs&V=m5f$R
7eP~
5`KMKM57u M O !![!]!!!!!c!>"""""#P#R######:$<$`$b$$$$(%*%v%x%%%%;&=&&&&&'''')'W'Y'''''''((E(G((())e)))))*t****8+q+s+++3,5,u,,-
-J-L-----.1.[.]...../#/I/K/l//////0!0!c!0B0e0000000 1E1o1q1u11112F2K22223 3c3g33344M4Q44444357555556"6o666677'7)7+7-7.7^7p7*8,88899: ::::*;_;;;;S;SiSSSS!T#TQTSTTTTTTUUV,VeXgXSYUYnYYYYYYYYYYZZZ&Z>Z@ZLZ_ZrZtZZZZZZZZZZZ
[[#[1[?[A[Q[i[y[{[[
l

T!h
!!!!!Q[[[[[[[[[\\\\$\5\7\C\T\n\p\z\\\\\\\\\\\\\]]]]0]=]?]K]W]f]h]s]x]]]]]]]]]]]]]^^^!^-^/^?^P^e^g^i^k^y^{^bbddeff*h!!!!!!
l

T!h
O*h,hBiDixiiijjkkkk&k(k3k5k7k9kPkRkikkkmkokkkkkkkll'l)lMlOlQlSlflhlzl|lllllllllllllmm-m/mFmHm_mamwmymmmmmmmmmmmmmnn n"n7n9n!c!c!!!R9nPnRninkn}nnnnnnnnnnnnnnoooo-o/oAoCoUoWogoioyo{ooooooooooooopp%p'p@pBp[p]pvpxpppppppppqq q"q;q=qVqXqqqsqqqqqqqqq!r#rErGrkrmrrrrr!c!cZrrrrrss9s;sUsWsxszssssssssstt.t0tKtMtfthtttttttttttuu+u-uNuPuqusuuuuuuuvv'v)v?vAv}vvvvvvww5w7w9w;w=w?wAwCw!(!c!cJdescincludesyntaxdescripparamreturnserrorsseeparamtexterrors2descrip2returns2returns3valval1val2descrip3descrip4val3val4notesnotes2Notes3Notes4commentserrors3errors4code
hdr-file-codeerr-tableparamcode
NormalHeadF



@,x(!
h
`
`
`
`
@`
`
`



@`

p
p
p

`
`
`


`,
#p@p@ !"1



!""$dEEQUu4mmmmm65

!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqgstuvS"px52
)c&i8@FDWnv7'*:eZN#:@ajrxx.}5#5iTuCwOwYw\w_wbwewhwkwnwqwtwwwzw}wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwTS"
1
BpLU_+lp{x5sxe2y
) c& 1i8'A@FOuVDWa;knuv~7'*:eZ$5 N#<.7:BL"W]@aijrxx.}S5#8M
#X.5AJiT\u06N_~M
h
@G3T !"#$%&'2()*+[,-./001[23=4567889:;<=>?@A?BCD:EFBGBHIJBKLMNOoP?QRSTUVWXYZ[\]^_`Danbcdefghi$j,kl3m1n.op!qrzs,tu
v";TX}89
\




*h $(.,Sr3!RO
L>)7dFSWa"tm?:=?%x+",;HXgmkpYz=*Mu+~\!1=J[ctA~9U&PeR!!0f=/P[*h9nrCw

!"#$%&'()*+,-./0123456789:;<=>?@ABCDEgTimesSymbol"Helvetica
1CourierTimes New Roman5Courier New1MS LineDraw&Arial
*,u:999"')HMOX]_+03AFKNotw|!&+.OTW\ad#(+058otw|
38;@EHy~).16;>_dglqt





O
T
W
\
a
e











!%*/3.!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!,contentssockopt
SocketOptionsacceptbindclosesocketconnectgetpeernamegetsockname
getsockopthtonlhtonsinet_addrinet_ntoafcntllistenntohlntohsrecvrecvfromselectsendsendto
setsockoptshutdownsocket
gethostbyaddrnow
gethostbynamegetprotobynamegetprotobynumber
getservbyname
getservbyportWSAGetHostByAddrWSAGetHostByNameWSAGetProtoByNameWSAGetProtoByNumberWSAGetServByNameWSAGetServByPortWSASelectWindowWSACancelGetXbyYWSACancelBlockingCalWSASetBlockingHookWSASetLastError
WSAStartupWSAUnhookBlockingHooAppendixAAppendixBrpLQ? <
3m&s8JFNWnvT?-0@`T#:Faj";5g

!"#$%&'()*+,-./|pLQ? <
3m&s8JFNWnvTB-0@`T#:Faj";*5g#hsZZzZ|Y
WinSockAPI$WinSockAPI Specification Version 1.0Geoff ArnoldGeoff Arnold