Debian Codegraph @

upstream/debian-trixie/man3/mq_open.3

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