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