closesocket (Compact 2013)

3/26/2014

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.

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.

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

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 Compact.

Error code

Requirements

See Also

Reference

Socket Functions
accept (Windows Sockets)
ioctlsocket
linger
recv
setsockopt (Windows Sockets)
shutdown
socket (Windows Sockets)
WSAGetLastError
WSARecv
WSARecvFrom
WSASend
WSASendTo
WSAStartup