\" $NetBSD: mq.3,v 1.5 2011/02/26 12:56:35 wiz Exp $
\"
\" Copyright (c) 2010 Jukka Ruohonen <[email protected]>
\"
\" 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 July 28, 2010
Dt MQ 3
Os
Sh NAME
Nm mq ,
Nm mqueue
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 ) .
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 actually 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 represent (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.
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 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,
resource limits cannot be changed once the queue has been created.
In
Nx
the super user may however control the global resource limits by using few
Xr sysctl 7
variables.
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.
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
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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.