1.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" Portions of this text are reprinted and reproduced in electronic form 29.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 30.\" Portable Operating System Interface (POSIX), The Open Group Base 31.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 32.\" Electrical and Electronics Engineers, Inc and The Open Group. In the 33.\" event of any discrepancy between this version and the original IEEE and 34.\" The Open Group Standard, the original IEEE and The Open Group Standard is 35.\" the referee document. The original Standard can be obtained online at 36.\" http://www.opengroup.org/unix/online.html. 37.\" 38.Dd September 26, 2023 39.Dt MQ_OPEN 2 40.Os 41.Sh NAME 42.Nm mq_open 43.Nd "open a message queue (REALTIME)" 44.Sh LIBRARY 45.Lb librt 46.Sh SYNOPSIS 47.In mqueue.h 48.Ft mqd_t 49.Fn mq_open "const char *name" "int oflag" "..." 50.Sh DESCRIPTION 51The 52.Fn mq_open 53system call establishes the connection between a process and a message queue 54with a message queue descriptor. 55It creates an open message queue 56description that refers to the message queue, and a message queue descriptor 57that refers to that open message queue description. 58The message queue 59descriptor is used by other functions to refer to that message queue. 60The 61.Fa name 62argument points to a string naming a message queue. 63The 64.Fa name 65argument should conform to the construction rules for a pathname. 66The 67.Fa name 68should begin with a slash character. 69Processes calling 70.Fn mq_open 71with the same value of 72.Fa name 73refers to the same message queue object, as long as that name has not been 74removed. 75If the 76.Fa name 77argument is not the name of an existing message queue and creation is not 78requested, 79.Fn mq_open 80will fail and return an error. 81.Pp 82The 83.Fa oflag 84argument requests the desired receive and/or send access to the message 85queue. 86The requested access permission to receive messages or send messages 87would be granted if the calling process would be granted read or write access, 88respectively, to an equivalently protected file. 89.Pp 90The value of 91.Fa oflag 92is the bitwise-inclusive OR of values from the following list. 93Applications should specify exactly one of the first three values (access 94modes) below in the value of 95.Fa oflag : 96.Bl -tag -width ".Dv O_NONBLOCK" 97.It Dv O_RDONLY 98Open the message queue for receiving messages. 99The process can use the 100returned message queue descriptor with 101.Fn mq_receive , 102but not 103.Fn mq_send . 104A message queue may be open multiple times in the same or different processes 105for receiving messages. 106.It Dv O_WRONLY 107Open the queue for sending messages. 108The process can use the returned 109message queue descriptor with 110.Fn mq_send 111but not 112.Fn mq_receive . 113A message queue may be open multiple times in the same or different processes 114for sending messages. 115.It Dv O_RDWR 116Open the queue for both receiving and sending messages. 117The process can use 118any of the functions allowed for 119.Dv O_RDONLY 120and 121.Dv O_WRONLY . 122A message queue may be open multiple times in the same or different processes 123for sending messages. 124.El 125.Pp 126Any combination of the remaining flags may be specified in the value of 127.Fa oflag : 128.Bl -tag -width ".Dv O_NONBLOCK" 129.It Dv O_CREAT 130Create a message queue. 131It requires two additional arguments: 132.Fa mode , 133which is of type 134.Vt mode_t , 135and 136.Fa attr , 137which is a pointer to an 138.Vt mq_attr 139structure. 140If the pathname 141.Fa name 142has already been used to create a message queue that still exists, then 143this flag has no effect, except as noted under 144.Dv O_EXCL . 145Otherwise, a message queue will be created without any messages 146in it. 147The user ID of the message queue will be set to the effective user ID 148of the process, and the group ID of the message queue will be set to the 149effective group ID of the process. 150The permission bits of the message queue 151will be set to the value of the 152.Fa mode 153argument, except those set in the file mode creation mask of the process. 154When bits in 155.Fa mode 156other than the file permission bits are specified, the effect is 157unspecified. 158If 159.Fa attr 160is 161.Dv NULL , 162the message queue is created with implementation-defined default message 163queue attributes. 164If attr is 165.Pf non- Dv NULL 166and the calling process has the 167appropriate privilege on name, the message queue 168.Va mq_maxmsg 169and 170.Va mq_msgsize 171attributes will be set to the values of the corresponding members in the 172.Vt mq_attr 173structure referred to by 174.Fa attr . 175If 176.Fa attr 177is 178.Pf non- Dv NULL , 179but the calling process does not have the appropriate privilege 180on name, the 181.Fn mq_open 182function will fail and return an error without creating the message queue. 183.It Dv O_EXCL 184If 185.Dv O_EXCL 186and 187.Dv O_CREAT 188are set, 189.Fn mq_open 190will fail if the message queue name exists. 191.It Dv O_NONBLOCK 192Determines whether an 193.Fn mq_send 194or 195.Fn mq_receive 196waits for resources or messages that are not currently available, or fails 197with 198.Va errno 199set to 200.Er EAGAIN ; 201see 202.Xr mq_send 2 203and 204.Xr mq_receive 2 205for details. 206.El 207.Pp 208The 209.Fn mq_open 210system call does not add or remove messages from the queue. 211.Sh NOTES 212.Fx 213implements message queue based on file descriptor. 214The descriptor 215is inherited by child after 216.Xr fork 2 . 217The descriptor is closed in a new image after 218.Xr exec 3 . 219The 220.Xr select 2 221and 222.Xr kevent 2 223system calls are supported for message queue descriptor. 224.Pp 225Please see the 226.Xr mqueuefs 5 227man page for instructions on loading the module or compiling the service into 228the kernel. 229.Pp 230The number of queues available, the maximum number of messages per queue 231and the maximum message size are tunable 232.Xr sysctl 8 233parameters. 234Their defaults are as follows. 235.Bl -column kern.mqueue.maxmsgsize integerxxx 236.It Sy "Name Type Default" 237.It "kern.mqueue.maxmq integer 100" 238.It "kern.mqueue.maxmsgsize integer 16384" 239.It "kern.mqueue.maxmsg integer 100" 240.El 241.Sh RETURN VALUES 242Upon successful completion, the function returns a message queue 243descriptor; otherwise, the function returns 244.Po Vt mqd_t Pc Ns \-1 245and sets the global variable 246.Va errno 247to indicate the error. 248.Sh ERRORS 249The 250.Fn mq_open 251system call 252will fail if: 253.Bl -tag -width Er 254.It Bq Er EACCES 255The message queue exists and the permissions specified by 256.Fa oflag 257are denied, or the message queue does not exist and permission to create the 258message queue is denied. 259.It Bq Er EEXIST 260.Dv O_CREAT 261and 262.Dv O_EXCL 263are set and the named message queue already exists. 264.It Bq Er EINTR 265The 266.Fn mq_open 267function was interrupted by a signal. 268.It Bq Er EINVAL 269The 270.Fn mq_open 271function is not supported for the given name. 272.It Bq Er EINVAL 273.Dv O_CREAT 274was specified in 275.Fa oflag , 276the value of 277.Fa attr 278is not 279.Dv NULL , 280and either 281.Va mq_maxmsg 282or 283.Va mq_msgsize 284was less than or equal to zero. 285.It Bq Er EMFILE 286Too many message queue descriptors or file descriptors are currently in use 287by this process. 288.It Bq Er ENAMETOOLONG 289The length of the 290.Fa name 291argument exceeds 292.Brq Dv PATH_MAX 293or a pathname component 294is longer than 295.Brq Dv NAME_MAX . 296.It Bq Er ENFILE 297Too many message queues are currently open in the system. 298.It Bq Er ENOENT 299.Dv O_CREAT 300is not set and the named message queue does not exist. 301.It Bq Er ENOSPC 302There is insufficient space for the creation of the new message queue. 303.El 304.Sh SEE ALSO 305.Xr mq_close 2 , 306.Xr mq_getattr 2 , 307.Xr mq_receive 2 , 308.Xr mq_send 2 , 309.Xr mq_setattr 2 , 310.Xr mq_unlink 2 , 311.Xr mq_timedreceive 3 , 312.Xr mq_timedsend 3 , 313.Xr mqueuefs 5 314.Sh STANDARDS 315The 316.Fn mq_open 317system call conforms to 318.St -p1003.1-2004 . 319.Sh HISTORY 320Support for POSIX message queues first appeared in 321.Fx 7.0 . 322.Sh BUGS 323This implementation places strict requirements on the value of 324.Fa name : 325it must begin with a slash 326.Pq Ql / 327and contain no other slash characters. 328.Pp 329The 330.Fa mode 331and 332.Fa attr 333arguments are variadic and may result in different calling conventions 334than might otherwise be expected. 335.Sh COPYRIGHT 336Portions of this text are reprinted and reproduced in electronic form 337from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 338Portable Operating System Interface (POSIX), The Open Group Base 339Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 340Electrical and Electronics Engineers, Inc and The Open Group. In the 341event of any discrepancy between this version and the original IEEE and 342The Open Group Standard, the original IEEE and The Open Group Standard is 343the referee document. The original Standard can be obtained online at 344http://www.opengroup.org/unix/online.html. 345