Standard C Library Functions mq_receive(3C)
NAME
mq_receive, mq_timedreceive, mq_reltimedreceive_np - receive
a message from a message queueSYNOPSIS
#include
ssize_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len,
unsigned *msg_prio);
#include
#include
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);
ssize_t mq_reltimedreceive_np(mqd_t mqdes,
char *restrict msg_ptr, size_t msg_len,
unsigned *restrict msg_prio,
const struct timespec *restrict rel_timeout);
DESCRIPTION
The mq_receive() function receives the oldest of the highest
priority message(s) from the message queue specified by mqdes. If the size of the buffer in bytes, specified bymsg_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 tothe buffer pointed to by msg_ptr.
If the value of msg_len is greater than {SSIZE_MAX}, the
result is implementation-defined.
If msg_prio is not NULL, the priority of the selected mes-
sage 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 withmqdes, (see mq_open(3C) and mq_setattr(3C)), mq_receive()
blocks, waiting until a message is enqueued on the messagequeue, 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 theprocess of highest priority that has been waiting the long-
est is selected to receive the message. If the specifiedSunOS 5.11 Last change: 5 Feb 2008 1
Standard C Library Functions mq_receive(3C)
message queue is empty and O_NONBLOCK is set in the message
queue description associated with mqdes, no message isremoved 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 specifiedby mqdes as described for the mq_receive() function. How-
ever, if O_NONBLOCK was not specified when the message queue
was opened with the mq_open(3C) function, and no message
exists on the queue to satisfy the receive, the wait for such a message is terminated when the specified timeoutexpires. If O_NONBLOCK is set, this function is equivalent
to mq_receive().
The mq_reltimedreceive_np() function is identical to the
mq_timedreceive() function, except that the timeout is
specified as a relative time interval.For mq_timedreceive(), the timeout expires when the absolute
time specified by abs_timeout passes, as measured by the
CLOCK_REALTIME clock (that is, when the value of that clock
equals or exceeds abs_timeout), or if the absolute time
specified by abs_timeout has already been passed at the time
of the call.For mq_reltimedreceive_np(), the timeout expires when the
time interval specified by rel_timeout passes, as measured
by the CLOCK_REALTIME clock, or if the time interval speci-
fied by rel_timeout is negative at the time of the call.
The resolution of the timeout is the resolution of theCLOCK_REALTIME clock. The timespec argument is defined in
theheader. Under no circumstance does the operation fail with a timeout if a message can be removed from the message queue immedi-
ately. The validity of the timeout parameter need not be checked if a message can be removed from the message queue immediately.RETURN VALUES
Upon successful completion, mq_receive(), mq_timedreceive(),
and mq_reltimedreceive_np() return 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 functions return a value of -1, and sets errno to
SunOS 5.11 Last change: 5 Feb 2008 2
Standard C Library Functions mq_receive(3C)
indicate the error condition.ERRORS
The mq_receive(), mq_timedreceive(), and
mq_reltimedreceive_np() functions will fail if:
EAGAIN O_NONBLOCK was set in the message description
associated with mqdes, and the specified mes-
sage queue is empty. EBADF The mqdes argument is not a valid message queue descriptor open for reading. EINTR The function was interrupted by a signal. EINVAL The process or thread would have blocked, and the timeout parameter specified a nanoseconds field value less than zero or greater than or equal to 1,000 million.EMSGSIZE The specified message buffer size, msg_len, is
less than the message size member of the mes-
sage queue.ETIMEDOUT The O_NONBLOCK flag was not set when the mes-
sage queue was opened, but no message arrived on the queue before the specified timeout expired.The mq_receive(), mq_timedreceive(), and
mq_reltimedreceive_np() functions may fail if:
EBADMSG A data corruption problem with the message has been detected.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 5 Feb 2008 3
Standard C Library Functions mq_receive(3C)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
| Standard | See below. ||_____________________________|_____________________________|
For mq_receive() and mq_timedreceive(). see standards(5).
SEE ALSO
mqueue.h(3HEAD), mq_open(3C), mq_send(3C), mq_setattr(3C),
attributes(5), standards(5)SunOS 5.11 Last change: 5 Feb 2008 4