recv

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int recv (
int socketDescriptor,
char * bufferPtr,
int bufferLength,
int flags
);


Function Description

recv() is used to receive messages from another socket. recv() may be used only on a connected socket (see connect(), accept()). socketDescriptor is a socket created with socket() or accept(). The length of the message is returned. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket()). The length of the message returned could also be smaller than bufferLength (this is not an error). If no messages are available at the socket, the recv() call waits for a message to arrive, unless the socket is non-blocking, or the MSG_DONTWAIT flag is set in the flags parameter, in which case TM_SOCKET_ERROR is returned with socket error being set to TM_EWOULDBLOCK.

Out-of-band data not in the stream (urgent data when the SO_OOBINLINE option is not set (default)) (TCP protocol only).

A single out-of-band data byte is provided with the TCP protocol when the SO_OOBINLINE option is not set. If an out-of-band data byte is present, recv() with the MSG_OOB flag not set will not read past the position of the out-of-band data byte in a single recv() request. That is, if there are 10 bytes from the current read position until the out-of-band byte, and if we execute a recv() specifying a bufferLength of 20 bytes, and a flag value of 0, recv() will only return 10 bytes. This forced stopping is to allow us to execute the SOIOCATMARK tfIoctl() to determine when we are at the out-of-band byte mark. Alternatively, tfGetOobDataOffset() can be used instead of tfIoctl() to determine the offset of the out-of-band data byte. When we are at the mark, recv() with the MSG_OOB flag set can read the out-of-band data byte. Note that the user needs to either use select() or tfRegisterSocketCB() in order to know when out-of-band data has arrived or is arriving.

Out-of-band data (when the SO_OOBINLINE option is set (see setsockopt())) (TCP protocol only.).

If the SO_OOBINLINE option is enabled, the out-of-band data is left in the normal data stream and is read without specifying the MSG_OOB. More than one out-of-band data bytes can be in the stream at any given time. The out-of-band byte mark corresponds to the final byte of out-of-band data that was received. In this case, the MSG_OOB flag cannot be used with recv(). The out-of-band data will be read in line with the other data. Again, recv() will not read past the position of the out-of-band mark in a single recv() request. Again, tfIoctl() with the SOIOCATMARK, or tfGetOobDataOffset() can be used to determine where the last received out-of-band byte is in the stream. Note that the user needs to either use select() or tfRegisterSocketCB() in order to know when out-of-band data has arrived, or is arriving. select() may be used to determine when more data arrives, and/or when out-of-band data arrives. tfRegisterSocketCB() may be used to asynchronously determine when more data arrives, and/or when out-of-band data arrives.


Parameters

  • socketDescriptor
    The socket descriptor from which to receive the data.
  • bufferPtr
    The buffer into which the received data is put.
  • bufferLength
    The length.
  • flags
    See below for possible flags parameters that can be OR'ed together.


Flags

Value Meaning
MSG_DONTWAIT Don't wait for data, but rather return immediately.
MSG_OOB Read any "out-of-band" data present on the socket rather than the regular "in-band" data.
MSG_PEEK "Peek" at the data present on the socket; the data is returned, but not consumed, so that a subsequent recv() operation will see the same data.
MSG_WAITALL Block until the requested amount of data can be returned.


Return Values

  • > 0
    Number of bytes actually received from the socket.
  • TM_ENOERROR
    EOF or the remote host has closed the connection.
  • 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_EMSGSIZE
    The socket requires the message to be received atomically, and bufferLength was too small.
  • TM_EWOULDBLOCK
    The socket is marked as non-blocking or the MSG_DONTWAIT flag is used and no data is available to be read, or the MSG_OOB flag is set and the out-of-band data has not yet arrived from the peer.
  • TM_EINVAL
    One of the parameters is invalid, or the MSG_OOB flag is set and, either the SO_OOBINLINE option is set, or there is no out of band data to read or coming from the peer.
  • TM_ENOTCONN
    The socket is not connected.
  • TM_EHOSTUNREACH
    No route to the connected host.
  • TM_ETIMEDOUT
    The TCP connection has timed out.


Table of Contents >> Programmer's Reference