 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This function closes a socket.
int closesocket ( SOCKET s );
Parameters
- s
- [in] Descriptor that identifies a socket to close.
Return Values
Zero indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.
Windows CE does not support the WSACancelBlockingCallfunction; however, Windows CE returns the WSAEINTR error value if closesocketis called in the middle of executing a sockets call.
Remarks
For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:
- The Af_irda.h file must be explicitly included.
- The WSAENETDOWN error value is not supported.
- The standard linger options are supported.
Although IrDA does not provide a graceful close, IrSock defers closing until the receive queues are purged. Thus, an application can send data and immediately call the closesocketfunction confident that the receiver will copy the data before receiving an FD_CLOSE message.
The closesocketfunction closes a socket. Use it to release the socket descriptor sso that further references to swill fail with the error WSAENOTSOCK. Any pending blocking or asynchronous calls issued by any thread in this process are canceled without posting any notification messages.
An application should always have a matching call to closesocketfor each successful call to socketto return any socket resources to the system.
The semantics of closesocketare affected by the socket options SO_LINGER and SO_DONTLINGER as follows (SO_DONTLINGER is enabled by default; SO_LINGER is disabled).
Option Interval Type of close Wait for close? SO_DONTLINGER Do not care Graceful No SO_LINGER Zero Hard No SO_LINGER Nonzero Graceful Yes If SO_LINGER is set with a zero time-out interval (that is, the LINGERstructure members l_onoffis not zero and l_linger is zero), closesocketis not blocked even if queued data has not yet been sent or acknowledged. This is called a hard or abortive close, because the socket's virtual circuit is reset immediately, and any unsent data is lost. Any recvcall on the remote side of the circuit will fail with WSAECONNRESET.
If SO_LINGER is set with a nonzero time-out interval on a blocking socket, the closesocketcall blocks on a blocking socket until the remaining data has been sent or until the time-out expires. This is called a graceful disconnect. If the time-out expires before all data has been sent, the Windows Sockets implementation terminates the connection before closesocketreturns.
Enabling SO_LINGER with a nonzero time-out interval on a nonblocking socket is not recommended. In this case, the call to closesocketwill fail with an error of WSAEWOULDBLOCK if the close operation cannot be completed immediately. If closesocketfails with WSAEWOULDBLOCK the socket handle is still valid, and a disconnect is not initiated. The application must call closesocketagain to close the socket. If SO_DONTLINGER is set on a stream socket by setting the l_onoffmember of the LINGERstructure to zero, the closesocketcall will return immediately and does not receive WSAWOULDBLOCK whether the socket is blocking or nonblocking. However, any data queued for transmission will be sent, if possible, before the underlying socket is closed. This is also called a graceful disconnect. In this case, the Windows Sockets provider cannot release the socket and other resources for an arbitrary period, thus affecting applications that expect to use all available sockets. This is the default behavior (SO_DONTLINGER is set by default).
Note To assure that all data is sent and received on a connection, an application should call shutdownbefore calling closesocket. Also note, an FD_CLOSE network event is notposted after closesocketis called.
Here is a summary of closesocketbehavior:
- If SO_DONTLINGER enabled (the default setting) it always returns immediately – connection is gracefully closed in the background.
- If SO_LINGER enabled with a zero time-out: it always returns immediately - connection is reset/terminated.
- If SO_LINGER enabled with nonzero time-out:
- with blocking socket it blocks until all data sent or time-out expires.
- with nonblocking socket it returns immediately that indicates
failure.
For additional information please see Graceful shutdown, linger options, and socket closure for more information.
Requirements
Runs on Versions Defined in Include Link to Windows CE OS 1.0 and later Winsock.h Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
accept, socket, ioctlsocket, setsockopt