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