Debian Codegraph @

upstream/debian-trixie/man7/mq_overview.7

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