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

HTML markup by John English, Jun 1997.


TABLE OF CONTENTS

TABLE OF CONTENTS

ACKNOWLEDGMENTS

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
1.5 Revision History
      1.5.1 Windows Sockets Version 1.0
      1.5.2 Windows Sockets Version 1.1

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, h_errno & WSAGetLastError()
      2.6.4 Pointers
      2.6.5 Renamed functions
            2.6.5.1 close() & closesocket()
            2.6.5.2 ioctl() & 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
      2.6.10 Raw Sockets
2.7 Windows Sockets in Multithreaded Versions of Windows

3. SOCKET LIBRARY OVERVIEW

3.1 Socket Functions
      3.1.1 Blocking/Non blocking & Data Volatility
3.2 Database Functions
3.3 Microsoft Windows-specific 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
      3.3.5 Accessing a Windows Sockets DLL from an Intermediate DLL
      3.3.6 Internal use of Messages by Windows Sockets Implementations
      3.3.7 Private API Interfaces

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.19 send()
      4.1.20 sendto()
      4.1.21 setsockopt()
      4.1.22 shutdown()
      4.1.23 socket()
4.2 Database Routines
      4.2.1 gethostbyaddr()
      4.2.2 gethostbyname()
      4.2.3 gethostname()
      4.2.4 getprotobyname()
      4.2.5 getprotobynumber()
      4.2.6 getservbyname()
      4.2.7 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()

Appendix A. Error 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

Appendix B. Notes 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

Appendix C. For Further Reference

Appendix D. Background Information

D.1 Legal Status of Windows Sockets
D.2 The Story Behind the Windows Sockets Icon


ACKNOWLEDGMENTS

The authors would like to thank their companies for allowing them the time and resources to make this specification possible: JSB Corporation, Microdyne Corporation, FTP Software, Sun Microsystems, and Microsoft Corporation.

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 Net Manage, 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

J. Allard
Microsoft Corporation
jallard@microsoft.com

Chris Arap-Bologna
Distinct
chris@distinct.com

Larry Backman
FTP Software
backman@ftp.com

Alistair Banks
Microsoft Corporation
alistair@microsoft.com

Rob Barrow
JSB Corporation
robb@jsb.co.uk

Carl Beame
Beame & Whiteside
beame@mcmaster,ca

Dave Beaver
Microsoft Corporation
dbeaver@microsoft.com

Amatzia BenArtzi
NetManage, Inc.
amatzia@netmanage.com

Mark Beyer
Ungermann-Bass
mbeyer@ub.com

Nelson Bolyard
Silicon Graphics, Inc.
nelson@sgi.com

Pat Bonner
Hewlett-Packard
p_bonner@cnd.hp.com

Derek Brown
FTP Software
db@wco.ftp.com

Malcolm Butler
ICL
mcab@oasis.icl.co.uk

Mike Calbaum
Fronteir Technologies
mike@frontiertech.com

Isaac Chan
Microsoft Corporation
isaacc@microsoft.com

Khoji Darbani
Informix
khoji@informix.com

Nestor Fesas
Hughes LAN Systems
nestor@hls.com

Karanja Gakio
FTP Software
karanja@ftp.com

Vikas Garg
Distinct
vikas@distinct.com

Gary Gere
Gupta
ggere@gupta.com

Jim Gilroy
Microsoft Corporation
jamesg@microsoft.com

Bill Hayes
Hewlett-Packard
billh@hpchdpc.cnd.hp.com

Paul Hill
MIT
pbh@athena.mit.edu

Tmima Koren
Net Manage, Inc.
tmima@netmanage.com

Hoek Law
Citicorp
law@dcc.tti.com

Graeme Le Roux
Moresdawn P/L
-

Kevin Lewis
Novell
kevinl@novell.com

Roger Lin
3Com
roger_lin@3mail.3com.com

Terry Lister
Hewlett-Packard
tel@cnd.hp.com

Jeng Long Jiang
Wollongong
long@twg.com

Lee Murach
Network Research
lee@nrc.com

Pete Ostenson
Microsoft Corporation
peteo@microsoft.com

David Pool
Spry, Inc.
dave@spry.com

Bob Quinn
FTP Software
rcq@ftp.com

Glenn Reitsma
Hughes LAN Systems
glennr@hls.com

Brad Rice
Age
rice@age.com

Allen Rochkind
3Com
-

Jonathan Rosen
IBM
jrosen@vnet.ibm.com

Steve Stokes
Novell
stoke@novell.com

Joseph Tsai
3Com
joe_tsai@3mail.3com.com

James Van Bokkelen
FTP Software
jbvb@ftp.com

Miles Wu
Wollongong
wu@twg.com

Boris Yanovsky
NetManage, Inc.
boris@netmanage.com