POSIXMQCONTROL(1) FreeBSD General Commands Manual POSIXMQCONTROL(1)
NAME
posixmqcontrol - Control POSIX mqueuefs message queues
SYNOPSIS
posixmqcontrol create -q queue -s size -d depth [-m mode] [-g group]
[-u user]
posixmqcontrol info -q queue
posixmqcontrol recv -q queue
posixmqcontrol rm -q queue
posixmqcontrol send -q queue -c content [-p priority]
DESCRIPTION
The posixmqcontrol command allows separating POSIX message queue
administration from application stack. Defining and adjusting queue
attributes can be done without touching application code. It allows
creating queues, inspecting queue metadata, altering group and user
access to queues, dumping queue contents, and unlinking queues.
Unlinking removes the name from the system and frees underlying memory.
The maximum message size, maximum queue size, and current queue size are
displayed by the info subcommand. This output is similar to running cat
on a mqueuefs queue mounted under a mount point. This utility requires
the mqueuefs kernel module to be loaded but does not require mqueuefs to
be mounted as a file system.
The following subcommands are provided:
create Create the named queues, if they do not already exist. More
than one queue name may be created. The same maximum queue
depth and maximum message size are used to create all queues.
If a queue exists, then depth and size are optional.
The required size and depth arguments specify the maximum
message size (bytes per message) and maximum queue size (depth
or number of messages in the queue). The optional numerical
mode argument specifies the initial access mode. If the queue
exists but does not match the requested size and depth, this
utility will attempt to recreate the queue by first unlinking
and then creating it. This will fail if the queue is not empty
or is opened by other processes.
rm Unlink the queues specified - one attempt per queue. Failure
to unlink one queue does not stop this sub-command from
attempting to unlink the others.
info For each named queue, dispay the maximum message size, maximum
queue size, current queue depth, user owner id, group owner id,
and mode permission bits.
recv Wait for a message from a single named queue and display the
message to standard output.
send Send messages to one or more named queues. If multiple
messages and multiple queues are specified, the utility
attempts to send all messages to all queues. The optional -p
priority, if omitted, defaults to MQ_PRIO_MAX / 2 or medium
priority.
NOTES
A change of queue geometry (maximum message size and/or maximum number of
messages) requires destroying and re-creating the queue. As a safety
feature, the create subcommand refuses to destroy a non-empty queue. If
you use the rm subcommand to destroy a queue, any queued messages are
lost. To avoid down-time when altering queue attributes, consider
creating a new queue and configure reading applications to drain both new
and old queues. Retire the old queue once all writers have been updated
to write to the new queue.
EXIT STATUS
The posixmqcontrol utility exits 0 on success, and >0 if an error occurs.
o EX_NOTAVAILABLE usually means the mqueuefs kernel module is not
loaded.
o EX_USAGE reports one or more incorrect parameters.
EXAMPLES
o To retrieve the current message from a named queue, /1, use the
command
posixmqcontrol recv -q /1
o To create a queue with the name /2 with maximum message size 100 and
maximum queue depth 10, use the command
posixmqcontrol create -q /2 -s 100 -d 10
o To send a message to a queue with the name /3 use the command
posixmqcontrol send -q /3 -c 'some choice words.'
o To examine attributes of a queue named /4 use the command
posixmqcontrol info -q /4
SEE ALSO
mq_getattr(2), mq_open(2), mq_receive(2), mq_send(2), mq_setattr(2),
mq_unlink(2), mqueuefs(5)
BUGS
mq_timedsend and mq_timedrecv are not implemented. info reports a worst-
case estimate for QSIZE.
HISTORY
The posixmqcontrol command appeared in FreeBSD 15.0.
AUTHORS
The posixmqcontrol command and this manual page were written by Rick
Parrish <
[email protected].>
FreeBSD 14.1-RELEASE-p8 February 19, 2024 FreeBSD 14.1-RELEASE-p8