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 entry for mq and mqueue in the Utilities Reference.

---

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