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 to send messages to,
20 and receive messages from, a System V message queue. The calling
21 process must have write permission on the message queue in order to
22 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 in
177 the user namespace that governs its IPC namespace.
178 EAGAIN The message can't be sent due to the msg_qbytes limit for the
180 queue and IPC_NOWAIT was specified in msgflg.
181 EFAULT The address pointed to by msgp isn't accessible.
183 EIDRM The message queue was removed.
185 EINTR Sleeping on a full message queue condition, the process caught a
187 signal.
188 EINVAL Invalid msqid value, or nonpositive mtype value, or invalid
190 msgsz value (less than 0 or greater than the system value MSG‐
191 MAX).
192 ENOMEM The system does not have enough memory to make a copy of the
194 message pointed to by msgp.
195 When msgrcv() fails, errno will be set to one among the following val‐
197 ues:
198 E2BIG The message text length is greater than msgsz and MSG_NOERROR
200 isn't specified in msgflg.
201 EACCES The calling process does not have read permission on the message
203 queue, and does not have the CAP_IPC_OWNER capability in the
204 user namespace that governs its IPC namespace.
205 EFAULT The address pointed to by msgp isn't accessible.
207 EIDRM While the process was sleeping to receive a message, the message
209 queue was removed.
210 EINTR While the process was sleeping to receive a message, the process
212 caught a signal; see signal(7).
213 EINVAL msqid was invalid, or msgsz was less than 0.
215 EINVAL (since Linux 3.14)
217 msgflg specified MSG_COPY, but not IPC_NOWAIT.
218 EINVAL (since Linux 3.14)
220 msgflg specified both MSG_COPY and MSG_EXCEPT.
221 ENOMSG IPC_NOWAIT was specified in msgflg and no message of the
223 requested type existed on the message queue.
224 ENOMSG IPC_NOWAIT and MSG_COPY were specified in msgflg and the queue
226 contains less than msgtyp messages.
227 ENOSYS (since Linux 3.8)
229 MSG_COPY was specified in msgflg, and this kernel was configured
230 without CONFIG_CHECKPOINT_RESTORE.
231
233 POSIX.1-2001, POSIX.1-2008, SVr4.
234 The MSG_EXCEPT and MSG_COPY flags are Linux-specific; their definitions
236 can be obtained by defining the _GNU_SOURCE feature test macro.
237
239 The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on Linux
240 or by any version of POSIX. However, some old implementations required
241 the inclusion of these header files, and the SVID also documented their
242 inclusion. Applications intended to be portable to such old systems
243 may need to include these header files.
244 The msgp argument is declared as struct msgbuf * in glibc 2.0 and 2.1.
246 It is declared as void * in glibc 2.2 and later, as required by SUSv2
247 and SUSv3.
248 The following limits on message queue resources affect the msgsnd()
250 call:
251 MSGMAX Maximum size of a message text, in bytes (default value: 8192
253 bytes). On Linux, this limit can be read and modified via
254 /proc/sys/kernel/msgmax.
255 MSGMNB Maximum number of bytes that can be held in a message queue
257 (default value: 16384 bytes). On Linux, this limit can be read
258 and modified via /proc/sys/kernel/msgmnb. A privileged process
259 (Linux: a process with the CAP_SYS_RESOURCE capability) can
260 increase the size of a message queue beyond MSGMNB using the
261 msgctl(2) IPC_SET operation.
262 The implementation has no intrinsic system-wide limits on the number of
264 message headers (MSGTQL) and the number of bytes in the message pool
265 (MSGPOOL).
266
268 In Linux 3.13 and earlier, if msgrcv() was called with the MSG_COPY
269 flag, but without IPC_NOWAIT, and the message queue contained less than
270 msgtyp messages, then the call would block until the next message is
271 written to the queue. At that point, the call would return a copy of
272 the message, regardless of whether that message was at the ordinal
273 position msgtyp. This bug is fixed in Linux 3.14.
274 Specifying both MSG_COPY and MSC_EXCEPT in msgflg is a logical error
276 (since these flags impose different interpretations on msgtyp). In
277 Linux 3.13 and earlier, this error was not diagnosed by msgrcv(). This
278 bug is fixed in Linux 3.14.
279
281 The program below demonstrates the use of msgsnd() and msgrcv().
282 The example program is first run with the -s option to send a message
284 and then run again with the -r option to receive a message.
285 The following shell session shows a sample run of the program:
287 $ ./a.out -s
289 sent: a message at Wed Mar 4 16:25:45 2015
290 $ ./a.out -r
292 message received: a message at Wed Mar 4 16:25:45 2015
293 Program source
295 #include <stdio.h>
297 #include <stdlib.h>
298 #include <string.h>
299 #include <time.h>
300 #include <unistd.h>
301 #include <errno.h>
302 #include <sys/types.h>
303 #include <sys/ipc.h>
304 #include <sys/msg.h>
305 struct msgbuf {
307 long mtype;
308 char mtext[80];
309 };
310 static void
312 usage(char *prog_name, char *msg)
313 {
314 if (msg != NULL)
315 fputs(msg, stderr);
316 fprintf(stderr, "Usage: %s [options]\n", prog_name);
318 fprintf(stderr, "Options are:\n");
319 fprintf(stderr, "-s send message using msgsnd()\n");
320 fprintf(stderr, "-r read message using msgrcv()\n");
321 fprintf(stderr, "-t message type (default is 1)\n");
322 fprintf(stderr, "-k message queue key (default is 1234)\n");
323 exit(EXIT_FAILURE);
324 }
325 static void
327 send_msg(int qid, int msgtype)
328 {
329 struct msgbuf msg;
330 time_t t;
331 msg.mtype = msgtype;
333 time(&t);
335 snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
336 ctime(&t));
337 if (msgsnd(qid, (void *) &msg, sizeof(msg.mtext),
339 IPC_NOWAIT) == -1) {
340 perror("msgsnd error");
341 exit(EXIT_FAILURE);
342 }
343 printf("sent: %s\n", msg.mtext);
344 }
345 static void
347 get_msg(int qid, int msgtype)
348 {
349 struct msgbuf msg;
350 if (msgrcv(qid, (void *) &msg, sizeof(msg.mtext), msgtype,
352 MSG_NOERROR | IPC_NOWAIT) == -1) {
353 if (errno != ENOMSG) {
354 perror("msgrcv");
355 exit(EXIT_FAILURE);
356 }
357 printf("No message available for msgrcv()\n");
358 } else
359 printf("message received: %s\n", msg.mtext);
360 }
361 int
363 main(int argc, char *argv[])
364 {
365 int qid, opt;
366 int mode = 0; /* 1 = send, 2 = receive */
367 int msgtype = 1;
368 int msgkey = 1234;
369 while ((opt = getopt(argc, argv, "srt:k:")) != -1) {
371 switch (opt) {
372 case 's':
373 mode = 1;
374 break;
375 case 'r':
376 mode = 2;
377 break;
378 case 't':
379 msgtype = atoi(optarg);
380 if (msgtype <= 0)
381 usage(argv[0], "-t option must be greater than 0\n");
382 break;
383 case 'k':
384 msgkey = atoi(optarg);
385 break;
386 default:
387 usage(argv[0], "Unrecognized option\n");
388 }
389 }
390 if (mode == 0)
392 usage(argv[0], "must use either -s or -r option\n");
393 qid = msgget(msgkey, IPC_CREAT | 0666);
395 if (qid == -1) {
397 perror("msgget");
398 exit(EXIT_FAILURE);
399 }
400 if (mode == 2)
402 get_msg(qid, msgtype);
403 else
404 send_msg(qid, msgtype);
405 exit(EXIT_SUCCESS);
407 }
408
410 msgctl(2), msgget(2), capabilities(7), mq_overview(7), sysvipc(7)
411
413 This page is part of release 5.02 of the Linux man-pages project. A
414 description of the project, information about reporting bugs, and the
415 latest version of this page, can be found at
416 https://www.kernel.org/doc/man-pages/.
417Linux 2019-08-02 MSGOP(2)