shutdown

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int shutdown (
int socketDescriptor,
int howToShutdown
);


Function Description

Shutdown a socket in read, write, or both directions determined by the parameter howToShutdown. This function is often used to implement a graceful shutdown, by allowing the pending output to clear and be processed by the peer before closing the socket. This is demonstrated below for a blocking mode TCP socket. If you call tfClose() immediately after a send(), Treck will try to ensure that all data is sent and acknowledged before destroying the socket (with timeouts dictated by the underlying protocol).
/* Send the sign-off message */
retCode = send(sockDescr, sendBuf, sendLen, 0);
    . . .
/* Close our side of the connection */
retCode = shutdown(sockDescr, 1);
    . . .
/* Wait until the peer closes (you may want a timeout in case the peer never closes) */
do
{
    retCode = recv(sockDescr, recvBuf, sizeof(recvBuf), 0);
} while (retCode > 0);
    . . .
/* Dispose of the socket */
retCode = tfClose(sockDescr);
    . . .


Parameters

  • socketDescriptor
    The socket descriptor from which to receive the data.
  • howToShutdown
    Direction:
  • 0 -> Read
  • 1 -> Write
  • 2 -> Both


Return Values

  • TM_ENOERROR
    Success
  • TM_SOCKET_ERROR
    Failure


Note Note: TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself.

To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).


Possible socket errors

  • TM_EBADF
    The socket descriptor is invalid.
  • TM_EINVAL
    One of the parameters is invalid.
  • TM_EOPNOTSUPP
    Invalid socket type. shutdown() can only be used for TCP sockets.
  • TM_ESHUTDOWN
    The socket is already closed or is in the process of closing.


Table of Contents >> Programmer's Reference