2 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .TH mq_receive 3 (date) "Linux man-pages (unreleased)"
8 mq_receive, mq_timedreceive \- receive a message from a message queue
11 .RI ( librt ", " \-lrt )
14 .B #include <mqueue.h>
16 .BI "ssize_t mq_receive(mqd_t " mqdes ", char " msg_ptr [. msg_len ],
17 .BI " size_t " msg_len ", unsigned int *" msg_prio );
20 .B #include <mqueue.h>
22 .BI "ssize_t mq_timedreceive(mqd_t " mqdes ", \
23 char *restrict " msg_ptr [. msg_len ],
24 .BI " size_t " msg_len ", unsigned int *restrict " msg_prio ,
25 .BI " const struct timespec *restrict " abs_timeout );
30 Feature Test Macro Requirements for glibc (see
31 .BR feature_test_macros (7)):
34 .BR mq_timedreceive ():
36 _POSIX_C_SOURCE >= 200112L
40 removes the oldest message with the highest priority from
41 the message queue referred to by the message queue descriptor
43 and places it in the buffer pointed to by
47 argument specifies the size of the buffer pointed to by
49 this must be greater than or equal to the
51 attribute of the queue (see
55 is not NULL, then the buffer to which it points is used
56 to return the priority associated with the received message.
58 If the queue is empty, then, by default,
60 blocks until a message becomes available,
61 or the call is interrupted by a signal handler.
64 flag is enabled for the message queue description,
65 then the call instead fails immediately with the error
68 .BR mq_timedreceive ()
71 except that if the queue is empty and the
73 flag is not enabled for the message queue description, then
75 points to a structure which specifies how long the call will block.
76 This value is an absolute timeout in seconds and nanoseconds
77 since the Epoch, 1970-01-01 00:00:00 +0000 (UTC),
82 If no message is available,
83 and the timeout has already expired by the time of the call,
84 .BR mq_timedreceive ()
90 .BR mq_timedreceive ()
91 return the number of bytes in the received message;
92 on error, \-1 is returned, with
94 set to indicate the error.
98 The queue was empty, and the
100 flag was set for the message queue description referred to by
104 The descriptor specified in
106 was invalid or not opened for reading.
109 The call was interrupted by a signal handler; see
113 The call would have blocked, and
115 was invalid, either because
117 was less than zero, or because
119 was less than zero or greater than 1000 million.
125 attribute of the message queue.
128 The call timed out before a message could be transferred.
130 For an explanation of the terms used in this section, see
138 Interface Attribute Value
141 .BR mq_timedreceive ()
142 T} Thread safety MT-Safe
148 POSIX.1-2001, POSIX.1-2008.
151 .BR mq_timedreceive ()
152 is a system call, and
154 is a library function layered on top of that system call.