The
mq_receive() function receives the oldest of the highest priority message(s) from the message queue specified by
mqdes. 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. Otherwise, the selected message will be removed from the queue and copied to the buffer pointed to by the
msg_ptr argument.
If the argument
msg_prio is not
NULL, the priority of the selected message will be stored in the location referenced by
msg_prio.
If the specified message queue is empty and
O_NONBLOCK is not set in the message queue description associated with
mqdes,
mq_receive() blocks until a message is enqueued on the message queue or until
mq_receive() is interrupted by a signal. If more than one thread is waiting to receive a message when a message arrives at an empty queue, then the thread of highest priority that has been waiting the longest will be selected to receive the message. If the specified message queue is empty and
O_NONBLOCK is set in the message queue description associated with
mqdes, no message will be removed from the queue, and
mq_receive() returns an error.
The timeout expires when the absolute time specified by
abs_timeout passes, as measured by the clock on which timeouts are based (that is, when the value of that clock equals or exceeds
abs_timeout), or if the absolute time specified by
abs_timeout has already been passed at the time of the call.
The resolution of the timeout is based on the CLOCK_REALTIME clock. The
timespec argument is defined in the
<time.h> header.
Under no circumstance will the operation fail with a timeout if a message can be removed from the message queue immediately. The validity of the
abs_timeout parameter will not be checked if a message can be removed from the message queue immediately.