Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Add mq(3), a manual page for the POSIX message queues. This ...
details: https://anonhg.NetBSD.org/src/rev/b1c4f9dae281
branches: trunk
changeset: 755479:b1c4f9dae281
user: jruoho <jruoho%NetBSD.org@localhost>
date: Mon Jun 07 07:11:27 2010 +0000
description:
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.
diffstat:
distrib/sets/lists/comp/mi | 8 +-
lib/librt/Makefile | 6 +-
lib/librt/mq.3 | 400 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 411 insertions(+), 3 deletions(-)
diffs (truncated from 486 to 300 lines):
diff -r 329b1f4dfa68 -r b1c4f9dae281 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Mon Jun 07 04:48:47 2010 +0000
+++ b/distrib/sets/lists/comp/mi Mon Jun 07 07:11:27 2010 +0000
@@ -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
diff -r 329b1f4dfa68 -r b1c4f9dae281 lib/librt/Makefile
--- a/lib/librt/Makefile Mon Jun 07 04:48:47 2010 +0000
+++ b/lib/librt/Makefile Mon Jun 07 07:11:27 2010 +0000
@@ -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
diff -r 329b1f4dfa68 -r b1c4f9dae281 lib/librt/mq.3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/librt/mq.3 Mon Jun 07 07:11:27 2010 +0000
@@ -0,0 +1,400 @@
+.\" $NetBSD: mq.3,v 1.1 2010/06/07 07:11:28 jruoho Exp $
+.\"
+.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen%iki.fi@localhost>
+.\"
+.\" 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:
Home |
Main Index |
Thread Index |
Old Index