2.11BSD/man/cat2/recv.0

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 11/26/99	  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 11/26/99	  May 23, 1986				2