Irie Pascal Programmer's Reference Manual

12.15.1 The shutdown function

Description

The shutdown function disables the reception of data from a socket, and/or the transmission of data through a socket, and can be used on all types of sockets. The shutdown function does not close the socket. Any resources attached to the socket will not be freed until the closesocket function is called.

To ensure that all data is sent and received on a connected socket before it is closed, your program should use the shutdown function to close the connection before calling the closesocket function to close the socket. For example, to initiate a graceful disconnect:

Call the shutdown to disable the transmission of data.
Call the recv function until zero or SOCKET_ERROR is returned.
Call the closesocket function.

The shutdown function does not block regardless of the SO_LINGER setting on the socket. You should not rely on being able to re-use a socket after it has been shut down. In particular, a Windows Sockets provider is not required to support the use of the connect function on a socket that has been shut down.

Declaration

The system include file WinSock2.inc contains the following declaration for the shutdown function:

 function shutdown(s : SOCKET; how : integer) : integer;
  external dll='ws2_32.dll';

Arguments

The First Argument

The first argument passed to the shutdown function is the socket that you want to disable, the reception of data from and/or disable the transmission of data through.

The Second Argument

The second argument passed to the shutdown function specifies whether you want to disable the receptioin of data, the transmission of data or both, and can have the follow values:

SD_RECEIVE - subsequent calls to the recv function on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP sockets, if there is still data queued on the socket waiting to be received, or data arrives subsequently, the connection is reset, since the data cannot be delivered to the user. For UDP sockets, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated.
SD_SEND - subsequent calls to the send function are disallowed. For TCP sockets, a FIN will be sent after all data is sent and acknowledged by the receiver.
SD_BOTH - disables both sending and receiving as described above.

Return Values

The shutdown 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, SD_RECEIVE, SD_SEND, SD_BOTH, and SOCKET_ERROR 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.

Contents | Prev | Next