recv(3N) UNIX System V recv(3N)
NAME
recv, recvfrom, recvmsg - receive a message from a socket
SYNOPSIS
#include <sys/types.h>
int recv(int s, char *buf, int len, int flags);
int recvfrom(int s, char *buf, int len, int flags, caddr_t from,
int *fromlen);
int recvmsg(int s, struct msghdr *msg, int flags);
DESCRIPTION
s is a socket created with socket. recv, recvfrom, and recvmsg are used
to receive messages from another socket. recv may be used only on a
connected socket [see connect(3N)], while recvfrom and recvmsg may be
used to receive data on a socket whether it is in a connected state or
not.
If from is not a NULL pointer, the source address of the message is
filled in. fromlen is a value-result parameter, initialized to the size
of the buffer associated with from, and modified on return to indicate
the actual size of the address stored there. The length of the message
is returned. If a message is too long to fit in the supplied buffer,
excess bytes may be discarded depending on the type of socket the message
is received from [see socket(3N)].
If no messages are available at the socket, the receive call waits for a
message to arrive, unless the socket is nonblocking [see fcntl(2)] in
which case -1 is returned with the external variable errno set to
EWOULDBLOCK.
The select call may be used to determine when more data arrives.
The flags parameter is formed by ORing one or more of the following:
MSGOOB Read any out-of-band data present on the socket rather than the
regular in-band data.
MSGPEEK Peek at the data present on the socket; the data is returned,
but not consumed, so that a subsequent receive operation will
see the same data.
The recvmsg() call uses a msghdr structure to minimize the number of
directly supplied parameters. This structure is defined in sys/socket.h
and includes the following members:
caddr_t msg_name; /* optional address */
int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter/gather array */
int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_accrights; /* access rights sent/received */
int msg_accrightslen;
10/89 Page 1
recv(3N) UNIX System V recv(3N)
Here msgname and msgnamelen specify the destination address if the
socket is unconnected; msgname may be given as a NULL pointer if no
names are desired or required. The msgiov and msgiovlen describe the
scatter-gather locations, as described in read. A buffer to receive any
access rights sent along with the message is specified in msgaccrights,
which has length msgaccrightslen.
RETURN VALUE
These calls return the number of bytes received, or -1 if an error
occurred.
ERRORS
The calls fail if:
EBADF s is an invalid descriptor.
ENOTSOCK s is a descriptor for a file, not a socket.
EINTR The operation was interrupted by delivery of a signal
before any data was available to be received.
EWOULDBLOCK The socket is marked non-blocking and the requested
operation would block.
ENOMEM There was insufficient user memory available for the
operation to complete.
ENOSR There were insufficient STREAMS resouces available
for the operation to complete.
SEE ALSO
connect(3N), getsockopt(3N), send(3N), socket(3N).
fcntl(2), ioctl(2), read(2) in the Programmer's Reference Manual.
NOTES
The type of address structure passed to recv depends on the address
family. UNIX domain sockets (address family AFUNIX) require a
socketaddrun structure as defined in sys/un.h; Internet domain sockets
(address family AFINET) require a sockaddrin structure as defined in
netinet/in.h. Other address families may require other structures. Use
the structure appropriate to the address family; cast the structure
address to a generic caddrt in the call to recv and pass the size of the
structure in the fromlen argument.
See ``The Sockets Interface'' section in the Programmer's Guide:
Networking Interfaces for details.
Page 2 10/89