recv()

Receive a message from a socket

Synopsis:

#include <sys/types.h>
#include <sys/socket.h>

ssize_t recv( int s,
              void * buf,
              size_t len,
              int flags );

Arguments:

s
The descriptor for the socket; see socket().
buf
A pointer to a buffer where the function can store the message.
len
The size of the buffer. If len is greater than SSIZE_MAX (see <limits.h>), the function fails and sets errno to EOVERFLOW.
flags
A combination formed by ORing one or more of the values:
  • MSG_OOB — process out-of-band data. This flag requests receipt of out-of-band data that wouldn't be received in the normal data stream. You can't use this flag with protocols that place expedited data at the head of the normal data queue.
  • MSG_PEEK — peek at the incoming message. This flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data.
  • MSG_WAITALL — wait for full request or error. This flag requests that the operation block until the full request is satisfied. But the call may still return less data than requested if a signal is caught, if an error or disconnect occurs, or if the next data to be received is of a different type than that returned.

Library:

libsocket

Use the -l socket option to qcc to link against this library.

Description:

The recv() function receives a message from a socket. It's normally used only on a connected socket—see connect()—and is identical to recvfrom() with a zero from parameter.

This routine returns the length of the message on successful completion. If a message is too long for the supplied buffer, buf, then excess bytes might be discarded, depending on the type of socket that the message is received from; see socket().

If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking—see ioctl()—in which case -1 is returned and the external variable errno is set to EWOULDBLOCK. Normally, the receive calls return any data available, up to the requested amount, rather than wait for the full amount requested; this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt().

You can use select() to determine when more data is to arrive.

Returns:

The number of bytes received, 0 if there are no messages available and the peer has disconnected, or -1 if an error occurs (errno is set).

Errors:

EBADF
Invalid descriptor s.
EFAULT
The receive buffer is outside the process's address space.
EINTR
The receive was interrupted by delivery of a signal before any data was available.
ENOTCONN
The socket is associated with a connection-oriented protocol and hasn't been connected; see connect() and accept().
EOVERFLOW
An attempt was made to receive an amount of data that exceeds the allowable limit.
EWOULDBLOCK
Either the socket is marked nonblocking and the receive operation would block, or a receive timeout had been set and the timeout expired before data was received.

The errno variable can also be set to any of the errors indicated by MsgSendv().

Classification:

POSIX 1003.1

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes