recv()

PROTOTYPE

#include <sockets.h>

ssize_t recv(int socket, void *buffer, size_t length, int flags);

DESCRIPTION

recv() reads data from the socket specified by socket. buffer points where the data is copied to. length is the number of bytes to read. flags is 0 or a bitwise OR of the following symbols that modify recv()’s behavior:

• MSG_DONTWAIT: Temporarily makes the socket non-blocking.
• MSG_OOB: Enables receipt of urgent out-of-band data byte (TCP only).
• MSG_PEEK: Reads data without removing it from socket receive buffer or datagram queue.
• MSG_WAITALL: Prevents return until all requested bytes have been read (TCP only).

TCP sockets used by recv() must be connected. If the connection is lost, recv() calls succeed until all previously received data has been read. recv() returns 0 if the socket has been shut down for reading (shutdown(socket, SHUT_RD)) or the peer has closed the connection and all previously buffered data has been read. TCP data is treated as a continuous byte stream.

UDP sockets used by recv() must have a local address assigned by bind() or sendto(). UDP data is transferred as datagrams. Each recv() call consumes one datagram. If length is less than the datagram size, recv() discards the additional bytes, sets errno to EMSGSIZE, and returns -1. The return value is 0 if a datagram with no data is received.

If no data is waiting, recv() behaves as follows: if the socket is blocking (the default), it waits until data arrives or the receive timeout expires. The default wait is forever, but other values can be set by the setsockopt() SO_RCVTIMEO option. If the socket is non-blocking, recv() sets errno to EWOULDBLOCK and returns -1. A socket is made non-blocking using the ioctlsocket() FIONBIO option or (temporarily) the MSG_DONTWAIT flag.

If successful, recv() returns the number of bytes read. Otherwise, it sets errno and returns -1.

ERROR CODES

ECONNABORTED	Connection was aborted because of unacknowledged transmissions.
ECONNRESET	Connection was forcibly closed by remote host (received RST).
EFAULT	buffer is NULL and length is not 0.
EHOSTUNREACH	Timed out after receiving a “host unreachable” ICMP message.
EINVAL	MSG_OOB is set and either SO_OODINLINE is set or no urgent data is available, UDP socket is not bound to a local port number, or the flags combination is illegal.
EMSGSIZE	Datagram size is larger than length and was truncated (UDP only).
ENETDOWN	TargetTCP has not been initialized.
ENOTCONN	The socket is unconnected (TCP only).
ENOTSOCK	socket is not a valid socket handle.
EOPNOTSUPP	MSG_OOB or MSG_WAITALL specified for UDP socket.
ETIMEDOUT	Timeout expired before recv() completed (connection not dropped).
EWOULDBLOCK	The socket is non-blocking and no data is currently available to receive.

EXAMPLE

  /*-------------------------------------------------------------------*/
  /* Try to receive BUF_SIZE bytes.                                    */
  /*-------------------------------------------------------------------*/
  length = recv(sock, RcvBuf, BUF_SIZE, MSG_WAITALL);
  if (length == -1)
    return -1;
  total += length;

  /*-------------------------------------------------------------------*/
  /* Break if the connection has been closed.                          */
  /*-------------------------------------------------------------------*/
  if (length == 0)
    break;