closesocket  1OHRGV3

The Windows Sockets closesocket function closes a socket.

int closesocket (

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

If SO_LINGER is set (that is, the l_onoff field of the linger structure is nonzero; see Multipoint and Multicast SemanticsWZD6W2) 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 SemanticsWZD6W2) 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.YYO.X 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.YYO.X 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

See Also