Debian Codegraph @

upstream/debian-unstable/man3/mq_receive.3

raw
1 '\" t
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH mq_receive 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mq_receive, mq_timedreceive \- receive a message from a message queue
10 .SH LIBRARY
11 Real-time library
12 .RI ( librt ,\~ \-lrt )
13 .SH SYNOPSIS
14 .nf
15 .B #include <mqueue.h>
16 .P
17 .BR "ssize_t mq_receive(" "size_t msg_len;"
18 .BI " mqd_t " mqdes ", char " msg_ptr [ msg_len ],
19 .BI " size_t " msg_len ", unsigned int *" msg_prio );
20 .P
21 .B #include <time.h>
22 .B #include <mqueue.h>
23 .P
24 .BR "ssize_t mq_timedreceive(" "size_t msg_len;"
25 .BI " mqd_t " mqdes ", char *restrict " msg_ptr [ msg_len ],
26 .BI " size_t " msg_len ", unsigned int *restrict " msg_prio ,
27 .BI " const struct timespec *restrict " abs_timeout );
28 .fi
29 .P
30 .ad l
31 .RS -4
32 Feature Test Macro Requirements for glibc (see
33 .BR feature_test_macros (7)):
34 .RE
35 .P
36 .BR mq_timedreceive ():
37 .nf
38 _POSIX_C_SOURCE >= 200112L
39 .fi
40 .SH DESCRIPTION
41 .BR mq_receive ()
42 removes the oldest message with the highest priority from
43 the message queue referred to by the message queue descriptor
44 .IR mqdes ,
45 and places it in the buffer pointed to by
46 .IR msg_ptr .
47 The
48 .I msg_len
49 argument specifies the size of the buffer pointed to by
50 .IR msg_ptr ;
51 this must be greater than or equal to the
52 .I mq_msgsize
53 attribute of the queue (see
54 .BR mq_getattr (3)).
55 If
56 .I msg_prio
57 is not NULL, then the buffer to which it points is used
58 to return the priority associated with the received message.
59 .P
60 If the queue is empty, then, by default,
61 .BR mq_receive ()
62 blocks until a message becomes available,
63 or the call is interrupted by a signal handler.
64 If the
65 .B O_NONBLOCK
66 flag is enabled for the message queue description,
67 then the call instead fails immediately with the error
68 .BR EAGAIN .
69 .P
70 .BR mq_timedreceive ()
71 behaves just like
72 .BR mq_receive (),
73 except that if the queue is empty and the
74 .B O_NONBLOCK
75 flag is not enabled for the message queue description, then
76 .I abs_timeout
77 points to a structure which specifies how long the call will block.
78 This value is an absolute timeout in seconds and nanoseconds
79 since the Epoch, 1970-01-01 00:00:00 +0000 (UTC),
80 specified in a
81 .BR timespec (3)
82 structure.
83 .P
84 If no message is available,
85 and the timeout has already expired by the time of the call,
86 .BR mq_timedreceive ()
87 returns immediately.
88 .SH RETURN VALUE
89 On success,
90 .BR mq_receive ()
91 and
92 .BR mq_timedreceive ()
93 return the number of bytes in the received message;
94 on error, \-1 is returned, with
95 .I errno
96 set to indicate the error.
97 .SH ERRORS
98 .TP
99 .B EAGAIN
100 The queue was empty, and the
101 .B O_NONBLOCK
102 flag was set for the message queue description referred to by
103 .IR mqdes .
104 .TP
105 .B EBADF
106 The descriptor specified in
107 .I mqdes
108 was invalid or not opened for reading.
109 .TP
110 .B EINTR
111 The call was interrupted by a signal handler;
112 see
113 .BR signal (7).
114 .TP
115 .B EINVAL
116 The call would have blocked, and
117 .I abs_timeout
118 was invalid, either because
119 .I tv_sec
120 was less than zero, or because
121 .I tv_nsec
122 was less than zero or greater than 1000 million.
123 .TP
124 .B EMSGSIZE
125 .I msg_len
126 was less than the
127 .I mq_msgsize
128 attribute of the message queue.
129 .TP
130 .B ETIMEDOUT
131 The call timed out before a message could be transferred.
132 .SH ATTRIBUTES
133 For an explanation of the terms used in this section, see
134 .BR attributes (7).
135 .TS
136 allbox;
137 lbx lb lb
138 l l l.
139 Interface Attribute Value
140 T{
141 .na
142 .nh
143 .BR mq_receive (),
144 .BR mq_timedreceive ()
145 T} Thread safety MT-Safe
146 .TE
147 .SH VERSIONS
148 On Linux,
149 .BR mq_timedreceive ()
150 is a system call, and
151 .BR mq_receive ()
152 is a library function layered on top of that system call.
153 .SH STANDARDS
154 POSIX.1-2008.
155 .SH HISTORY
156 POSIX.1-2001.
157 .SH SEE ALSO
158 .BR mq_close (3),
159 .BR mq_getattr (3),
160 .BR mq_notify (3),
161 .BR mq_open (3),
162 .BR mq_send (3),
163 .BR mq_unlink (3),
164 .BR timespec (3),
165 .BR mq_overview (7),
166 .BR time (7)