closesocket

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function closes an existing socket.

Syntax

int closesocket(
  SOCKET s
);

Parameters

s
[in] Descriptor identifying the socket to close.

Return Value

If no error occurs, this function returns zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Remarks

Use this function to release the socket descriptor s so that further references to s 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.

Any pending overlapped send and receive operations issued by any thread in this process are also canceled. Any event, completion routine, or completion port action specified for these overlapped operations is performed. 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 the socket (Windows Sockets) function to return any socket resources to the system.

The following table shows how the semantics of closesocket are affected by the socket options SO_LINGER and SO_DONTLINGER. By default, SO_DONTLINGER is enabled and 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 linger structure members l_onoff is nonzero and 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 non-blocking 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.

Note

When closesocket is called on a non-blocking socket with a non-zero time-out interval, the call will return success (0) and the handle will be invalid. However, the socket will still attempt to send all pending data until the timeout expires.

If SO_DONTLINGER is set on a stream socket by setting the l_onoff member of the linger structure to zero, the closesocket call 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 ensure that all data is sent and received on a connection, an application should call shutdown before calling closesocket. Also note, an FD_CLOSE network event is not posted after closesocket is called.

The following list shows the closesocket function behavior:

If SO_DONTLINGER is enabled (the default setting), it always returns immediately — connection is gracefully closed in the background.
If SO_LINGER is enabled with a zero time-out, it always returns immediately — connection is reset/terminated.
If SO_LINGER is enabled with a nonzero time-out, it blocks until all data sent or time-out expires (with a blocking socket) and returns immediately indicating failure (with a nonblocking socket).

Notes for IrDA Sockets

The WSAENETDOWN error code is not supported.
The Af_irda.h header file must be explicitly included.
The standard linger options are supported.
Although IrDA does not provide a graceful close, IrDA will defer closing until receive queues are purged. Thus, an application can send data and immediately call the closesocket function and be confident that the receiver will copy the data before receiving an FD_CLOSE message.

Note

Asynchronous transfer mode (ATM) is not supported in Windows Embedded CE.

For more inforamtion about IrDA support in Windows Embedded CE, see Infrared Communications.

Error code

Error code	Description
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEINPROGRESS	A blocking Winsock call is in progress, or the service provider is still processing a callback function.
WSAEINTR	The socket was closed.
WSAEWOULDBLOCK	The socket is marked as nonblocking and SO_LINGER is set to a nonzero time-out value.

Requirements

Header	winsock2.h
Library	Ws2.lib
Windows Embedded CE	Windows CE 1.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later