Windows Sockets

Note

Acknowledgements

• Joel Golberger of InfoMagic, Inc. for the work he did on the Windows Help version of the Windows Sockets Specification. I used his .RTF file as the source file for this document.
• Chris Hector of Cray Research Inc. for his package rtftohtml, which was used to generate this document.

Table of Contents

• Authors and Copyright
• Acknowledgments
• Introduction
• What is Windows Sockets
• Berkeley Sockets
• Microsoft Windows and Windows-specific extensions
• The Status of this Specification
• Revision History
• Windows Sockets Version 1.0
• Windows Sockets Version 1.1
• Programming with Sockets
• Windows Sockets Stack Installation Checking
• Sockets
• Basic concepts
• Client-server model
• Out-of-band data
• Broadcasting
• Byte Ordering
• Socket Options
• Database Files
• Deviation from Berkeley Sockets
• socket data type and error values
• select() and FD_*
• Error codes - errno, h_errno & WSAGetLastError()
• Pointers
• Renamed functions
• Blocking routines & EINPROGRESS
• Maximum number of sockets supported
• Include files
• Return values on API failure
• Raw Sockets
• Windows Sockets in Multithreaded Versions of Windows
• Socket Library Overview
• Socket Functions
• Blocking/Non blocking & Data Volatility
• Database Functions
• Microsoft Windows-specific Extension Functions
• Asynchronous select() Mechanism
• Asynchronous Support Routines
• Hooking Blocking Methods
• Error Handling
• Accessing a Windows Sockets DLL from an Intermediate DLL
• Internal use of Messages by Windows Sockets Implementations
• Private API Interfaces
• Socket Library Reference
• Socket Routines
• accept()
• bind()
• closesocket()
• connect()
• getpeername()
• getsockname()
• getsockopt()
• htonl()
• htons()
• inet_addr()
• inet_ntoa()
• ioctlsocket()
• listen()
• ntohl()
• ntohs()
• recv()
• recvfrom()
• select()
• send()
• sendto()
• setsockopt()
• shutdown()
• socket()
• Database Routines
• gethostbyaddr()
• gethostbyname()
• gethostname()
• getprotobyname()
• getprotobynumber()
• getservbyname()
• GetServByPort()
• Microsoft Windows-specific Extensions
• WSAAsyncGetHostByAddr()
• WSAAsyncGetHostByName()
• WSAAsyncGetProtoByName()
• WSAAsyncGetProtoByNumber()
• WSAAsyncGetServByName()
• WSAAsyncGetServByPort()
• WSAAsyncSelect()
• WSACancelAsyncRequest()
• WSACancelBlockingCall()
• WSACleanup()
• WSAGetLastError()
• WSAIsBlocking()
• WSASetBlockingHook()
• WSASetLastError()
• WSAStartup()
• WSAUnhookBlockingHook()
• Appendices
• Error Codes and Header Files
• Error Codes
• Header Files
• Berkeley Header Files
• Windows Sockets Header File - winsock.h
• Notes for Windows Sockets Suppliers
• Introduction
• Windows Sockets Components
• Development Components
• Run Time Components
• Multithreadedness and blocking routines.
• Database Files
• FD_ISSET
• Error Codes
• DLL Ordinal Numbers
• Validation Suite
• For Further Reference
• Background Information
• Origins of Windows Sockets
• Legal Status of Windows Sockets
• The Story Behind the Windows Sockets Icon

Authors and Copyright

Martin Hall
Mark Towfiq
Geoff Arnold
David Treadwell
Henry Sanders

Copyright (c) 1992 by Martin Hall, Mark Towfiq
Geoff Arnold, David Treadwell and Henry Sanders

All rights reserved.

Acknowledgments

 Special thanks should also be extended to the other efforts contributing to the success of Windows Sockets. The original draft was heavily influenced by existing specifications offered and detailed by JSB Corporation and NetManage, Inc. The "version 1.0 debate" hosted by Microsoft in Seattle allowed many of the members of the working group to hash out final details for 1.0 vis-a-vis.

Sun Microsystems was kind enough to allow first time implementors to "plug and play" beta software during the first Windows Sock-A-Thon of Windows Sockets applications and implementations at Interop Fall '92. Microsoft has shared WSAT (the Windows Sockets API Tester) with other Windows Sockets implementors as a standard Windows Sockets test suite to aid in testing their implementations. Finally, Sun Microsystems and FTP Software plan to host the Windows Sock-A-Thon II in Boston February '93.

Without the contributions of the individuals and corporations involved in the working group, Windows Sockets would never have been as thoroughly reviewed and completed as quickly. In just one year, several competitors in the networking business developed a useful specification with something to show for it! Many thanks to all which participated, either in person or on e-mail to the Windows Sockets effort. The authors would like to thank everyone who participated in any way, and apologize in advance for anyone we have omitted.

List of contributors:

Martin Hall     (Chairman)      JSB Corporation         martinh@jsbus.com

Mark Towfiq     (Coordinator)   Microdyne Corporation   towfiq@microdyne.com

Geoff Arnold    (Editor 1.0)    Sun Microsystems        geoff@east.sun.com

David Treadwell (Editor 1.1)    Microsoft Corporation   davidtr@microsoft.com

Henry Sanders                   Microsoft Corporation   henrysa@microsoft.com

Introduction

What is Windows Sockets

 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.

Berkeley Sockets

 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.

Microsoft Windows and Windows-specific extensions

Windows Sockets makes provisions for multithreaded Windows processes. A process contains one or more threads of execution. In the Windows 3.1 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.

The Status of this Specification

Revision History

Windows Sockets Version 1.0

Windows Sockets Version 1.1

• Inclusion of the gethostname() routine to simplify retrieval of the host's name and address.

 

• Definition of DLL ordinal values below 1000 as reserved for Windows Sockets and ordinals above 1000 as unrestricted. This allows Windows Sockets vendors to include private interfaces to their DLLs without risking that the ordinals choosen will conflict with a future version of Windows Sockets.

 

• Addition of a reference count to WSAStartup() and WSACleanup(), requiring correspondences between the calls. This allows applications and third-party DLLs to make use of a Windows Sockets implementation without being concerned about the calls to these APIs made by the other.

 

• Change of return type of inet_addr() from struct in_addr to unsigned long. This was required due to different handling of four-byte structure returns between the Microsoft and Borland C compilers.

 

• Change of WSAAsyncSelect() semantics from "edge-triggerred" to "level-triggerred". The level-triggerred semantics significantly simplify an application's use of this routine.

 

• Change the ioctlsocket() FIONBIO semantics to fail if a WSAAsyncSelect() call is outstanding on the socket.

 

• Addition of the TCP_NODELAY socket option for RFC 1122 conformance.

Programming with Sockets

Windows Sockets Stack Installation Checking

 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.

 For further details of where to obtain Windows Sockets components, see " Windows Sockets Components".

Sockets

Basic concepts

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.

Client-server model

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.

Out-of-band data

 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 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 to indicate the point at which the out-of-band data was sent. An application can use the SIOCATMARK ioctlsocket() command 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.

Broadcasting

 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.

Byte Ordering

 Any reference to IP addresses or port numbers passed to or from a Windows Sockets routine must be in network order. This includes the IP address and port fields of a struct sockaddr_in (but not the sin_family field).

 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.

Socket Options

Value           Type            Meaning                 Default         Note

--------------- --------------- ----------------------- --------------- ----

SO_ACCEPTCON    BOOL            Socket is listen()ing.

                                FALSE unless a listen()

                                has been performed

 for the transmission of

 broadcast messages.

SO_DEBUG BOOL Debugging is enabled. FALSE (i)

 SO_DONTLINGER BOOL If true, the SO_LINGER TRUE

 option is disabled..

SO_DONTROUTE BOOL Routing is disabled. FALSE (i)

 SO_ERROR int Retrieve error status 0

 and clear.

SO_KEEPALIVE BOOL Keepalives are being FALSE

 sent.

SO_LINGER struct linger Returns the current l_onoff is 0

 FAR * linger options.

 SO_OOBINLINE BOOL Out-of-band data is FALSE

 being received in the

 normal data stream.

SO_RCVBUF int Buffer size for Implementation (i)

 receives dependant.

 SO_REUSEADDR BOOL The address to which FALSE

 this socket is bound

 can be used by others.

SO_SNDBUF int Buffer size for sends Implementation (i)

 dependant.

 SO_TYPE int The type of the socket As created

 (e.g. SOCK_STREAM). via socket()

 TCP_NODELAY BOOL Disables the Nagle Implementation

 algorithm for send dependant.

 coalescing.

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.

Database Files

Deviation from Berkeley Sockets

 socket data type and error values

 select() and FD_*

 Error codes -- errno, h_errno & WSAGetLastError()

 Pointers

 Renamed functions

 Blocking routines & EINPROGRESS

 Maximum number of sockets supported

 Include files

 Return values on API failure

socket data type and error values

 In UNIX, all handles, including socket handles, are small, non-negative intergers, and some applications make assumptions that this will be true. Windows Sockets handles have no restrictions, other than that the value INVALID_SOCKET is not a valid socket. Socket handles may take any value in the range 0 to INVALID_SOCKET-1.

 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 */

        {...}

s = socket(...);

if (s == INVALID_SOCKET)

        {...}

select() and FD_*

Error codes -- errno, h_errno & WSAGetLastError()

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

#define errno WSAGetLastError()

 TYPICAL BSD STYLE:

r = recv(...);

if (r == -1

    && errno == EWOULDBLOCK)

        {...}

r = recv(...);

if (r == -1       /* (but see below) */

    && WSAGetLastError() == EWOULDBLOCK)

        {...}

r = recv(...);

if (r == -1

    && WSAGetLastError() == WSAEWOULDBLOCK)

        {...}

Pointers

Renamed functions

 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.

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

Blocking routines & EINPROGRESS

Maximum number of sockets supported

 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(). 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, for example adding -DFD_SETSIZE=128 as an option to the compiler command line for Microsoft C. 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.

Include files

Return values on API failure

 TYPICAL BSD STYLE:

r = recv(...);

if (r == -1     /* or r < 0 */

    && errno == EWOULDBLOCK)

        {...}

r = recv(...);

if (r == SOCKET_ERROR

    && WSAGetLastError() == WSAEWOULDBLOCK)

        {...}

Raw Sockets

Windows Sockets in Multithreaded Versions of Windows

Closing a socket in one thread that has an outstanding blocking call on the same socket in another thread will cause the blocking call to fail with WSAEINTR, just as if the operation were cancelled. This also applies if there is a select() call outstanding and the application closes one of the sockets being selected.

 There is no default blocking hook installed in preemptive multithreaded versions of Windows. This is because the machine will not be blocked if a single application is waiting for an operation to complete and hence not calling PeekMessage() or GetMessage() which cause the application to yield in nonpremptive Windows. However, for backwards compatibility the WSASetBlockingHook() call is implemented in multithreaded versions of Windows, and any application whose behavior depends on the default blocking hook may install their own blocking hook which duplicates the default hook's semantics, if desired. 

Socket Library Overview

Socket Functions

 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. Only blocks if SO_LINGER is set.

 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.

 * The routine can block if acting on a blocking socket.

Blocking/Non blocking & Data Volatility

 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. All routines which can block are listed with an asterisk in the tables above and below.

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

 The Windows Sockets DLL will call the blocking hook function only if all of the following are true: the routine is one which is defined as being able to block, the specified socket is a blocking socket, and the request cannot be completed immediately. (A socket is set to blocking by default, but the IOCTL FIONBIO and WSAAsyncSelect() both set a socket to nonblocking mode.) If an application uses only non-blocking sockets and uses the WSAAsyncSelect() and/or the WSAAsyncGetXByY() routines instead of select() and the getXbyY() routines, then the blocking hook will never be called and the application does not need to be concerned with the reentrancy issues the blocking hook can introduce.

 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.

Database Functions

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

 gethostname() Retrieve the name of the local host.

 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.

 * The routine can block under some circumstances.

Microsoft Windows-specific Extension Functions

 Asynchronous select() Mechanism

 Asynchronous Support Routines

 Hooking Blocking Methods

 Error Handling

 Accessing a Windows Sockets DLL from an Intermediate DLL

 Internal Use of Messages by Windows Sockets Implementations

 Private API Interfaces

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 asynchronous message based

 WSAAsyncGetServByName() implementation of the standard Berkeley

 WSAAsyncGetServByPort() 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

Asynchronous select() Mechanism

 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

 

Asynchronous Support Routines

Hooking Blocking Methods

Error Handling

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

Accessing a Windows Sockets DLL from an Intermediate DLL

There are (at least) two ways to accomplish this. The simplest method is for the intermediate DLL to have calls similiar to WSAStartup() and WSACleanup() that applications call as appropriate. The DLL would then call WSAStartup() or WSACleanup() from within these routines. Another mechanism is for the intermediate DLL to build a table of task handles, which are obtained from the GetCurrentTask() Windows API, and at each entry point into the intermediate DLL check whether WSAStartup() has been called for the current task, then call WSAStartup() if necessary.

 If a DLL makes a blocking call and does not install its own blocking hook, then the DLL author must be aware that control may be returned to the application either by an application-installed blocking hook or by the default blocking hook. Thus, it is possible that the application will cancel the DLL's blocking operation via WSACancelBlockingCall(). If this occurs, the DLL's blocking operation will fail with the error code WSAEINTR, and the DLL must return control to the calling task as quickly as possible, as the used has likely pressed a cancel or close button and the task has requested control of the CPU. It is recommended that DLLs which make blocking calls install their own blocking hooks with WSASetBlockingHook() to prevent unforeseen interactions between the application and the DLL.

Note that this is not necessary for DLLs in Windows NT because of its different process and DLL structure. Under Windows NT, the intermediate DLL could simply call WSAStartup() in its DLL initialization routine, which is called whenever a new process which uses the DLL starts.

Internal use of Messages by Windows Sockets Implementations

Private API Interfaces

 If an application uses private interfaces of a particular vendor's Windows Sockets DLL, it is recommended that the DLL not be statically linked with the application but rather dynamically loaded with the Windows routines LoadLibrary() and GetProcAddress(). This allows the application to give an informative error message if it is run on a system with a Windows Sockets DLL that does not support the same set of extended functionality. 

Socket Library Reference

Socket Routines

In each routine it is indicated that the header file winsock.h must be included. Header Files 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.

accept()

Description

 #include <winsock.h>

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

s

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

addr

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

addrlen

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

Remarks

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

Return Value

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

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEFAULT

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

WSAEINTR

The (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESS

A blocking Windows Sockets call is in progress.

WSAEINVAL

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

WSAEMFILE

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

WSAENOBUFS

No buffer space is available.

WSAENOTSOCK

The descriptor is not a socket.

WSAEOPNOTSUPP

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

WSAEWOULDBLOCK

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

See Also

bind()

Description

 #include <winsock.h>

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

s

A descriptor identifying an unbound socket.

name

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

        struct sockaddr {

                u_short sa_family;

                char    sa_data[14];

        };

namelen

The length of the name.

Remarks

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

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

    SOCKADDR_IN sin;

    SOCKET s;

    u_short alport = IPPORT_RESERVED;



    sin.sin_family = AF_INET;

    sin.sin_addr.s_addr = 0;

    for (;;) {

        sin.sin_port = htons(alport);

        if (bind(s, (LPSOCKADDR)&sin, sizeof (sin)) == 0) {

            /* it worked */

        }

        if ( GetLastError() != WSAEADDRINUSE) {

            /* fail */

        }

        alport--;

        if (alport == IPPORT_RESERVED/2 ) {

            /* fail--all unassigned reserved ports are */

            /* in use. */

        }

    }

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEADDRINUSE

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

WSAEFAULT

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

WSAEINTR

The (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESS

A blocking Windows Sockets call is in progress.

WSAEAFNOSUPPORT

The specified address family is not supported by

this protocol.

WSAEINVAL

The socket is already bound to an address.

WSAENOBUFS

Not enough buffers available, too many connections.

WSAENOTSOCK

The descriptor is not a socket.

closesocket()

Description

 #include <winsock.h>

 int FAR PASCAL closesocket ( SOCKET s);

s

A descriptor identifying a socket.

Remarks

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

Option          Interval        Type of close           Wait for close?

--------------- --------------- ----------------------- ----------------

SO_DONTLINGER   Don't care      Graceful                No



SO_LINGER       Zero            Hard                    No



SO_LINGER       Non-zero        Graceful                Yes

 If SO_LINGER is set with a non-zero timeout interval, the closesocket() call blocks until the remaining data has been sent or until the timeout expires. This is called a graceful disconnect. Note that if the socket is set to non-blocking and SO_LINGER is set to a non-zero timeout, the call to closesocket() will fail with an error of WSAEWOULDBLOCK. If SO_DONTLINGER is set on a stream socket (i.e. the l_onoff field of the linger structure is zero; see Socket Options, getsockopt() and setsockopt()), the closesocket() call will return immediately. However, any data queued for transmission will be sent if possible before the underlying socket is closed. This is also called a graceful disconnect. Note that in this case the Windows Sockets implementation may not release the socket and other resources for an arbitrary period, which may affect applications which expect to use all available sockets.

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAENOTSOCK

The descriptor is not a socket.

WSAEINPROGRESS

A blocking Windows Sockets call is in progress.

WSAEINTR

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

WSAEWOULDBLOCK

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

See Also

connect()

Description

 #include <winsock.h>

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

s

A descriptor identifying an unconnected socket.

name

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

namelen

The length of the name.

Remarks

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.

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

1. Use select() to determine the completion of the connection request by checking if the socket is writeable, or
2. If your application is using the message-based WSAAsyncSelect() to indicate interest in connection events, then your application will receive an FD_CONNECT message when the connect operation is complete.

Return Value

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

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEADDRINUSE

The specified address is already in use.

WSAEINTR

The (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESS

A blocking Windows Sockets call is in progress.

WSAEADDRNOTAVAIL

The specified address is not available from the local machine.

WSAEAFNOSUPPORT

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

WSAECONNREFUSED

The attempt to connect was forcefully rejected.

WSAEDESTADDREQ

A destination address is required.

WSAEFAULT

The namelen argument is incorrect.

WSAEINVAL

The socket is not already bound to an address.

WSAEISCONN

The socket is already connected.

WSAEMFILE

No more file descriptors are available.

WSAENETUNREACH

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

WSAENOBUFS

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

WSAENOTSOCK

The descriptor is not a socket.

WSAETIMEDOUT

Attempt to connect timed out without establishing a connection

WSAEWOULDBLOCK

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

See Also

getpeername()

Description

 #include <winsock.h>

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

s

A descriptor identifying a connected socket.

name

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

namelen

A pointer to the size of the name structure.

Remarks

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEFAULT

The namelen argument is not large enough.

WSAEINPROGRESS

A blocking Windows Sockets call is in progress.

WSAENOTCONN

The socket is not connected.

WSAENOTSOCK

The descriptor is not a socket.

See Also

getsockname()

Description

 #include <winsock.h>

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

s

A descriptor identifying a bound socket.

name

Receives the address (name) of the socket.

namelen

The size of the name buffer.

Remarks

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

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

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEFAULT

The namelen argument is not large enough.

WSAEINPROGRESS

A blocking Windows Sockets operation is in progress.

WSAENOTSOCK

The descriptor is not a socket.

WSAEINVAL

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

See Also

getsockopt()

Description

 #include <winsock.h>

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

s

A descriptor identifying a socket.

level

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

optname

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

optval

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

optlen

A pointer to the size of the optval buffer.

Remarks

 If the option was never set with setsockopt(), then getsockopt() returns the default value for the option.

 The following options are supported for getsockopt(). The Type identifies the type of data addressed by optval. The TCP_NODELAY option uses level IPPROTO_TCP, all other options use level SOL_SOCKET.

Value           Type            Meaning

--------------- --------------- -----------------------------------------------

SO_ACCEPTCONN   BOOL            Socket is listen()ing.



SO_BROADCAST    BOOL            Socket is configured for the transmission of

                                broadcast messages.



SO_DEBUG        BOOL            Debugging is enabled.  



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



SO_DONTROUTE    BOOL            Routing is disabled.



SO_ERROR        int             Retrieve error status and clear.



SO_KEEPALIVE    BOOL            Keepalives are being sent.



SO_LINGER       struct linger   Returns the current linger options.

                FAR *



SO_OOBINLINE    BOOL            Out-of-band data is being received in the

                                normal data stream.  



SO_RCVBUF       int             Buffer size for receives



SO_REUSEADDR    BOOL            The socket may be bound to an address which

                                is already in use.



SO_SNDBUF       int             Buffer size for sends



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



TCP_NODELAY     BOOL            Disables the Nagle algorithm for send

                                coalescing.

Value           Type            Meaning

--------------- --------------- -----------------------------------------------

SO_RCVLOWAT     int             Receive low water mark



SO_RCVTIMEO     int             Receive timeout



SO_SNDLOWAT     int             Send low water mark



SO_SNDTIMEO     int             Send timeout



IP_OPTIONS                      Get options in IP header.



TCP_MAXSEG      int             Get TCP maximum segment size.

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEFAULT

The optlen argument was invalid.

WSAEINPROGRESS

A blocking Windows Sockets operation is in progress.

WSAENOPROTOOPT

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

WSAENOPROTOOPT

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

WSAENOTSOCK

The descriptor is not a socket.

See Also

htonl()

Description

 #include <winsock.h>

 u_long PASCAL FAR htonl ( u_long hostlong);

hostlong

A 32-bit number in host byte order.

Remarks

Return Value

See Also

htons()

Description

 #include <winsock.h>

 u_short PASCAL FAR htons ( u_short hostshort );

hostshort

A 16-bit number in host byte order.

Remarks

Return Value

See Also

inet_addr()

Description

 #include <winsock.h>

 unsigned long PASCAL FAR inet_addr ( const char FAR * cp );

cp

A character string representing a number expressed in the Internet standard ``.'' notation.

Remarks

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

• a.b.c.d
• a.b.c
• a.b
• a

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

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

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

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

Return Value

See Also

inet_ntoa()

Description

 #include <winsock.h>

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

in

A structure which represents an Internet host address.

Remarks

Return Value

See Also

ioctlsocket()

Description

 #include <winsock.h>

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

s

A descriptor identifying a socket.

cmd

The command to perform on the socket s.

argp

A pointer to a parameter for cmd.

Remarks

FIONBIO

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

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

FIONREAD

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

SIOCATMARK

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

Compatibility

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEINVAL

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

WSAEINPROGRESS

A blocking Windows Sockets operation is in progress.

WSAENOTSOCK

The descriptor s is not a socket.

See Also

listen()

Description

 #include <winsock.h>

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

s

A descriptor identifying a bound, unconnected socket.

backlog

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

Remarks

 This function is typically used by servers that could have more than one connection request at a time: if a connection request arrives with the queue full, the client will receive an error with an indication of WSAECONNREFUSED. listen() attempts to continue to function rationally when there are no available descriptors. It will accept connections until the queue is emptied. If descriptors become available, a later call to listen() or accept() will re-fill the queue to the current or most recent ``backlog'', if possible, and resume listening for incoming connections.

Compatibility

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEADDRINUSE

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

WSAEINPROGRESS

A blocking Windows Sockets operation is in progress.

WSAEFAULT

An invalid argument was given.

WSAEINVAL

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

WSAEISCONN

The socket is already connected.

WSAEMFILE

No more file descriptors are available.

WSAENOBUFS

No buffer space is available.

WSAENOTSOCK

The descriptor is not a socket.

WSAEOPNOTSUPP

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

See Also

ntohl()

Description

 #include <winsock.h>

 u_long PASCAL FAR ntohl ( u_long netlong);

netlong

A 32-bit number in network byte order.

Remarks

Return Value

See Also

ntohs()

Description

 #include <winsock.h>

 u_short PASCAL FAR ntohs ( u_short netshort );

netshort

A 16-bit number in network byte order.

Remarks

Return Value

See Also

recv()

Description

 #include <winsock.h>

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

s

A descriptor identifying a connected socket.

buf

A buffer for the incoming data.

len

The length of buf.

flags

Specifies the way in which the call is made.

Remarks

 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, and recv() returns the error WSAEMSGSIZE. If no incoming data is available at the socket, the recv() call waits for data to arrive unless the socket is non-blocking. In this case a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select() or WSAAsyncSelect() calls may be used to determine when more data arrives. If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a recv() will complete immediately with 0 bytes received. If the connection has been abortively disconnected, a recv() will fail with the error WSAECONNRESET.

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

MSG_PEEK

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

MSG_OOB

Process out-of-band data (See Out of Band Data for a discussion of this topic.)

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAENOTCONN

The socket is not connected.

WSAEINTR

The (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESS

A blocking Windows Sockets operation is in progress.

WSAENOTSOCK

The descriptor is not a socket.

WSAEOPNOTSUPP

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

WSAESHUTDOWN

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

WSAEWOULDBLOCK

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

WSAEMSGSIZE

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

WSAEINVAL

The socket has not been bound with bind().

WSAECONNABORTED

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

WSAECONNRESET

The virtual circuit was reset by the remote side.

See Also

recvfrom()

Description

 #include <winsock.h>

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

s

A descriptor identifying a bound socket.

buf

A buffer for the incoming data.

len

The length of buf.

flags

Specifies the way in which the call is made.

from

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

fromlen

An optional pointer to the size of the from buffer.

Remarks

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

 For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the size of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the message, the excess data is lost, and recvfrom() returns the error code WSAEMSGSIZE. If from is non-zero, and the socket is of type SOCK_DGRAM, the network address of the peer which sent the data is copied to the corresponding struct sockaddr. The value pointed to by fromlen is initialized to the size of this structure, and is modified on return to indicate the actual size of the address stored there.

 If no incoming data is available at the socket, the recvfrom() call waits for data to arrive unless the socket is non-blocking. In this case a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select() or WSAAsyncSelect() calls may be used to determine when more data arrives. If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a recvfrom() will complete immediately with 0 bytes received. If the connection has been abortively disconnected, a recvfrom() will fail with the error WSAECONNRESET.

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

MSG_PEEK

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

MSG_OOB

Process out-of-band data (See Out of Band Data for a discussion of this topic.)

Return Value

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEFAULT

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

WSAEINTR

The (blocking) call was canceled via WSACancelBlockingCall()

WSAEINPROGRESS

A blocking Windows Sockets operation is in progress.

WSAEINVAL

The socket has not been bound with bind().

WSAENOTCONN

The socket is not connected (SOCK_STREAM only).

WSAENOTSOCK

The descriptor is not a socket.

WSAEOPNOTSUPP

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

WSAESHUTDOWN

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

WSAEWOULDBLOCK

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

WSAEMSGSIZE

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

WSAECONNABORTED

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

WSCONNRESET

The virtual circuit was reset by the remote side.

See Also

select()

Description

 #include <winsock.h>

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

nfds

This argument is ig