mq_receive

receive a message from a queue

Synopsis:

#include <mqueue.h>
int mq_receive (mqd_t mqdes, 
                char *msg_ptr, 
                size_t msg_len, 
                unsigned int *msg_prio);

Description:

The mq_receive() function is used to receive the oldest of the highest priority messages in the queue specified by mqdes. The priority of the message received is put in the location pointed to by msg_prio, the data itself in the location pointed to by msg_ptr, and the size received is returned.

If mq_receive() is called with a msg_len of anything other than the mq_msgsize of the specified queue, and the QNX extended option MQ_READBUF_DYNAMIC hasn't been set in the queue's mq_flags, then mq_receive() returns an error, and errno is set to EINVAL.

The mq_receive() call blocks if all the following occur:

• there are no messages on the queue specified
• O_NONBLOCK wasn't set in oflag during mq_open()
• MQ_NONBLOCK isn't present in the queue's mq_flags

If multiple mq_receive() calls are blocked on a single queue, then they're unblocked in FIFO order as messages arrive.

If msg_prio isn't NULL, then the location it references is used to store the priority of the message removed from the queue.

Calling read() with an file descriptor that represents a message queue is analogous to calling mq_receive() with a NULL msg_prio.

Returns:

Upon successful completion, mq_receive() returns the size of the message removed from the queue specified. If the call fails, it returns -1 as the size, no message is removed from the queue, and errno is set.

Errors:

EAGAIN

O_NONBLOCK or MQ_NONBLOCK was set and there are no messages currently on the specified queue.

EBADF

mqdes doesn't represent a valid queue open for reading.

EMSGSIZE

This value indicates one of the following:

• the QNX extended option MQ_READBUF_DYNAMIC hasn't been set, and the given msg_len is shorter than the mq_msgsize for the given queue
• the extended option MQ_READBUF_DYNAMIC has been set, but the given msg_len is too short for the message that would have been received

EINTR

The operation was interrupted by a signal.

See also:

errno, mq_close(), mq_getattr(), mq_notify(), mq_open(), mq_send(), mq_setattr(), mq_unlink(), read()

Classification:

POSIX 1003.4

Systems:

QNX