Receives a message from a message queue.
Standard C Library (libc.a)
#include <mqueue.h>
ssize_t mq_receive (mqdes, msg_ptr, msg_len, msg_prio)
mqd_t mqdes;
char *msg_ptr;
size_t msg_len;
unsigned *msg_prio;The mq_receive subroutine receives the oldest of the highest priority messages from the message queue specified by the mqdes parameter. If the size of the buffer in bytes, specified by the msg_len parameter, is less than the mq_msgsize attribute of the message queue, the subroutine fails and returns an error. Otherwise, the selected message is removed from the queue and copied to the buffer pointed to by the msg_ptr parameter.
If the msg_prio parameter is not NULL, the priority of the selected message is stored in the location referenced by msg_prio.
If the specified message queue is empty and the O_NONBLOCK flag is not set in the message queue description associated with the mqdes parameter, the mq_receive subroutine 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 and the Priority Scheduling option is supported, the thread of highest priority that has been waiting the longest is selected to receive the message. If the specified message queue is empty and the O_NONBLOCK flag is set in the message queue description associated with the mqdes parameter, no message is removed from the queue, and the mq_receive subroutine returns an error.
| Item | Description |
|---|---|
| mqdes | Specifies the message queue descriptor. |
| msg_ptr | Points to the buffer where the message is copied. |
| msg_len | Specifies the length of the message, in bytes. |
| msg_prio | Stores the priority of the selected message. |
Upon successful completion, the mq_receive subroutine 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, and the subroutine returns -1 and sets errno to indicate the error.
| Item | Description |
|---|---|
| EAGAIN | The O_NONBLOCK flag was set in the message description associated with the mqdes parameter, and the specified message queue is empty. |
| EBADF | The mqdes parameter is not a valid message queue descriptor open for reading. |
| EFAULT | Invalid used address. |
| EIDRM | The specified message queue was removed during the required operation. |
| EINTR | The mq_receive subroutine was interrupted by a signal. |
| EINVAL | The msg_ptr parameter is null. |
| EMSGSIZE | The specified message buffer size, msg_len, is less than the message size attribute of the message queue. |
| ENOMEM | Insufficient memory for the required operation. |
| ENOTSUP | This function is not supported with processes that have been checkpoint-restart'ed. |