]>
Commit | Line | Data |
---|---|---|
80a99f39 | 1 | '\" t |
c11b1abf | 2 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
80a99f39 | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
80a99f39 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
80a99f39 MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
17 | .\" the use of the information contained herein. The author(s) may not |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
80a99f39 MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
80a99f39 | 25 | .\" |
4b8c67d9 | 26 | .TH MQ_OPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
80a99f39 MK |
27 | .SH NAME |
28 | mq_open \- open a message queue | |
29 | .SH SYNOPSIS | |
30 | .nf | |
87d17de4 | 31 | .BR "#include <fcntl.h>" " /* For O_* constants */" |
84c517a4 | 32 | .BR "#include <sys/stat.h>" " /* For mode constants */" |
80a99f39 | 33 | .B #include <mqueue.h> |
68e4db0a | 34 | .PP |
80a99f39 | 35 | .BI "mqd_t mq_open(const char *" name ", int " oflag ); |
c13182ef | 36 | .BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode , |
911db49e | 37 | .BI " struct mq_attr *" attr ); |
80a99f39 | 38 | .fi |
68e4db0a | 39 | .PP |
1b2d3fca | 40 | Link with \fI\-lrt\fP. |
80a99f39 MK |
41 | .SH DESCRIPTION |
42 | .BR mq_open () | |
43 | creates a new POSIX message queue or opens an existing queue. | |
44 | The queue is identified by | |
45 | .IR name . | |
c13182ef MK |
46 | For details of the construction of |
47 | .IR name , | |
80a99f39 MK |
48 | see |
49 | .BR mq_overview (7). | |
847e0d88 | 50 | .PP |
80a99f39 MK |
51 | The |
52 | .I oflag | |
53 | argument specifies flags that control the operation of the call. | |
87d17de4 MK |
54 | (Definitions of the flags values can be obtained by including |
55 | .IR <fcntl.h> .) | |
c13182ef | 56 | Exactly one of the following must be specified in |
4df883b9 | 57 | .IR oflag : |
80a99f39 MK |
58 | .TP |
59 | .B O_RDONLY | |
60 | Open the queue to receive messages only. | |
61 | .TP | |
62 | .B O_WRONLY | |
63 | Open the queue to send messages only. | |
64 | .TP | |
65 | .B O_RDWR | |
66 | Open the queue to both send and receive messages. | |
67 | .PP | |
68 | Zero or more of the following flags can additionally be | |
69 | .IR OR ed | |
70 | in | |
71 | .IR oflag : | |
72 | .TP | |
d74f8059 MK |
73 | .BR O_CLOEXEC " (since Linux 2.6.26)" |
74 | .\" commit 269f21344b23e552c21c9e2d7ca258479dcd7a0a | |
75 | Set the close-on-exec flag for the message queue descriptor. | |
76 | See | |
77 | .BR open (2) | |
78 | for a discussion of why this flag is useful. | |
79 | .TP | |
80a99f39 MK |
80 | .B O_CREAT |
81 | Create the message queue if it does not exist. | |
82 | The owner (user ID) of the message queue is set to the effective | |
c13182ef MK |
83 | user ID of the calling process. |
84 | The group ownership (group ID) is set to the effective group ID | |
80a99f39 | 85 | of the calling process. |
9ee4a2b6 | 86 | .\" In reality the filesystem IDs are used on Linux. |
80a99f39 MK |
87 | .TP |
88 | .B O_EXCL | |
89 | If | |
90 | .B O_CREAT | |
91 | was specified in | |
92 | .IR oflag , | |
93 | and a queue with the given | |
94 | .I name | |
95 | already exists, then fail with the error | |
96 | .BR EEXIST . | |
8d121cc5 MK |
97 | .TP |
98 | .B O_NONBLOCK | |
99 | Open the queue in nonblocking mode. | |
100 | In circumstances where | |
101 | .BR mq_receive (3) | |
102 | and | |
103 | .BR mq_send (3) | |
104 | would normally block, these functions instead fail with the error | |
105 | .BR EAGAIN . | |
80a99f39 | 106 | .PP |
c13182ef | 107 | If |
80a99f39 | 108 | .B O_CREAT |
c13182ef | 109 | is specified in |
80a99f39 MK |
110 | .IR oflag , |
111 | then two additional arguments must be supplied. | |
112 | The | |
113 | .I mode | |
c13182ef | 114 | argument specifies the permissions to be placed on the new queue, |
7295b7ed | 115 | as for |
80a99f39 | 116 | .BR open (2). |
87d17de4 MK |
117 | (Symbolic definitions for the permissions bits can be obtained by including |
118 | .IR <sys/stat.h> .) | |
80a99f39 | 119 | The permissions settings are masked against the process umask. |
847e0d88 | 120 | .PP |
1ce0421b MK |
121 | The fields of the |
122 | .IR "struct mq_attr" | |
123 | pointed to | |
124 | .I attr | |
125 | specify the maximum number of messages and | |
126 | the maximum size of messages that the queue will allow. | |
127 | This structure is defined as follows: | |
847e0d88 | 128 | .PP |
e646a1ba | 129 | .PP |
1ce0421b | 130 | .in +4n |
e646a1ba | 131 | .EX |
1ce0421b MK |
132 | struct mq_attr { |
133 | long mq_flags; /* Flags (ignored for mq_open()) */ | |
134 | long mq_maxmsg; /* Max. # of messages on queue */ | |
135 | long mq_msgsize; /* Max. message size (bytes) */ | |
136 | long mq_curmsgs; /* # of messages currently in queue | |
137 | (ignored for mq_open()) */ | |
138 | }; | |
b8302363 | 139 | .EE |
1ce0421b | 140 | .in |
847e0d88 | 141 | .PP |
1ce0421b | 142 | Only the |
5501509f MK |
143 | .I mq_maxmsg |
144 | and | |
145 | .I mq_msgsize | |
1ce0421b | 146 | fields are employed when calling |
5501509f | 147 | .BR mq_open (); |
1ce0421b | 148 | the values in the remaining fields are ignored. |
847e0d88 | 149 | .PP |
80a99f39 MK |
150 | If |
151 | .I attr | |
c13182ef | 152 | is NULL, then the queue is created with implementation-defined |
80a99f39 | 153 | default attributes. |
d8e8fd10 MK |
154 | Since Linux 3.5, two |
155 | .I /proc | |
156 | files can be used to control these defaults; see | |
157 | .BR mq_overview (7) | |
158 | for details. | |
80a99f39 MK |
159 | .SH RETURN VALUE |
160 | On success, | |
161 | .BR mq_open () | |
c13182ef | 162 | returns a message queue descriptor for use by other |
80a99f39 | 163 | message queue functions. |
c13182ef | 164 | On error, |
80a99f39 | 165 | .BR mq_open () |
c13182ef | 166 | returns |
80a99f39 MK |
167 | .IR "(mqd_t)\ \-1", |
168 | with | |
169 | .I errno | |
170 | set to indicate the error. | |
171 | .SH ERRORS | |
172 | .TP | |
c3efd1ac | 173 | .B EACCES |
c13182ef | 174 | The queue exists, but the caller does not have permission to |
80a99f39 MK |
175 | open it in the specified mode. |
176 | .TP | |
b2e7d072 MK |
177 | .B EACCES |
178 | .I name | |
179 | contained more than one slash. | |
180 | .\" Note that this isn't consistent with the same case for sem_open() | |
181 | .TP | |
eab64696 MK |
182 | .B EEXIST |
183 | Both | |
184 | .B O_CREAT | |
185 | and | |
186 | .B O_EXCL | |
187 | were specified in | |
188 | .IR oflag , | |
189 | but a queue with this | |
190 | .I name | |
191 | already exists. | |
192 | .TP | |
80a99f39 | 193 | .B EINVAL |
98df6740 MK |
194 | .\" glibc checks whether the name starts with a "/" and if not, |
195 | .\" gives this error | |
c8aba8ed TR |
196 | .I name |
197 | doesn't follow the format in | |
198 | .BR mq_overview (7). | |
199 | .TP | |
200 | .B EINVAL | |
80a99f39 | 201 | .B O_CREAT |
c13182ef MK |
202 | was specified in |
203 | .IR oflag , | |
204 | and | |
80a99f39 MK |
205 | .I attr |
206 | was not NULL, but | |
94e9d9fe | 207 | .I attr\->mq_maxmsg |
80a99f39 | 208 | or |
94e9d9fe | 209 | .I attr\->mq_msqsize |
80a99f39 MK |
210 | was invalid. |
211 | Both of these fields must be greater than zero. | |
212 | In a process that is unprivileged (does not have the | |
213 | .B CAP_SYS_RESOURCE | |
214 | capability), | |
94e9d9fe | 215 | .I attr\->mq_maxmsg |
80a99f39 MK |
216 | must be less than or equal to the |
217 | .I msg_max | |
218 | limit, and | |
94e9d9fe | 219 | .I attr\->mq_msgsize |
80a99f39 MK |
220 | must be less than or equal to the |
221 | .I msgsize_max | |
c13182ef | 222 | limit. |
80a99f39 | 223 | In addition, even in a privileged process, |
94e9d9fe | 224 | .I attr\->mq_maxmsg |
80a99f39 MK |
225 | cannot exceed the |
226 | .B HARD_MAX | |
227 | limit. | |
228 | (See | |
c13182ef | 229 | .BR mq_overview (7) |
80a99f39 MK |
230 | for details of these limits.) |
231 | .TP | |
80a99f39 | 232 | .B EMFILE |
e24fbf10 | 233 | The per-process limit on the number of open file |
26c32fab MK |
234 | and message queue descriptors has been reached |
235 | (see the description of | |
236 | .BR RLIMIT_NOFILE | |
237 | in | |
238 | .BR getrlimit (2)). | |
80a99f39 MK |
239 | .TP |
240 | .B ENAMETOOLONG | |
0daa9e92 | 241 | .I name |
80a99f39 MK |
242 | was too long. |
243 | .TP | |
244 | .B ENFILE | |
e258766b MK |
245 | The system-wide limit on the total number of open files |
246 | and message queues has been reached. | |
80a99f39 MK |
247 | .TP |
248 | .B ENOENT | |
249 | The | |
250 | .B O_CREAT | |
c13182ef | 251 | flag was not specified in |
80a99f39 | 252 | .IR oflag , |
c13182ef | 253 | and no queue with this |
80a99f39 MK |
254 | .I name |
255 | exists. | |
256 | .TP | |
1e22e666 MK |
257 | .B ENOENT |
258 | .I name | |
259 | was just "/" followed by no other characters. | |
260 | .\" Note that this isn't consistent with the same case for sem_open() | |
261 | .TP | |
80a99f39 MK |
262 | .B ENOMEM |
263 | Insufficient memory. | |
264 | .TP | |
265 | .B ENOSPC | |
266 | Insufficient space for the creation of a new message queue. | |
267 | This probably occurred because the | |
268 | .I queues_max | |
269 | limit was encountered; see | |
270 | .BR mq_overview (7). | |
73d140c7 | 271 | .SH ATTRIBUTES |
82ceb9e2 PH |
272 | For an explanation of the terms used in this section, see |
273 | .BR attributes (7). | |
274 | .TS | |
275 | allbox; | |
276 | lb lb lb | |
277 | l l l. | |
278 | Interface Attribute Value | |
279 | T{ | |
73d140c7 | 280 | .BR mq_open () |
82ceb9e2 PH |
281 | T} Thread safety MT-Safe |
282 | .TE | |
80a99f39 | 283 | .SH CONFORMING TO |
70dae155 | 284 | POSIX.1-2001, POSIX.1-2008. |
5eeca37c | 285 | .SH NOTES |
0722a578 | 286 | .SS C library/kernel differences |
5eeca37c MK |
287 | The |
288 | .BR mq_open () | |
289 | library function is implemented on top of a system call of the same name. | |
290 | The library function performs the check that the | |
291 | .I name | |
292 | starts with a slash (/), giving the | |
293 | .B EINVAL | |
294 | error if it does not. | |
295 | The kernel system call expects | |
296 | .I name | |
297 | to contain no preceding slash, | |
298 | so the C library function passes | |
299 | .I name | |
300 | without the preceding slash (i.e., | |
301 | .IR name+1 ) | |
302 | to the system call. | |
80a99f39 | 303 | .SH BUGS |
c13182ef MK |
304 | In kernels before 2.6.14, |
305 | the process umask was not applied to the permissions specified in | |
80a99f39 | 306 | .IR mode . |
47297adb | 307 | .SH SEE ALSO |
80a99f39 MK |
308 | .BR mq_close (3), |
309 | .BR mq_getattr (3), | |
310 | .BR mq_notify (3), | |
311 | .BR mq_receive (3), | |
312 | .BR mq_send (3), | |
313 | .BR mq_unlink (3), | |
314 | .BR mq_overview (7) |