1MQ_OPEN(3P)                POSIX Programmer's Manual               MQ_OPEN(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       mq_open — open a message queue (REALTIME)
14

SYNOPSIS

16       #include <mqueue.h>
17
18       mqd_t mq_open(const char *name, int oflag, ...);
19

DESCRIPTION

21       The mq_open() function shall establish the connection between a process
22       and a message queue with a message queue descriptor. It shall create an
23       open message queue description that refers to the message queue, and  a
24       message  queue  descriptor  that  refers  to  that  open  message queue
25       description. The message queue descriptor is used by other functions to
26       refer  to that message queue. The name argument points to a string nam‐
27       ing a message queue. It is unspecified whether the name appears in  the
28       file  system  and  is visible to other functions that take pathnames as
29       arguments. The name argument conforms to the construction rules  for  a
30       pathname,  except  that  the interpretation of <slash> characters other
31       than the leading <slash> character in name  is  implementation-defined,
32       and  that  the  length limits for the name argument are implementation-
33       defined and need not be the same as the pathname limits {PATH_MAX}  and
34       {NAME_MAX}.   If name begins with the <slash> character, then processes
35       calling mq_open() with the same value of name shall refer to  the  same
36       message  queue  object,  as  long as that name has not been removed. If
37       name does not begin with the <slash> character, the effect is implemen‐
38       tation-defined.  If  the  name  argument is not the name of an existing
39       message queue and creation is not requested, mq_open() shall  fail  and
40       return an error.
41
42       A  message queue descriptor may be implemented using a file descriptor,
43       in which case applications can open up to at least {OPEN_MAX} file  and
44       message queues.
45
46       The  oflag  argument requests the desired receive and/or send access to
47       the message queue. The requested access permission to receive  messages
48       or  send  messages  shall  be  granted  if the calling process would be
49       granted read or write access, respectively,  to  an  equivalently  pro‐
50       tected file.
51
52       The  value of oflag is the bitwise-inclusive OR of values from the fol‐
53       lowing list.  Applications shall specify exactly one of the first three
54       values (access modes) below in the value of oflag:
55
56       O_RDONLY    Open  the message queue for receiving messages. The process
57                   can  use  the  returned  message  queue   descriptor   with
58                   mq_receive(),  but  not  mq_send().  A message queue may be
59                   open multiple times in the same or different processes  for
60                   receiving messages.
61
62       O_WRONLY    Open  the  queue  for sending messages. The process can use
63                   the returned message queue descriptor  with  mq_send()  but
64                   not  mq_receive().   A  message  queue may be open multiple
65                   times in the same or different processes for  sending  mes‐
66                   sages.
67
68       O_RDWR      Open the queue for both receiving and sending messages. The
69                   process can use any of the functions allowed  for  O_RDONLY
70                   and O_WRONLY. A message queue may be open multiple times in
71                   the same or different processes for sending messages.
72
73       Any combination of the remaining flags may be specified in the value of
74       oflag:
75
76       O_CREAT     Create  a  message  queue. It requires two additional argu‐
77                   ments: mode, which shall be of type mode_t, and attr, which
78                   shall be a pointer to an mq_attr structure. If the pathname
79                   name has already been used to create a message  queue  that
80                   still  exists,  then this flag shall have no effect, except
81                   as noted under O_EXCL.  Otherwise, a message queue shall be
82                   created without any messages in it. The user ID of the mes‐
83                   sage queue shall be set to the effective  user  ID  of  the
84                   process.  The group ID of the message queue shall be set to
85                   the effective group ID of the process; however, if the name
86                   argument is visible in the file system, the group ID may be
87                   set to the group ID of the containing directory. When  bits
88                   in  mode other than the file permission bits are specified,
89                   the effect is unspecified. If attr  is  NULL,  the  message
90                   queue  shall be created with implementation-defined default
91                   message queue attributes. If attr is non-NULL and the call‐
92                   ing process has appropriate privileges on name, the message
93                   queue mq_maxmsg and mq_msgsize attributes shall be  set  to
94                   the  values  of  the  corresponding  members in the mq_attr
95                   structure referred to by attr.  The values of the  mq_flags
96                   and  mq_curmsgs  members  of the mq_attr structure shall be
97                   ignored. If attr is non-NULL, but the calling process  does
98                   not  have  appropriate  privileges  on  name, the mq_open()
99                   function shall fail and return an  error  without  creating
100                   the message queue.
101
102       O_EXCL      If  O_EXCL and O_CREAT are set, mq_open() shall fail if the
103                   message queue name exists. The check for the  existence  of
104                   the  message queue and the creation of the message queue if
105                   it does not exist shall be atomic  with  respect  to  other
106                   threads  executing  mq_open()  naming  the  same  name with
107                   O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not
108                   set, the result is undefined.
109
110       O_NONBLOCK  Determines  whether  an mq_send() or mq_receive() waits for
111                   resources or messages that are not currently available,  or
112                   fails  with  errno  set  to  [EAGAIN];  see  mq_send()  and
113                   mq_receive() for details.
114
115       The mq_open() function does not add or remove messages from the queue.
116

RETURN VALUE

118       Upon successful completion, the function shall return a  message  queue
119       descriptor;  otherwise,  the  function  shall  return (mqd_t)−1 and set
120       errno to indicate the error.
121

ERRORS

123       The mq_open() function shall fail if:
124
125       EACCES The message queue exists and the permissions specified by  oflag
126              are  denied,  or the message queue does not exist and permission
127              to create the message queue is denied.
128
129       EEXIST O_CREAT and O_EXCL are set and the named message  queue  already
130              exists.
131
132       EINTR  The mq_open() function was interrupted by a signal.
133
134       EINVAL The mq_open() function is not supported for the given name.
135
136       EINVAL O_CREAT  was  specified in oflag, the value of attr is not NULL,
137              and either mq_maxmsg or mq_msgsize was less  than  or  equal  to
138              zero.
139
140       EMFILE Too  many message queue descriptors or file descriptors are cur‐
141              rently in use by this process.
142
143       ENFILE Too many message queues are currently open in the system.
144
145       ENOENT O_CREAT is not set and the named message queue does not exist.
146
147       ENOSPC There is insufficient space for the creation of the new  message
148              queue.
149
150       If  any  of  the following conditions occur, the mq_open() function may
151       return (mqd_t)−1 and set errno to the corresponding value.
152
153       ENAMETOOLONG
154              The length of the name  argument  exceeds  {_POSIX_PATH_MAX}  on
155              systems   that   do  not  support  the  XSI  option  or  exceeds
156              {_XOPEN_PATH_MAX} on XSI systems, or has  a  pathname  component
157              that  is  longer  than  {_POSIX_NAME_MAX} on systems that do not
158              support the XSI option or longer than {_XOPEN_NAME_MAX}  on  XSI
159              systems.
160
161       The following sections are informative.
162

EXAMPLES

164       None.
165

APPLICATION USAGE

167       None.
168

RATIONALE

170       None.
171

FUTURE DIRECTIONS

173       A  future version might require the mq_open() and mq_unlink() functions
174       to have semantics similar to normal file system operations.
175

SEE ALSO

177       mq_close(),  mq_getattr(),   mq_receive(),   mq_send(),   mq_setattr(),
178       mq_unlink(), msgctl(), msgget(), msgrcv(), msgsnd()
179
180       The Base Definitions volume of POSIX.1‐2008, <mqueue.h>
181
183       Portions  of  this text are reprinted and reproduced in electronic form
184       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
185       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
186       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
187       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
188       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
189       event of any discrepancy between this version and the original IEEE and
190       The Open Group Standard, the original IEEE and The Open Group  Standard
191       is  the  referee document. The original Standard can be obtained online
192       at http://www.unix.org/online.html .
193
194       Any typographical or formatting errors that appear  in  this  page  are
195       most likely to have been introduced during the conversion of the source
196       files to man page format. To report such errors,  see  https://www.ker
197       nel.org/doc/man-pages/reporting_bugs.html .
198
199
200
201IEEE/The Open Group                  2013                          MQ_OPEN(3P)
Impressum