NAME

posixmqcontrol — Control POSIX mqueuefs message queues

SYNOPSIS

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.

• EX_NOTAVAILABLE usually means the mqueuefs kernel module is not loaded.
• EX_USAGE reports one or more incorrect parameters.

EXAMPLES

• To retrieve the current message from a named queue, /1, use the command
  posixmqcontrol recv -q /1
• 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
• To send a message to a queue with the name /3 use the command
  posixmqcontrol send -q /3 -c 'some choice words.'
• 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 <unitrunker@unitrunker.net.>