]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it> |
e6356d61 | 2 | .\" and Copyright 2015 Bill Pemberton <wfp5p@worldbroken.com> |
fea681da | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond <esr@thyrsus.com> | |
7 | .\" Modified Mon Jul 10 21:09:59 2000 by aeb | |
c11b1abf | 8 | .\" Modified 1 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
9 | .\" Language clean-ups. |
10 | .\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX | |
d9bfdb9c | 11 | .\" Added note on restart behavior of msgsnd() and msgrcv() |
c13182ef | 12 | .\" Formatting clean-ups (argument and field names marked as .I |
fea681da | 13 | .\" instead of .B) |
c11b1abf | 14 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 15 | .\" Added notes on capability requirements |
c11b1abf | 16 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fe1c5199 MK |
17 | .\" Language and formatting clean-ups |
18 | .\" Added notes on /proc files | |
bea08fec | 19 | .\" |
ab47278f | 20 | .TH MSGOP 2 (date) "Linux man-pages (unreleased)" |
fea681da | 21 | .SH NAME |
47f065d6 | 22 | msgrcv, msgsnd \- System V message queue operations |
2f033039 AC |
23 | .SH LIBRARY |
24 | Standard C library | |
8fc3b2cf | 25 | .RI ( libc ", " \-lc ) |
fea681da MK |
26 | .SH SYNOPSIS |
27 | .nf | |
521bf584 | 28 | .B #include <sys/msg.h> |
c6d039a3 | 29 | .P |
c64cd13e AC |
30 | .BI "int msgsnd(int " msqid ", const void " msgp [. msgsz "], size_t " msgsz , |
31 | .BI " int " msgflg ); | |
c6d039a3 | 32 | .P |
c64cd13e | 33 | .BI "ssize_t msgrcv(int " msqid ", void " msgp [. msgsz "], size_t " msgsz \ |
521bf584 MK |
34 | ", long " msgtyp , |
35 | .BI " int " msgflg ); | |
36 | .fi | |
fea681da | 37 | .SH DESCRIPTION |
fe1c5199 MK |
38 | The |
39 | .BR msgsnd () | |
40 | and | |
41 | .BR msgrcv () | |
83a9c27c | 42 | system calls are used to send messages to, |
efbfd7ec | 43 | and receive messages from, a System\ V message queue. |
fe1c5199 MK |
44 | The calling process must have write permission on the message queue |
45 | in order to send a message, and read permission to receive a message. | |
c6d039a3 | 46 | .P |
fe1c5199 MK |
47 | The |
48 | .I msgp | |
ed4c2b69 | 49 | argument is a pointer to a caller-defined structure |
fea681da | 50 | of the following general form: |
c6d039a3 | 51 | .P |
a08ea57c | 52 | .in +4n |
6b96e707 | 53 | .EX |
7295b7ed MK |
54 | struct msgbuf { |
55 | long mtype; /* message type, must be > 0 */ | |
56 | char mtext[1]; /* message data */ | |
57 | }; | |
6b96e707 | 58 | .EE |
a08ea57c | 59 | .in |
c6d039a3 | 60 | .P |
fea681da MK |
61 | The |
62 | .I mtext | |
63 | field is an array (or other structure) whose size is specified by | |
64 | .IR msgsz , | |
2fda57bd | 65 | a nonnegative integer value. |
fea681da MK |
66 | Messages of zero length (i.e., no |
67 | .I mtext | |
68 | field) are permitted. | |
69 | The | |
70 | .I mtype | |
fe1c5199 MK |
71 | field must have a strictly positive integer value. |
72 | This value can be | |
fea681da | 73 | used by the receiving process for message selection |
fe1c5199 MK |
74 | (see the description of |
75 | .BR msgrcv () | |
76 | below). | |
49ecc7a0 | 77 | .SS msgsnd() |
fea681da | 78 | The |
fe1c5199 | 79 | .BR msgsnd () |
fea681da MK |
80 | system call appends a copy of the message pointed to by |
81 | .I msgp | |
82 | to the message queue whose identifier is specified | |
83 | by | |
84 | .IR msqid . | |
c6d039a3 | 85 | .P |
fe1c5199 MK |
86 | If sufficient space is available in the queue, |
87 | .BR msgsnd () | |
fea681da | 88 | succeeds immediately. |
64190fa6 | 89 | The queue capacity is governed by the |
0da5e58a | 90 | .I msg_qbytes |
fea681da | 91 | field in the associated data structure for the message queue. |
d9bfdb9c | 92 | During queue creation this field is initialized to |
fea681da MK |
93 | .B MSGMNB |
94 | bytes, but this limit can be modified using | |
64190fa6 | 95 | .BR msgctl (2). |
ab1b15aa MK |
96 | A message queue is considered to be full if either of the following |
97 | conditions is true: | |
cdede5cd | 98 | .IP \[bu] 3 |
ab1b15aa MK |
99 | Adding a new message to the queue would cause the total number of bytes |
100 | in the queue to exceed the queue's maximum size (the | |
64190fa6 DB |
101 | .I msg_qbytes |
102 | field). | |
cdede5cd | 103 | .IP \[bu] |
ab1b15aa MK |
104 | Adding another message to the queue would cause the total number of messages |
105 | in the queue to exceed the queue's maximum size (the | |
64190fa6 | 106 | .I msg_qbytes |
ab1b15aa MK |
107 | field). |
108 | This check is necessary to prevent an unlimited number of zero-length | |
109 | messages being placed on the queue. | |
110 | Although such messages contain no data, | |
111 | they nevertheless consume (locked) kernel memory. | |
c6d039a3 | 112 | .P |
fe1c5199 | 113 | If insufficient space is available in the queue, then the default |
d9bfdb9c | 114 | behavior of |
fe1c5199 | 115 | .BR msgsnd () |
fea681da MK |
116 | is to block until space becomes available. |
117 | If | |
118 | .B IPC_NOWAIT | |
fe1c5199 MK |
119 | is specified in |
120 | .IR msgflg , | |
fea681da MK |
121 | then the call instead fails with the error |
122 | .BR EAGAIN . | |
c6d039a3 | 123 | .P |
c13182ef | 124 | A blocked |
fe1c5199 | 125 | .BR msgsnd () |
49ecc7a0 | 126 | call may also fail if: |
cdede5cd | 127 | .IP \[bu] 3 |
b75101c3 | 128 | the queue is removed, |
49ecc7a0 | 129 | in which case the system call fails with |
fea681da MK |
130 | .I errno |
131 | set to | |
49ecc7a0 MK |
132 | .BR EIDRM ; |
133 | or | |
cdede5cd | 134 | .IP \[bu] |
49ecc7a0 | 135 | a signal is caught, in which case the system call fails |
fea681da MK |
136 | with |
137 | .I errno | |
138 | set to | |
6602d44b MK |
139 | .BR EINTR ; see |
140 | .BR signal (7). | |
49ecc7a0 MK |
141 | .RB ( msgsnd () |
142 | is never automatically restarted after being interrupted by a | |
0425de01 | 143 | signal handler, regardless of the setting of the |
fea681da MK |
144 | .B SA_RESTART |
145 | flag when establishing a signal handler.) | |
c6d039a3 | 146 | .P |
fea681da MK |
147 | Upon successful completion the message queue data structure is updated |
148 | as follows: | |
cdede5cd | 149 | .IP \[bu] 3 |
fea681da MK |
150 | .I msg_lspid |
151 | is set to the process ID of the calling process. | |
cdede5cd | 152 | .IP \[bu] |
fea681da MK |
153 | .I msg_qnum |
154 | is incremented by 1. | |
cdede5cd | 155 | .IP \[bu] |
fea681da MK |
156 | .I msg_stime |
157 | is set to the current time. | |
49ecc7a0 MK |
158 | .SS msgrcv() |
159 | The | |
fe1c5199 | 160 | .BR msgrcv () |
49ecc7a0 | 161 | system call removes a message from the queue specified by |
fea681da | 162 | .I msqid |
6e0e514c | 163 | and places it in the buffer |
40725279 | 164 | pointed to by |
6e0e514c | 165 | .IR msgp . |
c6d039a3 | 166 | .P |
fea681da MK |
167 | The argument |
168 | .I msgsz | |
169 | specifies the maximum size in bytes for the member | |
170 | .I mtext | |
171 | of the structure pointed to by the | |
172 | .I msgp | |
173 | argument. | |
174 | If the message text has length greater than | |
175 | .IR msgsz , | |
d9bfdb9c | 176 | then the behavior depends on whether |
0daa9e92 | 177 | .B MSG_NOERROR |
c13182ef | 178 | is specified in |
fe1c5199 MK |
179 | .IR msgflg . |
180 | If | |
0daa9e92 | 181 | .B MSG_NOERROR |
fe1c5199 | 182 | is specified, then |
fea681da | 183 | the message text will be truncated (and the truncated part will be |
c13182ef | 184 | lost); if |
0daa9e92 | 185 | .B MSG_NOERROR |
fe1c5199 MK |
186 | is not specified, then |
187 | the message isn't removed from the queue and | |
188 | the system call fails returning \-1 with | |
fea681da MK |
189 | .I errno |
190 | set to | |
191 | .BR E2BIG . | |
c6d039a3 | 192 | .P |
9535c592 MK |
193 | Unless |
194 | .B MSG_COPY | |
195 | is specified in | |
1ae6b2c7 | 196 | .I msgflg |
9535c592 MK |
197 | (see below), |
198 | the | |
fea681da | 199 | .I msgtyp |
9535c592 | 200 | argument specifies the type of message requested, as follows: |
cdede5cd | 201 | .IP \[bu] 3 |
fea681da MK |
202 | If |
203 | .I msgtyp | |
fe1c5199 | 204 | is 0, |
fea681da | 205 | then the first message in the queue is read. |
cdede5cd | 206 | .IP \[bu] |
fea681da MK |
207 | If |
208 | .I msgtyp | |
fe1c5199 MK |
209 | is greater than 0, |
210 | then the first message in the queue of type | |
fea681da MK |
211 | .I msgtyp |
212 | is read, unless | |
213 | .B MSG_EXCEPT | |
fe1c5199 | 214 | was specified in |
fea681da MK |
215 | .IR msgflg , |
216 | in which case | |
fe1c5199 | 217 | the first message in the queue of type not equal to |
fea681da MK |
218 | .I msgtyp |
219 | will be read. | |
cdede5cd | 220 | .IP \[bu] |
fea681da MK |
221 | If |
222 | .I msgtyp | |
fe1c5199 MK |
223 | is less than 0, |
224 | then the first message in the queue with the lowest type less than or | |
fea681da MK |
225 | equal to the absolute value of |
226 | .I msgtyp | |
227 | will be read. | |
c6d039a3 | 228 | .P |
fea681da MK |
229 | The |
230 | .I msgflg | |
fe1c5199 MK |
231 | argument is a bit mask constructed by ORing together zero or more |
232 | of the following flags: | |
233 | .TP | |
fea681da | 234 | .B IPC_NOWAIT |
6e0e514c | 235 | Return immediately if no message of the requested type is in the queue. |
fe1c5199 MK |
236 | The system call fails with |
237 | .I errno | |
238 | set to | |
fea681da | 239 | .BR ENOMSG . |
fe1c5199 | 240 | .TP |
9535c592 MK |
241 | .BR MSG_COPY " (since Linux 3.8)" |
242 | .\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8 | |
243 | Nondestructively fetch a copy of the message at the ordinal position | |
244 | in the queue specified by | |
245 | .I msgtyp | |
246 | (messages are considered to be numbered starting at 0). | |
efeece04 | 247 | .IP |
fbc6aee2 | 248 | This flag must be specified in conjunction with |
9535c592 | 249 | .BR IPC_NOWAIT , |
fbc6aee2 | 250 | with the result that, if there is no message available at the given position, |
9535c592 MK |
251 | the call fails immediately with the error |
252 | .BR ENOMSG . | |
fbc6aee2 MK |
253 | Because they alter the meaning of |
254 | .I msgtyp | |
255 | in orthogonal ways, | |
1ae6b2c7 | 256 | .B MSG_COPY |
fbc6aee2 | 257 | and |
1ae6b2c7 | 258 | .B MSG_EXCEPT |
fbc6aee2 MK |
259 | may not both be specified in |
260 | .IR msgflg . | |
efeece04 | 261 | .IP |
fbc6aee2 | 262 | The |
1ae6b2c7 | 263 | .B MSG_COPY |
fbc6aee2 | 264 | flag was added for the implementation of |
9535c592 MK |
265 | the kernel checkpoint-restore facility and |
266 | is available only if the kernel was built with the | |
267 | .B CONFIG_CHECKPOINT_RESTORE | |
268 | option. | |
269 | .TP | |
fea681da MK |
270 | .B MSG_EXCEPT |
271 | Used with | |
272 | .I msgtyp | |
fe1c5199 MK |
273 | greater than 0 |
274 | to read the first message in the queue with message type that differs | |
fea681da MK |
275 | from |
276 | .IR msgtyp . | |
fe1c5199 | 277 | .TP |
fea681da MK |
278 | .B MSG_NOERROR |
279 | To truncate the message text if longer than | |
280 | .I msgsz | |
281 | bytes. | |
c6d039a3 | 282 | .P |
fea681da MK |
283 | If no message of the requested type is available and |
284 | .B IPC_NOWAIT | |
fe1c5199 | 285 | isn't specified in |
fea681da MK |
286 | .IR msgflg , |
287 | the calling process is blocked until one of the following conditions occurs: | |
cdede5cd | 288 | .IP \[bu] 3 |
fe1c5199 | 289 | A message of the desired type is placed in the queue. |
cdede5cd | 290 | .IP \[bu] |
fea681da | 291 | The message queue is removed from the system. |
c0f5164f | 292 | In this case, the system call fails with |
fea681da MK |
293 | .I errno |
294 | set to | |
295 | .BR EIDRM . | |
cdede5cd | 296 | .IP \[bu] |
fea681da | 297 | The calling process catches a signal. |
c0f5164f | 298 | In this case, the system call fails with |
fea681da MK |
299 | .I errno |
300 | set to | |
301 | .BR EINTR . | |
49ecc7a0 MK |
302 | .RB ( msgrcv () |
303 | is never automatically restarted after being interrupted by a | |
0425de01 | 304 | signal handler, regardless of the setting of the |
49ecc7a0 MK |
305 | .B SA_RESTART |
306 | flag when establishing a signal handler.) | |
c6d039a3 | 307 | .P |
fea681da MK |
308 | Upon successful completion the message queue data structure is updated |
309 | as follows: | |
310 | .IP | |
311 | .I msg_lrpid | |
312 | is set to the process ID of the calling process. | |
313 | .IP | |
314 | .I msg_qnum | |
315 | is decremented by 1. | |
316 | .IP | |
317 | .I msg_rtime | |
318 | is set to the current time. | |
47297adb | 319 | .SH RETURN VALUE |
9862ec0c | 320 | On success, |
fe1c5199 MK |
321 | .BR msgsnd () |
322 | returns 0 | |
fea681da | 323 | and |
704a18f0 | 324 | .BR msgrcv () |
fea681da MK |
325 | returns the number of bytes actually copied into the |
326 | .I mtext | |
327 | array. | |
9862ec0c MK |
328 | On failure, both functions return \-1, and set |
329 | .I errno | |
330 | to indicate the error. | |
fea681da | 331 | .SH ERRORS |
fe1c5199 | 332 | .BR msgsnd () |
f2fa0558 | 333 | can fail with the following errors: |
89b3c6b8 | 334 | .TP |
fea681da MK |
335 | .B EACCES |
336 | The calling process does not have write permission on the message queue, | |
337 | and does not have the | |
0daa9e92 | 338 | .B CAP_IPC_OWNER |
a42a171f | 339 | capability in the user namespace that governs its IPC namespace. |
c13182ef | 340 | .TP |
fea681da MK |
341 | .B EAGAIN |
342 | The message can't be sent due to the | |
343 | .I msg_qbytes | |
344 | limit for the queue and | |
345 | .B IPC_NOWAIT | |
fe1c5199 | 346 | was specified in |
704a18f0 | 347 | .IR msgflg . |
fea681da MK |
348 | .TP |
349 | .B EFAULT | |
350 | The address pointed to by | |
351 | .I msgp | |
352 | isn't accessible. | |
353 | .TP | |
354 | .B EIDRM | |
355 | The message queue was removed. | |
356 | .TP | |
357 | .B EINTR | |
358 | Sleeping on a full message queue condition, the process caught a signal. | |
359 | .TP | |
360 | .B EINVAL | |
361 | Invalid | |
362 | .I msqid | |
657316c0 | 363 | value, or nonpositive |
fea681da MK |
364 | .I mtype |
365 | value, or | |
366 | invalid | |
367 | .I msgsz | |
368 | value (less than 0 or greater than the system value | |
369 | .BR MSGMAX ). | |
370 | .TP | |
371 | .B ENOMEM | |
c13182ef | 372 | The system does not have enough memory to make a copy of the |
6e0e514c MK |
373 | message pointed to by |
374 | .IR msgp . | |
c6d039a3 | 375 | .P |
fe1c5199 | 376 | .BR msgrcv () |
f2fa0558 | 377 | can fail with the following errors: |
89b3c6b8 | 378 | .TP |
fea681da MK |
379 | .B E2BIG |
380 | The message text length is greater than | |
381 | .I msgsz | |
382 | and | |
383 | .B MSG_NOERROR | |
fe1c5199 | 384 | isn't specified in |
fea681da MK |
385 | .IR msgflg . |
386 | .TP | |
387 | .B EACCES | |
388 | The calling process does not have read permission on the message queue, | |
389 | and does not have the | |
0daa9e92 | 390 | .B CAP_IPC_OWNER |
3294109d | 391 | capability in the user namespace that governs its IPC namespace. |
c13182ef | 392 | .TP |
fea681da MK |
393 | .B EFAULT |
394 | The address pointed to by | |
395 | .I msgp | |
396 | isn't accessible. | |
397 | .TP | |
398 | .B EIDRM | |
399 | While the process was sleeping to receive a message, | |
400 | the message queue was removed. | |
401 | .TP | |
402 | .B EINTR | |
403 | While the process was sleeping to receive a message, | |
6602d44b MK |
404 | the process caught a signal; see |
405 | .BR signal (7). | |
fea681da MK |
406 | .TP |
407 | .B EINVAL | |
84004133 | 408 | .I msqid |
fe1c5199 | 409 | was invalid, or |
fea681da | 410 | .I msgsz |
fe1c5199 | 411 | was less than 0. |
fea681da | 412 | .TP |
fbc6aee2 MK |
413 | .BR EINVAL " (since Linux 3.14)" |
414 | .I msgflg | |
415 | specified | |
416 | .BR MSG_COPY , | |
417 | but not | |
418 | .BR IPC_NOWAIT . | |
419 | .TP | |
420 | .BR EINVAL " (since Linux 3.14)" | |
421 | .I msgflg | |
422 | specified both | |
1ae6b2c7 | 423 | .B MSG_COPY |
fbc6aee2 MK |
424 | and |
425 | .BR MSG_EXCEPT . | |
426 | .TP | |
fea681da MK |
427 | .B ENOMSG |
428 | .B IPC_NOWAIT | |
fe1c5199 | 429 | was specified in |
fea681da MK |
430 | .I msgflg |
431 | and no message of the requested type existed on the message queue. | |
9535c592 MK |
432 | .TP |
433 | .B ENOMSG | |
434 | .B IPC_NOWAIT | |
435 | and | |
436 | .B MSG_COPY | |
437 | were specified in | |
438 | .I msgflg | |
439 | and the queue contains less than | |
440 | .I msgtyp | |
441 | messages. | |
442 | .TP | |
443 | .BR ENOSYS " (since Linux 3.8)" | |
e38283d7 | 444 | Both |
ab365f43 | 445 | .B MSG_COPY |
e38283d7 MK |
446 | and |
447 | .B IPC_NOWAIT | |
448 | were specified in | |
9535c592 MK |
449 | .IR msgflg , |
450 | and this kernel was configured without | |
451 | .BR CONFIG_CHECKPOINT_RESTORE . | |
3113c7f3 | 452 | .SH STANDARDS |
4131356c | 453 | POSIX.1-2008. |
c6d039a3 | 454 | .P |
9e9f8a2d MK |
455 | The |
456 | .B MSG_EXCEPT | |
9535c592 MK |
457 | and |
458 | .B MSG_COPY | |
459 | flags are Linux-specific; | |
460 | their definitions can be obtained by defining the | |
9e9f8a2d | 461 | .B _GNU_SOURCE |
9535c592 | 462 | .\" MSG_COPY since glibc 2.18 |
9e9f8a2d | 463 | feature test macro. |
4131356c AC |
464 | .SH HISTORY |
465 | POSIX.1-2001, SVr4. | |
c6d039a3 | 466 | .P |
c13182ef | 467 | The |
6e0e514c | 468 | .I msgp |
d8ae7578 MK |
469 | argument is declared as \fIstruct msgbuf\ *\fP in |
470 | glibc 2.0 and 2.1. | |
6a616b5b | 471 | It is declared as \fIvoid\ *\fP |
d8ae7578 | 472 | in glibc 2.2 and later, as required by SUSv2 and SUSv3. |
4131356c | 473 | .SH NOTES |
ba17901d | 474 | The following limits on message queue resources affect the |
fe1c5199 | 475 | .BR msgsnd () |
ba17901d | 476 | call: |
89b3c6b8 | 477 | .TP |
fea681da | 478 | .B MSGMAX |
faeaa68c MK |
479 | Maximum size of a message text, in bytes (default value: 8192 bytes). |
480 | On Linux, this limit can be read and modified via | |
481 | .IR /proc/sys/kernel/msgmax . | |
fea681da MK |
482 | .TP |
483 | .B MSGMNB | |
faeaa68c MK |
484 | Maximum number of bytes that can be held in a message queue |
485 | (default value: 16384 bytes). | |
486 | On Linux, this limit can be read and modified via | |
487 | .IR /proc/sys/kernel/msgmnb . | |
2cd12d64 MK |
488 | A privileged process |
489 | (Linux: a process with the | |
490 | .B CAP_SYS_RESOURCE | |
491 | capability) | |
492 | can increase the size of a message queue beyond | |
fea681da | 493 | .B MSGMNB |
faeaa68c | 494 | using the |
0bfa087b | 495 | .BR msgctl (2) |
faeaa68c MK |
496 | .B IPC_SET |
497 | operation. | |
c6d039a3 | 498 | .P |
2f0edc6c | 499 | The implementation has no intrinsic system-wide limits on the |
fea681da MK |
500 | number of message headers |
501 | .RB ( MSGTQL ) | |
2f0edc6c | 502 | and the number of bytes in the message pool |
fea681da | 503 | .RB ( MSGPOOL ). |
9535c592 | 504 | .SH BUGS |
fbc6aee2 MK |
505 | In Linux 3.13 and earlier, |
506 | if | |
9535c592 | 507 | .BR msgrcv () |
fbc6aee2 | 508 | was called with the |
1ae6b2c7 | 509 | .B MSG_COPY |
9535c592 MK |
510 | flag, but without |
511 | .BR IPC_NOWAIT , | |
fbc6aee2 | 512 | and the message queue contained less than |
9535c592 | 513 | .I msgtyp |
fbc6aee2 | 514 | messages, then the call would block until the next message is written |
9535c592 | 515 | to the queue. |
bea08fec | 516 | .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2 |
fbc6aee2 | 517 | At that point, the call would return a copy of the message, |
9535c592 | 518 | .I regardless |
fbc6aee2 | 519 | of whether that message was at the ordinal position |
9535c592 | 520 | .IR msgtyp . |
fbc6aee2 MK |
521 | This bug is fixed |
522 | .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c | |
523 | in Linux 3.14. | |
c6d039a3 | 524 | .P |
9535c592 MK |
525 | Specifying both |
526 | .B MSG_COPY | |
527 | and | |
528 | .B MSC_EXCEPT | |
529 | in | |
530 | .I msgflg | |
531 | is a logical error (since these flags impose different interpretations on | |
532 | .IR msgtyp ). | |
fbc6aee2 | 533 | In Linux 3.13 and earlier, |
bea08fec | 534 | .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2 |
fbc6aee2 MK |
535 | this error was not diagnosed by |
536 | .BR msgrcv (). | |
537 | This bug is fixed | |
538 | .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c | |
539 | in Linux 3.14. | |
a14af333 | 540 | .SH EXAMPLES |
b60093ff BP |
541 | The program below demonstrates the use of |
542 | .BR msgsnd () | |
543 | and | |
544 | .BR msgrcv (). | |
c6d039a3 | 545 | .P |
b60093ff | 546 | The example program is first run with the \fB\-s\fP option to send a |
a98b2e1b | 547 | message and then run again with the \fB\-r\fP option to receive a |
b60093ff | 548 | message. |
c6d039a3 | 549 | .P |
b60093ff | 550 | The following shell session shows a sample run of the program: |
c6d039a3 | 551 | .P |
b60093ff | 552 | .in +4n |
a26bed1f | 553 | .EX |
b60093ff BP |
554 | .RB "$" " ./a.out \-s" |
555 | sent: a message at Wed Mar 4 16:25:45 2015 | |
c6d039a3 | 556 | .P |
b60093ff BP |
557 | .RB "$" " ./a.out \-r" |
558 | message received: a message at Wed Mar 4 16:25:45 2015 | |
a26bed1f | 559 | .EE |
b60093ff BP |
560 | .in |
561 | .SS Program source | |
562 | \& | |
33857069 | 563 | .\" SRC BEGIN (msgop.c) |
e7d0bb47 | 564 | .EX |
47b94bbd | 565 | #include <errno.h> |
b60093ff BP |
566 | #include <stdio.h> |
567 | #include <stdlib.h> | |
b60093ff BP |
568 | #include <sys/ipc.h> |
569 | #include <sys/msg.h> | |
47b94bbd AC |
570 | #include <time.h> |
571 | #include <unistd.h> | |
fe5dba13 | 572 | \& |
b60093ff BP |
573 | struct msgbuf { |
574 | long mtype; | |
575 | char mtext[80]; | |
576 | }; | |
fe5dba13 | 577 | \& |
b60093ff BP |
578 | static void |
579 | usage(char *prog_name, char *msg) | |
580 | { | |
581 | if (msg != NULL) | |
582 | fputs(msg, stderr); | |
fe5dba13 | 583 | \& |
d1a71985 MK |
584 | fprintf(stderr, "Usage: %s [options]\en", prog_name); |
585 | fprintf(stderr, "Options are:\en"); | |
586 | fprintf(stderr, "\-s send message using msgsnd()\en"); | |
587 | fprintf(stderr, "\-r read message using msgrcv()\en"); | |
588 | fprintf(stderr, "\-t message type (default is 1)\en"); | |
589 | fprintf(stderr, "\-k message queue key (default is 1234)\en"); | |
b60093ff BP |
590 | exit(EXIT_FAILURE); |
591 | } | |
fe5dba13 | 592 | \& |
b60093ff BP |
593 | static void |
594 | send_msg(int qid, int msgtype) | |
595 | { | |
0b94bd78 AC |
596 | time_t t; |
597 | struct msgbuf msg; | |
fe5dba13 | 598 | \& |
b60093ff | 599 | msg.mtype = msgtype; |
fe5dba13 | 600 | \& |
b60093ff | 601 | time(&t); |
a98b2e1b | 602 | snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s", |
4687ab0e | 603 | ctime(&t)); |
fe5dba13 | 604 | \& |
180698be | 605 | if (msgsnd(qid, &msg, sizeof(msg.mtext), |
4687ab0e AC |
606 | IPC_NOWAIT) == \-1) |
607 | { | |
b60093ff BP |
608 | perror("msgsnd error"); |
609 | exit(EXIT_FAILURE); | |
610 | } | |
d1a71985 | 611 | printf("sent: %s\en", msg.mtext); |
b60093ff | 612 | } |
fe5dba13 | 613 | \& |
b60093ff BP |
614 | static void |
615 | get_msg(int qid, int msgtype) | |
616 | { | |
617 | struct msgbuf msg; | |
fe5dba13 | 618 | \& |
180698be | 619 | if (msgrcv(qid, &msg, sizeof(msg.mtext), msgtype, |
b60093ff BP |
620 | MSG_NOERROR | IPC_NOWAIT) == \-1) { |
621 | if (errno != ENOMSG) { | |
622 | perror("msgrcv"); | |
623 | exit(EXIT_FAILURE); | |
624 | } | |
d1a71985 | 625 | printf("No message available for msgrcv()\en"); |
ef20b0bf | 626 | } else { |
d1a71985 | 627 | printf("message received: %s\en", msg.mtext); |
ef20b0bf | 628 | } |
b60093ff | 629 | } |
fe5dba13 | 630 | \& |
b60093ff BP |
631 | int |
632 | main(int argc, char *argv[]) | |
633 | { | |
0b94bd78 AC |
634 | int qid, opt; |
635 | int mode = 0; /* 1 = send, 2 = receive */ | |
636 | int msgtype = 1; | |
637 | int msgkey = 1234; | |
fe5dba13 | 638 | \& |
b60093ff BP |
639 | while ((opt = getopt(argc, argv, "srt:k:")) != \-1) { |
640 | switch (opt) { | |
b957f81f | 641 | case \[aq]s\[aq]: |
b60093ff BP |
642 | mode = 1; |
643 | break; | |
b957f81f | 644 | case \[aq]r\[aq]: |
b60093ff BP |
645 | mode = 2; |
646 | break; | |
b957f81f | 647 | case \[aq]t\[aq]: |
b60093ff BP |
648 | msgtype = atoi(optarg); |
649 | if (msgtype <= 0) | |
d1a71985 | 650 | usage(argv[0], "\-t option must be greater than 0\en"); |
b60093ff | 651 | break; |
b957f81f | 652 | case \[aq]k\[aq]: |
b60093ff BP |
653 | msgkey = atoi(optarg); |
654 | break; | |
655 | default: | |
d1a71985 | 656 | usage(argv[0], "Unrecognized option\en"); |
b60093ff BP |
657 | } |
658 | } | |
fe5dba13 | 659 | \& |
b60093ff | 660 | if (mode == 0) |
d1a71985 | 661 | usage(argv[0], "must use either \-s or \-r option\en"); |
fe5dba13 | 662 | \& |
b60093ff | 663 | qid = msgget(msgkey, IPC_CREAT | 0666); |
fe5dba13 | 664 | \& |
b60093ff BP |
665 | if (qid == \-1) { |
666 | perror("msgget"); | |
667 | exit(EXIT_FAILURE); | |
668 | } | |
fe5dba13 | 669 | \& |
b60093ff BP |
670 | if (mode == 2) |
671 | get_msg(qid, msgtype); | |
672 | else | |
673 | send_msg(qid, msgtype); | |
fe5dba13 | 674 | \& |
b60093ff BP |
675 | exit(EXIT_SUCCESS); |
676 | } | |
e7d0bb47 | 677 | .EE |
33857069 | 678 | .\" SRC END |
47297adb | 679 | .SH SEE ALSO |
fea681da MK |
680 | .BR msgctl (2), |
681 | .BR msgget (2), | |
a9b305d6 | 682 | .BR capabilities (7), |
2c5e151c | 683 | .BR mq_overview (7), |
343cdc5a | 684 | .BR sysvipc (7) |