mq_receive(3c)

NAME
     mq_receive - receive a message from a queue

C SYNOPSIS
     #include <mqueue.h>

     int mq_receive (mqd_t mqd, char *msgptr, size_t msglen, unsigned int
     *msgprio);

DESCRIPTION
     mq_receive removes a message, of size msglen bytes, from the message
     queue named by the mqd descriptor, and copies it to the buffer at address
     msgptr.

     Messages are removed in priority order with higher priority messages
     removed before the lower priority messages. The larger the numerical
     value of the priority, the more important the message.  If the argument
     msgprio is not NULL, the priority of the message removed is stored at
     address msgprio.  Messages of equal priority are removed in FIFO order.

     If the O_NONBLOCK flag is set for the mdq message queue descriptor,
     mq_receive will not block when the queue is empty [see mq_setattr(3c)].
     Otherwise, mq_receive will block until either a message is present in the
     queue, or mq_receive is interrupted by a signal.

     If multiple processes are waiting to receive a message from the queue,
     the highest priority process will receive the message when it is
     delivered.  Processes with equal priorities, blocked waiting for
     messages, are unblocked in FIFO order when messages arrive.

     mq_receive will fail if one or more of the following conditions are true:

     [EAGAIN]       The O_NONBLOCK flag is set for the mqd queue descriptor
                    and the queue is empty.

     [EBADF]        The message queue descriptor, mqd, is not valid or the
                    queue was not opened for reading.

     [EINTR]        The mq_receive system call was interrupted by a signal.

     [EMSGSIZE]     The size of the buffer, msglen, is less than the value of
                    the mq_maxsize attribute of the queue.

SEE ALSO
     mq_open(3c), intro(3c), mq_unlink(3c), mq_send(3c), mq_getattr(3c),
     mq_notify(3c)

DIAGNOSTICS
     Upon successful completion, mq_receive returns the number of bytes in the
     message received, with the message copied to the buffer pointed to by
     msgptr and the priority of the message stored in the location pointed to
     by msgprio.  Otherwise, no message is removed from the queue and a value
     of -1 is returned and errno is set to indicate the error.