recv(3)

NAME
recv, recvfrom - receive a message from a socket

SYNOPSIS
#include <sys/socket.h>

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

  AF_UNIX only:
#include <sys/un.h>

int recvfrom(int s, void *buf, size_t len, int flags,
    struct sockaddr *from, size_t *fromlen);

DESCRIPTION
recv and recvfrom are used to receive messages from a socket.

s is a socket descriptor from which messages are received. buf is a pointer to the buffer into which the messages are placed. len is the maximum number of bytes that can fit in the buffer referenced by buf.

If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has been established (see connect(3)). For connectionless sockets such as SOCK_DGRAM, these calls can be used whether a connection has been specified or not.

recvfrom operates in the same manner as recv except that it is able to return the address of the socket from which the message was sent. For connected datagram sockets, recvfrom simply returns the same address as getpeername(2). For stream sockets, recvfrom retrieves data in the same manner as recv, but does not return the socket address of the sender. If from is non-zero, the source address of the message is placed in the socket address structure pointed to by from. fromlen is a value-result parameter, initialized to the size of the structure associated with from, and modified on return to indicate the actual size of the address stored there. If the memory pointed to by from is not large enough to contain the entire address, only the first fromlen bytes of the address are returned.

The length of the message is returned.

For message-based sockets such as SOCK_DGRAM, the entire message must be read in a single operation. If a message is too long to fit in the supplied buffer, the excess bytes are discarded. For stream-based sockets such as SOCK_STREAM, there is no concept of message boundaries. In this case, data is returned to the user as soon as it becomes available, and no data is discarded.

If no data is available to be received, recv waits for a message to arrive unless non-blocking mode is enabled. You can enable non-blocking mode by setting the O_NDELAY flag using fcntl. O_NDELAY is defined in <fcntl.h>. If non-blocking mode is enabled, the recv request completes in one of three ways:

    •   If there is enough data available to satisfy the entire request, recv completes successfully, having read all the data, and returns the number of bytes read.

    •   If there is not enough data available to satisfy the entire request, recv completes successfully, having read as much data as possible, and returns the number of bytes it was able to read.

    •   If there is no data available, recv completes successfully, having read no data, and returns 0.

If the O_NDELAY flag is cleared using fcntl, non-blocking I/O, if previously enabled, is disabled. In this case, recv always executes completely (blocking as necessary) and returns the number of bytes read.

The select(3) call can be used to determine when more data arrives by selecting the socket for reading.

The flags parameter can be set to MSG_PEEK, MSG_OOB, both, or zero. If it is set to MSG_PEEK, any data returned to the user still is treated as if it had not been read. The next recv re-reads the same data. The MSG_OOB flag is used to alert the other process with an urgent message, using a logically independent transmission channel associated with a pair of connected stream sockets. Refer to SEE ALSO below for details. MSG_PEEK and MSG_OOB are not supported for AF_UNIX sockets.

A read(3) call made to a socket behaves in exactly the same way as a recv with flags set to zero.

RETURN VALUE
If the recv or recvfrom call is successful, it returns the number of bytes received. If the call fails, -1 is returned and an error code is stored in errno.

DIAGNOSTICS
The call to recv or recvfrom fail if:

    [EBADF]
        The argument s is an invalid descriptor.

    [EINVAL]
        The argument s is not a socket.

    [EINTR]
        The receive was interrupted by delivery of a signal before any data was available for the receive.

    [ENOTCONN]
        Receive on a SOCK_STREAM socket that is not yet connected.

    [EOPNOTSUPP]
        The MSG_OOB or MSG_PEEK flag was set for any AF_UNIX socket. Neither MSG_PEEK nor MSG_OOB is supported for AF_UNIX sockets.

SEE ALSO
getsockopt(3), read(3), select(3), send(3), socket(3).