mq_timedreceive(), mq_timedreceive_monotonic()

Receive a message from a message queue

Synopsis:

#include <mqueue.h>
#include <time.h>

ssize_t mq_timedreceive( 
                mqd_t mqdes,
                char * msg_ptr, 
                size_t msg_len,
                unsigned int * msg_prio,
                const struct timespec * abs_timeout );

ssize_t mq_timedreceive_monotonic( 
                mqd_t mqdes,
                char * msg_ptr, 
                size_t msg_len,
                unsigned int * msg_prio,
                const struct timespec * abs_timeout );

Arguments:

mqdes

The descriptor of the message queue you want to receive a message from, returned by mq_open().

msg_ptr

A pointer to a buffer where the function can store the message data.

msg_len

The size of the buffer, in bytes.

msg_prio

NULL, or a pointer to a location where the function can store the priority of the message that it removed from the queue.

abs_timeout

A pointer to a timespec structure that specifies the absolute time (not the relative time to the current time) to wait before the function stops trying to receive messages.

Library:

• For the traditional implementation, libc

  Use the -l c option to qcc to link against this library. This library is usually included automatically.

• For the alternate implementation using asynchronous messages, libmq

  Use the -l mq option to qcc to link against this library.

Description:

The mq_timedreceive() function receives the oldest of the highest priority messages in the queue specified by mqdes. The mq_timedreceive_monotonic() function is a QNX Neutrino extension; it's similar to mq_timedreceive(), but it uses CLOCK_MONOTONIC, so the timeout isn't affected by changes to the system time.

---

Neutrino supports two implementations of message queues: a traditional implementation, and an alternate one that uses asynchronous messages. For more information, see the entries for mq and mqueue in the Utilities Reference, as well as the Managing POSIX Message Queues technote.

---

If you call mq_timedreceive() with a msg_len of anything other than the mq_msgsize of the specified queue, then mq_timedreceive() returns an error, and errno is set to EINVAL.

If there are no messages on the queue specified, and O_NONBLOCK wasn't set (in the oflag argument to mq_open()), then the mq_timedreceive() call blocks. If multiple mq_timedreceive() calls are blocked on a single queue, then they're unblocked in FIFO order as messages arrive.

In the traditional (mqueue) implementation, calling read() with mqdes is analogous to calling mq_timedreceive() with a NULL msg_prio.

Returns:

The size of the message removed from the queue, or -1 if an error occurred (no message is removed from the queue, and errno is set).

Errors:

EAGAIN

The O_NONBLOCK flag was set and there are no messages currently on the specified queue.

EBADF

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

EINTR

The operation was interrupted by a signal.

EINVAL

One of the following:

• The msg_ptr argument isn't a valid pointer, or msg_len is less than 0, or msg_len is less than the message size specified in mq_open(). The default message size is 4096 bytes.
• The process or thread would have blocked, and the abs_timeout parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.

EMSGSIZE

The given msg_len is shorter than the mq_msgsize for the given queue or the given msg_len is too short for the message that would have been received.

ETIMEDOUT

The timeout value was exceeded.

Examples:

Specify an absolute timeout of 1 second:

struct   timespec tm;

clock_gettime(CLOCK_REALTIME, &tm);
tm.tv_sec += 1;
if( 0 > mq_timedreceive( fd, buf, 4096, NULL,  &tm ) )  {
  ...
}

Classification:

mq_timedreceive() is POSIX 1003.1 MSG; mq_timedreceive_monotonic() is QNX Neutrino

See also:

mq_close(), mq_open(), mq_receive(), mq_send(), mq_timedsend(), timespec

mq, mqueue in the Utilities Reference

Managing POSIX Message Queues technote.