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:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
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 OS extension; it's similar to mq_timedreceive(), but it uses CLOCK_MONOTONIC, so the timeout isn't affected by changes to the system time.
If you want to choose the clock against which the timeout is measured, you can instead use mq_clockreceive(), which is similar to mq_timedreceive() and mq_timedreceive_monotonic() and differs only because of its clock parameter (clk). Choosing the clock prevents the timeout from being affected by changes to the system time.
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.
Examples:
See the example for mq_open().
Classification:
mq_timedreceive() is POSIX 1003.1; mq_timedreceive_monotonic() is QNX OS
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Signal handler | Yes |
| Thread | Yes |