Download RTEMS POSIX API User's Guide

Chapter 16: Message Passing Manager
259
16.4.5 mq receive - Receive a Message from a Message Queue
CALLING SEQUENCE:
#include <mqueue.h>
size_t mq_receive(
mqd_t
mqdes,
char
*msg_ptr,
size_t
msg_len,
unsigned int *msg_prio
);
STATUS CODES:
EBADF - The descriptor does not represent a valid message queue, or the queue was opened
for write only O WRONLY EMSGSIZE - The msg len is less than the mq msgsize attribute
of the message queue EAGAIN - The message queue is non-blocking, and the queue is empty
EINTR - The message queue is blocking. While the process was waiting for a message to
arrive on the queue, a signal arrived that interrupted the wait.
DESCRIPTION:
The mq receive function is used to receive the oldest of the highest priority message(s) from
the message queue specified by mqdes. The messages are received in FIFO order within
the priorities. The received message’s priority is stored in the location referenced by the
msg prio. If the msg prio is a NULL, the priority is discarded. The message is removed
and stored in an area pointed to by msg ptr whose length is of msg len. The msg len must
be at least equal to the mq msgsize attribute of the message queue.
The blocking behavior of the message queue is set by O NONBLOCK at mq open or by
setting O NONBLOCK in mq flags in a call to mq setattr. If this is a blocking queue, the
process blocks and waits on an empty queue. If this a non-blocking queue, the process does
not block.
Upon successful completion, mq receive returns the length of the selected message in bytes
and the message is removed from the queue. Otherwise, no message is removed from the
queue, the function returns a value of -1, and sets errno to indicate the error.
NOTES:
If the size of the buffer in bytes, specified by the msg len argument, is less than the
mq msgsize attribute of the message queue, the function fails and returns an error