RTEMS 4.7.2 On-Line Library

Message Passing Manager mq_receive - Receive a Message from a Message Queue

RTEMS POSIX API User's Guide

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

RTEMS POSIX API User's Guide