mq_clocksend()

Send a message to a message queue with a timeout measured against a specific clock

Synopsis:

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

int mq_clocksend(
                mqd_t mqdes, 
                const 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 put the message into, returned by mq_open().
msg_ptr: A pointer to the message data.
msg_len: The size of the buffer, in bytes.
msg_prio: The priority of the message, in the range from 0 through (MQ_PRIO_MAX - 1).
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 send 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_clocksend() function puts a message of size msg_len and pointed to by msg_ptr into the queue indicated by mqdes. The new message has a priority of msg_prio.

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.

The queue maintained is in priority order, and in FIFO order within the same priority.

If the number of elements on the specified queue is equal to its mq_maxmsg, and O_NONBLOCK wasn't set (in the oflag argument to mq_open()), the call to mq_clocksend() blocks. It becomes unblocked when there's room on the queue to send the given message. If more than one mq_clocksend() is blocked on a given queue, and space becomes available in that queue to send, then the mq_clocksend() with the highest priority message is unblocked.

Returns:

-1 if an error occurred (errno is set). Any other value indicates success.

Errors:

EAGAIN

The O_NONBLOCK flag was set when opening the queue, and the specified queue is full.

EBADF

The mqdes argument doesn't represent a valid message queue descriptor, or mqdes isn't opened for writing.

EINTR

The call was interrupted by a signal.

EINVAL

One of the following is true:

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 value of msg_prio is greater than (MQ_PRIO_MAX - 1).
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 msg_len argument is greater than the msgsize associated with the specified queue.

ETIMEDOUT

The timeout value was exceeded.

Classification:

POSIX 1003.1

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