mmssggrrccvv() -- General Function (libc)

Receive a message
#iinncclluuddee <ssyyss/ttyyppeess.hh>
#iinncclluuddee <ssyyss/iippcc.hh>
#iinncclluuddee <ssyyss/mmssgg.hh>
mmssggrrccvv(_i_d, _b_u_f_f_e_r, _s_i_z_e, _t_y_p_e, _f_l_a_g)
iinntt _i_d, _s_i_z_e, _f_l_a_g; lloonngg *_b_u_f_f_e_r; lloonngg _t_y_p_e;

The  function  mmssggrrccvv() reads  a  message from  the  queue associated  with
identifier _i_d, and writes it into the user-defined chunk of memory to which
_b_u_f_f_e_r points.  The memory to which _b_u_f_f_e_r points has a layout similar to a
structure with the following members (if we pretend mmtteexxtt[] is legal C):

struct msgbuf {
     long mtype;            /* message type */
     char mtext[];          /* message text */
};

mmttyyppee gives the message's type, as specified by the sending process.  mmtteexxtt
gives the text of the message.

_s_i_z_e gives  the size  of the message's  text, in bytes.   mmssggrrccvv() silently
truncates the received message to _s_i_z_e  if it more than _s_i_z_e bytes long and
(_f_l_a_g & MMSSGG_NNOOEERRRROORR) is true.

_t_y_p_e gives the type of message being requested.  mmssggrrccvv obeys the following
rules when it reads the message queue:

-> If _t_y_p_e equals 00LL, it reads the first message in the queue.

-> If _t_y_p_e is greater than 00LL, it reads the first message of _t_y_p_e.

-> If _t_y_p_e is  less than 00LL, it reads the  first message whose type is less
   than or equal to the absolute value of _t_y_p_e.

If the  message queue contains no  message of the desired,  the behavior of
mmssggrrccvv() is  determined by the  value of _f_l_a_g.  If _f_l_a_g contains  the value
IIPPCC_NNOOWWAAIITT (i.e.,  _f_l_a_g & IIPPCC_NNOOWWAAIITT  is true) then mmssggrrccvv()  sets eerrrrnnoo to
EEAAGGAAIINN and returns -1.  If, however, _f_l_a_g does not contain IIPPCC_NNOOWWAAIITT, then
mmssggrrccvv() suspends execution until one of the following occurs:

11. A message of the desired type appears on the queue.

22. _i_d is removed from the system.   mmssggrrccvv() sets eerrrrnnoo to EEDDOOMM and returns
   -1.

33. The calling process receives a signal.  mmssggrrccvv() sets eerrrrnnoo to EEIINNTTRR and
   returns -1.  The calling process then resumes execution in the manner by
   signal received.   For information on  what given signals  mean, see the
   Lexicon entry for ssiiggnnaall().

mmssggrrccvv() also fails and returns no message if any of the following is true:

-> _i_d  is  not a  valid  message-queue identifier.   mmssggrrccvv  sets eerrrrnnoo  to
   EEIINNVVAALL.

-> The calling process lacks operation permission (EEAACCCCEESS).

-> _s_i_z_e is less than zero (EEIINNVVAALL).

-> The  message's  size  is  greater  than  _s_i_z_e bytes  long  and  (_f_l_a_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 _t_y_p_e  and (_f_l_a_g &
   IIPPCC_NNOOWWAAIITT) is true (EEAAGGAAIINN).

-> _b_u_f_f_e_r points to an illegal address (EEFFAAUULLTT).

When mmssggrrccvv()  has successfully received its message,  it modifies the data
structure associated with _i_d in the following ways:

-> It decrements field mmssgg_qqnnuumm by one.

-> It sets mmssgg_llrrppiidd to the identifier of the process that called mmssggrrccvv().

-> It sets mmssgg_rrttiimmee to the current time.

When  it  completes  successfully, mmssggrrccvv()  returns  the  number of  bytes
written into the field mmtteexxtt of the structure pointed to by _b_u_f_f_e_r.

_E_x_a_m_p_l_e
For an example of this function, see the Lexicon entry for mmssggggeett().

_F_i_l_e_s
/uussrr/iinncclluuddee/ssyyss/iippcc.hh
/uussrr/iinncclluuddee/ssyyss/mmssgg.hh

_S_e_e _A_l_s_o
lliibbcc, mmssggccttll(), mmssggggeett(), mmssggssnndd()
