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.Dd September 28, 2019 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.Sh RETURN VALUES 230Upon successful completion, the function returns a message queue 231descriptor; otherwise, the function returns 232.Po Vt mqd_t Pc Ns \-1 233and sets the global variable 234.Va errno 235to indicate the error. 236.Sh ERRORS 237The 238.Fn mq_open 239system call 240will fail if: 241.Bl -tag -width Er 242.It Bq Er EACCES 243The message queue exists and the permissions specified by 244.Fa oflag 245are denied, or the message queue does not exist and permission to create the 246message queue is denied. 247.It Bq Er EEXIST 248.Dv O_CREAT 249and 250.Dv O_EXCL 251are set and the named message queue already exists. 252.It Bq Er EINTR 253The 254.Fn mq_open 255function was interrupted by a signal. 256.It Bq Er EINVAL 257The 258.Fn mq_open 259function is not supported for the given name. 260.It Bq Er EINVAL 261.Dv O_CREAT 262was specified in 263.Fa oflag , 264the value of 265.Fa attr 266is not 267.Dv NULL , 268and either 269.Va mq_maxmsg 270or 271.Va mq_msgsize 272was less than or equal to zero. 273.It Bq Er EMFILE 274Too many message queue descriptors or file descriptors are currently in use 275by this process. 276.It Bq Er ENAMETOOLONG 277The length of the 278.Fa name 279argument exceeds 280.Brq Dv PATH_MAX 281or a pathname component 282is longer than 283.Brq Dv NAME_MAX . 284.It Bq Er ENFILE 285Too many message queues are currently open in the system. 286.It Bq Er ENOENT 287.Dv O_CREAT 288is not set and the named message queue does not exist. 289.It Bq Er ENOSPC 290There is insufficient space for the creation of the new message queue. 291.El 292.Sh SEE ALSO 293.Xr mq_close 2 , 294.Xr mq_getattr 2 , 295.Xr mq_receive 2 , 296.Xr mq_send 2 , 297.Xr mq_setattr 2 , 298.Xr mq_unlink 2 , 299.Xr mq_timedreceive 3 , 300.Xr mq_timedsend 3 , 301.Xr mqueuefs 5 302.Sh STANDARDS 303The 304.Fn mq_open 305system call conforms to 306.St -p1003.1-2004 . 307.Sh HISTORY 308Support for POSIX message queues first appeared in 309.Fx 7.0 . 310.Sh BUGS 311This implementation places strict requirements on the value of 312.Fa name : 313it must begin with a slash 314.Pq Ql / 315and contain no other slash characters. 316.Pp 317The 318.Fa mode 319and 320.Fa attr 321arguments are variadic and may result in different calling conventions 322than might otherwise be expected. 323.Sh COPYRIGHT 324Portions of this text are reprinted and reproduced in electronic form 325from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 326Portable Operating System Interface (POSIX), The Open Group Base 327Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 328Electrical and Electronics Engineers, Inc and The Open Group. In the 329event of any discrepancy between this version and the original IEEE and 330The Open Group Standard, the original IEEE and The Open Group Standard is 331the referee document. The original Standard can be obtained online at 332http://www.opengroup.org/unix/online.html. 333