mq_timedreceive()

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 );

Library:

libc

Description:

The mq_timedreceive() function is used to receive the oldest of the highest priority messages in the queue specified by mqdes. The priority of the message received is put in the location pointed to by msg_prio, the data itself in the location pointed to by msg_ptr, and the size received is returned.

The time contained in the abs_timeout argument specifies the absolute time (not the relative time to the current time) to wait before it stops trying to receive messages.

If mq_timedreceive() is called 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 isn't set in oflag during mq_open(), and MQ_NONBLOCK isn't present in the queue's mq_flags, 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.

If msg_prio isn't NULL, then the priority of the message removed from the queue are stored in the location referenced by msg_prio.

Calling read() with mqdes is analogous to calling mq_timedreceive() with a NULL msg_prio.

Returns:

The size of the message removed from the queue. If the call fails, -1 is returned as the size, no message is removed from the queue, and errno is set.

Errors:

EAGAIN

The O_NONBLOCK or MQ_NONBLOCK flags were 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

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.

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:

Here's how to specify an absolute timeout for 1 second:

struct   timespec tm;
  clock_gettime(CLOCK_REALTIME, &tm);
  tm.tv_sec += 1;
  if( 0 > mq_timedreceive( fd, buf, 4096, NULL,  t ) )  {
}

Classification:

POSIX 1003.1d (draft)

See also:

mq_close(), mq_open(), mq_send(), mq_timedsend()