recv(2)

NAME

recv(), recvfrom(), recvmsg() — receive a message from a socket

SYNOPSIS

#include <sys/socket.h> 

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

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

int recvmsg(int s, struct msghdr msg[], int flags); 

UNIX 03 Only (X/Open Sockets)

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

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

ssize_t recvmsg(int s, struct msghdr *msg, int flags); 

Obsolescent UNIX 95 Only (X/Open Sockets)

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

DESCRIPTION

The recv(), recvfrom(), and recvmsg() system calls 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(2)). 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() (see 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 nonzero, 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.

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. See the AF_CCITT Only subsection below for a list of the exceptions to this behavior for connections in the address family AF_CCITT.

recvmsg() performs the same action as recv(), but scatters the read data into the buffers specified in the msghdr structure (see X/Open Sockets Only below). This structure is defined in <sys/socket.h> and has the following form (HP-UX BSD Sockets Only):

struct msghdr { 
    caddr_t   msg_name;            /* optional address */ 
    int       msg_namelen;         /* size of address  */ 
    struct    iovec *msg_iov;      /* scatter array for data */ 
    int       msg_iovlen;          /* # of elements in msg_iov */ 
    caddr_t   msg_accrights;       /* access rights */ 
    int       msg_accrightslen;    /* size of msg_accrights */ 
} 

msg_name points to a sockaddr structure in which the address of the sending socket is to be stored, if the socket is connectionless; msg_name may be a null pointer if no name is specified. msg_iov specifies the locations of the character arrays for storing the incoming data. msg_accrights specifies a buffer to receive any access rights sent along with the message. Access rights are limited to file descriptors of size int. If access rights are not being transferred, set the msg_accrights field to NULL. Access rights are supported only for AF_UNIX.

By default, recv(), recvfrom() and recvmsg() are blocking system calls and do not complete until there is data to read or the end of the socket data stream is reached (the remote side of a connection-based socket has performed an orderly shutdown and there is no more data to read).

There are three ways to enable nonblocking mode:

With the FIOSNBIO ioctl() request
With the O_NONBLOCK fcntl() flag
With the O_NDELAY fcntl() flag

Although the use of FIONBIO is not recommended, if nonblocking I/O is enabled using FIOSNBIO or the equivalent FIONBIO request (defined in <sys/ioctl.h> and explained in ioctl(2), ioctl(5) and socket(7)), the recv() request completes in one of six ways:

If there is enough data available to satisfy the entire request, recv() completes successfully, having read all of 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() returns -1 and errno is set to EWOULDBLOCK.
If the remote side of a connection-based socket has performed an orderly shutdown and there is no more data to read (the socket has reached the end of its data stream), recv() returns 0.
If the remote side of a connection-based socket has reset the connection, recv() returns -1 and sets errno to ECONNRESET.
If an error occurs, recv() returns -1 and sets errno to indicate the error.

If nonblocking I/O is disabled using FIOSNBIO, recv() always executes completely (blocking as necessary) and returns the number of bytes read.

If the O_NONBLOCK flag is set using fcntl() (defined in <sys/fcntl.h> and explained in fcntl(2) and fcntl(5)), POSIX-style nonblocking I/O is enabled. In this case, the recv() request completes in one of six 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, having read no data, and returns -1 and sets errno to EAGAIN.
If the remote side of a connection-based socket has performed an orderly shutdown and there is no more data to read (the socket has reached the end of its data stream), recv() returns 0.
If the remote side of a connection-based socket has reset the connection, recv() returns -1 and sets errno to ECONNRESET.
If an error occurs, recv() returns -1 and errno is set to indicate the error.

If the O_NDELAY flag is set using fcntl() (defined in <sys/fcntl.h> and explained in fcntl(2) and fcntl(5)), nonblocking I/O is enabled. In this case, the recv() request completes in one of five 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 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 the remote side of a connection-based socket has performed an orderly shutdown and there is no more data to read (the socket has reached the end of its data stream), recv() completes and returns 0. The recv() call will also complete and return 0 when there is no data to read. To distinguish this condition from the end of the data stream, you can use a select() or poll() call to check for data before calling recv(). If the select() or poll() call indicates that an event has occurred on the socket, the subsequent but recv() call will only return 0 if the socket has reached the end of the data stream.
If the remote side of a connection-based socket has reset the connection, recv() returns -1 and sets errno to ECONNRESET.
If an error occurs, recv() returns -1 and errno is set to indicate the error.

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

Since both the fcntl() O_NONBLOCK and O_NDELAY flags and ioctl() FIOSNBIO request are supported, some clarification on how these features interact is necessary. If the O_NONBLOCK or O_NDELAY flag has been set, recv() requests behave accordingly, regardless of any FIOSNBIO requests. If neither the O_NONBLOCK flag nor the O_NDELAY flag has been set, FIOSNBIO requests control the behavior of recv().

By default nonblocking I/O is disabled.

select() 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() rereads the same data. The MSG_OOB flag is used to receive out-of-band data. For TCP SOCK_STREAM sockets, both the MSG_PEEK and MSG_OOB flags can be set at the same time. The MSG_OOB flag value is supported for TCP SOCK_STREAM sockets only. MSG_OOB is not supported for AF_UNIX or AF_VME_LINK sockets.

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

AF_CCITT Only

Connections in the address family AF_CCITT support message-based sockets only. Although the user specifies connection-based communications (SOCK_STREAM), the X.25 subsystem communicates via messages. This address family does not support SOCK_DGRAM socket types.

Normally, each recv() returns one complete X.25 message. If the socket is in nonblocking mode, recv() behaves as described above. Note that if the user specifies len less than the actual X.25 message size, the excess data is discarded and no error indication is returned. The size of the next available message as well as the state of MDTF, D, and Q bits can be obtained with ioctl(X25_NEXT_MSG_STAT).

Connections of the address family AF_CCITT receive data in the same way as message-based connections described above, with the following additions and exceptions:

recvfrom() is supported; however, the from and fromlen parameters are ignored (that is, it works in the same manner as recv()).
To receive a message in fragments of the complete X.25 message, use ioctl(X25_SET_FRAGMENT_SIZE). The state of the MDTF bit is 1 for all except the last fragment of the message.
The MSG_OOB flag is supported.
The MSG_PEEK flag is supported; the two flags can be combined.
If a message is received that is larger than the user-controlled maximum message size, the X.25 subsystem RESETs the circuit, discards the data, and sends the out-of-band event OOB_VC_MESSAGE_TOO_BIG to the socket.

X/Open Sockets Only

For X/Open Sockets, the msghdr structure has the following form:

(UNIX 03) 
  
struct msghdr { 
    void       *msg_name;           /* optional address */ 
    socklen_t   msg_namelen;        /* size of address  */ 
    struct      iovec *msg_iov;     /* scatter array for data */ 
    int         msg_iovlen;         /* # of elements in msg_iov */ 
    void       *msg_control;        /* ancillary data, see below */ 
    socklen_t   msg_controllen;     /* ancillary data buffer len */ 
    int         msg_flags;          /* flags on received message */ 
} 
  
Obsolescent (UNIX 95) 
  
struct msghdr { 
    void       *msg_name;           /* optional address */ 
    size_t      msg_namelen;        /* size of address  */ 
    struct      iovec *msg_iov;     /* scatter array for data */ 
    int         msg_iovlen;         /* # of elements in msg_iov */ 
    void       *msg_control;        /* ancillary data, see below */ 
    size_t      msg_controllen;     /* ancillary data buffer len */ 
    int         msg_flags;          /* flags on received message */ 
} 

msg_control specifies a buffer to receive any ancillary data sent along with the message. Ancillary data consists of a sequence of pairs, each consisting of a cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the cmsghdr structure contains descriptive information that allows an application to correctly parse the data. cmsghdr has the following structure:

(UNIX 03) 
  
struct cmsghdr { 
    socklen_t  cmsg_len;      /* data byte count, including hdr*/ 
    int        cmsg_level;    /* originating protocol */ 
    int        cmsg_type;     /* protocol-specific type */ 
} 
  
Obsolescent (UNIX 95) 
  
struct cmsghdr { 
    size_t     cmsg_len;      /* data byte count, including hdr*/ 
    int        cmsg_level;    /* originating protocol */ 
    int        cmsg_type;     /* protocol-specific type */ 
} 

If the cmsg_level is SOL_SOCKET, and cmsg_type is SCM_RIGHTS, then it indicates that the data array contains the access rights to be received. Access rights are supported only for AF_UNIX. Access rights are limited to file descriptors of size int.

If the cmsg_level is IPPROTO_IPV6, then cmsg_type must be one of the supported types: IPV6_PKTINFO, IPV6_HOPLIMIT, IPV6_NEXTHOP, IPV6_RTHDR, IPV6_HOPOPTS, IPV6_DSTOPTS or IPV6_RTHDRDSTOPTS. (See description in IPv6(7P)).

If ancillary data are not being transferred, set the msg_control field to NULL, and set the msg_controllen field to 0.

The flags parameter accepts a new value, MSG_WAITALL, which requests that the function block until the full amount of data requested can be returned. The function may return a smaller amount of data if a signal is caught, the connection is terminated, or an error is pending for the socket.

On successful completion of recvmsg(), the msg_flags member of the message header is the bitwise-inclusive OR of all of the following flags that indicate conditions detected for the received message.

MSG_EOR: End of record was received (if supported by the protocol).
MSG_OOB: Out-of-band data was received.
MSG_TRUNC: Normal data was truncated.
MSG_CTRUNC: Control data was truncated.

X/Open Sockets Compilation Environment

See xopen_networking(7).

DEPENDENCIES

AF_CCITT

recvfrom() is supported; however, the from and fromlen parameters are ignored (it works in the same manner as recv()).

The O_NDELAY fcntl() call is not supported over X.25 links. Use the FIOSNBIO ioctl() call instead to enable nonblocking I/0.

RETURN VALUE

recv(), recvfrom(), and recvmsg() return the following values:

n: Successful completion. n is the number of bytes received.
0: The socket is blocking and the transport connection to the remote node failed, or the remote side of a connection-based socket has performed an orderly shutdown and there is no more data to read (the socket has reached the end of its data stream). Sockets with the O_NDELAY flag set may also return 0 at any time when there is no data available.
-1: Failure. errno is set to indicate the error.

ERRORS

If recv(), recvfrom(), or recvmsg() fails, errno is set to one of the following values.

EAGAIN

Non-blocking I/O is enabled using O_NONBLOCK flag with fcntl() and the receive operation would block, or the socket has an error that was set asynchronously. An asynchronous error can be caused by a gateway failing to forward a datagram because the datagram exceeds the MTU of the next-hop network and the "Don't Fragment" (DF) bit in the datagram is set. (See SO_PMTU in getsockopt(2).)

EBADF

The argument s is an invalid descriptor.

ECONNRESET

A connection was forcibly closed by a peer.

EFAULT

An invalid pointer was specified in the buf, from, or fromlen parameter, or in the msghdr structure.

EINTR

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

EINVAL

The len parameter or a length in the msghdr structure is invalid; or no data is available on receive of out of band data.

EMFILE

The number of file descriptors available to the calling process has been exceeded.

EMSGSIZE

A length in the msghdr structure is invalid.

ENOBUFS

Insufficient resources were available in the system to perform the operation.

ENOPROTOOPT

The remote system or an intermediate system in the communications path does not support a protocol option sent by the local system. This option may have been set using a getsockopt() or setsockopt() call, or set as a system parameter.

ENOSR

Buffers could not be allocated for the message that was to be created due to insufficient STREAMS memory resources.

ENOTCONN

Receive on a SOCK_STREAM socket that is not yet connected.

ENOTSOCK

The argument s is a valid file descriptor, but it is not a socket.

EOPNOTSUPP

The MSG_OOB flag was set for a UDP SOCK_DGRAM message-based socket, or MSG_OOB or MSG_PEEK was set for any AF_UNIX socket. The MSG_OOB flag is supported only for stream-based TCP SOCK_STREAM sockets. Neither MSG_PEEK nor MSG_OOB is supported for AF_UNIX sockets.

AF_CCITT only: recv() was issued on a listen() socket.

ETIMEDOUT

The connection timed out during connection establishment, or due to a transmission timeout on active connection.

EWOULDBLOCK

Non-blocking I/O is enabled using ioctl() FIOSNBIO request, and the requested operation would block.

OBSOLESCENCE

Currently, the socklen_t and size_t types are the same size. This is compatible with the UNIX 95 and UNIX 03 profiles. However, in a future release, socklen_t might be a different size. In that case, passing a size_t pointer will evoke compile-time warnings, which must be corrected in order for the application to behave correctly. Also, the size of the msghdr and cmsghdr structures and the relative position of their members will be different, which might affect application behavior. Applications that use socklen_t now, where appropriate, will avoid such migration problems. On the other hand, applications that need to be portable to the UNIX 95 profile should follow the X/Open specification (see xopen_networking(7)).

WARNINGS

Linking binary objects compiled to X/Open Sockets specification and binary objects compiled to HP-UX BSD Sockets specification to the same executable may result in unexpected behavior, including application abnormal termination and unexpected socket errors. See xopen_networking(7) for details and remedy.

FUTURE DIRECTION

Currently, the default behavior is the HP-UX BSD Sockets; however, it might be changed to X/Open Sockets in a future release. At that time, any HP-UX BSD Sockets behavior that is incompatible with X/Open Sockets might be obsoleted. Applications that conform to the X/Open specification now will avoid migration problems (see xopen_networking(7)).

AUTHOR

recv(), recvmsg(), and recvfrom() were developed by HP and the University of California, Berkeley.

STANDARDS CONFORMANCE

recv(): XPG4, UNIX 95, UNIX 03