1MSGOP(2) System Calls Manual MSGOP(2)
2
6 msgrcv, msgsnd - System V message queue operations
7
9 Standard C library (libc, -lc)
10
12 #include <sys/msg.h>
13 int msgsnd(int msqid, const void msgp[.msgsz], size_t msgsz,
15 int msgflg);
16 ssize_t msgrcv(int msqid, void msgp[.msgsz], size_t msgsz, long msgtyp,
18 int msgflg);
19
21 The msgsnd() and msgrcv() system calls are used to send messages to,
22 and receive messages from, a System V message queue. The calling
23 process must have write permission on the message queue in order to
24 send a message, and read permission to receive a message.
25 The msgp argument is a pointer to a caller-defined structure of the
27 following general form:
28 struct msgbuf {
30 long mtype; /* message type, must be > 0 */
31 char mtext[1]; /* message data */
32 };
33 The mtext field is an array (or other structure) whose size is speci‐
35 fied by msgsz, a nonnegative integer value. Messages of zero length
36 (i.e., no mtext field) are permitted. The mtype field must have a
37 strictly positive integer value. This value can be used by the receiv‐
38 ing process for message selection (see the description of msgrcv() be‐
39 low).
40 msgsnd()
42 The msgsnd() system call appends a copy of the message pointed to by
43 msgp to the message queue whose identifier is specified by msqid.
44 If sufficient space is available in the queue, msgsnd() succeeds imme‐
46 diately. The queue capacity is governed by the msg_qbytes field in the
47 associated data structure for the message queue. During queue creation
48 this field is initialized to MSGMNB bytes, but this limit can be modi‐
49 fied using msgctl(2). A message queue is considered to be full if ei‐
50 ther of the following conditions is true:
51 • Adding a new message to the queue would cause the total number of
53 bytes in the queue to exceed the queue's maximum size (the
54 msg_qbytes field).
55 • Adding another message to the queue would cause the total number of
57 messages in the queue to exceed the queue's maximum size (the
58 msg_qbytes field). This check is necessary to prevent an unlimited
59 number of zero-length messages being placed on the queue. Although
60 such messages contain no data, they nevertheless consume (locked)
61 kernel memory.
62 If insufficient space is available in the queue, then the default be‐
64 havior of msgsnd() is to block until space becomes available. If
65 IPC_NOWAIT is specified in msgflg, then the call instead fails with the
66 error EAGAIN.
67 A blocked msgsnd() call may also fail if:
69 • the queue is removed, in which case the system call fails with errno
71 set to EIDRM; or
72 • a signal is caught, in which case the system call fails with errno
74 set to EINTR;see signal(7). (msgsnd() is never automatically
75 restarted after being interrupted by a signal handler, regardless of
76 the setting of the SA_RESTART flag when establishing a signal han‐
77 dler.)
78 Upon successful completion the message queue data structure is updated
80 as follows:
81 • msg_lspid is set to the process ID of the calling process.
83 • msg_qnum is incremented by 1.
85 • msg_stime is set to the current time.
87 msgrcv()
89 The msgrcv() system call removes a message from the queue specified by
90 msqid and places it in the buffer pointed to by msgp.
91 The argument msgsz specifies the maximum size in bytes for the member
93 mtext of the structure pointed to by the msgp argument. If the message
94 text has length greater than msgsz, then the behavior depends on
95 whether MSG_NOERROR is specified in msgflg. If MSG_NOERROR is speci‐
96 fied, then the message text will be truncated (and the truncated part
97 will be lost); if MSG_NOERROR is not specified, then the message isn't
98 removed from the queue and the system call fails returning -1 with er‐
99 rno set to E2BIG.
100 Unless MSG_COPY is specified in msgflg (see below), the msgtyp argument
102 specifies the type of message requested, as follows:
103 • If msgtyp is 0, then the first message in the queue is read.
105 • If msgtyp is greater than 0, then the first message in the queue of
107 type msgtyp is read, unless MSG_EXCEPT was specified in msgflg, in
108 which case the first message in the queue of type not equal to msg‐
109 typ will be read.
110 • If msgtyp is less than 0, then the first message in the queue with
112 the lowest type less than or equal to the absolute value of msgtyp
113 will be read.
114 The msgflg argument is a bit mask constructed by ORing together zero or
116 more of the following flags:
117 IPC_NOWAIT
119 Return immediately if no message of the requested type is in the
120 queue. The system call fails with errno set to ENOMSG.
121 MSG_COPY (since Linux 3.8)
123 Nondestructively fetch a copy of the message at the ordinal po‐
124 sition in the queue specified by msgtyp (messages are considered
125 to be numbered starting at 0).
126 This flag must be specified in conjunction with IPC_NOWAIT, with
128 the result that, if there is no message available at the given
129 position, the call fails immediately with the error ENOMSG. Be‐
130 cause they alter the meaning of msgtyp in orthogonal ways,
131 MSG_COPY and MSG_EXCEPT may not both be specified in msgflg.
132 The MSG_COPY flag was added for the implementation of the kernel
134 checkpoint-restore facility and is available only if the kernel
135 was built with the CONFIG_CHECKPOINT_RESTORE option.
136 MSG_EXCEPT
138 Used with msgtyp greater than 0 to read the first message in the
139 queue with message type that differs from msgtyp.
140 MSG_NOERROR
142 To truncate the message text if longer than msgsz bytes.
143 If no message of the requested type is available and IPC_NOWAIT isn't
145 specified in msgflg, the calling process is blocked until one of the
146 following conditions occurs:
147 • A message of the desired type is placed in the queue.
149 • The message queue is removed from the system. In this case, the
151 system call fails with errno set to EIDRM.
152 • The calling process catches a signal. In this case, the system call
154 fails with errno set to EINTR. (msgrcv() is never automatically
155 restarted after being interrupted by a signal handler, regardless of
156 the setting of the SA_RESTART flag when establishing a signal han‐
157 dler.)
158 Upon successful completion the message queue data structure is updated
160 as follows:
161 msg_lrpid is set to the process ID of the calling process.
163 msg_qnum is decremented by 1.
165 msg_rtime is set to the current time.
167
169 On success, msgsnd() returns 0 and msgrcv() returns the number of bytes
170 actually copied into the mtext array. On failure, both functions re‐
171 turn -1, and set errno to indicate the error.
172
174 msgsnd() can fail with the following errors:
175 EACCES The calling process does not have write permission on the mes‐
177 sage queue, and does not have the CAP_IPC_OWNER capability in
178 the user namespace that governs its IPC namespace.
179 EAGAIN The message can't be sent due to the msg_qbytes limit for the
181 queue and IPC_NOWAIT was specified in msgflg.
182 EFAULT The address pointed to by msgp isn't accessible.
184 EIDRM The message queue was removed.
186 EINTR Sleeping on a full message queue condition, the process caught a
188 signal.
189 EINVAL Invalid msqid value, or nonpositive mtype value, or invalid ms‐
191 gsz value (less than 0 or greater than the system value MSGMAX).
192 ENOMEM The system does not have enough memory to make a copy of the
194 message pointed to by msgp.
195 msgrcv() can fail with the following errors:
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 re‐
222 quested 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 Both MSG_COPY and IPC_NOWAIT were specified in msgflg, and this
229 kernel was configured without CONFIG_CHECKPOINT_RESTORE.
230
232 POSIX.1-2008.
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 POSIX.1-2001, SVr4.
239 The msgp argument is declared as struct msgbuf * in glibc 2.0 and 2.1.
241 It is declared as void * in glibc 2.2 and later, as required by SUSv2
242 and SUSv3.
243
245 The following limits on message queue resources affect the msgsnd()
246 call:
247 MSGMAX Maximum size of a message text, in bytes (default value: 8192
249 bytes). On Linux, this limit can be read and modified via
250 /proc/sys/kernel/msgmax.
251 MSGMNB Maximum number of bytes that can be held in a message queue (de‐
253 fault value: 16384 bytes). On Linux, this limit can be read and
254 modified via /proc/sys/kernel/msgmnb. A privileged process
255 (Linux: a process with the CAP_SYS_RESOURCE capability) can in‐
256 crease the size of a message queue beyond MSGMNB using the ms‐
257 gctl(2) IPC_SET operation.
258 The implementation has no intrinsic system-wide limits on the number of
260 message headers (MSGTQL) and the number of bytes in the message pool
261 (MSGPOOL).
262
264 In Linux 3.13 and earlier, if msgrcv() was called with the MSG_COPY
265 flag, but without IPC_NOWAIT, and the message queue contained less than
266 msgtyp messages, then the call would block until the next message is
267 written to the queue. At that point, the call would return a copy of
268 the message, regardless of whether that message was at the ordinal po‐
269 sition msgtyp. This bug is fixed in Linux 3.14.
270 Specifying both MSG_COPY and MSC_EXCEPT in msgflg is a logical error
272 (since these flags impose different interpretations on msgtyp). In
273 Linux 3.13 and earlier, this error was not diagnosed by msgrcv(). This
274 bug is fixed in Linux 3.14.
275
277 The program below demonstrates the use of msgsnd() and msgrcv().
278 The example program is first run with the -s option to send a message
280 and then run again with the -r option to receive a message.
281 The following shell session shows a sample run of the program:
283 $ ./a.out -s
285 sent: a message at Wed Mar 4 16:25:45 2015
286 $ ./a.out -r
288 message received: a message at Wed Mar 4 16:25:45 2015
289 Program source
291 #include <errno.h>
293 #include <stdio.h>
294 #include <stdlib.h>
295 #include <sys/ipc.h>
296 #include <sys/msg.h>
297 #include <time.h>
298 #include <unistd.h>
299 struct msgbuf {
301 long mtype;
302 char mtext[80];
303 };
304 static void
306 usage(char *prog_name, char *msg)
307 {
308 if (msg != NULL)
309 fputs(msg, stderr);
310 fprintf(stderr, "Usage: %s [options]\n", prog_name);
312 fprintf(stderr, "Options are:\n");
313 fprintf(stderr, "-s send message using msgsnd()\n");
314 fprintf(stderr, "-r read message using msgrcv()\n");
315 fprintf(stderr, "-t message type (default is 1)\n");
316 fprintf(stderr, "-k message queue key (default is 1234)\n");
317 exit(EXIT_FAILURE);
318 }
319 static void
321 send_msg(int qid, int msgtype)
322 {
323 time_t t;
324 struct msgbuf msg;
325 msg.mtype = msgtype;
327 time(&t);
329 snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
330 ctime(&t));
331 if (msgsnd(qid, &msg, sizeof(msg.mtext),
333 IPC_NOWAIT) == -1)
334 {
335 perror("msgsnd error");
336 exit(EXIT_FAILURE);
337 }
338 printf("sent: %s\n", msg.mtext);
339 }
340 static void
342 get_msg(int qid, int msgtype)
343 {
344 struct msgbuf msg;
345 if (msgrcv(qid, &msg, sizeof(msg.mtext), msgtype,
347 MSG_NOERROR | IPC_NOWAIT) == -1) {
348 if (errno != ENOMSG) {
349 perror("msgrcv");
350 exit(EXIT_FAILURE);
351 }
352 printf("No message available for msgrcv()\n");
353 } else {
354 printf("message received: %s\n", msg.mtext);
355 }
356 }
357 int
359 main(int argc, char *argv[])
360 {
361 int qid, opt;
362 int mode = 0; /* 1 = send, 2 = receive */
363 int msgtype = 1;
364 int msgkey = 1234;
365 while ((opt = getopt(argc, argv, "srt:k:")) != -1) {
367 switch (opt) {
368 case 's':
369 mode = 1;
370 break;
371 case 'r':
372 mode = 2;
373 break;
374 case 't':
375 msgtype = atoi(optarg);
376 if (msgtype <= 0)
377 usage(argv[0], "-t option must be greater than 0\n");
378 break;
379 case 'k':
380 msgkey = atoi(optarg);
381 break;
382 default:
383 usage(argv[0], "Unrecognized option\n");
384 }
385 }
386 if (mode == 0)
388 usage(argv[0], "must use either -s or -r option\n");
389 qid = msgget(msgkey, IPC_CREAT | 0666);
391 if (qid == -1) {
393 perror("msgget");
394 exit(EXIT_FAILURE);
395 }
396 if (mode == 2)
398 get_msg(qid, msgtype);
399 else
400 send_msg(qid, msgtype);
401 exit(EXIT_SUCCESS);
403 }
404
406 msgctl(2), msgget(2), capabilities(7), mq_overview(7), sysvipc(7)
407Linux man-pages 6.05 2023-05-03 MSGOP(2)