|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH MQ_RECEIVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
mq_receive,
|
|
Packit |
7cfc04 |
mq_timedreceive
|
|
Packit |
7cfc04 |
\(em receive a message from a message queue (\fBREALTIME\fP)
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <mqueue.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
ssize_t mq_receive(mqd_t \fImqdes\fP, char *\fImsg_ptr\fP, size_t \fImsg_len\fP,
|
|
Packit |
7cfc04 |
unsigned *\fImsg_prio\fP);
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
#include <mqueue.h>
|
|
Packit |
7cfc04 |
#include <time.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
ssize_t mq_timedreceive(mqd_t \fImqdes\fP, char *restrict \fImsg_ptr\fP,
|
|
Packit |
7cfc04 |
size_t \fImsg_len\fP, unsigned *restrict \fImsg_prio\fP,
|
|
Packit |
7cfc04 |
const struct timespec *restrict \fIabstime\fP);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fImq_receive\fR()
|
|
Packit |
7cfc04 |
function shall receive the oldest of the highest priority
|
|
Packit |
7cfc04 |
message(s) from the message queue specified by
|
|
Packit |
7cfc04 |
.IR mqdes .
|
|
Packit |
7cfc04 |
If the size of the buffer in bytes, specified by the
|
|
Packit |
7cfc04 |
.IR msg_len
|
|
Packit |
7cfc04 |
argument, is less than the
|
|
Packit |
7cfc04 |
.IR mq_msgsize
|
|
Packit |
7cfc04 |
attribute of the message queue, the function shall fail and return an
|
|
Packit |
7cfc04 |
error. Otherwise, the selected message shall be removed from the queue
|
|
Packit |
7cfc04 |
and copied to the buffer pointed to by the
|
|
Packit |
7cfc04 |
.IR msg_ptr
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the value of
|
|
Packit |
7cfc04 |
.IR msg_len
|
|
Packit |
7cfc04 |
is greater than
|
|
Packit |
7cfc04 |
{SSIZE_MAX},
|
|
Packit |
7cfc04 |
the result is implementation-defined.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the argument
|
|
Packit |
7cfc04 |
.IR msg_prio
|
|
Packit |
7cfc04 |
is not NULL, the priority of the selected message shall be stored in the
|
|
Packit |
7cfc04 |
location referenced by
|
|
Packit |
7cfc04 |
.IR msg_prio .
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the specified message queue is empty and O_NONBLOCK
|
|
Packit |
7cfc04 |
is not set in the message queue description associated with
|
|
Packit |
7cfc04 |
.IR mqdes ,
|
|
Packit |
7cfc04 |
\fImq_receive\fR()
|
|
Packit |
7cfc04 |
shall block until a message is enqueued on the message queue or until
|
|
Packit |
7cfc04 |
\fImq_receive\fR()
|
|
Packit |
7cfc04 |
is interrupted by a signal. If more than one thread is waiting to
|
|
Packit |
7cfc04 |
receive a message when a message arrives at an empty queue and the
|
|
Packit |
7cfc04 |
Priority Scheduling option is supported, then the thread of highest
|
|
Packit |
7cfc04 |
priority that has been waiting the longest shall be selected to receive
|
|
Packit |
7cfc04 |
the message. Otherwise, it is unspecified which waiting thread receives
|
|
Packit |
7cfc04 |
the message. If the specified message queue is empty and O_NONBLOCK is
|
|
Packit |
7cfc04 |
set in the message queue description associated with
|
|
Packit |
7cfc04 |
.IR mqdes ,
|
|
Packit |
7cfc04 |
no message shall be removed from the queue, and
|
|
Packit |
7cfc04 |
\fImq_receive\fR()
|
|
Packit |
7cfc04 |
shall return an error.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fImq_timedreceive\fR()
|
|
Packit |
7cfc04 |
function shall receive the oldest of the highest priority messages
|
|
Packit |
7cfc04 |
from the message queue specified by
|
|
Packit |
7cfc04 |
.IR mqdes
|
|
Packit |
7cfc04 |
as described for the
|
|
Packit |
7cfc04 |
\fImq_receive\fR()
|
|
Packit |
7cfc04 |
function. However, if O_NONBLOCK was not specified when the message
|
|
Packit |
7cfc04 |
queue was opened via the
|
|
Packit |
7cfc04 |
\fImq_open\fR()
|
|
Packit |
7cfc04 |
function, and no message exists on the queue to satisfy the receive,
|
|
Packit |
7cfc04 |
the wait for such a message shall be terminated when the specified
|
|
Packit |
7cfc04 |
timeout expires. If O_NONBLOCK is set, this function is equivalent to
|
|
Packit |
7cfc04 |
\fImq_receive\fR().
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The timeout expires when the absolute time specified by
|
|
Packit |
7cfc04 |
.IR abstime
|
|
Packit |
7cfc04 |
passes, as measured by the clock on which timeouts are based (that is,
|
|
Packit |
7cfc04 |
when the value of that clock equals or exceeds
|
|
Packit |
7cfc04 |
.IR abstime ),
|
|
Packit |
7cfc04 |
or if the absolute time specified by
|
|
Packit |
7cfc04 |
.IR abstime
|
|
Packit |
7cfc04 |
has already been passed at the time of the call.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The timeout shall be based on the CLOCK_REALTIME clock.
|
|
Packit |
7cfc04 |
The resolution of the timeout shall be the resolution of the clock on
|
|
Packit |
7cfc04 |
which it is based. The
|
|
Packit |
7cfc04 |
.IR timespec
|
|
Packit |
7cfc04 |
argument is defined in the
|
|
Packit |
7cfc04 |
.IR <time.h>
|
|
Packit |
7cfc04 |
header.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Under no circumstance shall the operation fail with a timeout if a
|
|
Packit |
7cfc04 |
message can be removed from the message queue immediately. The validity
|
|
Packit |
7cfc04 |
of the
|
|
Packit |
7cfc04 |
.IR abstime
|
|
Packit |
7cfc04 |
parameter need not be checked if a message can be removed from the
|
|
Packit |
7cfc04 |
message queue immediately.
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
Upon successful completion, the
|
|
Packit |
7cfc04 |
\fImq_receive\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fImq_timedreceive\fR()
|
|
Packit |
7cfc04 |
functions shall return the length of the selected message in bytes and
|
|
Packit |
7cfc04 |
the message shall be removed from the queue. Otherwise, no message
|
|
Packit |
7cfc04 |
shall be removed from the queue, the functions shall return a value of
|
|
Packit |
7cfc04 |
\(mi1, and set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to indicate the error.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
These functions shall fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EAGAIN
|
|
Packit |
7cfc04 |
O_NONBLOCK was set in the message description associated with
|
|
Packit |
7cfc04 |
.IR mqdes ,
|
|
Packit |
7cfc04 |
and the specified message queue is empty.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EBADF
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR mqdes
|
|
Packit |
7cfc04 |
argument is not a valid message queue descriptor open for reading.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EMSGSIZE
|
|
Packit |
7cfc04 |
The specified message buffer size,
|
|
Packit |
7cfc04 |
.IR msg_len ,
|
|
Packit |
7cfc04 |
is less than the message size attribute of the message queue.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINTR
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fImq_receive\fR()
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
\fImq_timedreceive\fR()
|
|
Packit |
7cfc04 |
operation was interrupted by a signal.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINVAL
|
|
Packit |
7cfc04 |
The process or thread would have blocked, and the
|
|
Packit |
7cfc04 |
.IR abstime
|
|
Packit |
7cfc04 |
parameter specified a nanoseconds field value less than zero or greater
|
|
Packit |
7cfc04 |
than or equal to 1\|000 million.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ETIMEDOUT
|
|
Packit |
7cfc04 |
The O_NONBLOCK flag was not set when the message queue was opened, but
|
|
Packit |
7cfc04 |
no message arrived on the queue before the specified timeout expired.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
These functions may fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EBADMSG
|
|
Packit |
7cfc04 |
The implementation has detected a data corruption problem with the
|
|
Packit |
7cfc04 |
message.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fImq_open\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fImq_send\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fImsgctl\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fImsgget\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fImsgrcv\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fImsgsnd\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fItime\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fB<mqueue.h>\fP",
|
|
Packit |
7cfc04 |
.IR "\fB<time.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|