mirror of https://github.com/mkerrisk/man-pages
177 lines
6.2 KiB
Plaintext
177 lines
6.2 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "MQ_RECEIVE" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" mq_receive
|
|
.SH NAME
|
|
mq_receive, mq_timedreceive \- receive a message from a message queue
|
|
(\fBREALTIME\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <mqueue.h>
|
|
.br
|
|
.sp
|
|
ssize_t mq_receive(mqd_t\fP \fImqdes\fP\fB, char *\fP\fImsg_ptr\fP\fB,
|
|
size_t\fP \fImsg_len\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ unsigned *\fP\fImsg_prio\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
.sp
|
|
\fP
|
|
.LP
|
|
\fB
|
|
.br
|
|
#include <mqueue.h>
|
|
.br
|
|
#include <time.h>
|
|
.br
|
|
ssize_t mq_timedreceive(mqd_t\fP \fImqdes\fP\fB, char *restrict\fP
|
|
\fImsg_ptr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t\fP \fImsg_len\fP\fB, unsigned *restrict\fP \fImsg_prio\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB);
|
|
\fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fImq_receive\fP() function shall receive the oldest of the highest
|
|
priority message(s) from the message queue specified by
|
|
\fImqdes\fP. If the size of the buffer in bytes, specified by the
|
|
\fImsg_len\fP argument, is less than the \fImq_msgsize\fP
|
|
attribute of the message queue, the function shall fail and return
|
|
an error. Otherwise, the selected message shall be removed from
|
|
the queue and copied to the buffer pointed to by the \fImsg_ptr\fP
|
|
argument.
|
|
.LP
|
|
If the value of \fImsg_len\fP is greater than {SSIZE_MAX}, the result
|
|
is implementation-defined.
|
|
.LP
|
|
If the argument \fImsg_prio\fP is not NULL, the priority of the selected
|
|
message shall be stored in the location referenced by
|
|
\fImsg_prio\fP.
|
|
.LP
|
|
If the specified message queue is empty and O_NONBLOCK is not set
|
|
in the message queue description associated with \fImqdes\fP,
|
|
\fImq_receive\fP() shall block until a message is enqueued on the
|
|
message queue or until \fImq_receive\fP() is interrupted by a
|
|
signal. If more than one thread is waiting to receive a message when
|
|
a message arrives at an empty queue and the Priority
|
|
Scheduling option is supported, then the thread of highest priority
|
|
that has been waiting the longest shall be selected to receive
|
|
the message. Otherwise, it is unspecified which waiting thread receives
|
|
the message. If the specified message queue is empty and
|
|
O_NONBLOCK is set in the message queue description associated with
|
|
\fImqdes\fP, no message shall be removed from the queue, and
|
|
\fImq_receive\fP() shall return an error.
|
|
.LP
|
|
The \fImq_timedreceive\fP() function shall receive the oldest of the
|
|
highest priority messages from the message queue specified by
|
|
\fImqdes\fP as described for the \fImq_receive\fP() function. However,
|
|
if O_NONBLOCK was not specified when the message queue was
|
|
opened via the \fImq_open\fP() function, and no message exists on
|
|
the queue to satisfy the
|
|
receive, the wait for such a message shall be terminated when the
|
|
specified timeout expires. If O_NONBLOCK is set, this function is
|
|
equivalent to \fImq_receive\fP().
|
|
.LP
|
|
The timeout expires when the absolute time specified by \fIabs_timeout\fP
|
|
passes, as measured by the clock on which timeouts
|
|
are based (that is, when the value of that clock equals or exceeds
|
|
\fIabs_timeout\fP), or if the absolute time specified by
|
|
\fIabs_timeout\fP has already been passed at the time of the call.
|
|
.LP
|
|
If the Timers option is supported, the timeout shall be based on the
|
|
CLOCK_REALTIME clock; if the Timers option is not
|
|
supported, the timeout shall be based on the system clock as returned
|
|
by the \fItime\fP()
|
|
function.
|
|
.LP
|
|
The resolution of the timeout shall be the resolution of the clock
|
|
on which it is based. The \fItimespec\fP argument is defined in
|
|
the \fI<time.h>\fP header.
|
|
.LP
|
|
Under no circumstance shall the operation fail with a timeout if a
|
|
message can be removed from the message queue immediately.
|
|
The validity of the \fIabs_timeout\fP parameter need not be checked
|
|
if a message can be removed from the message queue
|
|
immediately.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, the \fImq_receive\fP() \ and \fImq_timedreceive\fP()
|
|
functions shall return the length of the selected message in bytes
|
|
and the message shall be removed from
|
|
the queue. Otherwise, no message shall be removed from the queue,
|
|
the functions shall return a value of -1, and set \fIerrno\fP to
|
|
indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fImq_receive\fP() \ and \fImq_timedreceive\fP()
|
|
functions shall fail if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
O_NONBLOCK was set in the message description associated with \fImqdes\fP,
|
|
and the specified message queue is empty.
|
|
.TP 7
|
|
.B EBADF
|
|
The \fImqdes\fP argument is not a valid message queue descriptor open
|
|
for reading.
|
|
.TP 7
|
|
.B EMSGSIZE
|
|
The specified message buffer size, \fImsg_len\fP, is less than the
|
|
message size attribute of the message queue.
|
|
.TP 7
|
|
.B EINTR
|
|
The \fImq_receive\fP() \ or \fImq_timedreceive\fP()
|
|
operation was interrupted by a signal.
|
|
.TP 7
|
|
.B EINVAL
|
|
The process or thread would have blocked, and the \fIabs_timeout\fP
|
|
parameter specified a nanoseconds field value less than zero
|
|
or greater than or equal to 1000 million.
|
|
.TP 7
|
|
.B 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.
|
|
.sp
|
|
.LP
|
|
The \fImq_receive\fP() \ and \fImq_timedreceive\fP()
|
|
functions may fail if:
|
|
.TP 7
|
|
.B EBADMSG
|
|
The implementation has detected a data corruption problem with the
|
|
message.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fImq_open\fP() , \fImq_send\fP() , \fImq_timedsend\fP() , \fImsgctl\fP()
|
|
, \fImsgget\fP() , \fImsgrcv\fP() , \fImsgsnd\fP() , \fItime\fP()
|
|
, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<mqueue.h>\fP,
|
|
\fI<time.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|