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