mq_receive

Langue: en

Version: DECEMBER 2002 (mandriva - 01/05/08)

Autres sections - même nom

Section: 2 (Appels système)

NAME

mq_receive - receive a message from a message queue

SYNOPSIS

gcc [ flag... ] file ... -lmqueue [ library... ]

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

ssize_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len, unsigned int *msg_prio);

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

DESCRIPTION

The mq_receive() function is used to receive the oldest of the highest priority message(s) from the message queue specified by mqdes. If the size of the buffer in bytes, specified by msg_len, is less than the mq_msgsize member of the message queue, the function fails and returns an error. Otherwise, the selected message is removed from the queue and copied to the buffer pointed to by msg_ptr.

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

If the specified message queue is empty and O_NONBLOCK is not set in the message queue description associated with mqdes, (see mq_open(2) and mq_setattr(2)), mq_receive() blocks, waiting until a message is enqueued on the message queue, or until mq_receive() is interrupted by a signal. If more than one process (or thread) is waiting to receive a message when a message arrives at an empty queue, then the process of highest priority that has been waiting the longest is selected to receive the message. If the specified message queue is empty and O_NONBLOCK is set in the message queue description associated with mqdes, 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 message queue specified by mqdes as described for the mq_receive() function. However, if O_NONBLOCK was not specified when the message queue was opened via the mq_open() function, and no message exists on the queue to satisfy the receive, the wait for such a message is terminated when the specified timeout expires. The timeout is given as absolute value. If there is a (common) need to use relative timeout i.e. to wait for some time specified from the time of mq_timedreceive() invocation then abs_timeout fields must be the sum of current time and the relative timeout. If O_NONBLOCK is set, this function is equivalent to mq_receive().

RETURN VALUES

Upon successful completion, mq_receive() returns the length of the selected message in bytes and the message is removed from the queue. Otherwise, no message is removed from the queue, the function returns a value of -1, and sets errno to indicate the error condition.

DIAGNOSTICS

The mq_receive() function will fail if:
EAGAIN
O_NONBLOCK was set in the message description associated with mqdes, and the specified message queue is empty.
EBADF
The mqdes argument is not a valid message queue descriptor open for reading.
EINTR
The mq_receive() function operation was interrupted by a signal.
EMSGSIZE
The specified message buffer size, msg_len, is less than the message size member of the message queue.
ENOMEM
Kernel failed to allocate necessary memory.
EINVAL
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.
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.
EFAULT
msg_ptr, msg_prio or abs_timeout points outside your accessible address space.

AUTHORS

Krzysztof Benedyczak <golbi@mat.uni.torun.pl>
Michal Wronski <wrona@mat.uni.torun.pl>

CONFORMING TO

IEEE Std 1003.1-2001

SEE ALSO

mq_send(2), mq_setattr(2), mq_open(2)