diff options
Diffstat (limited to 'man/man7/mq_overview.7')
| -rw-r--r-- | man/man7/mq_overview.7 | 389 |
1 files changed, 389 insertions, 0 deletions
diff --git a/man/man7/mq_overview.7 b/man/man7/mq_overview.7 new file mode 100644 index 000000000..51ad14d3a --- /dev/null +++ b/man/man7/mq_overview.7 @@ -0,0 +1,389 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_overview 7 (date) "Linux man-pages (unreleased)" +.SH NAME +mq_overview \- overview of POSIX message queues +.SH DESCRIPTION +POSIX message queues allow processes to exchange data in +the form of messages. +This API is distinct from that provided by System V message queues +.RB ( msgget (2), +.BR msgsnd (2), +.BR msgrcv (2), +etc.), but provides similar functionality. +.P +Message queues are created and opened using +.BR mq_open (3); +this function returns a +.I message queue descriptor +.RI ( mqd_t ), +which is used to refer to the open message queue in later calls. +Each message queue is identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.B NAME_MAX +(i.e., 255) characters consisting of an initial slash, +followed by one or more characters, none of which are slashes. +Two processes can operate on the same queue by passing the same name to +.BR mq_open (3). +.P +Messages are transferred to and from a queue using +.BR mq_send (3) +and +.BR mq_receive (3). +When a process has finished using the queue, it closes it using +.BR mq_close (3), +and when the queue is no longer required, it can be deleted using +.BR mq_unlink (3). +Queue attributes can be retrieved and (in some cases) modified using +.BR mq_getattr (3) +and +.BR mq_setattr (3). +A process can request asynchronous notification +of the arrival of a message on a previously empty queue using +.BR mq_notify (3). +.P +A message queue descriptor is a reference to an +.I "open message queue description" +(see +.BR open (2)). +After a +.BR fork (2), +a child inherits copies of its parent's message queue descriptors, +and these descriptors refer to the same open message queue descriptions +as the corresponding message queue descriptors in the parent. +Corresponding message queue descriptors in the two processes share the flags +.RI ( mq_flags ) +that are associated with the open message queue description. +.P +Each message has an associated +.IR priority , +and messages are always delivered to the receiving process +highest priority first. +Message priorities range from 0 (low) to +.I sysconf(_SC_MQ_PRIO_MAX)\ \-\ 1 +(high). +On Linux, +.I sysconf(_SC_MQ_PRIO_MAX) +returns 32768, but POSIX.1 requires only that +an implementation support at least priorities in the range 0 to 31; +some implementations provide only this range. +.P +The remainder of this section describes some specific details +of the Linux implementation of POSIX message queues. +.SS Library interfaces and system calls +In most cases the +.BR mq_* () +library interfaces listed above are implemented +on top of underlying system calls of the same name. +Deviations from this scheme are indicated in the following table: +.RS +.TS +lB lB +l l. +Library interface System call +mq_close(3) close(2) +mq_getattr(3) mq_getsetattr(2) +mq_notify(3) mq_notify(2) +mq_open(3) mq_open(2) +mq_receive(3) mq_timedreceive(2) +mq_send(3) mq_timedsend(2) +mq_setattr(3) mq_getsetattr(2) +mq_timedreceive(3) mq_timedreceive(2) +mq_timedsend(3) mq_timedsend(2) +mq_unlink(3) mq_unlink(2) +.TE +.RE +.SS Versions +POSIX message queues have been supported since Linux 2.6.6. +glibc support has been provided since glibc 2.3.4. +.SS Kernel configuration +Support for POSIX message queues is configurable via the +.B CONFIG_POSIX_MQUEUE +kernel configuration option. +This option is enabled by default. +.SS Persistence +POSIX message queues have kernel persistence: +if not removed by +.BR mq_unlink (3), +a message queue will exist until the system is shut down. +.SS Linking +Programs using the POSIX message queue API must be compiled with +.I cc \-lrt +to link against the real-time library, +.IR librt . +.SS /proc interfaces +The following interfaces can be used to limit the amount of +kernel memory consumed by POSIX message queues and to set +the default attributes for new message queues: +.TP +.IR /proc/sys/fs/mqueue/msg_default " (since Linux 3.5)" +This file defines the value used for a new queue's +.I mq_maxmsg +setting when the queue is created with a call to +.BR mq_open (3) +where +.I attr +is specified as NULL. +The default value for this file is 10. +The minimum and maximum are as for +.IR /proc/sys/fs/mqueue/msg_max . +A new queue's default +.I mq_maxmsg +value will be the smaller of +.I msg_default +and +.IR msg_max . +Before Linux 2.6.28, the default +.I mq_maxmsg +was 10; +from Linux 2.6.28 to Linux 3.4, the default was the value defined for the +.I msg_max +limit. +.TP +.I /proc/sys/fs/mqueue/msg_max +This file can be used to view and change the ceiling value for the +maximum number of messages in a queue. +This value acts as a ceiling on the +.I attr\->mq_maxmsg +argument given to +.BR mq_open (3). +The default value for +.I msg_max +is 10. +The minimum value is 1 (10 before Linux 2.6.28). +The upper limit is +.BR HARD_MSGMAX . +The +.I msg_max +limit is ignored for privileged processes +.RB ( CAP_SYS_RESOURCE ), +but the +.B HARD_MSGMAX +ceiling is nevertheless imposed. +.IP +The definition of +.B HARD_MSGMAX +has changed across kernel versions: +.RS +.IP \[bu] 3 +Up to Linux 2.6.32: +.I 131072\~/\~sizeof(void\~*) +.IP \[bu] +Linux 2.6.33 to Linux 3.4: +.I (32768\~*\~sizeof(void\~*) / 4) +.IP \[bu] +Since Linux 3.5: +.\" commit 5b5c4d1a1440e94994c73dddbad7be0676cd8b9a +65,536 +.RE +.TP +.IR /proc/sys/fs/mqueue/msgsize_default " (since Linux 3.5)" +This file defines the value used for a new queue's +.I mq_msgsize +setting when the queue is created with a call to +.BR mq_open (3) +where +.I attr +is specified as NULL. +The default value for this file is 8192 (bytes). +The minimum and maximum are as for +.IR /proc/sys/fs/mqueue/msgsize_max . +If +.I msgsize_default +exceeds +.IR msgsize_max , +a new queue's default +.I mq_msgsize +value is capped to the +.I msgsize_max +limit. +Before Linux 2.6.28, the default +.I mq_msgsize +was 8192; +from Linux 2.6.28 to Linux 3.4, the default was the value defined for the +.I msgsize_max +limit. +.TP +.I /proc/sys/fs/mqueue/msgsize_max +This file can be used to view and change the ceiling on the +maximum message size. +This value acts as a ceiling on the +.I attr\->mq_msgsize +argument given to +.BR mq_open (3). +The default value for +.I msgsize_max +is 8192 bytes. +The minimum value is 128 (8192 before Linux 2.6.28). +The upper limit for +.I msgsize_max +has varied across kernel versions: +.RS +.IP \[bu] 3 +Before Linux 2.6.28, the upper limit is +.BR INT_MAX . +.IP \[bu] +From Linux 2.6.28 to Linux 3.4, the limit is 1,048,576. +.IP \[bu] +Since Linux 3.5, the limit is 16,777,216 +.RB ( HARD_MSGSIZEMAX ). +.RE +.IP +The +.I msgsize_max +limit is ignored for privileged process +.RB ( CAP_SYS_RESOURCE ), +but, since Linux 3.5, the +.B HARD_MSGSIZEMAX +ceiling is enforced for privileged processes. +.TP +.I /proc/sys/fs/mqueue/queues_max +This file can be used to view and change the system-wide limit on the +number of message queues that can be created. +The default value for +.I queues_max +is 256. +No ceiling is imposed on the +.I queues_max +limit; privileged processes +.RB ( CAP_SYS_RESOURCE ) +can exceed the limit (but see BUGS). +.SS Resource limit +The +.B RLIMIT_MSGQUEUE +resource limit, which places a limit on the amount of space +that can be consumed by all of the message queues +belonging to a process's real user ID, is described in +.BR getrlimit (2). +.SS Mounting the message queue filesystem +On Linux, message queues are created in a virtual filesystem. +(Other implementations may also provide such a feature, +but the details are likely to differ.) +This filesystem can be mounted (by the superuser) using the following +commands: +.P +.in +4n +.EX +.RB "#" " mkdir /dev/mqueue" +.RB "#" " mount \-t mqueue none /dev/mqueue" +.EE +.in +.P +The sticky bit is automatically enabled on the mount directory. +.P +After the filesystem has been mounted, the message queues on the system +can be viewed and manipulated using the commands usually used for files +(e.g., +.BR ls (1) +and +.BR rm (1)). +.P +The contents of each file in the directory consist of a single line +containing information about the queue: +.P +.in +4n +.EX +.RB "$" " cat /dev/mqueue/mymq" +QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260 +.EE +.in +.P +These fields are as follows: +.TP +.B QSIZE +Number of bytes of data in all messages in the queue (but see BUGS). +.TP +.B NOTIFY_PID +If this is nonzero, then the process with this PID has used +.BR mq_notify (3) +to register for asynchronous message notification, +and the remaining fields describe how notification occurs. +.TP +.B NOTIFY +Notification method: +0 is +.BR SIGEV_SIGNAL ; +1 is +.BR SIGEV_NONE ; +and +2 is +.BR SIGEV_THREAD . +.TP +.B SIGNO +Signal number to be used for +.BR SIGEV_SIGNAL . +.SS Linux implementation of message queue descriptors +On Linux, a message queue descriptor is actually a file descriptor. +(POSIX does not require such an implementation.) +This means that a message queue descriptor can be monitored using +.BR select (2), +.BR poll (2), +or +.BR epoll (7). +This is not portable. +.P +The close-on-exec flag (see +.BR open (2)) +is automatically set on the file descriptor returned by +.BR mq_open (2). +.SS IPC namespaces +For a discussion of the interaction of POSIX message queue objects and +IPC namespaces, see +.BR ipc_namespaces (7). +.SH NOTES +System V message queues +.RB ( msgget (2), +.BR msgsnd (2), +.BR msgrcv (2), +etc.) are an older API for exchanging messages between processes. +POSIX message queues provide a better designed interface than +System V message queues; +on the other hand POSIX message queues are less widely available +(especially on older systems) than System V message queues. +.P +Linux does not currently (Linux 2.6.26) support the use of access control +lists (ACLs) for POSIX message queues. +.SH BUGS +Since Linux 3.5 to Linux 3.14, the kernel imposed a ceiling of 1024 +.RB ( HARD_QUEUESMAX ) +on the value to which the +.I queues_max +limit could be raised, +and the ceiling was enforced even for privileged processes. +This ceiling value was removed in Linux 3.14, +and patches to stable Linux 3.5.x to Linux 3.13.x also removed the ceiling. +.P +As originally implemented (and documented), +the QSIZE field displayed the total number of (user-supplied) +bytes in all messages in the message queue. +Some changes in Linux 3.5 +.\" commit d6629859b36d +inadvertently changed the behavior, +so that this field also included a count of kernel overhead bytes +used to store the messages in the queue. +This behavioral regression was rectified in Linux 4.2 +.\" commit de54b9ac253787c366bbfb28d901a31954eb3511 +(and earlier stable kernel series), +so that the count once more included just the bytes of user data +in messages in the queue. +.SH EXAMPLES +An example of the use of various message queue functions is shown in +.BR mq_notify (3). +.SH SEE ALSO +.BR getrlimit (2), +.BR mq_getsetattr (2), +.BR poll (2), +.BR select (2), +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR epoll (7), +.BR namespaces (7) |