Windows
Sockets
Windows Sockets
An Open Interface for
Network Programming under
Microsoft
Windows
Version 1.1
20 January 1993
Martin Hall
Mark Towfiq
Geoff Arnold
David Treadwell
Henry Sanders
Copyright
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 winsock@microdyne.com.
Requests to be added to the Windows Sockets mailing list should be
addressed to winsock-request@microdyne.com. This
specification, archives of the mailing list, and other information on
Windows Sockets are available via anonymous FTP from the host
microdyne.com, directory /pub/winsock. Questions about products
conforming to this specification should be addressed to the vendors of
the products.
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.
Revision history:
1.0 Rev.A June 11, 1992
1.0 Rev.B June 16, 1992
1.0 Rev. C October 12, 1992
1.1 January, 1993
ii
Windows Sockets
Version 1.1
TABLE OF CONTENTS
TABLE OF CONTENTS.....................................................................................................................iii
ACKNOWLEDGMENTS....................................................................................................................vi
1. INTRODUCTION ..........................................................................................................................1
1.1 What is Windows Sockets? ..............................................................................................1
1.2 Berkeley Sockets..............................................................................................................1
1.3 Microsoft Windows and Windows-specific extensions.....................................................1
1.4 The Status of this Specification........................................................................................2
1.5 Revision History ..............................................................................................................2
1.5.1 Windows Sockets Version 1.0 .........................................................................2
1.5.2 Windows Sockets Version 1.1 .........................................................................2
2. PROGRAMMING WITH SOCKETS .............................................................................................4
2.1 Windows Sockets Stack Installation Checking .................................................................4
2.2 Sockets.............................................................................................................................4
2.2.1 Basic concepts.................................................................................................4
2.2.2 Client-server model .........................................................................................4
2.2.3 Out-of-band data..............................................................................................5
2.2.4 Broadcasting....................................................................................................5
2.3 Byte Ordering ..................................................................................................................6
2.4 Socket Options.................................................................................................................6
2.5 Database Files..................................................................................................................7
2.6 Deviation from Berkeley Sockets.....................................................................................7
2.6.1 socket data type and error values .....................................................................8
2.6.2 select() and FD_* ............................................................................................8
2.6.3 Error codes - errno, h_errno & WSAGetLastError().........................................8
2.6.4 Pointers ...........................................................................................................9
2.6.5 Renamed functions..........................................................................................9
2.6.5.1 close() & closesocket()....................................................................9
2.6.5.1 ioctl() & ioctlsocket()......................................................................9
2.6.6 Blocking routines & EINPROGRESS..............................................................9
2.6.7 Maximum number of sockets supported...........................................................9
2.6.8 Include files.....................................................................................................10
2.6.9 Return values on API failure............................................................................10
2.6.10 Raw Sockets..................................................................................................10
2.7 Windows Sockets in Multithreaded Versions of Windows................................................10
3. SOCKET LIBRARY OVERVIEW.................................................................................................12
3.1 Socket Functions..............................................................................................................12
3.1.1 Blocking/Non blocking & Data Volatility........................................................12
3.2 Database Functions ..........................................................................................................13
3.3 Microsoft Windows-specific Extension Functions............................................................14
3.3.1 Asynchronous select() Mechanism...................................................................15
3.3.2 Asynchronous Support Routines ......................................................................15
3.3.3 Hooking Blocking Methods.............................................................................15
3.3.4 Error Handling.................................................................................................16
3.3.5 Accessing a Windows Sockets DLL from an Intermediate DLL ......................16
3.3.6 Internal use of Messages by Windows Sockets Implementations......................16
3.3.7 Private API Interfaces......................................................................................17
4. SOCKET LIBRARY REFERENCE................................................................................................18
iii
4.1 Socket Routines ...............................................................................................................18
4.1.1 accept() ...........................................................................................................19
4.1.2 bind()...............................................................................................................21
4.1.3 closesocket()....................................................................................................23
4.1.4 connect() .........................................................................................................25
4.1.5 getpeername()..................................................................................................27
4.1.6 getsockname() .................................................................................................28
4.1.7 getsockopt().....................................................................................................29
4.1.8 htonl() .............................................................................................................31
4.1.9 htons().............................................................................................................32
4.1.10 inet_addr().....................................................................................................33
4.1.11 inet_ntoa().....................................................................................................34
4.1.12 ioctlsocket()...................................................................................................35
4.1.13 listen()...........................................................................................................37
4.1.14 ntohl()............................................................................................................39
4.1.15 ntohs() ...........................................................................................................40
4.1.16 recv().............................................................................................................41
4.1.17 recvfrom() .....................................................................................................43
4.1.18 select()...........................................................................................................46
4.1.19 send() ............................................................................................................48
4.1.20 sendto() .........................................................................................................50
4.1.21 setsockopt() ...................................................................................................53
4.1.22 shutdown().....................................................................................................56
4.1.23 socket()..........................................................................................................58
4.2 Database Routines............................................................................................................60
4.2.1 gethostbyaddr()................................................................................................60
4.2.2 gethostbyname()..............................................................................................62
4.2.3 gethostname()..................................................................................................63
4.2.4 getprotobyname() ............................................................................................64
4.2.5 getprotobynumber().........................................................................................66
4.2.6 getservbyname()..............................................................................................67
4.2.7 getservbyport() ................................................................................................69
4.3 Microsoft Windows-specific Extensions...........................................................................70
4.3.1 WSAAsyncGetHostByAddr() ..........................................................................70
4.3.2 WSAAsyncGetHostByName().........................................................................73
4.3.3 WSAAsyncGetProtoByName()........................................................................76
4.3.4 WSAAsyncGetProtoByNumber() ....................................................................79
4.3.5 WSAAsyncGetServByName().........................................................................82
4.3.6 WSAAsyncGetServByPort()............................................................................85
4.3.7 WSAAsyncSelect()..........................................................................................88
4.3.8 WSACancelAsyncRequest()............................................................................94
4.3.9 WSACancelBlockingCall()..............................................................................96
4.3.10 WSACleanup() ..............................................................................................98
4.3.11 WSAGetLastError().......................................................................................100
4.3.12 WSAIsBlocking() ..........................................................................................101
4.3.13 WSASetBlockingHook()................................................................................102
4.3.14 WSASetLastError() .......................................................................................104
4.3.15 WSAStartup()................................................................................................105
4.3.16 WSAUnhookBlockingHook() ........................................................................109
Appendix A. Error Codes and Header Files ........................................................................................110
A.1 Error Codes.....................................................................................................................110
A.2 Header Files....................................................................................................................112
A.2.1 Berkeley Header Files.....................................................................................112
A.2.2 Windows Sockets Header File - winsock.h......................................................113
iv
Appendix B. Notes for Windows Sockets Suppliers............................................................................125
B.1 Introduction.....................................................................................................................125
B.2 Windows Sockets Components........................................................................................125
B.2.1 Development Components ..............................................................................125
B.2.2 Run Time Components ...................................................................................125
B.3 Multithreadedness and blocking routines.........................................................................125
B.4 Database Files .................................................................................................................126
B.5 FD_ISSET.......................................................................................................................126
B.6 Error Codes .....................................................................................................................126
B.7 DLL Ordinal Numbers.....................................................................................................126
B.8 Validation Suite...............................................................................................................127
Appendix C. For Further Reference....................................................................................................129
Appendix D. Background Information................................................................................................130
D.1 Legal Status of Windows Sockets....................................................................................130
D.2 The Story Behind the Windows Sockets Icon ..................................................................130
v
