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

CONFORMING TO

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

NOTES

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
244       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
248       The following limits on message queue  resources  affect  the  msgsnd()
249       call:
250
251       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
255       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
262       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

BUGS

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

EXAMPLE

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

SEE ALSO

409       msgctl(2), msgget(2), capabilities(7), mq_overview(7), svipc(7)
410

COLOPHON

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/.
416
417
418
419Linux                             2017-09-15                          MSGOP(2)
Impressum