1.\" $NetBSD: mq.3,v 1.3 2010/06/07 16:33:45 wiz Exp $ 2.\" 3.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 15.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 16.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 17.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 18.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd May 26, 2010 27.Dt MQ 3 28.Os 29.Sh NAME 30.Nm mq 31.Nd POSIX message queues (REALTIME) 32.Sh LIBRARY 33.Lb librt 34.Sh SYNOPSIS 35.In mqueue.h 36.Sh DESCRIPTION 37The 38.St -p1003.1-2001 39standard defines and 40.Nx 41implements an interprocess communication 42.Pq Tn IPC 43interface known as 44.Tn POSIX 45message queues. 46Although the basic functionality is similar, 47.Nm 48is distinct from the older 49.At V 50message queues (see for example 51.Xr ipcs 1 52or 53.Xr msgget 2 ) . 54.Ss Rationale 55The rationale behind 56.Nm 57is to provide an efficient, priority-driven asynchronous 58.Tn IPC 59mechanism. 60When the 61.At V 62message queues were first implemented, the reasoning was similar: 63the only form of 64.Tn IPC 65was half-duplex pipes and message queues were 66seen to overcome the performance limitations with these. 67.Pp 68But arguably in modern systems there is little difference between 69the efficiency of the System V message queues, pipes, and 70.Tn UNIX 71domain sockets (if anything, the 72.At V 73message queues tend to be slower than the rest). 74The fundamental performance bottleneck is however still there with 75.Nm 76as well: data must be first copied from the sender to the kernel 77and then from the kernel to the receiver. 78The bigger the message, the higher the overhead. 79.Pp 80For realtime applications, 81.Nm 82offers some advantages: 83.Pp 84.Bl -enum -offset 2n 85.It 86Unlike the predecessors, 87.Nm 88provides an asynchronous notification mechanism. 89.It 90Messages are prioritized. 91The queue always remains sorted such that the 92oldest message of the highest priority is always received first, 93regardless of the number of messages in the queue. 94.It 95By default, the functions to send and receive messages are blocking calls. 96It is however possible to use non-blocking variants with 97.Nm . 98Furthermore, it is possible to specify timeouts to avoid 99non-deterministic blocking. 100.It 101Resource limits can be enforced \&-- or perhaps more importantly, 102the availability of resources can be ensured as the internal 103data structures are preallocated. 104.El 105.Ss Descriptors and Naming 106Comparable to pipes and 107.Tn FIFOs 108.Pq a.k.a. named pipes , 109all 110.Tn POSIX 111message queue operations are performed by using a descriptor. 112The used type is 113.Vt mqd_t , 114an abbreviation from a 115.Dq message queue descriptor . 116In the 117.Nx 118implementation this is actually an ordinary file descriptor. 119This means that it is possible, but not portable, to 120monitor a message queue descriptor by using 121.Xr poll 2 122or 123.Xr select 2 . 124.Pp 125Message queues are named by character 126strings that represent (absolute) pathnames. 127The used interface is analogous to the conventional file concepts. 128But unlike 129.Tn FIFOs 130and pipes, neither 131.Tn POSIX 132nor System V message queues are accessed by using 133.Xr open 2 , 134.Xr read 2 , 135or 136.Xr write 2 . 137Instead, equivalents such as 138.Fn mq_open , 139.Fn mq_close , 140and 141.Fn mq_unlink 142are used. 143.Pp 144The standard does not specify whether 145.Tn POSIX 146message queues are exposed at the file system level. 147In the 148.Nx 149implementation these are not seen in the file system. 150Thus, it can be argued that 151.Nm 152inherited an old problem with the System V message queues. 153Even if an implementation would have support for it, 154it is not portable to view message queues by 155.Xr ls 1 , 156remove these with 157.Xr rm 1 , 158or adjust the permissions with 159.Xr chmod 1 . 160.Ss Processes 161When a new process is created or the program is terminated, 162message queues behave like files. 163More specifically, when 164.Xr fork 2 165is called, files and message queues are inherited, and when the 166program terminates by calling 167.Xr exit 3 168or 169.Xr _exit 2 , 170both file descriptors and message queues are closed. 171However, the 172.Xr exec 3 173family of functions behave somewhat differently for 174message queues and files: all message queues are 175closed when a process calls one of the 176.Fn exec 177functions. 178In this respect 179.Tn POSIX 180message queues are closer to 181.Tn FIFOs 182than normal pipes. 183.Ss Attributes 184All message queues have an attribute associated with them. 185This is represented by the 186.Va mq_attr 187structure: 188.Bd -literal -offset indent 189struct mq_attr { 190 long mq_flags; 191 long mq_maxmsg; 192 long mq_msgsize; 193 long mq_curmsgs; 194}; 195.Ed 196.Pp 197The members in the the structure are: 198flags set for the message queue 199.Pq Va mq_flags , 200the maximum number of messages in the queue 201.Pq Va mq_maxmsg , 202the maximum size of each message 203.Pq Va mq_msgsize , 204and the number of queued messages 205.Pq Va mq_curmsgs . 206.Pp 207The overall resource requirements for a particular message queue are given by 208.Va mq_maxmsg 209and 210.Va mq_msgsize . 211These two can be specified when the queue is created by a call to 212.Fn mq_open . 213The constraints are enforced through the lifetime of the queue: 214an error is returned if a message larger than 215.Va mq_msgsize 216is sent, and if the message queue is already full, as determined by 217.Va mq_maxmsg , 218the call to queue a message will either block or error out. 219.Pp 220Although there are two functions, 221.Fn mq_getattr 222and 223.Fn mq_setattr , 224to retrieve and set attributes once 225the message queue has been created, 226the resource limits cannot be changed 227by an user once the queue has been created. 228To avoid blocking in case the maximum number of messages has been reached, the 229.Dv O_NONBLOCK 230flag can be set as an argument to 231.Fn mq_open . 232.Ss Asynchronous Notification 233Instead of blocking in the functions that receive messages, 234.Nm 235offers an asynchronous mechanism for a process to receive 236notifications that messages are available in the message queue. 237The function 238.Fn mq_notify 239is used to register for notification. 240Either a signal or a thread can be used as the type of notification; see 241.Xr sigevent 3 242for details. 243.Pp 244Bear in mind that no notification is sent for an arrival 245of a message to a non-empty message queue. 246In other words, 247.Fn mq_notify 248does not by itself ensure that a process 249will be notified every time a message arrives. 250Thus, after having called 251.Fn mq_notify , 252an application may need to repeatedly call 253.Fn mq_receive 254until the queue is empty. 255This requires that the message queue was created with the 256.Dv O_NONBLOCK 257flag; otherwise 258.Fn mq_receive 259blocks until a message is again queued 260or the call is interrupted by a signal. 261This may be a limitation for some realtime applications. 262.Ss Priorities 263Each message has a priority, ranging from 0 to the implementation-defined 264.Dv MQ_PRIO_MAX . 265The 266.Tn POSIX 267standard enforces the minimum value of the maximum priority to be 32. 268All messages are inserted into a message 269queue according to the specified priority. 270High priority messages are sent before low priority messages. 271If the used priority is constant, 272.Nm 273follows the 274.Tn FIFO 275.Pq First In, First Out 276principle. 277.Pp 278The basic rule of thumb with realtime prioritization is that low priority 279tasks should never unnecessarily delay high priority tasks. 280Priority inheritance is not however part of the provided 281.Tn API . 282The receiver process may run at low priority even 283when receiving high priority messages. 284To address this limitation and other potential realtime problems, 285the user may consider other functions from the 286.Lb librt . 287The process scheduling interface described in 288.Xr sched 3 289can be mentioned as an example. 290.Sh FUNCTIONS 291The following functions are available in the 292.Tn API . 293.Bl -column -offset indent "mq_timedreceive " "XXX" 294.It Sy Function Ta Sy Description 295.It Xr mq_open 3 Ta open a message queue 296.It Xr mq_close 3 Ta close a message queue 297.It Xr mq_unlink 3 Ta remove a message queue 298.It Xr mq_send 3 Ta send a message 299.It Xr mq_receive 3 Ta receive a message 300.It Xr mq_timedsend 3 Ta send a message with a timeout 301.It Xr mq_timedreceive 3 Ta receive a message with a timeout 302.It Xr mq_getattr 3 Ta get message queue attributes 303.It Xr mq_setattr 3 Ta set message queue attributes 304.It Xr mq_notify 3 Ta register asynchronous notify 305.El 306.Sh COMPATIBILITY 307Despite of some early fears, the 308.Tn POSIX 309message queue implementations are fairly compatible with each other. 310Nevertheless, few points can be noted for portable applications. 311.Bl -bullet 312.It 313It is not portable to use functions external to the 314.Tn API 315with message queue descriptors. 316.It 317The standard leaves the rules loose with 318respect to the message queue names. 319Only the interpretation of the first slash character is consistent; 320the following slash characters may or may not follow the conventional 321construction rules for a pathname. 322.It 323The length limits for a message queue name are implementation-defined. 324These may or may not follow the conventional pathname limits 325.Dv PATH_MAX 326and 327.Dv NAME_MAX . 328.El 329.Sh SEE ALSO 330.Rs 331.%A Bill O. Gallmeister 332.%T POSIX.4: Programming for the Real World 333.%I O'Reilly and Associates 334.%D 1995 335.Re 336.Rs 337.%A Richard W. Stevens 338.%T UNIX Network Programming, Volume 2: Interprocess Communications 339.%V Second Edition 340.%I Prentice Hall 341.%D 1998 342.Re 343.Sh STANDARDS 344The 345.Tn POSIX 346message queue implementation is expected to conform to 347.St -p1003.1-2001 . 348.Sh HISTORY 349The 350.Tn POSIX 351message queue 352.Tn API 353first appeared in 354.Nx 5.0 . 355.Sh CAVEATS 356User should be careful to unlink message queues at the program termination. 357Otherwise it is possible to leave them lying around. 358