]>
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 | .\" |
daf084cc | 26 | .TH MQ_OVERVIEW 7 2014-09-21 "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 |
80a99f39 | 77 | as the corresponding descriptors in the parent. |
c13182ef | 78 | Corresponding 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) |
f341304c MK |
91 | returns 32768, but POSIX.1-2001 requires only that |
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 |
80a99f39 MK |
140 | kernel memory consumed by POSIX message queues: |
141 | .TP | |
142 | .I /proc/sys/fs/mqueue/msg_max | |
c13182ef | 143 | This file can be used to view and change the ceiling value for the |
80a99f39 MK |
144 | maximum number of messages in a queue. |
145 | This value acts as a ceiling on the | |
94e9d9fe | 146 | .I attr\->mq_maxmsg |
80a99f39 MK |
147 | argument given to |
148 | .BR mq_open (3). | |
5bbdbc7e | 149 | The default value for |
80a99f39 | 150 | .I msg_max |
5bbdbc7e MK |
151 | is 10. |
152 | The minimum value is 1 (10 in kernels before 2.6.28). | |
153 | The upper limit is | |
2d5cee6b | 154 | .BR HARD_MSGMAX . |
5bd24c36 MK |
155 | The |
156 | .I msg_max | |
157 | limit is ignored for privileged processes | |
80a99f39 | 158 | .RB ( CAP_SYS_RESOURCE ), |
c7496b03 | 159 | but the |
8ef5d0c5 | 160 | .BR HARD_MSGMAX |
c7496b03 | 161 | ceiling is nevertheless imposed. |
2d5cee6b MK |
162 | The definition of |
163 | .BR HARD_MSGMAX | |
164 | has changed across kernel versions: | |
165 | before Linux 2.6.33, it was | |
166 | .IR "(131072\ /\ sizeof(void\ *))" | |
167 | (32768 on Linux/86); | |
168 | from Linux 2.6.33, it was | |
169 | .IR "(32768\ *\ sizeof(void\ *)/4)" ; | |
170 | since Linux 3.5, | |
171 | .\" commit 5b5c4d1a1440e94994c73dddbad7be0676cd8b9a | |
172 | it is 65,536. | |
80a99f39 MK |
173 | .TP |
174 | .I /proc/sys/fs/mqueue/msgsize_max | |
c13182ef | 175 | This file can be used to view and change the ceiling on the |
80a99f39 MK |
176 | maximum message size. |
177 | This value acts as a ceiling on the | |
94e9d9fe | 178 | .I attr\->mq_msgsize |
80a99f39 MK |
179 | argument given to |
180 | .BR mq_open (3). | |
5bbdbc7e MK |
181 | The default value for |
182 | .I msgsize_max | |
183 | is 8192 bytes. | |
184 | The minimum value is 128 (8192 in kernels before 2.6.28). | |
185 | The upper limit for | |
80a99f39 | 186 | .I msgsize_max |
81020547 MK |
187 | has varied across kernel versions: |
188 | before Linux 2.6.28, the upper limit was | |
5bbdbc7e | 189 | .BR INT_MAX ; |
81020547 MK |
190 | (that is, 2,147,483,647 on Linux/86); |
191 | starting with Linux 2.6.38, the limit was 1,048,576; | |
192 | since Linux 3.5, the limit is 16,777,216 | |
193 | .RB ( HARD_MSGSIZEMAX ). | |
194 | The | |
195 | .I msgsize_max | |
196 | limit is ignored for privileged process | |
197 | .RB ( CAP_SYS_RESOURCE ), | |
198 | but, since Linux 3.5, the | |
199 | .BR HARD_MSGSIZEMAX | |
200 | ceiling is enforced for privileged processes. | |
80a99f39 MK |
201 | .TP |
202 | .I /proc/sys/fs/mqueue/queues_max | |
c13182ef | 203 | This file can be used to view and change the system-wide limit on the |
80a99f39 | 204 | number of message queues that can be created. |
c13182ef | 205 | Only privileged processes |
80a99f39 MK |
206 | .RB ( CAP_SYS_RESOURCE ) |
207 | can create new message queues once this limit has been reached. | |
208 | The default value for | |
209 | .I queues_max | |
210 | is 256; it can be changed to any value in the range 0 to INT_MAX. | |
211 | .SS Resource limit | |
212 | The | |
0daa9e92 | 213 | .B RLIMIT_MSGQUEUE |
c13182ef MK |
214 | resource limit, which places a limit on the amount of space |
215 | that can be consumed by all of the message queues | |
216 | belonging to a process's real user ID, is described in | |
80a99f39 | 217 | .BR getrlimit (2). |
9ee4a2b6 MK |
218 | .SS Mounting the message queue filesystem |
219 | On Linux, message queues are created in a virtual filesystem. | |
c13182ef | 220 | (Other implementations may also provide such a feature, |
80a99f39 | 221 | but the details are likely to differ.) |
9ee4a2b6 | 222 | This filesystem can be mounted (by the superuser) using the following |
06ae751a | 223 | commands: |
a08ea57c | 224 | .in +4n |
80a99f39 MK |
225 | .nf |
226 | ||
06ae751a MK |
227 | .RB "#" " mkdir /dev/mqueue" |
228 | .RB "#" " mount \-t mqueue none /dev/mqueue" | |
80a99f39 MK |
229 | |
230 | .fi | |
a08ea57c | 231 | .in |
80a99f39 MK |
232 | The sticky bit is automatically enabled on the mount directory. |
233 | ||
9ee4a2b6 | 234 | After the filesystem has been mounted, the message queues on the system |
80a99f39 MK |
235 | can be viewed and manipulated using the commands usually used for files |
236 | (e.g., | |
237 | .BR ls (1) | |
238 | and | |
239 | .BR rm (1)). | |
240 | ||
c13182ef | 241 | The contents of each file in the directory consist of a single line |
80a99f39 | 242 | containing information about the queue: |
a08ea57c | 243 | .in +4n |
80a99f39 MK |
244 | .nf |
245 | ||
8339b8bc | 246 | .RB "$" " cat /dev/mqueue/mymq" |
80a99f39 | 247 | QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260 |
80a99f39 MK |
248 | |
249 | .fi | |
a08ea57c | 250 | .in |
80a99f39 MK |
251 | These fields are as follows: |
252 | .TP | |
2fadbfb5 | 253 | .B QSIZE |
80a99f39 MK |
254 | Number of bytes of data in all messages in the queue. |
255 | .TP | |
256 | .B NOTIFY_PID | |
c7094399 | 257 | If this is nonzero, then the process with this PID has used |
80a99f39 | 258 | .BR mq_notify (3) |
c13182ef | 259 | to register for asynchronous message notification, |
80a99f39 MK |
260 | and the remaining fields describe how notification occurs. |
261 | .TP | |
262 | .B NOTIFY | |
263 | Notification method: | |
c13182ef | 264 | 0 is |
80a99f39 MK |
265 | .BR SIGEV_SIGNAL ; |
266 | 1 is | |
4df883b9 | 267 | .BR SIGEV_NONE ; |
c13182ef | 268 | and |
80a99f39 MK |
269 | 2 is |
270 | .BR SIGEV_THREAD . | |
271 | .TP | |
272 | .B SIGNO | |
273 | Signal number to be used for | |
274 | .BR SIGEV_SIGNAL . | |
275 | .SS Polling message queue descriptors | |
276 | On Linux, a message queue descriptor is actually a file descriptor, | |
277 | and can be monitored using | |
278 | .BR select (2), | |
279 | .BR poll (2), | |
280 | or | |
2315114c | 281 | .BR epoll (7). |
80a99f39 | 282 | This is not portable. |
1f1d2a8d MK |
283 | .SS IPC namespaces |
284 | For a discussion of the interaction of System V IPC objects and | |
285 | IPC namespaces, see | |
286 | .BR namespaces (7). | |
47297adb | 287 | .SH CONFORMING TO |
80a99f39 MK |
288 | POSIX.1-2001. |
289 | .SH NOTES | |
290 | System V message queues | |
291 | .RB ( msgget (2), | |
292 | .BR msgsnd (2), | |
293 | .BR msgrcv (2), | |
294 | etc.) are an older API for exchanging messages between processes. | |
295 | POSIX message queues provide a better designed interface than | |
c13182ef MK |
296 | System V message queues; |
297 | on the other hand POSIX message queues are less widely available | |
80a99f39 | 298 | (especially on older systems) than System V message queues. |
8f36e23f MK |
299 | |
300 | Linux does not currently (2.6.26) support the use of access control | |
301 | lists (ACLs) for POSIX message queues. | |
80a99f39 MK |
302 | .SH EXAMPLE |
303 | An example of the use of various message queue functions is shown in | |
304 | .BR mq_notify (3). | |
47297adb | 305 | .SH SEE ALSO |
80a99f39 | 306 | .BR getrlimit (2), |
694ae673 | 307 | .BR mq_getsetattr (2), |
f0c34053 MK |
308 | .BR poll (2), |
309 | .BR select (2), | |
80a99f39 MK |
310 | .BR mq_close (3), |
311 | .BR mq_getattr (3), | |
312 | .BR mq_notify (3), | |
313 | .BR mq_open (3), | |
314 | .BR mq_receive (3), | |
315 | .BR mq_send (3), | |
316 | .BR mq_unlink (3), | |
4effb5be MK |
317 | .BR epoll (7), |
318 | .BR namespaces (7) |