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