4.3BSD-Tahoe/usr/man/cat2/recvmsg.0

RECV(2)             UNIX Programmer's Manual		  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, _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 7/9/88		  July 21, 1987                         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 iinntt.  If access rights are not being
     transferred, the _m_s_g__a_c_c_r_i_g_h_t_s field should be set to NULL.

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/9/88		  July 21, 1987                         2