mq_receive(), mq_timedreceive

receive a message from a message queue 

Realtime Function

SYNOPSIS

#include <mqueue.h>

#include <time.h>

ssize_t mq_timedreceive(mqd_t mqdes, char *restrict msg_ptr, size_t msg_len, unsigned *restrict msg_prio, const struct timespec *restrict abs_timeout);

DESCRIPTION

The mq_receive() function receives the oldest of the highest priority messages from the message specified by the mqdes argument, removes this message from the queue, and copies it to the buffer pointed to by the msg_ptr argument. If there is not enough space allocated in the buffer for the incoming message. mq_receive() fails and returns an error. The size of the buffer, in bytes, is specified by the msg_len argument, while the mq_msgsize attribute of the message queue gives the length of the message being received.

If the msg_prio argument is not NULL, the priority of the selected message is stored in the location pointed to by the msg_prio argument.

If the specified message queue is empty and does not have O_NONBLOCK set in its message queue description, mq_receive() blocks until there is a message in the queue or until a signal interrupts it. If a message arrives at an empty message queue when there are multiple threads waiting to receive a message, the Windows WaitForSingleObject() function determines which thread wakes up first. If the specified message queue is empty and has O_NONBLOCK set in its message queue description, no message is removed from the queue, and mq_receive() returns an error.

The mq_timedreceive() function receives the oldest of the highest priority messages from the specified message queue as for the mq_receive() function. If, however, O_NONBLOCK was not specified when the message queue was opened with the mq_open() function, and there is no message on the queue to satisfy the receive, the wait for such a message ends when the timeout specified by abs_timeout expires. If O_NONBLOCK is set, this function works exactly like mq_receive().

abs_timeout is an absolute time. It expires when the absolute time passes, as measured by the clock on which timeouts are based, of it the absolute time has already passed when the function was called. The timeout is based on the system clock as returned by time().

The resolution of the timeout is the resolution of the clock on which it is based. The <time.h> header defines the timespec type.

This operation never fails with a timeout if a message can immediately be removed from the message queue. In such a case, the validity of the abs_timeout argument is not checked.

PARAMETERS

abs_timeout 

Specifies the maximum wait for receiving a message on the specified message queue.

mqdes 

Specifies the message queue descriptor associated with the message queue on which messages are to be received.

msg_len 

Specifies the size, in bytes, of the buffer where the received message is stored.

msg_prio 

Stores the priority of the received message.

msg_ptr 

Points to the buffer where the received message is stored.

RETURN VALUES

On success, the mq_receive() and mq_timedreceive() function return the length of the received message in bytes and the message is removed from the queue. On failure, they return -1 and set errno to one of the following:

EAGAIN 

The O_NONBLOCK flag was set in the message description associated with mqdes, and the specified message queue is empty.

EBADF 

mqdes is not a valid message queue descriptor open for reading.

EBADMSG 

There was a data corruption problem with the message.

EMSGSIZE 

msg_len is less than the message size attribute of the specified message queue.

EINTR 

A signal interrupted an mq_receive() operation.

EINVAL 

The process or thread would have blocked, and the abs_timeout parameter specified an invalid value.

ENOSPC 

Too much space was requested for the buffer pointed to by msg_ptr.

ETIMEDOUT 

The O_NONBLOCK flag was not set when the message queue was opened, but no message arrived on the queue before the specified timeout expired.

CONFORMANCE

UNIX 03.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

On the NuTCRACKER Platform, the Windows WaitForSingle() function determines which thread is selected when multiple threads are waiting for a message to be received on the specified queue.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
mq_open(), mq_send(), mq_timedsend(), msgctl(), msgget(), msgrcv(), msgsnd(), time()

PTC MKS Toolkit 10.4 Documentation Build 39.