1.\" $NetBSD: mq_open.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ 2.\" 3.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 4.\" 5.Dd October 19, 2019 6.Dt MQ_OPEN 2 7.Os 8.Sh NAME 9.Nm mq_open 10.Nd open a message queue (REALTIME) 11.Sh LIBRARY 12.Lb librt 13.Sh SYNOPSIS 14.In mqueue.h 15.Ft mqd_t 16.Fn mq_open "const char *name" "int oflag" 17.In sys/types.h 18.Ft mqd_t 19.Fn mq_open "const char *name" "int oflag" "mode_t mode" "struct mq_attr *attr" 20.Sh DESCRIPTION 21The 22.Fn mq_open 23function establishes the connection between a process and a message queue 24with a message queue descriptor. 25It creates an open message queue description that refers to the message 26queue, and a message queue descriptor that refers to that open message 27queue description. 28The message queue descriptor is used by other functions to refer to that 29message queue. 30The 31.Fa name 32argument points to a string naming a message queue, 33which should conform to the construction rules for a pathname. 34The 35.Fa name 36should begin with a slash character. 37The processes calling 38.Fn mq_open 39with the same value of 40.Fa name 41will refer to the same message queue object, 42as long as that name has not been removed. 43If the 44.Fa name 45argument is not 46the name of an existing message queue and creation is not requested, 47.Fn mq_open 48fails and returns an error. 49.Pp 50The 51.Fa oflag 52argument requests the desired receive and/or send access to the message queue. 53The requested access permission to receive messages or send messages are 54granted if the calling process would be granted read or write access, 55respectively, to an equivalently protected file. 56.Pp 57The value of 58.Fa oflag 59is the bitwise-inclusive OR of values from the following list. 60Applications must specify exactly one of the first three values 61(access modes) below in the value of 62.Fa oflag : 63.Bl -tag -width ".Dv O_RDONLY" 64.It Dv O_RDONLY 65Open the message queue for receiving messages. 66The process can use the returned message queue descriptor with 67.Xr mq_receive 2 , 68but not 69.Xr mq_send 2 . 70.It Dv O_WRONLY 71Open the queue for sending messages. 72The process can use the returned message queue descriptor with 73.Xr mq_send 2 74but not 75.Xr mq_receive 2 . 76.It Dv O_RDWR 77Open the queue for both receiving and sending messages. 78The process can use any of the functions allowed for 79.Dv O_RDONLY 80and 81.Dv O_WRONLY . 82.El 83.Pp 84In all cases, a message queue may be open multiple times in the same 85or different processes for sending/receiving messages. 86.Pp 87Any combination of the remaining flags may be specified in the value of 88.Fa oflag : 89.Bl -tag -width ".Dv O_RDONLY" 90.It Dv O_CREAT 91Create a message queue. 92It requires two additional arguments: 93.Fa mode 94and 95.Fa attr . 96If the pathname 97.Fa name 98has already been used to create a message queue that still exists, 99then this flag will have no effect, except as noted under 100.Dv O_EXCL . 101Otherwise, a message queue will be created without any messages in it. 102The user ID of the message queue will be set to the effective user ID 103of the process, and the group ID of the message queue will be set to 104the effective group ID of the process. 105The permission bits of the message queue will be set to the value of the 106.Fa mode 107argument, except those set in the file mode creation mask of 108the process. 109When bits in 110.Fa mode 111other than the file permission bits are specified, the effect 112is unspecified. 113If 114.Fa attr 115is 116.Dv NULL , 117the message queue will be created with implementation-defined default 118message queue attributes. 119If 120.Fa attr 121is 122.No non- Ns Dv NULL 123and the calling process has the appropriate privilege on 124.Fa name , 125the message queue 126.Va mq_maxmsg 127and 128.Va mq_msgsize 129attributes will be set to the values of the corresponding members in the 130.Vt mq_attr 131structure referred to by 132.Fa attr . 133If 134.Fa attr 135is 136.No non- Ns Dv NULL , 137but the calling process does not have the 138appropriate privilege on 139.Fa name , 140the 141.Fn mq_open 142function will fail and return an error without creating the message queue. 143.It Dv O_EXCL 144If 145.Dv O_EXCL 146and 147.Dv O_CREAT 148are set, 149.Fn mq_open 150fails if the message queue 151.Fa name 152exists. 153The check for the existence of the message queue and the creation of the 154message queue if it does not exist will be atomic with respect to other 155threads executing 156.Fn mq_open 157naming the same 158.Fa name 159with 160.Dv O_EXCL 161and 162.Dv O_CREAT 163set. 164If 165.Dv O_EXCL 166is set and 167.Dv O_CREAT 168is not set, the result is undefined. 169.It Dv O_NONBLOCK 170Determines whether an 171.Xr mq_send 2 172or 173.Xr mq_receive 2 174waits for resources or messages that are not currently available, 175or fails with errno set to 176.Er EAGAIN . 177.El 178.Pp 179The 180.Fn mq_open 181function does not add or remove messages from the queue. 182.Sh NOTES 183The 184.Xr select 2 185and 186.Xr poll 2 187system calls to the message queue descriptor are supported by 188.Dx , 189however, it is not portable. 190.Sh RETURN VALUES 191Upon successful completion, 192.Fn mq_open 193returns a message queue descriptor. 194Otherwise, the function returns 195.Pq Vt mqd_t 196\-1 and sets the global variable 197.Va errno 198to indicate the error. 199.Sh ERRORS 200The 201.Fn mq_open 202function fails if: 203.Bl -tag -width Er 204.It Bq Er EACCES 205The message queue exists and the permissions specified by 206.Fa oflag 207are denied, or the message queue does not exist and permission 208to create the message queue is denied. 209.It Bq Er EEXIST 210.Dv O_CREAT 211and 212.Dv O_EXCL 213are set and the named message queue already exists. 214.It Bq Er EINTR 215The 216.Fn mq_open 217function was interrupted by a signal. 218.It Bq Er EINVAL 219The 220.Fn mq_open 221function is not supported for the given name, or 222.Dv O_CREAT 223was specified in 224.Fa oflag , 225the value of 226.Fa attr 227is not 228.Dv NULL , 229and either 230.Va mq_maxmsg 231or 232.Va mq_msgsize 233was less than or equal to zero. 234.It Bq Er EMFILE 235Too many message queue descriptors or file descriptors are currently 236in use by this process. 237.It Bq Er ENAMETOOLONG 238The length of the 239.Fa name 240argument exceeds 241.Brq Dv PATH_MAX 242or a pathname component is longer than 243.Brq Dv NAME_MAX . 244.It Bq Er ENFILE 245Too many message queues are currently open in the system. 246.It Bq Er ENOENT 247.Dv O_CREAT 248is not set and the named message queue does not exist. 249.It Bq Er ENOSPC 250There is insufficient space for the creation of the new message queue. 251.El 252.Sh SEE ALSO 253.Xr mq_close 2 , 254.Xr mq_getattr 2 , 255.Xr mq_notify 2 , 256.Xr mq_receive 2 , 257.Xr mq_send 2 , 258.Xr mq_setattr 2 , 259.Xr mq_unlink 2 260.Sh STANDARDS 261This function conforms to the 262.St -p1003.1-2001 263standard. 264.Sh HISTORY 265This function first appeared in 266.Dx 2.5 . 267.Sh COPYRIGHT 268Portions of this text are reprinted and reproduced in electronic form 269from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology 270-- Portable Operating System Interface (POSIX), The Open Group Base 271Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of 272Electrical and Electronics Engineers, Inc and The Open Group. 273In the 274event of any discrepancy between this version and the original IEEE and 275The Open Group Standard, the original IEEE and The Open Group Standard 276is the referee document. 277The original Standard can be obtained online at 278http://www.opengroup.org/unix/online.html . 279