1MSGOP(2)                   Linux Programmer's Manual                  MSGOP(2)
2
3
4

NAME

6       msgrcv, msgsnd - System V message queue operations
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/ipc.h>
11       #include <sys/msg.h>
12
13       int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg);
14
15       ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp,
16                      int msgflg);
17

DESCRIPTION

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
24       The msgp argument is a pointer to a  caller-defined  structure  of  the
25       following general form:
26
27           struct msgbuf {
28               long mtype;       /* message type, must be > 0 */
29               char mtext[1];    /* message data */
30           };
31
32       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
39   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
43       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
50       * 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
54       * 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
61       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
66       A blocked msgsnd() call may also fail if:
67
68       * the queue is removed, in which case the system call fails with  errno
69         set to EIDRM; or
70
71       * 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
77       Upon  successful completion the message queue data structure is updated
78       as follows:
79
80              msg_lspid is set to the process ID of the calling process.
81
82              msg_qnum is incremented by 1.
83
84              msg_stime is set to the current time.
85
86   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
90       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
99       Unless MSG_COPY is specified in msgflg (see below), the msgtyp argument
100       specifies the type of message requested, as follows:
101
102       * If msgtyp is 0, then the first message in the queue is read.
103
104       * 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
109       * 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
113       The msgflg argument is a bit mask constructed by ORing together zero or
114       more of the following flags:
115
116       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
120       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
125              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
131              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
135       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
139       MSG_NOERROR
140              To truncate the message text if longer than msgsz bytes.
141
142       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
146       * A message of the desired type is placed in the queue.
147
148       * The message queue is removed from the system.  In this case, the sys‐
149         tem call fails with errno set to EIDRM.
150
151       * 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
157       Upon successful completion the message queue data structure is  updated
158       as follows:
159
160              msg_lrpid is set to the process ID of the calling process.
161
162              msg_qnum is decremented by 1.
163
164              msg_rtime is set to the current time.
165

RETURN VALUE

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

ERRORS

172       When  msgsnd() fails, errno will be set to one among the following val‐
173       ues:
174
175       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
179       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
182       EFAULT The address pointed to by msgp isn't accessible.
183
184       EIDRM  The message queue was removed.
185
186       EINTR  Sleeping on a full message queue condition, the process caught a
187              signal.
188
189       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
193       ENOMEM The system does not have enough memory to make  a  copy  of  the
194              message pointed to by msgp.
195
196       When  msgrcv() fails, errno will be set to one among the following val‐
197       ues:
198
199       E2BIG  The message text length is greater than  msgsz  and  MSG_NOERROR
200              isn't specified in msgflg.
201
202       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
206       EFAULT The address pointed to by msgp isn't accessible.
207
208       EIDRM  While the process was sleeping to receive a message, the message
209              queue was removed.
210
211       EINTR  While the process was sleeping to receive a message, the process
212              caught a signal; see signal(7).
213
214       EINVAL msqid was invalid, or msgsz was less than 0.
215
216       EINVAL (since Linux 3.14)
217              msgflg specified MSG_COPY, but not IPC_NOWAIT.
218
219       EINVAL (since Linux 3.14)
220              msgflg specified both MSG_COPY and MSG_EXCEPT.
221
222       ENOMSG IPC_NOWAIT  was  specified  in  msgflg  and  no  message  of the
223              requested type existed on the message queue.
224
225       ENOMSG IPC_NOWAIT and MSG_COPY were specified in msgflg and  the  queue
226              contains less than msgtyp messages.
227
228       ENOSYS (since Linux 3.8)
229              MSG_COPY was specified in msgflg, and this kernel was configured
230              without CONFIG_CHECKPOINT_RESTORE.
231

CONFORMING TO

233       POSIX.1-2001, POSIX.1-2008, SVr4.
234
235       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

NOTES

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
245       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
249       The  following  limits  on  message queue resources affect the msgsnd()
250       call:
251
252       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
256       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
263       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

BUGS

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
275       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

EXAMPLE

281       The program below demonstrates the use of msgsnd() and msgrcv().
282
283       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
286       The following shell session shows a sample run of the program:
287
288           $ ./a.out -s
289           sent: a message at Wed Mar  4 16:25:45 2015
290
291           $ ./a.out -r
292           message received: a message at Wed Mar  4 16:25:45 2015
293
294   Program source
295
296       #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
306       struct msgbuf {
307           long mtype;
308           char mtext[80];
309       };
310
311       static void
312       usage(char *prog_name, char *msg)
313       {
314           if (msg != NULL)
315               fputs(msg, stderr);
316
317           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
326       static void
327       send_msg(int qid, int msgtype)
328       {
329           struct msgbuf msg;
330           time_t t;
331
332           msg.mtype = msgtype;
333
334           time(&t);
335           snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
336                   ctime(&t));
337
338           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
346       static void
347       get_msg(int qid, int msgtype)
348       {
349           struct msgbuf msg;
350
351           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
362       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
370           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
391           if (mode == 0)
392               usage(argv[0], "must use either -s or -r option\n");
393
394           qid = msgget(msgkey, IPC_CREAT | 0666);
395
396           if (qid == -1) {
397               perror("msgget");
398               exit(EXIT_FAILURE);
399           }
400
401           if (mode == 2)
402               get_msg(qid, msgtype);
403           else
404               send_msg(qid, msgtype);
405
406           exit(EXIT_SUCCESS);
407       }
408

SEE ALSO

410       msgctl(2), msgget(2), capabilities(7), mq_overview(7), sysvipc(7)
411

COLOPHON

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/.
417
418
419
420Linux                             2019-08-02                          MSGOP(2)
Impressum