1MSGOP(2) Linux Programmer's Manual MSGOP(2)
2
6 msgrcv, msgsnd - System V message queue operations
7
9 #include <sys/types.h>
10 #include <sys/ipc.h>
11 #include <sys/msg.h>
12 int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg);
14 ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp,
16 int msgflg);
17
19 The msgsnd() and msgrcv() system calls are used, respectively, to send
20 messages to, and receive messages from, a System V message queue. The
21 calling process must have write permission on the message queue in
22 order to send a message, and read permission to receive a message.
23 The msgp argument is a pointer to a caller-defined structure of the
25 following general form:
26 struct msgbuf {
28 long mtype; /* message type, must be > 0 */
29 char mtext[1]; /* message data */
30 };
31 The mtext field is an array (or other structure) whose size is speci‐
33 fied by msgsz, a nonnegative integer value. Messages of zero length
34 (i.e., no mtext field) are permitted. The mtype field must have a
35 strictly positive integer value. This value can be used by the receiv‐
36 ing process for message selection (see the description of msgrcv()
37 below).
38 msgsnd()
40 The msgsnd() system call appends a copy of the message pointed to by
41 msgp to the message queue whose identifier is specified by msqid.
42 If sufficient space is available in the queue, msgsnd() succeeds imme‐
44 diately. The queue capacity is governed by the msg_qbytes field in the
45 associated data structure for the message queue. During queue creation
46 this field is initialized to MSGMNB bytes, but this limit can be modi‐
47 fied using msgctl(2). A message queue is considered to be full if
48 either of the following conditions is true:
49 * Adding a new message to the queue would cause the total number of
51 bytes in the queue to exceed the queue's maximum size (the msg_qbytes
52 field).
53 * Adding another message to the queue would cause the total number of
55 messages in the queue to exceed the queue's maximum size (the
56 msg_qbytes field). This check is necessary to prevent an unlimited
57 number of zero-length messages being placed on the queue. Although
58 such messages contain no data, they nevertheless consume (locked)
59 kernel memory.
60 If insufficient space is available in the queue, then the default
62 behavior of msgsnd() is to block until space becomes available. If
63 IPC_NOWAIT is specified in msgflg, then the call instead fails with the
64 error EAGAIN.
65 A blocked msgsnd() call may also fail if:
67 * the queue is removed, in which case the system call fails with errno
69 set to EIDRM; or
70 * a signal is caught, in which case the system call fails with errno
72 set to EINTR;see signal(7). (msgsnd() is never automatically
73 restarted after being interrupted by a signal handler, regardless of
74 the setting of the SA_RESTART flag when establishing a signal han‐
75 dler.)
76 Upon successful completion the message queue data structure is updated
78 as follows:
79 msg_lspid is set to the process ID of the calling process.
81 msg_qnum is incremented by 1.
83 msg_stime is set to the current time.
85 msgrcv()
87 The msgrcv() system call removes a message from the queue specified by
88 msqid and places it in the buffer pointed to by msgp.
89 The argument msgsz specifies the maximum size in bytes for the member
91 mtext of the structure pointed to by the msgp argument. If the message
92 text has length greater than msgsz, then the behavior depends on
93 whether MSG_NOERROR is specified in msgflg. If MSG_NOERROR is speci‐
94 fied, then the message text will be truncated (and the truncated part
95 will be lost); if MSG_NOERROR is not specified, then the message isn't
96 removed from the queue and the system call fails returning -1 with
97 errno set to E2BIG.
98 Unless MSG_COPY is specified in msgflg (see below), the msgtyp argument
100 specifies the type of message requested, as follows:
101 * If msgtyp is 0, then the first message in the queue is read.
103 * If msgtyp is greater than 0, then the first message in the queue of
105 type msgtyp is read, unless MSG_EXCEPT was specified in msgflg, in
106 which case the first message in the queue of type not equal to msgtyp
107 will be read.
108 * If msgtyp is less than 0, then the first message in the queue with
110 the lowest type less than or equal to the absolute value of msgtyp
111 will be read.
112 The msgflg argument is a bit mask constructed by ORing together zero or
114 more of the following flags:
115 IPC_NOWAIT
117 Return immediately if no message of the requested type is in the
118 queue. The system call fails with errno set to ENOMSG.
119 MSG_COPY (since Linux 3.8)
121 Nondestructively fetch a copy of the message at the ordinal
122 position in the queue specified by msgtyp (messages are consid‐
123 ered to be numbered starting at 0).
124 This flag must be specified in conjunction with IPC_NOWAIT, with
126 the result that, if there is no message available at the given
127 position, the call fails immediately with the error ENOMSG.
128 Because they alter the meaning of msgtyp in orthogonal ways,
129 MSG_COPY and MSG_EXCEPT may not both be specified in msgflg.
130 The MSG_COPY flag was added for the implementation of the kernel
132 checkpoint-restore facility and is available only if the kernel
133 was built with the CONFIG_CHECKPOINT_RESTORE option.
134 MSG_EXCEPT
136 Used with msgtyp greater than 0 to read the first message in the
137 queue with message type that differs from msgtyp.
138 MSG_NOERROR
140 To truncate the message text if longer than msgsz bytes.
141 If no message of the requested type is available and IPC_NOWAIT isn't
143 specified in msgflg, the calling process is blocked until one of the
144 following conditions occurs:
145 * A message of the desired type is placed in the queue.
147 * The message queue is removed from the system. In this case, the sys‐
149 tem call fails with errno set to EIDRM.
150 * The calling process catches a signal. In this case, the system call
152 fails with errno set to EINTR. (msgrcv() is never automatically
153 restarted after being interrupted by a signal handler, regardless of
154 the setting of the SA_RESTART flag when establishing a signal han‐
155 dler.)
156 Upon successful completion the message queue data structure is updated
158 as follows:
159 msg_lrpid is set to the process ID of the calling process.
161 msg_qnum is decremented by 1.
163 msg_rtime is set to the current time.
165
167 On failure both functions return -1 with errno indicating the error,
168 otherwise msgsnd() returns 0 and msgrcv() returns the number of bytes
169 actually copied into the mtext array.
170
172 When msgsnd() fails, errno will be set to one among the following val‐
173 ues:
174 EACCES The calling process does not have write permission on the mes‐
176 sage queue, and does not have the CAP_IPC_OWNER capability.
177 EAGAIN The message can't be sent due to the msg_qbytes limit for the
179 queue and IPC_NOWAIT was specified in msgflg.
180 EFAULT The address pointed to by msgp isn't accessible.
182 EIDRM The message queue was removed.
184 EINTR Sleeping on a full message queue condition, the process caught a
186 signal.
187 EINVAL Invalid msqid value, or nonpositive mtype value, or invalid
189 msgsz value (less than 0 or greater than the system value MSG‐
190 MAX).
191 ENOMEM The system does not have enough memory to make a copy of the
193 message pointed to by msgp.
194 When msgrcv() fails, errno will be set to one among the following val‐
196 ues:
197 E2BIG The message text length is greater than msgsz and MSG_NOERROR
199 isn't specified in msgflg.
200 EACCES The calling process does not have read permission on the message
202 queue, and does not have the CAP_IPC_OWNER capability in the
203 user namespace that governs its IPC namespace.
204 EFAULT The address pointed to by msgp isn't accessible.
206 EIDRM While the process was sleeping to receive a message, the message
208 queue was removed.
209 EINTR While the process was sleeping to receive a message, the process
211 caught a signal; see signal(7).
212 EINVAL msqid was invalid, or msgsz was less than 0.
214 EINVAL (since Linux 3.14)
216 msgflg specified MSG_COPY, but not IPC_NOWAIT.
217 EINVAL (since Linux 3.14)
219 msgflg specified both MSG_COPY and MSG_EXCEPT.
220 ENOMSG IPC_NOWAIT was specified in msgflg and no message of the
222 requested type existed on the message queue.
223 ENOMSG IPC_NOWAIT and MSG_COPY were specified in msgflg and the queue
225 contains less than msgtyp messages.
226 ENOSYS (since Linux 3.8)
228 MSG_COPY was specified in msgflg, and this kernel was configured
229 without CONFIG_CHECKPOINT_RESTORE.
230
232 POSIX.1-2001, POSIX.1-2008, SVr4.
233 The MSG_EXCEPT and MSG_COPY flags are Linux-specific; their definitions
235 can be obtained by defining the _GNU_SOURCE feature test macro.
236
238 The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux
239 or by any version of POSIX. However, some old implementations required
240 the inclusion of these header files, and the SVID also documented their
241 inclusion. Applications intended to be portable to such old systems
242 may need to include these header files.
243 The msgp argument is declared as struct msgbuf * in glibc 2.0 and 2.1.
245 It is declared as void * in glibc 2.2 and later, as required by SUSv2
246 and SUSv3.
247 The following limits on message queue resources affect the msgsnd()
249 call:
250 MSGMAX Maximum size of a message text, in bytes (default value: 8192
252 bytes). On Linux, this limit can be read and modified via
253 /proc/sys/kernel/msgmax.
254 MSGMNB Maximum number of bytes that can be held in a message queue
256 (default value: 16384 bytes). On Linux, this limit can be read
257 and modified via /proc/sys/kernel/msgmnb. A privileged process
258 (Linux: a process with the CAP_SYS_RESOURCE capability) can
259 increase the size of a message queue beyond MSGMNB using the
260 msgctl(2) IPC_SET operation.
261 The implementation has no intrinsic system-wide limits on the number of
263 message headers (MSGTQL) and the number of bytes in the message pool
264 (MSGPOOL).
265
267 In Linux 3.13 and earlier, if msgrcv() was called with the MSG_COPY
268 flag, but without IPC_NOWAIT, and the message queue contained less than
269 msgtyp messages, then the call would block until the next message is
270 written to the queue. At that point, the call would return a copy of
271 the message, regardless of whether that message was at the ordinal
272 position msgtyp. This bug is fixed in Linux 3.14.
273 Specifying both MSG_COPY and MSC_EXCEPT in msgflg is a logical error
275 (since these flags impose different interpretations on msgtyp). In
276 Linux 3.13 and earlier, this error was not diagnosed by msgrcv(). This
277 bug is fixed in Linux 3.14.
278
280 The program below demonstrates the use of msgsnd() and msgrcv().
281 The example program is first run with the -s option to send a message
283 and then run again with the -r option to receive a message.
284 The following shell session shows a sample run of the program:
286 $ ./a.out -s
288 sent: a message at Wed Mar 4 16:25:45 2015
289 $ ./a.out -r
291 message received: a message at Wed Mar 4 16:25:45 2015
292 Program source
294 #include <stdio.h>
296 #include <stdlib.h>
297 #include <string.h>
298 #include <time.h>
299 #include <unistd.h>
300 #include <errno.h>
301 #include <sys/types.h>
302 #include <sys/ipc.h>
303 #include <sys/msg.h>
304 struct msgbuf {
306 long mtype;
307 char mtext[80];
308 };
309 static void
311 usage(char *prog_name, char *msg)
312 {
313 if (msg != NULL)
314 fputs(msg, stderr);
315 fprintf(stderr, "Usage: %s [options]\n", prog_name);
317 fprintf(stderr, "Options are:\n");
318 fprintf(stderr, "-s send message using msgsnd()\n");
319 fprintf(stderr, "-r read message using msgrcv()\n");
320 fprintf(stderr, "-t message type (default is 1)\n");
321 fprintf(stderr, "-k message queue key (default is 1234)\n");
322 exit(EXIT_FAILURE);
323 }
324 static void
326 send_msg(int qid, int msgtype)
327 {
328 struct msgbuf msg;
329 time_t t;
330 msg.mtype = msgtype;
332 time(&t);
334 snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
335 ctime(&t));
336 if (msgsnd(qid, (void *) &msg, sizeof(msg.mtext),
338 IPC_NOWAIT) == -1) {
339 perror("msgsnd error");
340 exit(EXIT_FAILURE);
341 }
342 printf("sent: %s\n", msg.mtext);
343 }
344 static void
346 get_msg(int qid, int msgtype)
347 {
348 struct msgbuf msg;
349 if (msgrcv(qid, (void *) &msg, sizeof(msg.mtext), msgtype,
351 MSG_NOERROR | IPC_NOWAIT) == -1) {
352 if (errno != ENOMSG) {
353 perror("msgrcv");
354 exit(EXIT_FAILURE);
355 }
356 printf("No message available for msgrcv()\n");
357 } else
358 printf("message received: %s\n", msg.mtext);
359 }
360 int
362 main(int argc, char *argv[])
363 {
364 int qid, opt;
365 int mode = 0; /* 1 = send, 2 = receive */
366 int msgtype = 1;
367 int msgkey = 1234;
368 while ((opt = getopt(argc, argv, "srt:k:")) != -1) {
370 switch (opt) {
371 case 's':
372 mode = 1;
373 break;
374 case 'r':
375 mode = 2;
376 break;
377 case 't':
378 msgtype = atoi(optarg);
379 if (msgtype <= 0)
380 usage(argv[0], "-t option must be greater than 0\n");
381 break;
382 case 'k':
383 msgkey = atoi(optarg);
384 break;
385 default:
386 usage(argv[0], "Unrecognized option\n");
387 }
388 }
389 if (mode == 0)
391 usage(argv[0], "must use either -s or -r option\n");
392 qid = msgget(msgkey, IPC_CREAT | 0666);
394 if (qid == -1) {
396 perror("msgget");
397 exit(EXIT_FAILURE);
398 }
399 if (mode == 2)
401 get_msg(qid, msgtype);
402 else
403 send_msg(qid, msgtype);
404 exit(EXIT_SUCCESS);
406 }
407
409 msgctl(2), msgget(2), capabilities(7), mq_overview(7), svipc(7)
410
412 This page is part of release 4.16 of the Linux man-pages project. A
413 description of the project, information about reporting bugs, and the
414 latest version of this page, can be found at
415 https://www.kernel.org/doc/man-pages/.
416Linux 2017-09-15 MSGOP(2)