mq_clockreceive()

Receive a message from a message queue with a timeout measured against a specific clock

Synopsis:

#include <mqueue.h>
#include <time.h>
  
ssize_t mq_clockreceive(
                mqd_t mqdes, 
                char *msg_ptr, 
                size_t msg_len,
                unsigned *msg_prio,
                clockid_t clk,
                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.
clk: The clock against which the time limit is measured. The clock source is specified using the clk variable. The clk variable must be set to either CLOCK_REALTIME, CLOCK_ SOFTTIME or CLOCK_MONOTONIC.
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 that uses the mq server and a queue in kernel space, libmq:
Use the -l mq option to qcc to link against this library.

Description:

The mq_clockreceive() function receives the oldest of the highest priority messages in the queue specified by mqdes.

Note: The message queue manager needs to be running. QNX Neutrino supports two implementations of message queues: a traditional implementation, and an alternate one that uses the mq server and a queue in kernel space. For more information, see the entries for mq and mqueue in the Utilities Reference, as well as the POSIX Message Queues: Two Implementations technote.

If you call mq_clockreceive() with a msg_len of anything other than the mq_msgsize of the specified queue, then mq_clockreceive() 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_clockreceive() call blocks. If multiple mq_clockreceive() calls are blocked on a single queue, then they're unblocked in FIFO order as messages arrive.

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 clock is used in a context which does not make sense for a timeout; for example, when using CLOCK_THREAD_CPUTIME_ID.
The use of the clock as a timeout is not supported; for example, when using another thread's CPUTIME clock.
The clock does not exist.
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.

Classification:

POSIX 1003.1

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes