Debian Codegraph @

upstream/debian-unstable/man7/mq_overview.7

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_overview 7 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mq_overview \- overview of POSIX message queues
10 .SH DESCRIPTION
11 POSIX message queues allow processes to exchange data in
12 the form of messages.
13 This API is distinct from that provided by System V message queues
14 .RB ( msgget (2),
15 .BR msgsnd (2),
16 .BR msgrcv (2),
17 etc.), but provides similar functionality.
18 .P
19 Message queues are created and opened using
20 .BR mq_open (3);
21 this function returns a
22 .I message queue descriptor
23 .RI ( mqd_t ),
24 which is used to refer to the open message queue in later calls.
25 Each message queue is identified by a name of the form
26 .IR /somename ;
27 that is, a null-terminated string of up to
28 .B NAME_MAX
29 (i.e., 255) characters consisting of an initial slash,
30 followed by one or more characters, none of which are slashes.
31 Two processes can operate on the same queue by passing the same name to
32 .BR mq_open (3).
33 .P
34 Messages are transferred to and from a queue using
35 .BR mq_send (3)
36 and
37 .BR mq_receive (3).
38 When a process has finished using the queue, it closes it using
39 .BR mq_close (3),
40 and when the queue is no longer required, it can be deleted using
41 .BR mq_unlink (3).
42 Queue attributes can be retrieved and (in some cases) modified using
43 .BR mq_getattr (3)
44 and
45 .BR mq_setattr (3).
46 A process can request asynchronous notification
47 of the arrival of a message on a previously empty queue using
48 .BR mq_notify (3).
49 .P
50 A message queue descriptor is a reference to an
51 .I "open message queue description"
52 (see
53 .BR open (2)).
54 After a
55 .BR fork (2),
56 a child inherits copies of its parent's message queue descriptors,
57 and these descriptors refer to the same open message queue descriptions
58 as the corresponding message queue descriptors in the parent.
59 Corresponding message queue descriptors in the two processes share the flags
60 .RI ( mq_flags )
61 that are associated with the open message queue description.
62 .P
63 Each message has an associated
64 .IR priority ,
65 and messages are always delivered to the receiving process
66 highest priority first.
67 Message priorities range from 0 (low) to
68 .I sysconf(_SC_MQ_PRIO_MAX)\ \-\ 1
69 (high).
70 On Linux,
71 .I sysconf(_SC_MQ_PRIO_MAX)
72 returns 32768, but POSIX.1 requires only that
73 an implementation support at least priorities in the range 0 to 31;
74 some implementations provide only this range.
75 .P
76 The remainder of this section describes some specific details
77 of the Linux implementation of POSIX message queues.
78 .SS Library interfaces and system calls
79 In most cases the
80 .BR mq_* ()
81 library interfaces listed above are implemented
82 on top of underlying system calls of the same name.
83 Deviations from this scheme are indicated in the following table:
84 .RS
85 .TS
86 lB lB
87 l l.
88 Library interface System call
89 mq_close(3) close(2)
90 mq_getattr(3) mq_getsetattr(2)
91 mq_notify(3) mq_notify(2)
92 mq_open(3) mq_open(2)
93 mq_receive(3) mq_timedreceive(2)
94 mq_send(3) mq_timedsend(2)
95 mq_setattr(3) mq_getsetattr(2)
96 mq_timedreceive(3) mq_timedreceive(2)
97 mq_timedsend(3) mq_timedsend(2)
98 mq_unlink(3) mq_unlink(2)
99 .TE
100 .RE
101 .SS Versions
102 POSIX message queues have been supported since Linux 2.6.6.
103 glibc support has been provided since glibc 2.3.4.
104 .SS Kernel configuration
105 Support for POSIX message queues is configurable via the
106 .B CONFIG_POSIX_MQUEUE
107 kernel configuration option.
108 This option is enabled by default.
109 .SS Persistence
110 POSIX message queues have kernel persistence:
111 if not removed by
112 .BR mq_unlink (3),
113 a message queue will exist until the system is shut down.
114 .SS Linking
115 Programs using the POSIX message queue API must be compiled with
116 .I cc \-lrt
117 to link against the real-time library,
118 .IR librt .
119 .SS /proc interfaces
120 The following interfaces can be used to limit the amount of
121 kernel memory consumed by POSIX message queues and to set
122 the default attributes for new message queues:
123 .TP
124 .IR /proc/sys/fs/mqueue/msg_default " (since Linux 3.5)"
125 This file defines the value used for a new queue's
126 .I mq_maxmsg
127 setting when the queue is created with a call to
128 .BR mq_open (3)
129 where
130 .I attr
131 is specified as NULL.
132 The default value for this file is 10.
133 The minimum and maximum are as for
134 .IR /proc/sys/fs/mqueue/msg_max .
135 A new queue's default
136 .I mq_maxmsg
137 value will be the smaller of
138 .I msg_default
139 and
140 .IR msg_max .
141 Before Linux 2.6.28, the default
142 .I mq_maxmsg
143 was 10;
144 from Linux 2.6.28 to Linux 3.4, the default was the value defined for the
145 .I msg_max
146 limit.
147 .TP
148 .I /proc/sys/fs/mqueue/msg_max
149 This file can be used to view and change the ceiling value for the
150 maximum number of messages in a queue.
151 This value acts as a ceiling on the
152 .I attr\->mq_maxmsg
153 argument given to
154 .BR mq_open (3).
155 The default value for
156 .I msg_max
157 is 10.
158 The minimum value is 1 (10 before Linux 2.6.28).
159 The upper limit is
160 .BR HARD_MSGMAX .
161 The
162 .I msg_max
163 limit is ignored for privileged processes
164 .RB ( CAP_SYS_RESOURCE ),
165 but the
166 .B HARD_MSGMAX
167 ceiling is nevertheless imposed.
168 .IP
169 The definition of
170 .B HARD_MSGMAX
171 has changed across kernel versions:
172 .RS
173 .IP \[bu] 3
174 Up to Linux 2.6.32:
175 .I 131072\~/\~sizeof(void\~*)
176 .IP \[bu]
177 Linux 2.6.33 to Linux 3.4:
178 .I (32768\~*\~sizeof(void\~*) / 4)
179 .IP \[bu]
180 Since Linux 3.5:
181 .\" commit 5b5c4d1a1440e94994c73dddbad7be0676cd8b9a
182 65,536
183 .RE
184 .TP
185 .IR /proc/sys/fs/mqueue/msgsize_default " (since Linux 3.5)"
186 This file defines the value used for a new queue's
187 .I mq_msgsize
188 setting when the queue is created with a call to
189 .BR mq_open (3)
190 where
191 .I attr
192 is specified as NULL.
193 The default value for this file is 8192 (bytes).
194 The minimum and maximum are as for
195 .IR /proc/sys/fs/mqueue/msgsize_max .
196 If
197 .I msgsize_default
198 exceeds
199 .IR msgsize_max ,
200 a new queue's default
201 .I mq_msgsize
202 value is capped to the
203 .I msgsize_max
204 limit.
205 Before Linux 2.6.28, the default
206 .I mq_msgsize
207 was 8192;
208 from Linux 2.6.28 to Linux 3.4, the default was the value defined for the
209 .I msgsize_max
210 limit.
211 .TP
212 .I /proc/sys/fs/mqueue/msgsize_max
213 This file can be used to view and change the ceiling on the
214 maximum message size.
215 This value acts as a ceiling on the
216 .I attr\->mq_msgsize
217 argument given to
218 .BR mq_open (3).
219 The default value for
220 .I msgsize_max
221 is 8192 bytes.
222 The minimum value is 128 (8192 before Linux 2.6.28).
223 The upper limit for
224 .I msgsize_max
225 has varied across kernel versions:
226 .RS
227 .IP \[bu] 3
228 Before Linux 2.6.28, the upper limit is
229 .BR INT_MAX .
230 .IP \[bu]
231 From Linux 2.6.28 to Linux 3.4, the limit is 1,048,576.
232 .IP \[bu]
233 Since Linux 3.5, the limit is 16,777,216
234 .RB ( HARD_MSGSIZEMAX ).
235 .RE
236 .IP
237 The
238 .I msgsize_max
239 limit is ignored for privileged process
240 .RB ( CAP_SYS_RESOURCE ),
241 but, since Linux 3.5, the
242 .B HARD_MSGSIZEMAX
243 ceiling is enforced for privileged processes.
244 .TP
245 .I /proc/sys/fs/mqueue/queues_max
246 This file can be used to view and change the system-wide limit on the
247 number of message queues that can be created.
248 The default value for
249 .I queues_max
250 is 256.
251 No ceiling is imposed on the
252 .I queues_max
253 limit;
254 privileged processes
255 .RB ( CAP_SYS_RESOURCE )
256 can exceed the limit (but see BUGS).
257 .SS Resource limit
258 The
259 .B RLIMIT_MSGQUEUE
260 resource limit, which places a limit on the amount of space
261 that can be consumed by all of the message queues
262 belonging to a process's real user ID, is described in
263 .BR getrlimit (2).
264 .SS Mounting the message queue filesystem
265 On Linux, message queues are created in a virtual filesystem.
266 (Other implementations may also provide such a feature,
267 but the details are likely to differ.)
268 This filesystem can be mounted (by the superuser) using the following
269 commands:
270 .P
271 .in +4n
272 .EX
273 .RB "#" " mkdir /dev/mqueue"
274 .RB "#" " mount \-t mqueue none /dev/mqueue"
275 .EE
276 .in
277 .P
278 The sticky bit is automatically enabled on the mount directory.
279 .P
280 After the filesystem has been mounted, the message queues on the system
281 can be viewed and manipulated using the commands usually used for files
282 (e.g.,
283 .BR ls (1)
284 and
285 .BR rm (1)).
286 .P
287 The contents of each file in the directory consist of a single line
288 containing information about the queue:
289 .P
290 .in +4n
291 .EX
292 .RB "$" " cat /dev/mqueue/mymq"
293 QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260
294 .EE
295 .in
296 .P
297 These fields are as follows:
298 .TP
299 .B QSIZE
300 Number of bytes of data in all messages in the queue (but see BUGS).
301 .TP
302 .B NOTIFY_PID
303 If this is nonzero, then the process with this PID has used
304 .BR mq_notify (3)
305 to register for asynchronous message notification,
306 and the remaining fields describe how notification occurs.
307 .TP
308 .B NOTIFY
309 Notification method:
310 0 is
311 .BR SIGEV_SIGNAL ;
312 1 is
313 .BR SIGEV_NONE ;
314 and
315 2 is
316 .BR SIGEV_THREAD .
317 .TP
318 .B SIGNO
319 Signal number to be used for
320 .BR SIGEV_SIGNAL .
321 .SS Linux implementation of message queue descriptors
322 On Linux, a message queue descriptor is actually a file descriptor.
323 (POSIX does not require such an implementation.)
324 This means that a message queue descriptor can be monitored using
325 .BR select (2),
326 .BR poll (2),
327 or
328 .BR epoll (7).
329 This is not portable.
330 .P
331 The close-on-exec flag (see
332 .BR open (2))
333 is automatically set on the file descriptor returned by
334 .BR mq_open (2).
335 .SS IPC namespaces
336 For a discussion of the interaction of POSIX message queue objects and
337 IPC namespaces, see
338 .BR ipc_namespaces (7).
339 .SH NOTES
340 System V message queues
341 .RB ( msgget (2),
342 .BR msgsnd (2),
343 .BR msgrcv (2),
344 etc.) are an older API for exchanging messages between processes.
345 POSIX message queues provide a better designed interface than
346 System V message queues;
347 on the other hand POSIX message queues are less widely available
348 (especially on older systems) than System V message queues.
349 .P
350 Linux does not currently (Linux 2.6.26) support the use of access control
351 lists (ACLs) for POSIX message queues.
352 .SH BUGS
353 Since Linux 3.5 to Linux 3.14, the kernel imposed a ceiling of 1024
354 .RB ( HARD_QUEUESMAX )
355 on the value to which the
356 .I queues_max
357 limit could be raised,
358 and the ceiling was enforced even for privileged processes.
359 This ceiling value was removed in Linux 3.14,
360 and patches to stable Linux 3.5.x to Linux 3.13.x also removed the ceiling.
361 .P
362 As originally implemented (and documented),
363 the QSIZE field displayed the total number of (user-supplied)
364 bytes in all messages in the message queue.
365 Some changes in Linux 3.5
366 .\" commit d6629859b36d
367 inadvertently changed the behavior,
368 so that this field also included a count of kernel overhead bytes
369 used to store the messages in the queue.
370 This behavioral regression was rectified in Linux 4.2
371 .\" commit de54b9ac253787c366bbfb28d901a31954eb3511
372 (and earlier stable kernel series),
373 so that the count once more included just the bytes of user data
374 in messages in the queue.
375 .SH EXAMPLES
376 An example of the use of various message queue functions is shown in
377 .BR mq_notify (3).
378 .SH SEE ALSO
379 .BR getrlimit (2),
380 .BR mq_getsetattr (2),
381 .BR poll (2),
382 .BR select (2),
383 .BR mq_close (3),
384 .BR mq_getattr (3),
385 .BR mq_notify (3),
386 .BR mq_open (3),
387 .BR mq_receive (3),
388 .BR mq_send (3),
389 .BR mq_unlink (3),
390 .BR epoll (7),
391 .BR namespaces (7)