1.\"- 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2024 Rick Parrish <unitrunker@unitrunker.net>. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd February 19, 2024 28.Dt POSIXMQCONTROL 1 29.Os 30.Sh NAME 31.Nm posixmqcontrol 32.Nd Control POSIX mqueuefs message queues 33.Sh SYNOPSIS 34.Nm 35.Ar create 36.Fl q Ar queue 37.Fl s Ar size 38.Fl d Ar depth 39.Op Fl m Ar mode 40.Op Fl g Ar group 41.Op Fl u Ar user 42.Nm 43.Ar info 44.Fl q Ar queue 45.Nm 46.Ar recv 47.Fl q Ar queue 48.Nm 49.Ar rm 50.Fl q Ar queue 51.Nm 52.Ar send 53.Fl q Ar queue 54.Fl c Ar content 55.Op Fl p Ar priority 56.Sh DESCRIPTION 57The 58.Nm 59command allows separating POSIX message queue administration from application 60stack. 61Defining and adjusting queue attributes can be done without touching 62application code. 63It allows creating queues, inspecting queue metadata, altering group and user 64access to queues, dumping queue contents, and unlinking queues. 65.Pp 66Unlinking removes the name from the system and frees underlying memory. 67.Pp 68The maximum message size, maximum queue size, and current queue size are 69displayed by the 70.Ic info 71subcommand. This output is similar to running 72.Ic cat 73on a mqueuefs queue mounted under a mount point. 74This utility requires the 75.Ic mqueuefs 76kernel module to be loaded but does not require 77.Ic mqueuefs 78to be mounted as a file system. 79.Pp 80The following subcommands are provided: 81.Bl -tag -width truncate 82.It Ic create 83Create the named queues, if they do not already exist. 84More than one queue name may be created. The same maximum queue depth and 85maximum message size are used to create all queues. 86If a queue exists, then depth and size are optional. 87.Pp 88The required 89.Ar size 90and 91.Ar depth 92arguments specify the maximum message size (bytes per message) and maximum queue 93size (depth or number of messages in the queue). 94The optional numerical 95.Ar mode 96argument specifies the initial access mode. 97If the queue exists but does not match the requested size and depth, this 98utility will attempt to recreate the queue by first unlinking and then creating 99it. 100This will fail if the queue is not empty or is opened by other processes. 101.It Ic rm 102Unlink the queues specified - one attempt per queue. 103Failure to unlink one queue does not stop this sub-command from attempting to 104unlink the others. 105.It Ic info 106For each named queue, dispay the maximum message size, maximum queue size, 107current queue depth, user owner id, group owner id, and mode permission bits. 108.It Ic recv 109Wait for a message from a single named queue and display the message to 110standard output. 111.It Ic send 112Send messages to one or more named queues. 113If multiple messages and multiple queues are specified, the utility attempts to 114send all messages to all queues. 115The optional -p priority, if omitted, defaults to MQ_PRIO_MAX / 2 or medium 116priority. 117.El 118.Sh NOTES 119A change of queue geometry (maximum message size and/or maximum number of 120messages) requires destroying and re-creating the queue. 121As a safety feature, 122the create subcommand refuses to destroy a non-empty queue. 123If you use the rm subcommand to destroy a queue, any queued messages are lost. 124To avoid down-time when altering queue attributes, consider creating a new 125queue and configure reading applications to drain both new and old queues. 126Retire the old queue once all writers have been updated to write to the new 127queue. 128.Sh EXIT STATUS 129.Ex -std 130.Bl -bullet 131.It 132EX_NOTAVAILABLE usually means the mqueuefs kernel module is not loaded. 133.It 134EX_USAGE reports one or more incorrect parameters. 135.El 136.Sh EXAMPLES 137.Bl -bullet 138.It 139To retrieve the current message from a named queue, 140.Pa /1 , 141use the command 142.Dl "posixmqcontrol recv -q /1" 143.It 144To create a queue with the name 145.Pa /2 146with maximum message size 100 and maximum queue depth 10, 147use the command 148.Dl "posixmqcontrol create -q /2 -s 100 -d 10" 149.It 150To send a message to a queue with the name 151.Pa /3 152use the command 153.Dl "posixmqcontrol send -q /3 -c 'some choice words.'" 154.It 155To examine attributes of a queue named 156.Pa /4 157use the command 158.Dl "posixmqcontrol info -q /4" 159.El 160.Sh SEE ALSO 161.Xr mq_open 2 , 162.Xr mq_getattr 2 , 163.Xr mq_receive 2 , 164.Xr mq_send 2 , 165.Xr mq_setattr 2 , 166.Xr mq_unlink 2 , 167.Xr mqueuefs 4 168.Sh BUGS 169mq_timedsend and mq_timedrecv are not implemented. 170info reports a worst-case estimate for QSIZE. 171.Sh HISTORY 172The 173.Nm 174command appeared in 175.Fx 14.1 . 176.Sh AUTHORS 177The 178.Nm 179command and this manual page were written by 180.An Rick Parrish Aq Mt unitrunker@unitrunker.net. 181