'\"macro stdmacro
.if n .pH g3n.recv @(#)recv	40.10 of 1/29/90
.\" Copyright 1989 AT&T
.hw EWOULDBLOCK
.nr X
.if \nX=0 .ds x} recv 3N "" "\&"
.if \nX=1 .ds x} recv 3N ""
.if \nX=2 .ds x} recv 3N "" "\&"
.if \nX=3 .ds x} recv "" "" "\&"
.TH \*(x}
.SH NAME
\f4recv, recvfrom, recvmsg\fP \- receive a message from a socket
.SH SYNOPSIS
.nf
.ft CW
#include <sys/types.h>
#include <sys/socket.h>
.LP
.ft CW
int recv(s, buf, len, flags)
int s;
char \(**buf;
int len, flags;
.LP
.ft CW
int recvfrom(s, buf, len, flags, from, fromlen)
int s;
char \(**buf;
int len, flags;
struct sockaddr \(**from;
int \(**fromlen;
.LP
.ft CW
int recvmsg(s, msg, flags)
int s;
struct msghdr \(**msg;
int flags;
.ft R
.fi
.SH DESCRIPTION
.LP
.I s
is a socket created with \f4socket\f1(3N).
\f4recv()\f1, \f4recvfrom()\f1, and \f4recvmsg()\f1
are used to receive messages from another socket.
\f4recv()\f1 may be used only on a
.I connected
socket (see \f4connect\f1(3N)), while \f4recvfrom()\f1 and
\f4recvmsg()\f1 may be used to receive data on a socket whether
it is in a connected state or not.
.LP
If
.I from
is not a
.SM NULL
pointer, the source address of the message is filled in.
.I fromlen
is a value-result parameter, initialized to the size of
the buffer associated with
.IR 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 \f4socket\f1(3N)).
.LP
If no messages are available at the socket, the
receive call waits for a message to arrive, unless
the socket is nonblocking (see \f4fcntl\f1(2))
in which case \f4-1\fP is returned with the external variable
\f4errno\f1 set to
\f4EWOULDBLOCK\f1.
.LP
The \f4select()\f1
call may be used to determine when more data arrives.
.LP
The
.I flags
parameter is formed by
.SM OR\s0ing
one or more of the following:
.TP 1i
\f4MSG_OOB\f1
Read any \(lqout-of-band\(rq data present on the
socket rather than the regular \(lqin-band\(rq data.
.TP
\f4MSG_PEEK\f1
\(lqPeek\(rq 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.
.LP
The \f4recvmsg()\f1 call uses a \f4msghdr\fP
structure to minimize the number of directly supplied parameters.
This structure is defined in \f4/usr/include/sys/socket.h\f1
and includes the following members:
.LP
.RS
.nf
.ft CW
.ta +\w'struct iovec\0'u +\w'msg_accrightslen;\0'u
\s-1caddr_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;\f1
.ft P
.fi
.DT
.RE
.LP
Here
\f4msg_name\fP
and
\f4msg_namelen\fP
specify the destination address if the socket is unconnected;
\f4msg_name\fP
may be given as a
.SM NULL
pointer if no names are desired or required.
The
\f4msg_iov\fP
and
\f4msg_iovlen\fP
describe the scatter-gather locations, as described in
\f4read\fP(2).
A buffer to receive any access rights sent along with the message is specified
in
\f4msg_accrights\fP,
which has length
\f4msg_accrightslen\fP.
.SH RETURN VALUE
.LP
These calls return the number of bytes received,
or \f4-1\fP if an error occurred.
.SH ERRORS
.LP
The calls fail if:
.TP 20
\f4EBADF\f1
.I s
is an invalid descriptor.
.TP
\f4ENOTSOCK\f1
.I s
is a descriptor for a file, not a socket.
.TP
\f4EINTR\f1
The operation was interrupted by delivery of a signal before
any data was available to be received.
.\".TP
.\".SM EFAULT
.\"The data was specified to be received into a non-existent
.\"or protected part of the process address space.
.TP
\f4EWOULDBLOCK\f1
The socket is marked non-blocking and the requested operation
would block.
.TP
\f4ENOMEM\f1
There was insufficient user memory available for the operation to
complete.
.TP
\f4ENOSR\f1
There were insufficient
.SM STREAMS
resouces available for the operation
to complete.
.SH SEE ALSO
\f4connect\f1(3N),
\f4fcntl\f1(2),
\f4getsockopt\f1(3N),
\f4ioctl\f1(2),
\f4read\f1(2),
.\"\f4select\f1(3),
\f4send\f1(3N),
\f4socket\f1(3N).
