closesocket - Microsoft Windows Telephony API (TAPI) Programmer's Reference (tapi.hlp)

Microsoft Windows Telephony API
(TAPI) Programmer's Reference

closesocket

The Windows Sockets closesocket function closes a socket.

int closesocket (

SOCKET s
);

Parameters
s

[in] A descriptor identifying a socket.

Remarks
This function closes a socket. More precisely, it releases the socket descriptor s, so that further references to s will fail with the error WSAENOTSOCK. If this is the last reference to an underlying socket, the associated naming information and queued data are discarded. Any pending blocking, asynchronous calls issued by any thread in this process are canceled without posting any notification messages, or signaling any event objects. Any pending overlapped send and receive operations (WSASend/WSASendTo/WSARecv/WSARecvFrom with an overlapped socket) issued by any thread in this process are also canceled without setting the event object or invoking the completion routine, if specified. In this case, the pending overlapped operations fail with the error status WSA_OPERATION_ABORTED. An application should always have a matching call to closesocket for each successful call to socket to return socket resources to the system.

The semantics of closesocket are affected by the socket options SO_LINGER and SO_DONTLINGER as follows (Note: by default SO_DONTLINGER is enabled. That is, SO_LINGER is disabled):

Option	Interval	Type of close	Wait for close?
SO_DONTLINGER	Don't care	Graceful	No
SO_LINGER	Zero	Hard	No
SO_LINGER	Nonzero	Graceful	Yes

If SO_LINGER is set (that is, the l_onoff field of the linger structure is nonzero; see Multipoint and Multicast Semantics) with a zero time-out interval (l_linger is zero), closesocket is 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 recv call 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 closesocket call 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 closesocket returns.

Enabling SO_LINGER with a nonzero time-out interval on a nonblocking socket is not recommended. In this case, the call to closesocket will fail with an error of WSAEWOULDBLOCK if the close operation cannot be completed immediately. If closesocket fails with WSAEWOULDBLOCK the socket handle is still valid, and a disconnect is not initiated. The application must call closesocket again to close the socket, although closesocket can continue to fail unless the application disables SO_DONTLINGER, enables SO_LINGER with a zero time-out, or calls shutdown to initiate closure.

If SO_DONTLINGER is set on a stream socket (that is, the l_onoff field of the linger structure is zero; see Multipoint and Multicast Semantics) 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 provider cannot release the socket and other resources for an arbitrary period, which can affect applications which expect to use all available sockets. This is the default behavior.

Note To assure that all data is sent and received on a connection, an application should call shutdown before calling closesocket (see Graceful shutdown, linger options and socket closure for more information). Also note, FD_CLOSE will not be posted after closesocket is called.

Here is a summary of closesocket behavior:

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

For additional information please see Graceful shutdown, linger options and socket closure for more information.

Return Values
If no error occurs, closesocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEWOULDBLOCK	The socket is marked as nonblocking and SO_LINGER is set to a nonzero time-out value.

See Also
accept, ioctlsocket, setsockopt, socket, WSAAsyncSelect, WSADuplicateSocket

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
OLE Programmer's Reference (ole.hlp)
Microsoft Windows Pen API Programmer's Reference (penapi.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (tapi.hlp)
Unix Manual Pages

greatis just4fun network