RECV(2)                                                                RECV(2)



NAME
       recv, recvfrom, recvmsg - receive a message from a socket

SYNOPSIS
       #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
       _R_e_c_v, _r_e_c_v_f_r_o_m, and _r_e_c_v_m_s_g are used to receive messages from a socket.

       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)),  while  _r_e_c_v_f_r_o_m and _r_e_c_v_m_s_g 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 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 nonblocking (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.

       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 */

       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 */
                   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 _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 locations, as described in _r_e_a_d(2).  A buffer to receive
       any  access  rights  sent  along  with  the  message  is  specified  in
       _m_s_g__a_c_c_r_i_g_h_t_s,  which  has  length _m_s_g__a_c_c_r_i_g_h_t_s_l_e_n.  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:

       [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]            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)



4.2 Berkeley Distribution        May 23, 1986                          RECV(2)