libc/sys/recv.2

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

cc = recv(s, buf, len, flags)
int cc, s;
char *buf;
int len, flags;

cc = recvfrom(s, buf, len, flags, from, fromlen)
int cc, s;
char *buf;
int len, flags;
struct sockaddr *from;
int *fromlen;

cc = recvmsg(s, msg, flags)
int cc, s;
struct msghdr msg[];
int flags;
 DESCRIPTION
 Recv ,  recvfrom , and
 recvmsg are used to receive messages from a socket.

The
 recv call is normally used only on a
 connected socket (see
 connect (2)), 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 non-zero, 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 in
 cc . 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 (2).
If no messages are available at the socket, the
receive call waits for a message to arrive, unless
the socket is nonblocking (see
 ioctl (2)) in which case a
 cc of -1 is returned with the external variable errno
set to EWOULDBLOCK.

The
 select (2) call may be used to determine when more data arrives.

The
 flags argument to a recv call is formed by
 or 'ing one or more of the values,


#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_PEEK 0x2 /* peek at incoming message */


The
 recvmsg call uses a
 msghdr structure to minimize the number of directly supplied parameters.
This structure has the following form, as defined in
 <sys/socket.h> :


struct msghdr {
 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;
};


Here
 msg_name and
 msg_namelen specify the destination address if the socket is unconnected;
 msg_name may be given as a null pointer if no names are desired or required.
The
 msg_iov and
 msg_iovlen describe the scatter gather locations, as described in
 read (2). A buffer to receive any access rights sent along with the message is specified
in
 msg_accrights , which has length
 msg_accrightslen . Access rights are currently limited to file descriptors,
which each occupy the size of an
 int .  "RETURN VALUE
These calls return the number of bytes received, or -1
if an error occurred.
 ERRORS
The calls fail if:
 20
[EBADF]
The argument s is an invalid descriptor.
 20
[ENOTSOCK]
The argument s is not a socket.
 20
[EWOULDBLOCK]
The socket is marked non-blocking and the receive operation
would block.
 20
[EINTR]
The receive was interrupted by delivery of a signal before
any data was available for the receive.
 20
[EFAULT]
The data was specified to be received into a non-existent
or protected part of the process address space.
 SEE ALSO
fcntl(2), read(2), send(2), select(2), getsockopt(2), socket(2)