man7/mq_overview.7

   1 '\" t
   2 .\" Hey Emacs! This file is -*- nroff -*- source.
   3 .\"
   4 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .TH MQ_OVERVIEW 7 2008-06-15 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 mq_overview \- Overview of POSIX message queues
  29 .SH DESCRIPTION
  30 POSIX message queues allow processes to exchange data in
  31 the form of messages.
  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
  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.
  44 Each message queue is identified by a name of the form
  45 .IR /somename .
  46 Two processes can operate on the same queue by passing the same name to
  47 .BR mq_open (3).
  48
  49 Messages are transferred to and from a queue using
  50 .BR mq_send (3)
  51 and
  52 .BR mq_receive (3).
  53 When a process has finished using the queue, it closes it using
  54 .BR mq_close (3),
  55 and when the queue is no longer required, it can be deleted using
  56 .BR mq_unlink (3).
  57 Queue attributes can be retrieved and (in some cases) modified using
  58 .BR mq_getattr (3)
  59 and
  60 .BR mq_setattr (3).
  61 A process can request asynchronous notification
  62 of the arrival of a message on a previously empty queue using
  63 .BR mq_notify (3).
  64
  65 A message queue descriptor is a reference to an
  66 .I "open message queue description"
  67 (cf.
  68 .BR open (2)).
  69 After a
  70 .BR fork (2),
  71 a child inherits copies of its parent's message queue descriptors,
  72 and these descriptors refer to the same open message queue descriptions
  73 as the corresponding descriptors in the parent.
  74 Corresponding descriptors in the two processes share the flags
  75 .RI ( mq_flags )
  76 that are associated with the open message queue description.
  77
  78 Each message has an associated
  79 .IR priority ,
  80 and messages are always delivered to the receiving process
  81 highest priority first.
  82 Message priorities range from 0 (low) to
  83 .I sysconf(_SC_MQ_PRIO_MAX)\ -\ 1
  84 (high).
  85 On Linux,
  86 .I sysconf(_SC_MQ_PRIO_MAX)
  87 returns 32768, but POSIX.1-2001 only requires
  88 an implementation to support priorities in the range 0 to 31;
  89 some implementations only provide this range.
  90 .PP
  91 The remainder of this section describes some specific details
  92 of the Linux implementation of POSIX message queues.
  93 .SS Library interfaces and system calls
  94 In most cases the
  95 .B mq_*()
  96 library interfaces listed above are implemented
  97 on top of underlying system calls of the same name.
  98 Deviations from this scheme are indicated in the following table:
  99 .in +4n
 100 .TS
 101 lB lB
 102 l l.
 103 Library interface       System call
 104 mq_close(3)     close(2)
 105 mq_getattr(3)   mq_getsetattr(2)
 106 mq_open(3)      mq_open(2)
 107 mq_receive(3)   mq_timedreceive(2)
 108 mq_send(3)      mq_timedsend(2)
 109 mq_setattr(3)   mq_getsetattr(2)
 110 mq_timedreceive(3)      mq_timedreceive(2)
 111 mq_timedsend(3) mq_timedsend(2)
 112 mq_unlink(3)    mq_unlink(2)
 113 .TE
 114 .in
 115 .SS Versions
 116 POSIX message queues have been supported on Linux since kernel 2.6.6.
 117 Glibc support has been provided since version 2.3.4.
 118 .SS Kernel configuration
 119 Support for POSIX message queues is configurable via the
 120 .B CONFIG_POSIX_MQUEUE
 121 kernel configuration option.
 122 This option is enabled by default.
 123 .SS Persistence
 124 POSIX message queues have kernel persistence:
 125 if not removed by
 126 .BR mq_unlink (3),
 127 a message queue will exist until the system is shut down.
 128 .SS Linking
 129 Programs using the POSIX message queue API must be compiled with
 130 .I cc \-lrt
 131 to link against the real-time library,
 132 .IR librt .
 133 .SS /proc interfaces
 134 The following interfaces can be used to limit the amount of
 135 kernel memory consumed by POSIX message queues:
 136 .TP
 137 .I /proc/sys/fs/mqueue/msg_max
 138 This file can be used to view and change the ceiling value for the
 139 maximum number of messages in a queue.
 140 This value acts as a ceiling on the
 141 .I attr\->mq_maxmsg
 142 argument given to
 143 .BR mq_open (3).
 144 The default and minimum value for
 145 .I msg_max
 146 is 10; the upper limit is
 147 .BR HARD_MAX :
 148 .IR "(131072\ /\ sizeof(void\ *))"
 149 (32768 on Linux/86).
 150 This limit is ignored for privileged processes
 151 .RB ( CAP_SYS_RESOURCE ),
 152 but the
 153 .BR HARD_MAX
 154 ceiling is nevertheless imposed.
 155 .TP
 156 .I /proc/sys/fs/mqueue/msgsize_max
 157 This file can be used to view and change the ceiling on the
 158 maximum message size.
 159 This value acts as a ceiling on the
 160 .I attr\->mq_msgsize
 161 argument given to
 162 .BR mq_open (3).
 163 The default and minimum value for
 164 .I msgsize_max
 165 is 8192 bytes; the upper limit is
 166 .B INT_MAX
 167 (2147483647 on Linux/86).
 168 This limit is ignored for privileged processes
 169 .RB ( CAP_SYS_RESOURCE ).
 170 .TP
 171 .I /proc/sys/fs/mqueue/queues_max
 172 This file can be used to view and change the system-wide limit on the
 173 number of message queues that can be created.
 174 Only privileged processes
 175 .RB ( CAP_SYS_RESOURCE )
 176 can create new message queues once this limit has been reached.
 177 The default value for
 178 .I queues_max
 179 is 256; it can be changed to any value in the range 0 to INT_MAX.
 180 .SS Resource limit
 181 The
 182 .B RLIMIT_MSGQUEUE
 183 resource limit, which places a limit on the amount of space
 184 that can be consumed by all of the message queues
 185 belonging to a process's real user ID, is described in
 186 .BR getrlimit (2).
 187 .SS Mounting the message queue file system
 188 On Linux, message queues are created in a virtual file system.
 189 (Other implementations may also provide such a feature,
 190 but the details are likely to differ.)
 191 This file system can be mounted using the following commands:
 192 .in +4n
 193 .nf
 194
 195 $ mkdir /dev/mqueue
 196 $ mount -t mqueue none /dev/mqueue
 197
 198 .fi
 199 .in
 200 The sticky bit is automatically enabled on the mount directory.
 201
 202 After the file system has been mounted, the message queues on the system
 203 can be viewed and manipulated using the commands usually used for files
 204 (e.g.,
 205 .BR ls (1)
 206 and
 207 .BR rm (1)).
 208
 209 The contents of each file in the directory consist of a single line
 210 containing information about the queue:
 211 .in +4n
 212 .nf
 213
 214 $ ls /dev/mqueue/mymq
 215 QSIZE:129     NOTIFY:2    SIGNO:0    NOTIFY_PID:8260
 216 $ mount -t mqueue none /dev/mqueue
 217
 218 .fi
 219 .in
 220 These fields are as follows:
 221 .TP
 222 .B
 223 QSIZE
 224 Number of bytes of data in all messages in the queue.
 225 .TP
 226 .B NOTIFY_PID
 227 If this is non-zero, then the process with this PID has used
 228 .BR mq_notify (3)
 229 to register for asynchronous message notification,
 230 and the remaining fields describe how notification occurs.
 231 .TP
 232 .B NOTIFY
 233 Notification method:
 234 0 is
 235 .BR SIGEV_SIGNAL ;
 236 1 is
 237 .BR SIGEV_NONE ;
 238 and
 239 2 is
 240 .BR SIGEV_THREAD .
 241 .TP
 242 .B SIGNO
 243 Signal number to be used for
 244 .BR SIGEV_SIGNAL .
 245 .SS Polling message queue descriptors
 246 On Linux, a message queue descriptor is actually a file descriptor,
 247 and can be monitored using
 248 .BR select (2),
 249 .BR poll (2),
 250 or
 251 .BR epoll (7).
 252 This is not portable.
 253 .SH "CONFORMING TO"
 254 POSIX.1-2001.
 255 .SH NOTES
 256 System V message queues
 257 .RB ( msgget (2),
 258 .BR msgsnd (2),
 259 .BR msgrcv (2),
 260 etc.) are an older API for exchanging messages between processes.
 261 POSIX message queues provide a better designed interface than
 262 System V message queues;
 263 on the other hand POSIX message queues are less widely available
 264 (especially on older systems) than System V message queues.
 265
 266 Linux does not currently (2.6.26) support the use of access control
 267 lists (ACLs) for POSIX message queues.
 268 .SH EXAMPLE
 269 An example of the use of various message queue functions is shown in
 270 .BR mq_notify (3).
 271 .SH "SEE ALSO"
 272 .BR getrlimit (2),
 273 .BR mq_getsetattr (2),
 274 .BR mq_close (3),
 275 .BR mq_getattr (3),
 276 .BR mq_notify (3),
 277 .BR mq_open (3),
 278 .BR mq_receive (3),
 279 .BR mq_send (3),
 280 .BR mq_unlink (3),
 281 .BR poll (2),
 282 .BR select (2),
 283 .BR epoll (4)