4.3BSD-Reno/share/man/cat2/recvmsg.0
RECV(2) 1990 RECV(2)
NNAAMMEE
recv, recvfrom, recvmsg - receive a message from a socket
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
##iinncclluuddee <<ssyyss//ssoocckkeett..hh>>
cccc == rreeccvv((ss,, bbuuff,, lleenn,, ffllaaggss))
iinntt cccc,, ss;;
cchhaarr **bbuuff;;
iinntt lleenn,, ffllaaggss;;
cccc == rreeccvvffrroomm((ss,, bbuuff,, lleenn,, ffllaaggss,, ffrroomm,, ffrroommlleenn))
iinntt cccc,, ss;;
cchhaarr **bbuuff;;
iinntt lleenn,, ffllaaggss;;
ssttrruucctt ssoocckkaaddddrr **ffrroomm;;
iinntt **ffrroommlleenn;;
cccc == rreeccvvmmssgg((ss,, mmssgg,, ffllaaggss))
iinntt cccc,, ss;;
ssttrruucctt mmssgghhddrr **mmssgg;;
iinntt ffllaaggss;;
DDEESSCCRRIIPPTTIIOONN
_R_e_c_v_f_r_o_m, and _r_e_c_v_m_s_g are used to receive messages from a
socket, and may be used to receive data on a socket whether
it is in a connected state or not.
If _f_r_o_m is non-zero, the source address of the message is
filled in. _F_r_o_m_l_e_n is a value-result parameter, initialized
to the size of the buffer associated with _f_r_o_m, and modified
on return to indicate the actual size of the address stored
there.
The _r_e_c_v call is normally used only on a _c_o_n_n_e_c_t_e_d socket
(see _c_o_n_n_e_c_t(2)) and is identitical to _r_e_c_f_r_o_m with a zero-
valued _f_r_o_m_l_e_n parameter. As it is redundant, it may not be
supported in future releases.
The length of the message is returned in _c_c. 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 _s_o_c_k_e_t(2)).
If no messages are available at the socket, the receive call
waits for a message to arrive, unless the socket is non-
blocking (see _i_o_c_t_l(2)) in which case a _c_c of -1 is returned
with the external variable errno set to EWOULDBLOCK.
The _s_e_l_e_c_t(2) call may be used to determine when more data
arrives.
Printed 7/27/90 May 1
RECV(2) 1990 RECV(2)
The _f_l_a_g_s argument to a recv call is formed by _o_r'ing one or
more of the values,
#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_PEEK 0x2 /* peek at incoming message */
#define MSG_DONTROUTE 0x4 /* send without using routing tables */
#define MSG_EOR 0x8 /* data completes record */
#define MSG_TRUNC 0x10 /* data discarded before delivery */
#define MSG_CTRUNC 0x20 /* control data lost before delivery */
The _r_e_c_v_m_s_g call uses a _m_s_g_h_d_r structure to minimize the
number of directly supplied parameters. This structure has
the following form, as defined in <_s_y_s/_s_o_c_k_e_t._h>:
struct msghdr {
caddr_t msg_name; /* optional address */
u_int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter/gather array */
u_int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_control; /* ancillary data, see below */
u_int msg_controllen; /* ancillary data buffer len */
int msg_flags; /* flags on received message */
};
Here _m_s_g__n_a_m_e and _m_s_g__n_a_m_e_l_e_n specify the destination
address if the socket is unconnected; _m_s_g__n_a_m_e may be given
as a null pointer if no names are desired or required. The
_m_s_g__i_o_v and _m_s_g__i_o_v_l_e_n describe the scatter gather loca-
tions, as described in _r_e_a_d(2). _m_s_g__c_o_n_t_r_o_l, which has
length _m_s_g__c_o_n_t_r_o_l_l_e_n. This is a buffer for other protocol
control related messages or other miscellaneous ancillary
data. The messages are of the form:
struct cmsghdr {
u_int cmsg_len; /* data byte count, including hdr */
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */
/* followed by
u_char cmsg_data[]; */
};
As an example, one could use this to learn of changes in the
data-stream in XNS/SPP, or in ISO, to obtain user-
connection-request data by requesting a recvmsg with no uio
provided immediately after an _a_c_c_e_p_t(), thought of here in
the sense of get-next-connection-request without an implicit
connection confirmation.
Open file descriptors are now passed as ancillary data for
AF_UNIX domain sockets, with cmsg_level being SOL_SOCKET and
cmsg_type being SCM_RIGHTS.
Printed 7/27/90 May 2
RECV(2) 1990 RECV(2)
_m_s_g__f_l_a_g_s is set on return in a way that may include some of
the same values specified for the flags parameter to a recv
system call. The returned values MSG_EOR indicates end-of-
record, MSG_TRUNC indicates that some trailing datagram data
was discarded, MSG_CTRUNC indicates that some control data
was discarded due to lack of space. MSG_OOB is returned to
indicate that expedited data was received.
RREETTUURRNN VVAALLUUEE
These calls return the number of bytes received, or -1 if an
error occurred.
EERRRROORRSS
The calls 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 avail-
able for the receive.
[EFAULT] The data was specified to be received
into a non-existent or protected part of
the process address space.
SSEEEE AALLSSOO
fcntl(2), read(2), send(2), select(2), getsockopt(2),
socket(2)
Printed 7/27/90 May 3