4.3BSD-UWisc/man/cat2/recv.2

RECV(2)             UNIX Programmer's Manual              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 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.

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



Printed 12/27/86          May 23, 1986                          1






RECV(2)             UNIX Programmer's Manual              RECV(2)



          #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 loca-
     tions, 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 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.

SEE ALSO
     fcntl(2), read(2), send(2), select(2), getsockopt(2),
     socket(2)




Printed 12/27/86          May 23, 1986                          2