diff options
Diffstat (limited to 'man7/mq_overview.7')
| -rw-r--r-- | man7/mq_overview.7 | 389 |
1 files changed, 0 insertions, 389 deletions
diff --git a/man7/mq_overview.7 b/man7/mq_overview.7 deleted file mode 100644 index 223f238..0000000 --- a/man7/mq_overview.7 +++ /dev/null @@ -1,389 +0,0 @@ -'\" t -.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH mq_overview 7 2023-10-31 "Linux man-pages 6.7" -.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) |