mq_timedsend(), mq_timedsend_monotonic()

Send a message to a message queue

Synopsis:

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

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

int mq_timedsend_monotonic(
                  mqd_t mqdes, 
                  const 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 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 to (MQ_PRIO_MAX-1).

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_timedsend() 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. The mq_timedsend_monotonic() function is a QNX Neutrino extension; it's similar to mq_timedsend(), 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.

---

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 and O_NONBLOCK wasn't set (in the oflag argument to mq_open()), the call to mq_timedsend() blocks. It becomes unblocked when there's room on the queue to send the given message. If more than one mq_timedsend() is blocked on a given queue, and space becomes available in that queue to send, then the mq_timedsend() with the highest priority message is unblocked.

In the traditional (mqueue) implementation, calling write() with mqdes is analogous to calling mq_timedsend() with a msg_prio of 0.

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 msg_len is negative.
• The msg_prio is greater than (MQ_PRIO_MAX-1).
• The msg_prio is less than 0.
• The MQ_PRIO_RESTRICT flag is set in the mq_attr member of mqdes, and msg_prio is greater than the priority of the calling process.
• 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.

Examples:

See the example for mq_timedreceive().

Classification:

mq_timedsend() is POSIX 1003.1 MSG; mq_timedsend_monotonic() is QNX Neutrino

See also:

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

mq, mqueue in the Utilities Reference