Description
The closesocket function closes a socket, and frees the resources attached to the socket. To assure that all data is sent and received on a connection, your program should call the shutdown function before calling the closesocket function. NOTE: An FD_CLOSE network event is not posted after the closesocket function is called.
Your program should always have a matching call to the closesocket function for each successful call to the createsocket function to return any socket resources to the system.
The behavior of the closesocket function can be affected by the socket options SO_LINGER and SO_DONTLINGER. When a socket is created SO_DONTLINGER is enabled (and therefore SO_LINGER is disabled).
SO_LINGER Enabled
If the SO_LINGER socket option is enabled with a zero time-out interval (that is, the linger structure members l_onoff is not zero and l_linger is zero), the closesocket function will not block even if queued data has not yet been sent or acknowledged. This is called a hard or abortive close, because the connection is reset immediately, and any unsent data is lost. Any recv function call on the remote side of the connection will fail, and the WSAGetLastError function with return WSAECONNRESET.
If the SO_LINGER socket option is set with a nonzero time-out interval on a socket with it's non-blocking mode disabled, the closesocket function will block until any 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 the closesocket function returns.
Enabling the SO_LINGER socket option with a nonzero time-out interval on a socket with it's non-blocking mode enabled is not recommended. In this case, the call to the closesocket function will fail, and the WSAGetLastError function will return WSAEWOULDBLOCK if the close operation cannot be completed immediately. However the socket handle is still valid, and a disconnect is not initiated. Your program must call the closesocket function again to close the socket.
SO_DONTLINGER Enabled
If the SO_DONTLINGER socket option is enabled on a stream socket by setting the l_onoff member of the linger structure to zero, the closesocket function call will return immediately and successfully, whether the socket has it's non-blocking mode enabled or disabled. 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 enabled by default).
Declaration
The system include file WinSock2.inc contains the following declarations for the linger type, and the closesocket function:
linger = packed record
l_onoff : u_short;
l_linger : u_short;
end;
function closesocket(s : SOCKET) : integer;
external dll='ws2_32.dll';Arguments
The First Argument
The first and only argument passed to the closesocket function is the socket that you want to close.
Return Values
The closesocket function returns a value of integer type that indicates whether the call was successful. A value of zero means that the call succeeded. A value of SOCKET_ERROR indicates that the called failed, and in this case you can use the WSAGetLastError function to retrieve a code that identifies the error that caused the call to fail. NOTE: The constants SO_LINGER, SO_DONTLINGER, WSAECONNRESET, WSAEWOULDBLOCK, SOCKET_ERROR, and the type linger are declared in the system include file WinSock2.inc.
Reference Information
The authoritative source of information about the WinSock2 library is the Microsoft Developers Network (MSDN). You can access the MSDN on the Microsoft website at msdn.microsoft.com.