套接口库函数参考.docx

1、套接口库函数参考目 录第五章 套接口库函数参考 25.1 Windows Socket 1.1库函数参考 25.1.1 accept() 25.1.2 bind() 35.1.3 closesocket() 45.1.4 connect() 55.1.5 getpeername() 65.1.6 getsockname() 75.1.7 getsockopt() 85.1.8 htonl() 95.1.9 htons() 105.1.10 inet_addr() 105.1.11 inet_ntoa() 115.1.12 ioctlsocket() 115.1.13 listen() 125.

2、1.14 ntohl() 135.1.15 ntohs() 145.1.16 recv() 145.1.17 recvfrom() 155.1.18 select() 165.1.19 send() 185.1.20 sendto() 195.1.21 setsockopt() 205.1.22 shutdown() 225.1.23 socket() 235.2 数据库函数 245.2.1 gethostbyaddr() 245.2.2 gethostbyname() 255.2.3 gethostname() 265.2.4 getprotobyname() 275.2.5 getprot

3、obynumber() 285.2.6 getservbyname() 285.2.7 getservbyport() 295.3 Windows扩展函数 305.3.1 WSAAsyncGetHostByAddr() 305.3.2 WSAAsyncGetHostByName() 325.3.3 WSAAsyncGetProtoByName() 335.3.4 WSAAsyncGetProtoByNumber() 355.3.5 WSAAsyncGetServByName() 365.3.6 WSAAsyncGetServByPort() 385.3.7 WSAAsyncSelect() 3

4、95.3.8 WSACancelAsyncRequest() 425.3.9 WSACancelBlockingCall() 435.3.10 WSACleanup() 445.3.11 WSAGetLastError() 455.3.12 WSAIsBlocking() 465.3.13 WSASetBlockingHook() 465.3.14 WSASetLastError() 475.3.15 WSAStartup() 485.3.16 WSAUnhookBlockingHook() 51第五章 套接口库函数参考5.1 Windows Socket 1.1库函数参考 本章以字母顺序列出

5、了套接口库函数，并介绍了技术细节。 使用任一库函数时应在程序中包含WINSOCK.H头文件。在附录A.2中还列出了一些与BERKELEY兼容的头文件。这些头文件只起到兼容性的作用，它们都包含了WINSOCK.H头文件，WINDOWS.H头文件也是必需的，但WINSOCK.H会视需要包含这一头文件。5.1.1 accept()简述： 在一个套接口接受一个连接。 #include SOCKET PASCAL FAR accept( SOCKET s, struct sockaddr FAR* addr, int FAR* addrlen); s：套接口描述字，该套接口在listen()后监听连接。

6、 addr：（可选）指针，指向一缓冲区，其中接收为通讯层所知的连接实体的地址。Addr参数的实际格式由套接口创建时所产生的地址族确定。 addrlen：（可选）指针，指向存有addr地址长度的整形数。注释： 本函数从s的等待连接队列中抽取第一个连接，创建一个与s同类的新的套接口并返回句柄。如果队列中无等待连接，且套接口为非阻塞方式，则accept()阻塞调用进程直至新的连接出现。如果套接口为非阻塞方式且队列中等待连接，则accept()返回一错误代码。已接受连接的套接口不能用于接受新的连接，原套接口仍保持开放。 addr参数为一个返回参数，其中填写的是为通讯层所知的连接实体地址。addr参数的

7、实际格式由通讯时产生的地址族确定。addrlen参数也是一个返回参数，在调用时初始化为addr所指的地址空间；在调用结束时它包含了实际返回的地址的长度（用字节数表示）。该函数与SOCK_STREAM类型的面向连接的套接口一起使用。如果addr与addrlen中有一个为零NULL，将不返回所接受的套接口远程地址的任何信息。返回值： 如果没有错误产生，则accept()返回一个描述所接受包的SOCKET类型的值。否则的话，返回INVALID_SOCKET错误，应用程序可通过调用WSAGetLastError()来获得特定的错误代码。 addrlen所指的整形数初始时包含addr所指地址空间的大小，

8、在返回时它包含实际返回地址的字节长度。错误代码： WSANOTINITIALISED：在使用此API之前应首先成功地调用WSAStartup()。 WSAENETDOWN： WINDOWS套接口实现检测到网络子系统失效。 WSAEFAULT： addrlen参数太小（小于socket结构的大小）。 WSAEINTR： 通过一个WSACancelBlockingCall()来取消一个（阻塞的）调用。 WSAEINPROGRESS： 一个阻塞的WINDOWS套接口调用正在运行中。 WSAEINVAL： 在accept()前未激活listen()。 WSAEMFILE： 调用accept()时队列为

9、空，无可用的描述字。 WSAENOBUFS： 无可用缓冲区空间。 WSAENOTSOCK： 描述字不是一个套接口。 WSAEOPNOTSUPP： 该套接口类型不支持面向连接服务。 WSAEWOULDBLOCK： 该套接口为非阻塞方式且无连接可供接受。参见： bind(), connect(), listen(), select(), socket(), WSAAsyncSelect().5.1.2 bind()简述： 将一本地地址与一套接口捆绑。 #include int PASCAL FAR bind( SOCKET s, const struct sockaddr FAR* name, i

10、nt namelen); s： 标识一未捆绑套接口的描述字。 name：赋予套接口的地址。sockaddr结构定义如下： struct sockaddr u_short sa_family; char sa_data14; ; namelen：name名字的长度。注释： 本函数适用于未连接的数据报或流类套接口，在connect()或listen()调用前使用。当用socket()创建套接口后，它便存在于一个名字空间（地址族）中，但并未赋名。bind()函数通过给一个未命名套接口分配一个本地名字来为套接口建立本地捆绑（主机地址/断口号）。 在Internet地址族中，一个名字包括几个组成部分，对

11、于SOCK_PGRAM和SOCK_STREAM类套接口，名字由三部分组成：主机地址，协议号（显式设置为UDP和TCP）和用以区分应用的端口号。如果一个应用并不关心分配给它的地址，则可将Internet地址设置为INADDR_ANY，或将端口号置为0。如果Internet地址段为INADDR_ANY，则可使用任意网络接口；在有多种主机环境下可简化编程。如果端口号置为0，则WINDOWS套接口实现将给应用程序分配一个值在1024到5000之间的唯一的端口。应用程序可在bind()后用getsockname()来获知所分配的地址，但必需注意的是，getsockname()只有在套接口连接成功后才会填

12、写Internet地址，这是由于在多种主机环境下若干种Internet地址都是有效的。 如果一个应用程序需要把端口捆绑到超过10245000范围的特定端口时，比如rsh需要捆绑到任一保留端口，则可如下编程： 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 work

13、ed */ if (GetLastError()!=WSAEADDRINUSE) /* fail */ alport-; if (alport=IPPORT_RESERVED/2) /* failall unassigned reserved ports are */ /* in use. */ 返回值： 如无错误发生，则bind()返回0。否则的话，将返回SOCKET_ERROR，应用程序可通过WSAGetLastError()获取相应错误代码。错误代码： WSANOTINITIALISED：在使用此API之前应首先成功地调用WSAStartup()。 WSAENETDOWN： WINDOW

14、S套接口实现检测到网络子系统失效。 WSAEADDRINUSE： 所定端口已在使用中（参见setoption()中的SO_REUSEADDR选项）。 WSAEFAULT： namelen参数太小（小于sockaddr结构的大小）。 WSAEINPROGRESS： 一个阻塞的WINDOWS套接口调用正在运行中。 WSAEAFNOSUPPORT： 本协议不支持所指定的地址族。 WSAEINVAL： 该套接口已与一个地址捆绑。 WSAENOBUFS： 无足够可用缓冲区，连接过多。 WSAENOTSOCK： 描述字不是一个套接口。参见： connect(), listen(), getsockname

15、(), setsockopt(), socket(), WSACancelBlockingCall().5.1.3 closesocket()简述： 关闭一个套接口。 #include int PASCAL FAR closesocket( SOCKET s); s：一个套接口的描述字。注释： 本函数关闭一个套接口。更确切地说，它释放套接口描述字s，以后对s的访问均以WSAENOTSOCK错误返回。若本次为对套接口的最后一次访问，则相应的名字信息及数据队列都将被释放。closesocket()的语义受SO_LINGER与SO_DONTLINGER选项影响，对比如下：选项 间隔 关闭方式 等待关

16、闭与否SO_DONTLINGER 不关心 优雅 否SO_LINGER 零 强制 否SO_LINGER 非零 优雅 是 若设置了SO_LINGER（亦即linger结构中的l_onoff域设为非零，参见2.4，4.1.7和4.1.21各节），并设置了零超时间隔，则closesocket()不被阻塞立即执行，不论是否有排队数据未发送或未被确认。这种关闭方式称为“强制”或“失效”关闭，因为套接口的虚电路立即被复位，且丢失了未发送的数据。在远端的recv()调用将以WSAECONNRESET出错。 若设置了SO_LINGER并确定了非零的超时间隔，则closesocket()调用阻塞进程，直到所剩数据

17、发送完毕或超时。这种关闭称为“优雅的”关闭。请注意如果套接口置为非阻塞且SO_LINGER设为非零超时，则closesocket()调用将以WSAEWOULDBLOCK错误返回。 若在一个流类套接口上设置了SO_DONTLINGER（也就是说将linger结构的l_onoff域设为零；参见2.4，4.1.7，4.1.21节），则closesocket()调用立即返回。但是，如果可能，排队的数据将在套接口关闭前发送。请注意，在这种情况下WINDOWS套接口实现将在一段不确定的时间内保留套接口以及其他资源，这对于想用所以套接口的应用程序来说有一定影响。返回值： 如无错误发生，则closesocke

18、t()返回0。否则的话，返回SOCKET_ERROR错误，应用程序可通过WSAGetLastError()获取相应错误代码。错误代码： WSANOTINITIALISED：在使用此API之前应首先成功地调用WSAStartup()。 WSAENETDOWN： WINDOWS套接口实现检测到网络子系统失效。 WSAENOTSOCK： 描述字不是一个套接口。 WSAEINPROGRESS： 一个阻塞的WINDOWS套接口调用正在运行中。 WSAEINTR： 通过一个WSACancelBlockingCall()来取消一个（阻塞的）调用。 WSAEWOULDBLOCK：该套接口设置为非阻塞方式且SO

19、_LINGER设置为非零超时间隔。参见： accept(), socket(), ioctlsocket(), setsockopt(), WSAAsyncSelect().5.1.4 connect()简述： 建立与一个端的连接。 #include int PASCAL FAR connect( SOCKET s, const struct sockaddr FAR* name, int namelen); s： 标识一个未连接套接口的描述字。 name： 欲进行连接的端口名。 namelen： 名字长度。注释： 本函数用于创建与指定外部端口的连接。s参数指定一个未连接的数据报或流类套接口。

20、如套接口未被捆绑，则系统赋给本地关联一个唯一的值，且设置套接口为已捆绑。请注意若名字结构中的地址域为全零的话，则connect()将返回WSAEADDRNOTAVAIL错误。 对于流类套接口（SOCK_STREAM类型），利用名字来与一个远程主机建立连接，一旦套接口调用成功返回，它就能收发数据了。对于数据报类套接口（SOCK_DGRAM类型），则设置成一个缺省的目的地址，并用它来进行后续的send()与recv()调用。返回值： 若无错误发生，则connect()返回0。否则的话，返回SOCKET_ERROR错误，应用程序可通过WSAGetLastError()获取相应错误代码。对阻塞套接口而

21、言，若返回值为SOCKET_ERROR则应用程序调用WSAGetLsatError()。如果它指出错误代码为WSAEWOULDBLOCK，则您的应用程序可以： 1.用select()，通过检查套接口是否可写，来确定连接请求是否完成。或者， 2.如果您的应用程序使用基于消息的WSAAsynSelect()来表示对连接事件的兴趣，则当连接操作完成后，您会收到一个FD_CONNECT消息。错误代码： WSAENOTINITIALISED：在使用此API之前应首先成功地调用WSAStartup()。 WSAENETDOWN： WINDOWS套接口实现检测到网络子系统失效。 WSAEADDRINUSE：

22、 所指的地址已在使用中。 WSAEINTR： 通过一个WSACancelBlockingCall()来取消一个（阻塞的）调用。 WSAEINPROGRESS： 一个阻塞的WINDOWS套接口调用正在运行中。 WSAEADDRNOTAVAIL：在本地机器上找不到所指的地址。 WSAENOTSUPPORT： 所指族中地址无法与本套接口一起使用。 WSAECONNREFUSED：连接尝试被强制拒绝。 WSAEDESTADDREQ： 需要目的地址。 WSAEFAULT： namelen参数不正确。 WSAEINVAL： 套接口没有准备好与一地址捆绑。 WSAEISCONN： 套接口早已连接。 WSAE

23、MFILE： 无多余文件描述字。 WSAENETUNREACH： 当前无法从本主机访问网络。 WSAENOBUFS： 无可用缓冲区。套接口未被连接。 WSAENOTSOCK： 描述字不是一个套接口。 WSAETIMEOUT： 超时时间到。 WSAEWOULDBLOCK： 套接口设置为非阻塞方式且连接不能立即建立。可用select()调用对套接口写，因为select()时会进行连接。参见： accept(), bind(), getsockname(), socket(), select(), WSAAsyncSelect().5.1.5 getpeername()简述： 获取与套接口相连的端地

24、址。 #include int PASCAL FAR getpeername( SOCKET s, struct sockaddr FAR* name, int FAR* namelen); s： 标识一已连接套接口的描述字。 name： 接收端地址的名字结构。 namelen： 一个指向名字结构的指针。注释： getpeername()函数用于从端口s中获取与它捆绑的端口名，并把它存放在sockaddr类型的name结构中。它适用于数据报或流类套接口。返回值： 若无错误发生，getpeername()返回0。否则的话，返回SOCKET_ERROR，应用程序可通过WSAGetLastError

25、()来获取相应的错误代码。错误代码： WSANOTINITIALISED： 在使用此API之前应首先成功地调用WSAStartup()。 WSAENETDOWN： WINDOWS套接口实现检测到网络子系统失效。 WSAEFAULT： namelen参数不够大。 WSAEINPROGRESS： 一个阻塞的WINDOWS套接口调用正在运行中。 WSAENOTCONN： 套接口未连接。 WSAENOTSOCK： 描述字不是一个套接口。参见： bind(), socket(), getsockname().5.1.6 getsockname()简述： 获取一个套接口的本地名字。 #include in

26、t PASCAL FAR getsockname( SOCKET s, struct sockaddr FAR* name, int FAR* namelen); s：标识一个已捆绑套接口的描述字。 name：接收套接口的地址（名字）。 namelen：名字缓冲区长度。注释： getsockname()函数用于获取一个套接口的名字。它用于一个已捆绑或已连接套接口s，本地地址将被返回。本调用特别适用于如下情况：未调用bind()就调用了connect()，这时唯有getsockname()调用可以获知系统内定的本地地址。在返回时，namelen参数包含了名字的实际字节数。 若一个套接口与INAD

27、DR_ANY捆绑，也就是说该套接口可以用任意主机的地址，此时除非调用connect()或accept()来连接，否则getsockname()将不会返回主机IP地址的任何信息。除非套接口被连接，WINDOWS套接口应用程序不应假设IP地址会从INADDR_ANY变成其他地址。这是因为对于多个主机环境下，除非套接口被连接，否则该套接口所用的IP地址是不可知的。返回值： 若无错误发生，getsockname()返回0。否则的话，返回SOCKET_ERROR错误，应用程序可通过WSAGetLastError()获取相应错误代码。错误代码： WSANOTINITIALISED：在使用此API之前应首先

28、成功地调用WSAStartup()。 WSAENETDOWN： WINDOWS套接口实现检测到网络子系统失效。 WSAEFAULT： namelen参数不够大。 WSAEINPROGRESS：一个阻塞的WINDOWS套接口调用正在运行中。 WSAENOTSOCK： 描述字不是一个套接口。 WSAEINVAL： 套接口未用bind()捆绑。参见： bind(), socket(), getpeername().5.1.7 getsockopt()简述： 获取一个套接口选项。 #include int PASCAL FAR getsockopt( SOCKET s, int level, int

29、optname, char FAR* optval, int FAR* optlen); s： 一个标识套接口的描述字。 level： 选项定义的层次。支持的层次仅有SOL_SOCKET和IPPROTO_TCP。 optname： 需获取的套接口选项。 optval： 指针，指向存放所获得选项值的缓冲区。 optlen： 指针，指向optval缓冲区的长度值。注释： getsockopt()函数用于获取任意类型、任意状态套接口的选项当前值，并把结果存入optval。在不同协议层上存在选项，但往往是在最高的“套接口”层次上，设置选项影响套接口的操作，诸如操作的阻塞与否、包的选径方式、带外数据的传

30、送等。 被选中选项的值放在optval缓冲区中。optlen所指向的整形数在初始时包含缓冲区的长度，在调用返回时被置为实际值的长度。对SO_LINGER选项而言，相当于linger结构的大小，对其他选项来说，是一个整形数的大小。 如果未进行setsockopt()调用，则getsockopt()返回系统缺省值。 getsockopt()支持下列选项。其中“类型”栏指出了optval所指向的值。仅有TCP_NODELAY选项使用了IPPROTO_TCP层；其余选项均使用SOL_SOCKET层。选项 类型 意义SO_ACCEPTCONN BOOL 套接口正在用listen()监听。SO_BROADCAST BOOL 套接口设置为传送广播信息。SO_DEBUG BOOL 允许调试。SO_DONTLINER BOOL 若为真，则SO_LINGER选项被禁止。SO_DONTROUTE BOOL 禁止选径。SO_ERROR int 获取错误状态并清除。SO_KEEPALIVE BOOL 发送“保持活动”信息。SO_LINGER struct linger FAR* 返回当前各linger选项。SO_OOBINLINE BOOL 在普通数据流中接收带外数据。SO_RCVBUF int 接收缓冲区