

msgrcv()               COHERENT System Call              msgrcv()




Receive a message

#include <sys/msg.h>
mmssggrrccvv(_m_s_q_i_d, _m_s_g_p, _m_s_g_s_z, _m_s_g_t_y_p, _m_s_g_f_l_g)
iinntt _m_s_q_i_d, _m_s_g_s_z, _m_s_g_f_l_g; ssttrruucctt mmssggbbuuff *_m_s_g_p; lloonngg _m_s_g_t_y_p;

msgrcv reads  a message from the queue  associated with the queue
identifier msqid  and writes  it in  the structure pointed  to by
msgp.  This structure consists of the following members:


long mtype;    /* message type */
char mtext[];  /* message text */


mtype is the received message's type, as specified by the sending
process.  mtext is the text of the message.  msgsz gives the size
of mtext,  in bytes.  The received message  is truncated to msgsz
bytes if  it is larger  than msgsz and (_m_s_g_f_l_g  & MMSSGG_NNOOEERRRROORR) is
true.  The truncated portion of  the message is lost, with no in-
dication given to the calling process.

msgtyp specifies the type of message requested, as follows:

*   If  msgtyp equals  0L,  the  first message  on  the queue  is
   received.

*  If msgtyp is greater than 0L, the first message of type msgtyp
   is received.

*  If  msgtyp is less  than 0L, the  first message of  the lowest
   type  that is  less than  or  equal to  the absolute  value of
   msgtyp is received.

msgflg specifies  the action  taken if  a message of  the desired
type is not on the queue, as follows:

*   If (_m_s_g_f_l_g  & IIPPCC_NNOOWWAAIITT)  is true,  the calling  process im-
   mediately returns -1 and sets errno to ENOMSG.

*   If  (_m_s_g_f_l_g  &  IIPPCC_NNOOWWAAIITT)  is  false, the  calling  process
   suspends execution until one of the following occurs:

11. A message of the desired type is placed on the queue.

22. msqid  is removed from  the system.  When  this occurs, msgrcv
   sets errno to EDOM

33. The  calling process receives  a signal that is  to be caught.
   In  this  case, a  message  is not  received  and the  calling
   process resumes execution in the manner prescribed in signal.

msgrcv fails  and no message is received if  any of the following
is true:


COHERENT Lexicon                                           Page 1




msgrcv()               COHERENT System Call              msgrcv()




*  msqid  is not a valid message  queue identifier.  msgrcv errno
   to EINVAL.

*   Operation  permission   is  denied  to  the  calling  process
   (EEAACCCCEESS).

*  msgsz is less than zero (EEIINNVVAALL).

*   mtext is  greater than  msgsz and  (_m_s_g_f_l_g &  MMSSGG_NNOOEERRRROORR) is
   false (EE22BBIIGG).

*  The queue  does not contain a message of  the desired type and
   (_m_s_g_t_y_p & IIPPCC_NNOOWWAAIITT) is true (EENNOOMMSSGG).

*  msgp points to an illegal address (EEFFAAUULLTT).

Upon successful completion,  the following actions are taken with
respect to the data structure associated with msqid:

*  msg_qnum is decremented by one.

*   msg_lrpid  is set  equal  to the  process  identifier of  the
   calling process.

*  msg_rtime is set equal to the current time.

***** Return Values *****

If msgrcv returns  due to the receipt of a  signal, it returns -1
and sets  errno to EINTR.   If it returns  due to the  removal of
msqid  from the  system, it  returns -1 and  sets errno  to EDOM.
Upon successful  completion, msgrcv returns a  value equal to the
number of bytes written into mtext.  Otherwise, it returns -1 and
sets errno to an appropriate value.

***** Files *****

/usr/include/sys/ipc.h
/usr/include/sys/msg.h
/dev/msg

***** See Also *****

COHERENT system calls, msg, msgctl(), msgget(), msgsnd()

***** Notes *****

To improve portability, the COHERENT system implements the mmssgg as
a device driver rather than as an actual system call.







COHERENT Lexicon                                           Page 2


