msgrcv() -- General Function (libc)

Receive a message
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
msgrcv(id, buffer, size, type, flag)
int id, size, flag; long *buffer; long type;

The  function  msgrcv() reads  a  message from  the  queue associated  with
identifier id, and writes it into the user-defined chunk of memory to which
buffer points.  The memory to which buffer points has a layout similar to a
structure with the following members (if we pretend mtext[] is legal C):

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

mtype gives the message's type, as specified by the sending process.  mtext
gives the text of the message.

size gives  the size  of the message's  text, in bytes.   msgrcv() silently
truncates the received message to size  if it more than size bytes long and
(flag &amp; MSG_NOERROR) is true.

type gives the type of message being requested.  msgrcv obeys the following
rules when it reads the message queue:

-> If type equals 0L, it reads the first message in the queue.

-> If type is greater than 0L, it reads the first message of type.

-> If type is  less than 0L, it reads the  first message whose type is less
   than or equal to the absolute value of type.

If the message queue contains no  message of the desired type, the behavior
of msgrcv() is determined by the  value of flag. If flag contains the value
IPC_NOWAIT (i.e.,  flag &amp; IPC_NOWAIT is true)  then msgrcv() sets errno
to ENOMSG  and returns -1.  If, however, flag  does not contain IPC_NOWAIT,
then msgrcv() suspends execution until one of the following occurs:

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

2. id is removed from the system.  msgrcv() sets errno to EIDRM and returns
   -1.

3. The calling process receives a signal.  msgrcv() sets errno to EINTR 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 signal().

msgrcv() also fails and returns no message if any of the following is true:

-> id  is  not a  valid  message-queue identifier.   msgrcv  sets errno  to
   EINVAL.

-> The calling process lacks operation permission (EACCES).

-> size is less than zero (EINVAL).

-> The  message's size  is greater  than  size bytes  long and  (flag &amp;
   MSG_NOERROR) is false (E2BIG).

-> buffer points to an illegal address (EFAULT).

When msgrcv()  has successfully received its message,  it modifies the data
structure associated with id in the following ways:

-> It decrements field msg_qnum by one.

-> It sets msg_lrpid to the identifier of the process that called msgrcv().

-> It sets msg_rtime to the current time.

When  it  completes  successfully, msgrcv()  returns  the  number of  bytes
written into the field mtext of the structure pointed to by buffer.

Example

For an example of this function, see the Lexicon entry for msgget().

Files

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

See Also

libc,
msgctl(),
msgget(),
msgsnd()

© 2012 by Stephen A. Ness