SockClose | Closes a socket. |
SockShutdown | Prepares a socket for closing by refusing any further connections from other computers and returning any queued data. |
Closes a socket (which was created by SockSocket or gotten from SockAccept), and frees resources associated with it.
Calls the sockets library's closesocket() (and perhaps shutdown()) function.
Synopsis
err = SockClose(socket, how)
Args
socket is the socket returned by SockSocket or SockAccept.
If how is not omitted, then SockClose will implicitly call SockShutdown and how is the same as the how arg passed to SockShutdown.
Returns
Notes
The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.
If how is omitted, then SockShutdown should be called before SockClose.
The behavior of SockClose is affected by the socket option SO_LINGER as follows:
Option | Type of close | Wait for close? |
SO_LINGER is off | Graceful | No |
SO_LINGER is on with 0 timeout | Hard | No |
SO_LINGER is on with timeout | Graceful | Yes |
If SO_LINGER option is turned on with a zero timeout interval, then SockClose will not block even if queued data has not yet been sent or acknowledged by the underlying sockets library. This is called a "hard" or "abortive" close, because the socket is reset immediately, and any unsent data is lost. Any SockRecv call on the remote computer will fail with ErrNo = "ECONNRESET".
If SO_LINGER option is turned on with a nonzero timeout interval, then SockClose blocks until the remaining data has been sent or until the timeout expires. This is called a "graceful disconnect". Note that if the socket is set to non-blocking mode and remaining data needs to be sent, then SockClose will fail with ErrNo = "EWOULDBLOCK".
If SO_LINGER option is turned off with a stream socket, then SockClose 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 WIN32 sockets implementation may not release the socket and other resources for an arbitrary period, which may affect scripts that expect to use all available sockets.
Prepares a socket for closing (via SockClose) by refusing any further connections from other computers and returning any queued data. This is used on all types of sockets to disable reception, transmission, or both.
Calls the sockets library's shutdown() function.
Synopsis
err = SockShutDown(socket, how)
Args
socket is the socket returned by SockSocket or SockAccept.
how is a numeric value that indicates what types of operation will no longer be allowed. It is one of the following:
0 | Subsequent receives on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP, the TCP window is not changed, and incoming data will be accepted (but not acknowledged) until the window is exhausted. For UDP, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated. |
1 | Subsequent sends are disallowed. For TCP sockets, a FIN will be sent. |
2 | Disables (disallows) both sends and receives as described above. |
If omitted, how defaults to 1.
Returns
0 if success, or -1 if shutdown() fails.
Notes
The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.
SockShutDown does not close the socket, and resources attached to the socket will not be freed until SockClose is called.
SockShutDown does not block, regardless of the SO_LINGER setting on the socket.
A script should not rely on being able to reuse a socket after it has been shut down.