recv(2)

Requires Optional LAN/X.25 Software

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);

DESCRIPTION

recv, recvfrom, and recvmsg 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(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. See the AF_CCITT section 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. This structure is defined in <sys/socket.h>, and has the following form :

struct msghdr {
caddr_tmsg_name;/* optional address */
intmsg_namelen;/* size of address */
struct iovec *msg_iov;/* scatter array for data */
intmsg_iovlen;/* # of elements in msg_iov */
caddr_t msg_accrights;/* access rights */
intmsg_accrightslen; /* size of msg_accrights */
}

msg_name is the destination address if the socket is unconnected; msg_name may be a null pointer if no name is specified. msg_iov is the location of the scatter/gather 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_acccrights field to NULL. Access rights are supported only for AF_UNIX.

If no data is available to be received, recv waits for a message to arrive unless non-blocking mode is enabled. There are three ways to enable non-blocking mode:

• With the FIOSNBIO ioctl request,

• With the O_NONBLOCK fcntl flag,

• With the O_NDELAY fcntl flag.

If non-blocking I/O is enabled using FIOSNBIO (defined in <sys/ioctl.h> and explained in ioctl(2), ioctl(5) and socket(7)), 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 of the data, and returns the number of bytes read.

• If there is not enough data available to satisfy the entire request, recv complete 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 fails and errno is set to EWOULDBLOCK.

If non-blocking 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 non-blocking I/O is enabled. In this case, 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, having read no data, and returns −1 with errno set to EAGAIN.

If the O_NDELAY flag is set using fcntl (defined in <sys/fcntl.h> and explained in fcntl(2) and fcntl(5)), non-blocking I/O is enabled. In this case, 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_NONBLOCK or O_NDELAY flag is cleared using fcntl, the corresponding style of 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.

Since both the fcntl O_NONBLOCK and O_NDELAY flags and FIOSNBIO 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 nor O_NDELAY flag has been set, FIOSNBIO requests control the behavior of recv. The default is that non-blocking I/O is not enabled.

The select(2) 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. For stream-based 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 stream-based TCP SOCK_STREAM sockets only. MSG_PEEK and MSG_OOB are not supported for AF_UNIX sockets.

A read(2) 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 non-blocking mode, recv() behaves as described above. Note that if the user specifies len less than the actual X.25 message size, the excess data 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()).

• If the user wants to receive a message in fragments of the complete X.25 message, ioctl(X25_SET_FRAGMENT_SIZE) should be used. The state of MDTF bit is 1 on 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 (see af_ccitt(7F)), 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.

DEPENDENCIES

AF_CCITT
recvfrom() is supported; however, the from and fromlen parameters are ignored (that is, 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 non-blocking I/0.

RETURN VALUE

If the recv 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. A zero is returned if the socket is blocking and the transport connection to the remote node fails.

DIAGNOSTICS

The call to recv or recvfrom fail if:

[EBADF] The argument s is an invalid descriptor.

[ENOTSOCK] The argument s is not a socket.

[EWOULDBLOCK] The socket is marked non-blocking and the receive operation would block.

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

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

[EMSGSIZE] A length in the msghdr structure is invalid.

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

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

[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.

[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 only supported 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.

[ENOBUFS] Insufficient resources were available in the system to perform the operation.

[ECONNRESET] A connection was forcibly closed by a peer.

AUTHOR

recv was developed by the University of California, Berkeley

Museum

Related Articles