1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
2 .\" and Copyright 2015 Bill Pemberton <wfp5p@worldbroken.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
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
8 .\" Modified 1 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com>
9 .\" Language clean-ups.
10 .\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX
11 .\" Added note on restart behavior of msgsnd() and msgrcv()
12 .\" Formatting clean-ups (argument and field names marked as .I
14 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
15 .\" Added notes on capability requirements
16 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
17 .\" Language and formatting clean-ups
18 .\" Added notes on /proc files
20 .TH MSGOP 2 (date) "Linux man-pages (unreleased)"
22 msgrcv, msgsnd \- System V message queue operations
25 .RI ( libc ", " \-lc )
28 .B #include <sys/msg.h>
30 .BI "int msgsnd(int " msqid ", const void " msgp [. msgsz "], size_t " msgsz ,
33 .BI "ssize_t msgrcv(int " msqid ", void " msgp [. msgsz "], size_t " msgsz \
42 system calls are used to send messages to,
43 and receive messages from, a System\ V message queue.
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.
49 argument is a pointer to a caller-defined structure
50 of the following general form:
55 long mtype; /* message type, must be > 0 */
56 char mtext[1]; /* message data */
63 field is an array (or other structure) whose size is specified by
65 a nonnegative integer value.
66 Messages of zero length (i.e., no
71 field must have a strictly positive integer value.
73 used by the receiving process for message selection
74 (see the description of
80 system call appends a copy of the message pointed to by
82 to the message queue whose identifier is specified
86 If sufficient space is available in the queue,
89 The queue capacity is governed by the
91 field in the associated data structure for the message queue.
92 During queue creation this field is initialized to
94 bytes, but this limit can be modified using
96 A message queue is considered to be full if either of the following
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
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
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.
113 If insufficient space is available in the queue, then the default
116 is to block until space becomes available.
121 then the call instead fails with the error
126 call may also fail if:
128 the queue is removed,
129 in which case the system call fails with
135 a signal is caught, in which case the system call fails
142 is never automatically restarted after being interrupted by a
143 signal handler, regardless of the setting of the
145 flag when establishing a signal handler.)
147 Upon successful completion the message queue data structure is updated
151 is set to the process ID of the calling process.
157 is set to the current time.
161 system call removes a message from the queue specified by
163 and places it in the buffer
169 specifies the maximum size in bytes for the member
171 of the structure pointed to by the
174 If the message text has length greater than
176 then the behavior depends on whether
183 the message text will be truncated (and the truncated part will be
186 is not specified, then
187 the message isn't removed from the queue and
188 the system call fails returning \-1 with
200 argument specifies the type of message requested, as follows:
205 then the first message in the queue is read.
210 then the first message in the queue of type
217 the first message in the queue of type not equal to
224 then the first message in the queue with the lowest type less than or
225 equal to the absolute value of
231 argument is a bit mask constructed by ORing together zero or more
232 of the following flags:
235 Return immediately if no message of the requested type is in the queue.
236 The system call fails with
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
246 (messages are considered to be numbered starting at 0).
248 This flag must be specified in conjunction with
250 with the result that, if there is no message available at the given position,
251 the call fails immediately with the error
253 Because they alter the meaning of
259 may not both be specified in
264 flag was added for the implementation of
265 the kernel checkpoint-restore facility and
266 is available only if the kernel was built with the
267 .B CONFIG_CHECKPOINT_RESTORE
274 to read the first message in the queue with message type that differs
279 To truncate the message text if longer than
283 If no message of the requested type is available and
287 the calling process is blocked until one of the following conditions occurs:
289 A message of the desired type is placed in the queue.
291 The message queue is removed from the system.
292 In this case, the system call fails with
297 The calling process catches a signal.
298 In this case, the system call fails with
303 is never automatically restarted after being interrupted by a
304 signal handler, regardless of the setting of the
306 flag when establishing a signal handler.)
308 Upon successful completion the message queue data structure is updated
312 is set to the process ID of the calling process.
318 is set to the current time.
325 returns the number of bytes actually copied into the
328 On failure, both functions return \-1, and set
330 to indicate the error.
333 can fail with the following errors:
336 The calling process does not have write permission on the message queue,
337 and does not have the
339 capability in the user namespace that governs its IPC namespace.
342 The message can't be sent due to the
344 limit for the queue and
350 The address pointed to by
355 The message queue was removed.
358 Sleeping on a full message queue condition, the process caught a signal.
363 value, or nonpositive
368 value (less than 0 or greater than the system value
372 The system does not have enough memory to make a copy of the
373 message pointed to by
377 can fail with the following errors:
380 The message text length is greater than
388 The calling process does not have read permission on the message queue,
389 and does not have the
391 capability in the user namespace that governs its IPC namespace.
394 The address pointed to by
399 While the process was sleeping to receive a message,
400 the message queue was removed.
403 While the process was sleeping to receive a message,
404 the process caught a signal; see
413 .BR EINVAL " (since Linux 3.14)"
420 .BR EINVAL " (since Linux 3.14)"
431 and no message of the requested type existed on the message queue.
439 and the queue contains less than
443 .BR ENOSYS " (since Linux 3.8)"
450 and this kernel was configured without
451 .BR CONFIG_CHECKPOINT_RESTORE .
459 flags are Linux-specific;
460 their definitions can be obtained by defining the
462 .\" MSG_COPY since glibc 2.18
469 argument is declared as \fIstruct msgbuf\ *\fP in
471 It is declared as \fIvoid\ *\fP
472 in glibc 2.2 and later, as required by SUSv2 and SUSv3.
474 The following limits on message queue resources affect the
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 .
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 .
489 (Linux: a process with the
492 can increase the size of a message queue beyond
499 The implementation has no intrinsic system-wide limits on the
500 number of message headers
502 and the number of bytes in the message pool
505 In Linux 3.13 and earlier,
512 and the message queue contained less than
514 messages, then the call would block until the next message is written
516 .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
517 At that point, the call would return a copy of the message,
519 of whether that message was at the ordinal position
522 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
531 is a logical error (since these flags impose different interpretations on
533 In Linux 3.13 and earlier,
534 .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
535 this error was not diagnosed by
538 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
541 The program below demonstrates the use of
546 The example program is first run with the \fB\-s\fP option to send a
547 message and then run again with the \fB\-r\fP option to receive a
550 The following shell session shows a sample run of the program:
554 .RB "$" " ./a.out \-s"
555 sent: a message at Wed Mar 4 16:25:45 2015
557 .RB "$" " ./a.out \-r"
558 message received: a message at Wed Mar 4 16:25:45 2015
563 .\" SRC BEGIN (msgop.c)
579 usage(char *prog_name, char *msg)
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");
594 send_msg(int qid, int msgtype)
602 snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
605 if (msgsnd(qid, &msg, sizeof(msg.mtext),
608 perror("msgsnd error");
611 printf("sent: %s\en", msg.mtext);
615 get_msg(int qid, int msgtype)
619 if (msgrcv(qid, &msg, sizeof(msg.mtext), msgtype,
620 MSG_NOERROR | IPC_NOWAIT) == \-1) {
621 if (errno != ENOMSG) {
625 printf("No message available for msgrcv()\en");
627 printf("message received: %s\en", msg.mtext);
632 main(int argc, char *argv[])
635 int mode = 0; /* 1 = send, 2 = receive */
639 while ((opt = getopt(argc, argv, "srt:k:")) != \-1) {
648 msgtype = atoi(optarg);
650 usage(argv[0], "\-t option must be greater than 0\en");
653 msgkey = atoi(optarg);
656 usage(argv[0], "Unrecognized option\en");
661 usage(argv[0], "must use either \-s or \-r option\en");
663 qid = msgget(msgkey, IPC_CREAT | 0666);
671 get_msg(qid, msgtype);
673 send_msg(qid, msgtype);
682 .BR capabilities (7),