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