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.
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.
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_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.
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.
Classification:
mq_timedreceive() is
POSIX 1003.1;
mq_timedreceive_monotonic() is
QNX Neutrino
Safety: |
|
Cancellation point |
Yes |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |