Debian Codegraph @

upstream/debian-unstable/man3/mq_open.3

raw
1 '\" t
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH mq_open 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mq_open \- open a message queue
10 .SH LIBRARY
11 Real-time library
12 .RI ( librt ,\~ \-lrt )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <fcntl.h>" " /* For O_* constants */"
16 .BR "#include <sys/stat.h>" " /* For mode constants */"
17 .B #include <mqueue.h>
18 .P
19 .BI "mqd_t mq_open(const char *" name ", int " oflag );
20 .BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode ,
21 .BI " struct mq_attr *" attr );
22 .fi
23 .SH DESCRIPTION
24 .BR mq_open ()
25 creates a new POSIX message queue or opens an existing queue.
26 The queue is identified by
27 .IR name .
28 For details of the construction of
29 .IR name ,
30 see
31 .BR mq_overview (7).
32 .P
33 The
34 .I oflag
35 argument specifies flags that control the operation of the call.
36 (Definitions of the flags values can be obtained by including
37 .IR <fcntl.h> .)
38 Exactly one of the following must be specified in
39 .IR oflag :
40 .TP
41 .B O_RDONLY
42 Open the queue to receive messages only.
43 .TP
44 .B O_WRONLY
45 Open the queue to send messages only.
46 .TP
47 .B O_RDWR
48 Open the queue to both send and receive messages.
49 .P
50 Zero or more of the following flags can additionally be
51 .IR OR ed
52 in
53 .IR oflag :
54 .TP
55 .BR O_CLOEXEC " (since Linux 2.6.26)"
56 .\" commit 269f21344b23e552c21c9e2d7ca258479dcd7a0a
57 Set the close-on-exec flag for the message queue descriptor.
58 See
59 .BR open (2)
60 for a discussion of why this flag is useful.
61 .TP
62 .B O_CREAT
63 Create the message queue if it does not exist.
64 The owner (user ID) of the message queue is set to the effective
65 user ID of the calling process.
66 The group ownership (group ID) is set to the effective group ID
67 of the calling process.
68 .\" In reality the filesystem IDs are used on Linux.
69 .TP
70 .B O_EXCL
71 If
72 .B O_CREAT
73 was specified in
74 .IR oflag ,
75 and a queue with the given
76 .I name
77 already exists, then fail with the error
78 .BR EEXIST .
79 .TP
80 .B O_NONBLOCK
81 Open the queue in nonblocking mode.
82 In circumstances where
83 .BR mq_receive (3)
84 and
85 .BR mq_send (3)
86 would normally block, these functions instead fail with the error
87 .BR EAGAIN .
88 .P
89 If
90 .B O_CREAT
91 is specified in
92 .IR oflag ,
93 then two additional arguments must be supplied.
94 The
95 .I mode
96 argument specifies the permissions to be placed on the new queue,
97 as for
98 .BR open (2).
99 (Symbolic definitions for the permissions bits can be obtained by including
100 .IR <sys/stat.h> .)
101 The permissions settings are masked against the process umask.
102 .P
103 The fields of the
104 .I struct mq_attr
105 pointed to
106 .I attr
107 specify the maximum number of messages and
108 the maximum size of messages that the queue will allow.
109 This structure is defined as follows:
110 .P
111 .in +4n
112 .EX
113 struct mq_attr {
114 long mq_flags; /* Flags (ignored for mq_open()) */
115 long mq_maxmsg; /* Max.\& # of messages on queue */
116 long mq_msgsize; /* Max.\& message size (bytes) */
117 long mq_curmsgs; /* # of messages currently in queue
118 (ignored for mq_open()) */
119 };
120 .EE
121 .in
122 .P
123 Only the
124 .I mq_maxmsg
125 and
126 .I mq_msgsize
127 fields are employed when calling
128 .BR mq_open ();
129 the values in the remaining fields are ignored.
130 .P
131 If
132 .I attr
133 is NULL, then the queue is created with implementation-defined
134 default attributes.
135 Since Linux 3.5, two
136 .I /proc
137 files can be used to control these defaults;
138 see
139 .BR mq_overview (7)
140 for details.
141 .SH RETURN VALUE
142 On success,
143 .BR mq_open ()
144 returns a message queue descriptor for use by other
145 message queue functions.
146 On error,
147 .BR mq_open ()
148 returns
149 .IR "(mqd_t)\ \-1",
150 with
151 .I errno
152 set to indicate the error.
153 .SH ERRORS
154 .TP
155 .B EACCES
156 The queue exists, but the caller does not have permission to
157 open it in the specified mode.
158 .TP
159 .B EACCES
160 .I name
161 contained more than one slash.
162 .\" Note that this isn't consistent with the same case for sem_open()
163 .TP
164 .B EEXIST
165 Both
166 .B O_CREAT
167 and
168 .B O_EXCL
169 were specified in
170 .IR oflag ,
171 but a queue with this
172 .I name
173 already exists.
174 .TP
175 .B EINVAL
176 .\" glibc checks whether the name starts with a "/" and if not,
177 .\" gives this error
178 .I name
179 doesn't follow the format in
180 .BR mq_overview (7).
181 .TP
182 .B EINVAL
183 .B O_CREAT
184 was specified in
185 .IR oflag ,
186 and
187 .I attr
188 was not NULL, but
189 .I attr\->mq_maxmsg
190 or
191 .I attr\->mq_msqsize
192 was invalid.
193 Both of these fields must be greater than zero.
194 In a process that is unprivileged (does not have the
195 .B CAP_SYS_RESOURCE
196 capability),
197 .I attr\->mq_maxmsg
198 must be less than or equal to the
199 .I msg_max
200 limit, and
201 .I attr\->mq_msgsize
202 must be less than or equal to the
203 .I msgsize_max
204 limit.
205 In addition, even in a privileged process,
206 .I attr\->mq_maxmsg
207 cannot exceed the
208 .B HARD_MAX
209 limit.
210 (See
211 .BR mq_overview (7)
212 for details of these limits.)
213 .TP
214 .B EMFILE
215 The per-process limit on the number of open file
216 and message queue descriptors has been reached
217 (see the description of
218 .B RLIMIT_NOFILE
219 in
220 .BR getrlimit (2)).
221 .TP
222 .B ENAMETOOLONG
223 .I name
224 was too long.
225 .TP
226 .B ENFILE
227 The system-wide limit on the total number of open files
228 and message queues has been reached.
229 .TP
230 .B ENOENT
231 The
232 .B O_CREAT
233 flag was not specified in
234 .IR oflag ,
235 and no queue with this
236 .I name
237 exists.
238 .TP
239 .B ENOENT
240 .I name
241 was just "/" followed by no other characters.
242 .\" Note that this isn't consistent with the same case for sem_open()
243 .TP
244 .B ENOMEM
245 Insufficient memory.
246 .TP
247 .B ENOSPC
248 Insufficient space for the creation of a new message queue.
249 This probably occurred because the
250 .I queues_max
251 limit was encountered;
252 see
253 .BR mq_overview (7).
254 .SH ATTRIBUTES
255 For an explanation of the terms used in this section, see
256 .BR attributes (7).
257 .TS
258 allbox;
259 lbx lb lb
260 l l l.
261 Interface Attribute Value
262 T{
263 .na
264 .nh
265 .BR mq_open ()
266 T} Thread safety MT-Safe
267 .TE
268 .SH VERSIONS
269 .SS C library/kernel differences
270 The
271 .BR mq_open ()
272 library function is implemented on top of a system call of the same name.
273 The library function performs the check that the
274 .I name
275 starts with a slash (/), giving the
276 .B EINVAL
277 error if it does not.
278 The kernel system call expects
279 .I name
280 to contain no preceding slash,
281 so the C library function passes
282 .I name
283 without the preceding slash (i.e.,
284 .IR name+1 )
285 to the system call.
286 .SH STANDARDS
287 POSIX.1-2008.
288 .SH HISTORY
289 POSIX.1-2001.
290 .SH BUGS
291 Before Linux 2.6.14,
292 the process umask was not applied to the permissions specified in
293 .IR mode .
294 .SH SEE ALSO
295 .BR mq_close (3),
296 .BR mq_getattr (3),
297 .BR mq_notify (3),
298 .BR mq_receive (3),
299 .BR mq_send (3),
300 .BR mq_unlink (3),
301 .BR mq_overview (7)