1MQ_RECEIVE(3P) POSIX Programmer's Manual MQ_RECEIVE(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 mq_receive, mq_timedreceive - receive a message from a message queue
13 (REALTIME)
14
16 #include <mqueue.h>
17 ssize_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len,
19 unsigned *msg_prio);
20 #include <mqueue.h>
25 #include <time.h>
26 ssize_t mq_timedreceive(mqd_t mqdes, char *restrict msg_ptr,
27 size_t msg_len, unsigned *restrict msg_prio,
28 const struct timespec *restrict abs_timeout);
29
32 The mq_receive() function shall receive the oldest of the highest pri‐
33 ority message(s) from the message queue specified by mqdes. If the size
34 of the buffer in bytes, specified by the msg_len argument, is less than
35 the mq_msgsize attribute of the message queue, the function shall fail
36 and return an error. Otherwise, the selected message shall be removed
37 from the queue and copied to the buffer pointed to by the msg_ptr argu‐
38 ment.
39 If the value of msg_len is greater than {SSIZE_MAX}, the result is
41 implementation-defined.
42 If the argument msg_prio is not NULL, the priority of the selected mes‐
44 sage shall be stored in the location referenced by msg_prio.
45 If the specified message queue is empty and O_NONBLOCK is not set in
47 the message queue description associated with mqdes, mq_receive() shall
48 block until a message is enqueued on the message queue or until
49 mq_receive() is interrupted by a signal. If more than one thread is
50 waiting to receive a message when a message arrives at an empty queue
51 and the Priority Scheduling option is supported, then the thread of
52 highest priority that has been waiting the longest shall be selected to
53 receive the message. Otherwise, it is unspecified which waiting thread
54 receives the message. If the specified message queue is empty and
55 O_NONBLOCK is set in the message queue description associated with
56 mqdes, no message shall be removed from the queue, and mq_receive()
57 shall return an error.
58 The mq_timedreceive() function shall receive the oldest of the highest
60 priority messages from the message queue specified by mqdes as
61 described for the mq_receive() function. However, if O_NONBLOCK was not
62 specified when the message queue was opened via the mq_open() function,
63 and no message exists on the queue to satisfy the receive, the wait for
64 such a message shall be terminated when the specified timeout expires.
65 If O_NONBLOCK is set, this function is equivalent to mq_receive().
66 The timeout expires when the absolute time specified by abs_timeout
68 passes, as measured by the clock on which timeouts are based (that is,
69 when the value of that clock equals or exceeds abs_timeout), or if the
70 absolute time specified by abs_timeout has already been passed at the
71 time of the call.
72 If the Timers option is supported, the timeout shall be based on the
74 CLOCK_REALTIME clock; if the Timers option is not supported, the time‐
75 out shall be based on the system clock as returned by the time() func‐
76 tion.
77 The resolution of the timeout shall be the resolution of the clock on
79 which it is based. The timespec argument is defined in the <time.h>
80 header.
81 Under no circumstance shall the operation fail with a timeout if a mes‐
83 sage can be removed from the message queue immediately. The validity
84 of the abs_timeout parameter need not be checked if a message can be
85 removed from the message queue immediately.
86
88 Upon successful completion, the mq_receive() and mq_timedreceive()
89 functions shall return the length of the selected message in bytes and
90 the message shall be removed from the queue. Otherwise, no message
91 shall be removed from the queue, the functions shall return a value of
92 -1, and set errno to indicate the error.
93
95 The mq_receive() and mq_timedreceive() functions shall fail if:
96 EAGAIN O_NONBLOCK was set in the message description associated with
98 mqdes, and the specified message queue is empty.
99 EBADF The mqdes argument is not a valid message queue descriptor open
101 for reading.
102 EMSGSIZE
104 The specified message buffer size, msg_len, is less than the
105 message size attribute of the message queue.
106 EINTR The mq_receive() or mq_timedreceive() operation was interrupted
108 by a signal.
109 EINVAL The process or thread would have blocked, and the abs_timeout
111 parameter specified a nanoseconds field value less than zero or
112 greater than or equal to 1000 million.
113 ETIMEDOUT
115 The O_NONBLOCK flag was not set when the message queue was
116 opened, but no message arrived on the queue before the specified
117 timeout expired.
118 The mq_receive() and mq_timedreceive() functions may fail if:
121 EBADMSG
123 The implementation has detected a data corruption problem with
124 the message.
125 The following sections are informative.
128
130 None.
131
133 None.
134
136 None.
137
139 None.
140
142 mq_open(), mq_send(), mq_timedsend(), msgctl(), msgget(), msgrcv(),
143 msgsnd(), time(), the Base Definitions volume of IEEE Std 1003.1-2001,
144 <mqueue.h>, <time.h>
145
147 Portions of this text are reprinted and reproduced in electronic form
148 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
149 -- Portable Operating System Interface (POSIX), The Open Group Base
150 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
151 Electrical and Electronics Engineers, Inc and The Open Group. In the
152 event of any discrepancy between this version and the original IEEE and
153 The Open Group Standard, the original IEEE and The Open Group Standard
154 is the referee document. The original Standard can be obtained online
155 at http://www.opengroup.org/unix/online.html .
156IEEE/The Open Group 2003 MQ_RECEIVE(3P)