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