Module Name: src
Committed By: jruoho
Date: Mon Jun 7 07:11:28 UTC 2010
Modified Files:
src/distrib/sets/lists/comp: mi
src/lib/librt: Makefile
Added Files:
src/lib/librt: mq.3
Log Message:
Add mq(3), a manual page for the POSIX message queues. This tries to act as
a short introduction to the rationale and API, noting also some pros and cons.
rmind@: basically ok. Please feel free to adjust, correct, and extend.
To generate a diff of this commit:
cvs rdiff -u -r1.1456 -r1.1457 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.11 -r1.12 src/lib/librt/Makefile
cvs rdiff -u -r0 -r1.1 src/lib/librt/mq.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1456 src/distrib/sets/lists/comp/mi:1.1457
--- src/distrib/sets/lists/comp/mi:1.1456 Fri Jun 4 08:37:09 2010
+++ src/distrib/sets/lists/comp/mi Mon Jun 7 07:11:27 2010
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1456 2010/06/04 08:37:09 jmmv Exp $
+# $NetBSD: mi,v 1.1457 2010/06/07 07:11:27 jruoho Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -7167,6 +7167,7 @@
./usr/share/man/cat3/mpool_open.0 comp-c-catman .cat
./usr/share/man/cat3/mpool_put.0 comp-c-catman .cat
./usr/share/man/cat3/mpool_sync.0 comp-c-catman .cat
+./usr/share/man/cat3/mq.0 comp-c-catman .cat
./usr/share/man/cat3/mq_close.0 comp-c-catman .cat
./usr/share/man/cat3/mq_getattr.0 comp-c-catman .cat
./usr/share/man/cat3/mq_notify.0 comp-c-catman .cat
@@ -7175,6 +7176,7 @@
./usr/share/man/cat3/mq_send.0 comp-c-catman .cat
./usr/share/man/cat3/mq_setattr.0 comp-c-catman .cat
./usr/share/man/cat3/mq_unlink.0 comp-c-catman .cat
+./usr/share/man/cat3/mqueue.0 comp-c-catman .cat
./usr/share/man/cat3/mrand48.0 comp-c-catman .cat
./usr/share/man/cat3/mvaddch.0 comp-c-catman .cat
./usr/share/man/cat3/mvaddchnstr.0 comp-c-catman .cat
@@ -12992,6 +12994,7 @@
./usr/share/man/html3/mpool_open.html comp-c-htmlman html
./usr/share/man/html3/mpool_put.html comp-c-htmlman html
./usr/share/man/html3/mpool_sync.html comp-c-htmlman html
+./usr/share/man/html3/mq.html comp-c-htmlman html
./usr/share/man/html3/mq_close.html comp-c-htmlman html
./usr/share/man/html3/mq_getattr.html comp-c-htmlman html
./usr/share/man/html3/mq_notify.html comp-c-htmlman html
@@ -13000,6 +13003,7 @@
./usr/share/man/html3/mq_send.html comp-c-htmlman html
./usr/share/man/html3/mq_setattr.html comp-c-htmlman html
./usr/share/man/html3/mq_unlink.html comp-c-htmlman html
+./usr/share/man/html3/mqueue.html comp-c-htmlman html
./usr/share/man/html3/mrand48.html comp-c-htmlman html
./usr/share/man/html3/mvaddch.html comp-c-htmlman html
./usr/share/man/html3/mvaddchnstr.html comp-c-htmlman html
@@ -18805,6 +18809,7 @@
./usr/share/man/man3/mpool_open.3 comp-c-man .man
./usr/share/man/man3/mpool_put.3 comp-c-man .man
./usr/share/man/man3/mpool_sync.3 comp-c-man .man
+./usr/share/man/man3/mq.3 comp-c-man .man
./usr/share/man/man3/mq_close.3 comp-c-man .man
./usr/share/man/man3/mq_getattr.3 comp-c-man .man
./usr/share/man/man3/mq_notify.3 comp-c-man .man
@@ -18813,6 +18818,7 @@
./usr/share/man/man3/mq_send.3 comp-c-man .man
./usr/share/man/man3/mq_setattr.3 comp-c-man .man
./usr/share/man/man3/mq_unlink.3 comp-c-man .man
+./usr/share/man/man3/mqueue.3 comp-c-man .man
./usr/share/man/man3/mrand48.3 comp-c-man .man
./usr/share/man/man3/mvaddch.3 comp-c-man .man
./usr/share/man/man3/mvaddchnstr.3 comp-c-man .man
Index: src/lib/librt/Makefile
diff -u src/lib/librt/Makefile:1.11 src/lib/librt/Makefile:1.12
--- src/lib/librt/Makefile:1.11 Mon May 17 17:15:42 2010
+++ src/lib/librt/Makefile Mon Jun 7 07:11:28 2010
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.11 2010/05/17 17:15:42 jruoho Exp $
+# $NetBSD: Makefile,v 1.12 2010/06/07 07:11:28 jruoho Exp $
#
WARNS= 2
@@ -9,12 +9,14 @@
MAN+= aio.3 aio_cancel.3 aio_error.3 aio_fsync.3 aio_read.3 aio_return.3 \
aio_suspend.3 aio_write.3 lio_listio.3 \
- mq_close.3 mq_getattr.3 mq_notify.3 mq_open.3 mq_receive.3 \
+ mq.3 mq_close.3 mq_getattr.3 mq_notify.3 mq_open.3 mq_receive.3 \
mq_send.3 mq_setattr.3 mq_unlink.3 \
pset.3 sched.3 \
sem_destroy.3 sem_getvalue.3 sem_init.3 sem_open.3 sem_post.3 \
sem_wait.3
+MLINKS+= mq.3 mqueue.3
+
MLINKS+= sem_open.3 sem_close.3
MLINKS+= sem_open.3 sem_unlink.3
MLINKS+= sem_wait.3 sem_trywait.3
Added files:
Index: src/lib/librt/mq.3
diff -u /dev/null src/lib/librt/mq.3:1.1
--- /dev/null Mon Jun 7 07:11:29 2010
+++ src/lib/librt/mq.3 Mon Jun 7 07:11:28 2010
@@ -0,0 +1,400 @@
+.\" $NetBSD: mq.3,v 1.1 2010/06/07 07:11:28 jruoho Exp $
+.\"
+.\" Copyright (c) 2010 Jukka Ruohonen <jruoho...@iki.fi>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd May 26, 2010
+.Dt MQ 3
+.Os
+.Sh NAME
+.Nm mq
+.Nd POSIX message queues (REALTIME)
+.Sh LIBRARY
+.Lb librt
+.Sh SYNOPSIS
+.In mqueue.h
+.Sh DESCRIPTION
+The
+.St -p1003.1-2001
+standard defines and
+.Nx
+implements an interprocess communication
+.Pq Tn IPC
+interface known as
+.Tn POSIX
+message queues.
+Although the basic functionality is similar,
+.Nm
+is distinct from the older
+.At V
+message queues (see for example
+.Xr ipcs 1
+or
+.Xr msgget 2 ) .
+.Pp
+.Ss Rationale
+The rationale behind
+.Nm
+is to provide an efficient, priority-driven asynchronous
+.Tn IPC
+mechanism.
+When the
+.At V
+message queues were first implemented, the reasoning was similar:
+the only form of
+.Tn IPC
+was half-duplex pipes and message queues were
+seen to overcome the performance limitations with these.
+.Pp
+But arguably in modern systems there is little difference between
+the efficiency of the System V message queues, pipes, and
+.Tn UNIX
+domain sockets (if anything, the
+.At V
+message queues tend to be slower than the rest).
+The fundamental performance bottleneck is however still there with
+.Nm
+as well: data must be first copied from the sender to the kernel
+and then from the kernel to the receiver.
+The bigger the message, the higher the overhead.
+.Pp
+For realtime applications,
+.Nm
+offers some advantages:
+.Pp
+.Bl -enum -offset 2n
+.It
+Unlike the predecessors,
+.Nm
+provides an asynchronous notification mechanism.
+.It
+Messages are prioritized.
+The queue always remains sorted such that the
+oldest message of the highest priority is always received first,
+regardless of the number of messages in the queue.
+.It
+By default, the functions to send and receive messages are blocking calls.
+It is however possible to use non-blocking variants with
+.Nm .
+Furthermore, it is possible to specify timeouts to avoid
+non-deterministic blocking.
+.It
+Resource limits can be enforced \&-- or perhaps more importantly,
+the availability of resources can be ensured as the internal
+data structures are preallocated.
+.El
+.Ss Descriptors and Naming
+Comparable to pipes and
+.Tn FIFOs
+.Pq a.k.a. named pipes ,
+all
+.Tn POSIX
+message queue operations are performed by using a descriptor.
+The used type is
+.Vt mqd_t ,
+an abbreviation from a
+.Dq message queue descriptor .
+In the
+.Nx
+implementation this is actuallly an ordinary file descriptor.
+This means that it is possible, but not portable, to
+monitor a message queue descriptor by using
+.Xr poll 2
+or
+.Xr select 2 .
+.Pp
+Message queues are named by character
+strings that represents (absolute) pathnames.
+The used interface is analogous to the conventional file concepts.
+But unlike
+.Tn FIFOs
+and pipes, neither
+.Tn POSIX
+nor System V message queues are accessed by using
+.Xr open 2 ,
+.Xr read 2 ,
+or
+.Xr write 2 .
+Instead, equivalents such as
+.Fn mq_open ,
+.Fn mq_close ,
+and
+.Fn mq_unlink
+are used.
+.Pp
+The standard does not specify whether
+.Tn POSIX
+message queues are exposed at the file system level.
+In the
+.Nx
+implementation these are not seen in the file system.
+Thus, it can be argued that
+.Nm
+inherited an old problem with the System V message queues.
+Even if an implementation would have support for it,
+it is not portable to view message queues by
+.Xr ls 1 ,
+remove these with
+.Xr rm 1 ,
+or adjust the permissions with
+.Xr chmod 1 .
+.Ss Processes
+When a new process is created or the program is terminated,
+message queues behave like files.
+More specifically, when
+.Xr fork 2
+is called, files and message queues are inherited, and when the
+program terminates by calling
+.Xr exit 3
+or
+.Xr _exit 2 ,
+both file descriptors and message queues are closed.
+However, the
+.Xr exec 3
+family of functions behave somewhat differently for
+message queues and files: all message queues are
+closed when a process calls one of the
+.Fn exec
+functions.
+In this respect
+.Tn POSIX
+message queues are closer to
+.Tn FIFOs
+than normal pipes.
+.Ss Attributes
+All message queues have an attribute associated with them.
+This is represented by the
+.Va mq_attr
+structure:
+.Bd -literal -offset indent
+struct mq_attr {
+ long mq_flags;
+ long mq_maxmsg;
+ long mq_msgsize;
+ long mq_curmsgs;
+};
+.Ed
+.Pp
+The members in the the structure are:
+flags set for the message queue
+.Pq Va mq_flags ,
+the maximum number of messages in the queue
+.Pq Va mq_maxmsg ,
+the maximum size of each message
+.Pq Va mq_msgsize ,
+and the number of queued messages
+.Pq Va mq_curmsgs .
+.Pp
+The overall resource requirements for a particular message queue are given by
+.Va mq_maxmsg
+and
+.Va mq_msgsize .
+These two can be specified when the queue is created by a call to
+.Fn mq_open .
+The constraints are enforced through the lifetime of the queue:
+an error is returned if a message larger than
+.Va mq_msgsize
+is sent, and if the message queue is already full, as determined by
+.Va mq_maxmsg ,
+the call to queue a message will either block or error out.
+.Pp
+Although there are two functions,
+.Fn mq_getattr
+and
+.Fn mq_setattr ,
+to retrieve and set attributes once
+the message queue has been created,
+the resource limits cannot be changed
+by an user once the queue has been created.
+.\" The super user can however control the limits via few
+.\" .Xr sysctl 7
+.\" variables.
+To avoid blocking in case the maximum number of messages has been reached, the
+.Dv O_NONBLOCK
+flag can be set as an argument to
+.Fn mq_open .
+.Ss Asynchronous Notification
+Instead of blocking in the functions that receive messages,
+.Nm
+offers an asynchronous mechanism for a process to receive
+notifications that messages are available in the message queue.
+The function
+.Fn mq_notify
+is used to register for notification.
+Either a signal or a thread can be used as the type of notification; see
+.Xr sigevent 3
+for details.
+.Pp
+Bear in mind that no notification is sent for an arrival
+of a message to a non-empty message queue.
+In other words,
+.Fn mq_notify
+does not by itself ensure that a process
+will be notified every time a message arrives.
+Thus, after having called
+.Fn mq_notify ,
+an application may need to repeatedly call
+.Fn mq_receive
+until the queue is empty.
+This requires that the message queue was created with the
+.Dv O_NONBLOCK
+flag; otherwise
+.Fn mq_receive
+blocks until a message is again queued
+or the call is interrupted by a signal.
+This may be a limitation for some realtime applications.
+.Ss Priorities
+Each message has a priority, ranging from 0 to the implementation-defined
+.Dv MQ_PRIO_MAX .
+The
+.Tn POSIX
+standard enforces the minimum value of the maximum priority to be 32.
+All messages are inserted into a message
+queue according to the specified priority.
+High priority messages are sent before low priority messages.
+If the used priority is constant,
+.Nm
+follows the
+.Tn FIFO
+.Pq First In, First Out
+principle.
+.Pp
+The basic rule of thumb with realtime prioritization is that low priority
+tasks should never unnecessarily delay high priority tasks.
+Priority inheritance is not however part of the provided
+.Tn API .
+The receiver process may run at low priority even
+when receiving high priority messages.
+To address this limitation and other potential realtime problems,
+the user may consider other functions from the
+.Lb librt .
+The process scheduling interface described in
+.Xr sched 3
+can be mentioned as an example.
+.\"
+.\" XXX: Move this to sysctl(7).
+.\"
+.\" .Sh SYSCTL
+.\" The
+.\" .Nx
+.\" implementation defines few
+.\" .Xr sysctl 8
+.\" variables available for the superuser.
+.\" .Bl -tag -width "kern.mq_max_msgsize "-offset indent
+.\" .It kern.posix_msg
+.\" The version of the
+.\" .Tn POSIX
+.\" standard to which the system attempts
+.\" to conform with respect to the message queues.
+.\" .It kern.mq_open_max
+.\" The maximum number of message queue descriptors
+.\" that any process is able to open.
+.\" .It kern.mq_prio_max
+.\" The maximum priority of any message.
+.\" .It kern.mq_max_msgsize
+.\" The maximum size of any message.
+.\" .It kern.mq_def_maxmsg
+.\" The default number of messages in a message queue.
+.\" .El
+.Sh FUNCTIONS
+The following functions are available in the
+.Tn API.
+.Bl -column -offset indent "mq_timedreceive " "XXX"
+.It Sy Function Ta Sy Description
+.It Xr mq_open 3 Ta open a message queue
+.It Xr mq_close 3 Ta close a message queue
+.It Xr mq_unlink 3 Ta remove a message queue
+.It Xr mq_send 3 Ta send a message
+.It Xr mq_receive 3 Ta receive a message
+.It Xr mq_timedsend 3 Ta send a message with a timeout
+.It Xr mq_timedreceive 3 Ta receive a message with a timeout
+.It Xr mq_getattr 3 Ta get message queue attributes
+.It Xr mq_setattr 3 Ta set message queue attributes
+.It Xr mq_notify 3 Ta register asynchronous notify
+.El
+.\"
+.\" XXX: Fill this with fileops?
+.\"
+.\" .In addition, the
+.\" .Nx
+.\" implementation allows the following standard
+.\" .Tn I/O
+.\" and file manipulation calls to be used with message queues:
+.\" The following functions are available in the
+.\" .Tn API.
+.\" .Bl -column -offset indent "mq_timedreceive " "XXX"
+.\" .It Sy Function Ta Sy Description
+.\" .It Xr ...
+.\" .El
+.Sh COMPATIBILITY
+Despite of some early fears, the
+.Tn POSIX
+message queue implementations are fairly compatible with each other.
+Nevertheless, few points can be noted for portable applications.
+.Bl -bullet
+.It
+It is not portable to use functions external to the
+.Tn API
+with message queue descriptors.
+.It
+The standard leaves the rules loose with
+respect to the message queue names.
+Only the interpretation of the first slash character is consistent;
+the following slash characters may or may not follow the conventional
+construction rules for a pathname.
+.It
+The length limits for a message queue name are implementation-defined.
+These may or may not follow the conventional pathname limits
+.Dv PATH_MAX
+and
+.Dv NAME_MAX .
+.El
+.Sh SEE ALSO
+.Rs
+.%A Bill O. Gallmeister
+.%T POSIX.4: Programming for the Real World
+.%I O'Reilly and Associates
+.%D 1995
+.Re
+.Rs
+.%A Richard W. Stevens
+.%T UNIX Network Programming, Volume 2: Interprocess Communications
+.%V Second Edition
+.%I Prentice Hall
+.%D 1998
+.Re
+.Sh STANDARDS
+The
+.Tn POSIX
+message queue implementation is expected to conform to
+.St -p1003.1-2001 .
+.Sh HISTORY
+The
+.Tn POSIX
+message queue
+.Tn API
+first appeared in
+.Nx 5.0 .
+.Sh CAVEATS
+User should be careful to unlink message queues at the program termination.
+Otherwise it is possible to leave them lying around.
