1MSGOP(2) Linux Programmer's Manual MSGOP(2)
2
6 msgrcv, msgsnd - System V message queue operations
7
9 #include <sys/msg.h>
10 int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg);
12 ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp,
14 int msgflg);
15
17 The msgsnd() and msgrcv() system calls are used to send messages to,
18 and receive messages from, a System V message queue. The calling
19 process must have write permission on the message queue in order to
20 send a message, and read permission to receive a message.
21 The msgp argument is a pointer to a caller-defined structure of the
23 following general form:
24 struct msgbuf {
26 long mtype; /* message type, must be > 0 */
27 char mtext[1]; /* message data */
28 };
29 The mtext field is an array (or other structure) whose size is speci‐
31 fied by msgsz, a nonnegative integer value. Messages of zero length
32 (i.e., no mtext field) are permitted. The mtype field must have a
33 strictly positive integer value. This value can be used by the receiv‐
34 ing process for message selection (see the description of msgrcv() be‐
35 low).
36 msgsnd()
38 The msgsnd() system call appends a copy of the message pointed to by
39 msgp to the message queue whose identifier is specified by msqid.
40 If sufficient space is available in the queue, msgsnd() succeeds imme‐
42 diately. The queue capacity is governed by the msg_qbytes field in the
43 associated data structure for the message queue. During queue creation
44 this field is initialized to MSGMNB bytes, but this limit can be modi‐
45 fied using msgctl(2). A message queue is considered to be full if ei‐
46 ther of the following conditions is true:
47 • Adding a new message to the queue would cause the total number of
49 bytes in the queue to exceed the queue's maximum size (the msg_qbytes
50 field).
51 • Adding another message to the queue would cause the total number of
53 messages in the queue to exceed the queue's maximum size (the
54 msg_qbytes field). This check is necessary to prevent an unlimited
55 number of zero-length messages being placed on the queue. Although
56 such messages contain no data, they nevertheless consume (locked)
57 kernel memory.
58 If insufficient space is available in the queue, then the default be‐
60 havior of msgsnd() is to block until space becomes available. If
61 IPC_NOWAIT is specified in msgflg, then the call instead fails with the
62 error EAGAIN.
63 A blocked msgsnd() call may also fail if:
65 • the queue is removed, in which case the system call fails with errno
67 set to EIDRM; or
68 • a signal is caught, in which case the system call fails with errno
70 set to EINTR;see signal(7). (msgsnd() is never automatically
71 restarted after being interrupted by a signal handler, regardless of
72 the setting of the SA_RESTART flag when establishing a signal han‐
73 dler.)
74 Upon successful completion the message queue data structure is updated
76 as follows:
77 • msg_lspid is set to the process ID of the calling process.
79 • msg_qnum is incremented by 1.
81 • msg_stime is set to the current time.
83 msgrcv()
85 The msgrcv() system call removes a message from the queue specified by
86 msqid and places it in the buffer pointed to by msgp.
87 The argument msgsz specifies the maximum size in bytes for the member
89 mtext of the structure pointed to by the msgp argument. If the message
90 text has length greater than msgsz, then the behavior depends on
91 whether MSG_NOERROR is specified in msgflg. If MSG_NOERROR is speci‐
92 fied, then the message text will be truncated (and the truncated part
93 will be lost); if MSG_NOERROR is not specified, then the message isn't
94 removed from the queue and the system call fails returning -1 with er‐
95 rno set to E2BIG.
96 Unless MSG_COPY is specified in msgflg (see below), the msgtyp argument
98 specifies the type of message requested, as follows:
99 • If msgtyp is 0, then the first message in the queue is read.
101 • If msgtyp is greater than 0, then the first message in the queue of
103 type msgtyp is read, unless MSG_EXCEPT was specified in msgflg, in
104 which case the first message in the queue of type not equal to msgtyp
105 will be read.
106 • If msgtyp is less than 0, then the first message in the queue with
108 the lowest type less than or equal to the absolute value of msgtyp
109 will be read.
110 The msgflg argument is a bit mask constructed by ORing together zero or
112 more of the following flags:
113 IPC_NOWAIT
115 Return immediately if no message of the requested type is in the
116 queue. The system call fails with errno set to ENOMSG.
117 MSG_COPY (since Linux 3.8)
119 Nondestructively fetch a copy of the message at the ordinal po‐
120 sition in the queue specified by msgtyp (messages are considered
121 to be numbered starting at 0).
122 This flag must be specified in conjunction with IPC_NOWAIT, with
124 the result that, if there is no message available at the given
125 position, the call fails immediately with the error ENOMSG. Be‐
126 cause they alter the meaning of msgtyp in orthogonal ways,
127 MSG_COPY and MSG_EXCEPT may not both be specified in msgflg.
128 The MSG_COPY flag was added for the implementation of the kernel
130 checkpoint-restore facility and is available only if the kernel
131 was built with the CONFIG_CHECKPOINT_RESTORE option.
132 MSG_EXCEPT
134 Used with msgtyp greater than 0 to read the first message in the
135 queue with message type that differs from msgtyp.
136 MSG_NOERROR
138 To truncate the message text if longer than msgsz bytes.
139 If no message of the requested type is available and IPC_NOWAIT isn't
141 specified in msgflg, the calling process is blocked until one of the
142 following conditions occurs:
143 • A message of the desired type is placed in the queue.
145 • The message queue is removed from the system. In this case, the sys‐
147 tem call fails with errno set to EIDRM.
148 • The calling process catches a signal. In this case, the system call
150 fails with errno set to EINTR. (msgrcv() is never automatically
151 restarted after being interrupted by a signal handler, regardless of
152 the setting of the SA_RESTART flag when establishing a signal han‐
153 dler.)
154 Upon successful completion the message queue data structure is updated
156 as follows:
157 msg_lrpid is set to the process ID of the calling process.
159 msg_qnum is decremented by 1.
161 msg_rtime is set to the current time.
163
165 On success, msgsnd() returns 0 and msgrcv() returns the number of bytes
166 actually copied into the mtext array. On failure, both functions re‐
167 turn -1, and set errno to indicate the error.
168
170 msgsnd() can fail with the following errors:
171 EACCES The calling process does not have write permission on the mes‐
173 sage queue, and does not have the CAP_IPC_OWNER capability in
174 the user namespace that governs its IPC namespace.
175 EAGAIN The message can't be sent due to the msg_qbytes limit for the
177 queue and IPC_NOWAIT was specified in msgflg.
178 EFAULT The address pointed to by msgp isn't accessible.
180 EIDRM The message queue was removed.
182 EINTR Sleeping on a full message queue condition, the process caught a
184 signal.
185 EINVAL Invalid msqid value, or nonpositive mtype value, or invalid ms‐
187 gsz value (less than 0 or greater than the system value MSGMAX).
188 ENOMEM The system does not have enough memory to make a copy of the
190 message pointed to by msgp.
191 msgrcv() can fail with the following errors:
193 E2BIG The message text length is greater than msgsz and MSG_NOERROR
195 isn't specified in msgflg.
196 EACCES The calling process does not have read permission on the message
198 queue, and does not have the CAP_IPC_OWNER capability in the
199 user namespace that governs its IPC namespace.
200 EFAULT The address pointed to by msgp isn't accessible.
202 EIDRM While the process was sleeping to receive a message, the message
204 queue was removed.
205 EINTR While the process was sleeping to receive a message, the process
207 caught a signal; see signal(7).
208 EINVAL msqid was invalid, or msgsz was less than 0.
210 EINVAL (since Linux 3.14)
212 msgflg specified MSG_COPY, but not IPC_NOWAIT.
213 EINVAL (since Linux 3.14)
215 msgflg specified both MSG_COPY and MSG_EXCEPT.
216 ENOMSG IPC_NOWAIT was specified in msgflg and no message of the re‐
218 quested type existed on the message queue.
219 ENOMSG IPC_NOWAIT and MSG_COPY were specified in msgflg and the queue
221 contains less than msgtyp messages.
222 ENOSYS (since Linux 3.8)
224 Both MSG_COPY and IPC_NOWAIT were specified in msgflg, and this
225 kernel was configured without CONFIG_CHECKPOINT_RESTORE.
226
228 POSIX.1-2001, POSIX.1-2008, SVr4.
229 The MSG_EXCEPT and MSG_COPY flags are Linux-specific; their definitions
231 can be obtained by defining the _GNU_SOURCE feature test macro.
232
234 The msgp argument is declared as struct msgbuf * in glibc 2.0 and 2.1.
235 It is declared as void * in glibc 2.2 and later, as required by SUSv2
236 and SUSv3.
237 The following limits on message queue resources affect the msgsnd()
239 call:
240 MSGMAX Maximum size of a message text, in bytes (default value: 8192
242 bytes). On Linux, this limit can be read and modified via
243 /proc/sys/kernel/msgmax.
244 MSGMNB Maximum number of bytes that can be held in a message queue (de‐
246 fault value: 16384 bytes). On Linux, this limit can be read and
247 modified via /proc/sys/kernel/msgmnb. A privileged process
248 (Linux: a process with the CAP_SYS_RESOURCE capability) can in‐
249 crease the size of a message queue beyond MSGMNB using the ms‐
250 gctl(2) IPC_SET operation.
251 The implementation has no intrinsic system-wide limits on the number of
253 message headers (MSGTQL) and the number of bytes in the message pool
254 (MSGPOOL).
255
257 In Linux 3.13 and earlier, if msgrcv() was called with the MSG_COPY
258 flag, but without IPC_NOWAIT, and the message queue contained less than
259 msgtyp messages, then the call would block until the next message is
260 written to the queue. At that point, the call would return a copy of
261 the message, regardless of whether that message was at the ordinal po‐
262 sition msgtyp. This bug is fixed in Linux 3.14.
263 Specifying both MSG_COPY and MSC_EXCEPT in msgflg is a logical error
265 (since these flags impose different interpretations on msgtyp). In
266 Linux 3.13 and earlier, this error was not diagnosed by msgrcv(). This
267 bug is fixed in Linux 3.14.
268
270 The program below demonstrates the use of msgsnd() and msgrcv().
271 The example program is first run with the -s option to send a message
273 and then run again with the -r option to receive a message.
274 The following shell session shows a sample run of the program:
276 $ ./a.out -s
278 sent: a message at Wed Mar 4 16:25:45 2015
279 $ ./a.out -r
281 message received: a message at Wed Mar 4 16:25:45 2015
282 Program source
284 #include <stdio.h>
286 #include <stdlib.h>
287 #include <string.h>
288 #include <time.h>
289 #include <unistd.h>
290 #include <errno.h>
291 #include <sys/types.h>
292 #include <sys/ipc.h>
293 #include <sys/msg.h>
294 struct msgbuf {
296 long mtype;
297 char mtext[80];
298 };
299 static void
301 usage(char *prog_name, char *msg)
302 {
303 if (msg != NULL)
304 fputs(msg, stderr);
305 fprintf(stderr, "Usage: %s [options]\n", prog_name);
307 fprintf(stderr, "Options are:\n");
308 fprintf(stderr, "-s send message using msgsnd()\n");
309 fprintf(stderr, "-r read message using msgrcv()\n");
310 fprintf(stderr, "-t message type (default is 1)\n");
311 fprintf(stderr, "-k message queue key (default is 1234)\n");
312 exit(EXIT_FAILURE);
313 }
314 static void
316 send_msg(int qid, int msgtype)
317 {
318 struct msgbuf msg;
319 time_t t;
320 msg.mtype = msgtype;
322 time(&t);
324 snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
325 ctime(&t));
326 if (msgsnd(qid, &msg, sizeof(msg.mtext),
328 IPC_NOWAIT) == -1) {
329 perror("msgsnd error");
330 exit(EXIT_FAILURE);
331 }
332 printf("sent: %s\n", msg.mtext);
333 }
334 static void
336 get_msg(int qid, int msgtype)
337 {
338 struct msgbuf msg;
339 if (msgrcv(qid, &msg, sizeof(msg.mtext), msgtype,
341 MSG_NOERROR | IPC_NOWAIT) == -1) {
342 if (errno != ENOMSG) {
343 perror("msgrcv");
344 exit(EXIT_FAILURE);
345 }
346 printf("No message available for msgrcv()\n");
347 } else
348 printf("message received: %s\n", msg.mtext);
349 }
350 int
352 main(int argc, char *argv[])
353 {
354 int qid, opt;
355 int mode = 0; /* 1 = send, 2 = receive */
356 int msgtype = 1;
357 int msgkey = 1234;
358 while ((opt = getopt(argc, argv, "srt:k:")) != -1) {
360 switch (opt) {
361 case 's':
362 mode = 1;
363 break;
364 case 'r':
365 mode = 2;
366 break;
367 case 't':
368 msgtype = atoi(optarg);
369 if (msgtype <= 0)
370 usage(argv[0], "-t option must be greater than 0\n");
371 break;
372 case 'k':
373 msgkey = atoi(optarg);
374 break;
375 default:
376 usage(argv[0], "Unrecognized option\n");
377 }
378 }
379 if (mode == 0)
381 usage(argv[0], "must use either -s or -r option\n");
382 qid = msgget(msgkey, IPC_CREAT | 0666);
384 if (qid == -1) {
386 perror("msgget");
387 exit(EXIT_FAILURE);
388 }
389 if (mode == 2)
391 get_msg(qid, msgtype);
392 else
393 send_msg(qid, msgtype);
394 exit(EXIT_SUCCESS);
396 }
397
399 msgctl(2), msgget(2), capabilities(7), mq_overview(7), sysvipc(7)
400
402 This page is part of release 5.12 of the Linux man-pages project. A
403 description of the project, information about reporting bugs, and the
404 latest version of this page, can be found at
405 https://www.kernel.org/doc/man-pages/.
406Linux 2021-03-22 MSGOP(2)