closesocket

This function closes a socket.

At a Glance

Syntax

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 WSAEINTR error value.

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 closesocket function confident that the receiver will copy the data before receiving an FD_CLOSE message.

The closesocket function closes a socket. Use it to release the socket descriptor s so that further references to s will 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 closesocket for each successful call to socket to return any socket resources to the system.

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

If SO_LINGER is set with a zero time-out interval (that is, the LINGER structure members l_onoff is not zero 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 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. 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 assure 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.

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 that indicates failure.

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

See Also

accept, socket, ioctlsocket, setsockopt