man7/mq_overview.7

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