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

NAME

12       mq_open - open a message queue (REALTIME)
13

SYNOPSIS

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

RETURN VALUE

114       Upon successful completion, the function shall return a  message  queue
115       descriptor;  otherwise,  the  function  shall  return (mqd_t)-1 and set
116       errno to indicate the error.
117

ERRORS

119       The mq_open() function shall fail if:
120
121       EACCES The message queue exists and the permissions specified by  oflag
122              are  denied,  or the message queue does not exist and permission
123              to create the message queue is denied.
124
125       EEXIST O_CREAT and O_EXCL are set and the named message  queue  already
126              exists.
127
128       EINTR  The mq_open() function was interrupted by a signal.
129
130       EINVAL The mq_open() function is not supported for the given name.
131
132       EINVAL O_CREAT  was  specified in oflag, the value of attr is not NULL,
133              and either mq_maxmsg or mq_msgsize was less  than  or  equal  to
134              zero.
135
136       EMFILE Too  many message queue descriptors or file descriptors are cur‐
137              rently in use by this process.
138
139       ENAMETOOLONG
140              The length of the name argument exceeds {PATH_MAX} or a pathname
141              component is longer than {NAME_MAX}.
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
151       The following sections are informative.
152

EXAMPLES

154       None.
155

APPLICATION USAGE

157       None.
158

RATIONALE

160       None.
161

FUTURE DIRECTIONS

163       None.
164

SEE ALSO

166       mq_close(),  mq_getattr(),   mq_receive(),   mq_send(),   mq_setattr(),
167       mq_timedreceive(),  mq_timedsend(),  mq_unlink(),  msgctl(),  msgget(),
168       msgrcv(),    msgsnd(),    the    Base     Definitions     volume     of
169       IEEE Std 1003.1-2001, <mqueue.h>
170
172       Portions  of  this text are reprinted and reproduced in electronic form
173       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
174       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
175       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
176       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
177       event of any discrepancy between this version and the original IEEE and
178       The  Open Group Standard, the original IEEE and The Open Group Standard
179       is the referee document. The original Standard can be  obtained  online
180       at http://www.opengroup.org/unix/online.html .
181
182
183
184IEEE/The Open Group                  2003                          MQ_OPEN(3P)
Impressum