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 2021-03-22 "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 ", size_t " msgsz \
33 .BI "ssize_t msgrcv(int " msqid ", void *" msgp ", 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 .
453 POSIX.1-2001, POSIX.1-2008, SVr4.
459 flags are Linux-specific;
460 their definitions can be obtained by defining the
462 .\" MSG_COPY since glibc 2.18
467 argument is declared as \fIstruct msgbuf\ *\fP in
469 It is declared as \fIvoid\ *\fP
470 in glibc 2.2 and later, as required by SUSv2 and SUSv3.
472 The following limits on message queue resources affect the
477 Maximum size of a message text, in bytes (default value: 8192 bytes).
478 On Linux, this limit can be read and modified via
479 .IR /proc/sys/kernel/msgmax .
482 Maximum number of bytes that can be held in a message queue
483 (default value: 16384 bytes).
484 On Linux, this limit can be read and modified via
485 .IR /proc/sys/kernel/msgmnb .
487 (Linux: a process with the
490 can increase the size of a message queue beyond
497 The implementation has no intrinsic system-wide limits on the
498 number of message headers
500 and the number of bytes in the message pool
503 In Linux 3.13 and earlier,
510 and the message queue contained less than
512 messages, then the call would block until the next message is written
514 .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
515 At that point, the call would return a copy of the message,
517 of whether that message was at the ordinal position
520 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
529 is a logical error (since these flags impose different interpretations on
531 In Linux 3.13 and earlier,
532 .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
533 this error was not diagnosed by
536 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
539 The program below demonstrates the use of
544 The example program is first run with the \fB\-s\fP option to send a
545 message and then run again with the \fB\-r\fP option to receive a
548 The following shell session shows a sample run of the program:
552 .RB "$" " ./a.out \-s"
553 sent: a message at Wed Mar 4 16:25:45 2015
555 .RB "$" " ./a.out \-r"
556 message received: a message at Wed Mar 4 16:25:45 2015
561 .\" SRC BEGIN (msgop.c)
577 usage(char *prog_name, char *msg)
582 fprintf(stderr, "Usage: %s [options]\en", prog_name);
583 fprintf(stderr, "Options are:\en");
584 fprintf(stderr, "\-s send message using msgsnd()\en");
585 fprintf(stderr, "\-r read message using msgrcv()\en");
586 fprintf(stderr, "\-t message type (default is 1)\en");
587 fprintf(stderr, "\-k message queue key (default is 1234)\en");
592 send_msg(int qid, int msgtype)
600 snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
603 if (msgsnd(qid, &msg, sizeof(msg.mtext),
606 perror("msgsnd error");
609 printf("sent: %s\en", msg.mtext);
613 get_msg(int qid, int msgtype)
617 if (msgrcv(qid, &msg, sizeof(msg.mtext), msgtype,
618 MSG_NOERROR | IPC_NOWAIT) == \-1) {
619 if (errno != ENOMSG) {
623 printf("No message available for msgrcv()\en");
625 printf("message received: %s\en", msg.mtext);
630 main(int argc, char *argv[])
633 int mode = 0; /* 1 = send, 2 = receive */
637 while ((opt = getopt(argc, argv, "srt:k:")) != \-1) {
646 msgtype = atoi(optarg);
648 usage(argv[0], "\-t option must be greater than 0\en");
651 msgkey = atoi(optarg);
654 usage(argv[0], "Unrecognized option\en");
659 usage(argv[0], "must use either \-s or \-r option\en");
661 qid = msgget(msgkey, IPC_CREAT | 0666);
669 get_msg(qid, msgtype);
671 send_msg(qid, msgtype);
680 .BR capabilities (7),