1MSGOP(2)                      System Calls Manual                     MSGOP(2)
2
3
4

NAME

6       msgrcv, msgsnd - System V message queue operations
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/msg.h>
13
14       int msgsnd(int msqid, const void msgp[.msgsz], size_t msgsz,
15                      int msgflg);
16
17       ssize_t msgrcv(int msqid, void msgp[.msgsz], size_t msgsz, long msgtyp,
18                      int msgflg);
19

DESCRIPTION

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
26       The msgp argument is a pointer to a  caller-defined  structure  of  the
27       following general form:
28
29           struct msgbuf {
30               long mtype;       /* message type, must be > 0 */
31               char mtext[1];    /* message data */
32           };
33
34       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
41   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
45       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
52       •  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
56       •  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
63       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
68       A blocked msgsnd() call may also fail if:
69
70       •  the queue is removed, in which case the system call fails with errno
71          set to EIDRM; or
72
73       •  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
79       Upon  successful completion the message queue data structure is updated
80       as follows:
81
82msg_lspid is set to the process ID of the calling process.
83
84msg_qnum is incremented by 1.
85
86msg_stime is set to the current time.
87
88   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
92       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
101       Unless MSG_COPY is specified in msgflg (see below), the msgtyp argument
102       specifies the type of message requested, as follows:
103
104       •  If msgtyp is 0, then the first message in the queue is read.
105
106       •  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
111       •  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
115       The msgflg argument is a bit mask constructed by ORing together zero or
116       more of the following flags:
117
118       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
122       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
127              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
133              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
137       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
141       MSG_NOERROR
142              To truncate the message text if longer than msgsz bytes.
143
144       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
148       •  A message of the desired type is placed in the queue.
149
150       •  The  message  queue  is  removed from the system.  In this case, the
151          system call fails with errno set to EIDRM.
152
153       •  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
159       Upon successful completion the message queue data structure is  updated
160       as follows:
161
162              msg_lrpid is set to the process ID of the calling process.
163
164              msg_qnum is decremented by 1.
165
166              msg_rtime is set to the current time.
167

RETURN VALUE

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

ERRORS

174       msgsnd() can fail with the following errors:
175
176       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
180       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
183       EFAULT The address pointed to by msgp isn't accessible.
184
185       EIDRM  The message queue was removed.
186
187       EINTR  Sleeping on a full message queue condition, the process caught a
188              signal.
189
190       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
193       ENOMEM The system does not have enough memory to make  a  copy  of  the
194              message pointed to by msgp.
195
196       msgrcv() can fail with the following errors:
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  re‐
222              quested 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              Both MSG_COPY and IPC_NOWAIT were specified in msgflg, and  this
229              kernel was configured without CONFIG_CHECKPOINT_RESTORE.
230

STANDARDS

232       POSIX.1-2008.
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

HISTORY

238       POSIX.1-2001, SVr4.
239
240       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

NOTES

245       The following limits on message queue  resources  affect  the  msgsnd()
246       call:
247
248       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
252       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
259       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

BUGS

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

EXAMPLES

277       The program below demonstrates the use of msgsnd() and msgrcv().
278
279       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
282       The following shell session shows a sample run of the program:
283
284           $ ./a.out -s
285           sent: a message at Wed Mar  4 16:25:45 2015
286
287       $ ./a.out -r
288       message received: a message at Wed Mar  4 16:25:45 2015
289
290   Program source
291
292       #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
300       struct msgbuf {
301           long mtype;
302           char mtext[80];
303       };
304
305       static void
306       usage(char *prog_name, char *msg)
307       {
308           if (msg != NULL)
309               fputs(msg, stderr);
310
311           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
320       static void
321       send_msg(int qid, int msgtype)
322       {
323           time_t         t;
324           struct msgbuf  msg;
325
326           msg.mtype = msgtype;
327
328           time(&t);
329           snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
330                    ctime(&t));
331
332           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
341       static void
342       get_msg(int qid, int msgtype)
343       {
344           struct msgbuf msg;
345
346           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
358       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
366           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
387           if (mode == 0)
388               usage(argv[0], "must use either -s or -r option\n");
389
390           qid = msgget(msgkey, IPC_CREAT | 0666);
391
392           if (qid == -1) {
393               perror("msgget");
394               exit(EXIT_FAILURE);
395           }
396
397           if (mode == 2)
398               get_msg(qid, msgtype);
399           else
400               send_msg(qid, msgtype);
401
402           exit(EXIT_SUCCESS);
403       }
404

SEE ALSO

406       msgctl(2), msgget(2), capabilities(7), mq_overview(7), sysvipc(7)
407
408
409
410Linux man-pages 6.05              2023-05-03                          MSGOP(2)
Impressum