.\" $NetBSD: mq.3,v 1.1 2010/06/07 07:11:28 jruoho Exp $
.\"
.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@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.