man2/msgop.2

   1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   2 .\" and Copyright 2015 Bill Pemberton <wfp5p@worldbroken.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond <esr@thyrsus.com>
  27 .\" Modified Mon Jul 10 21:09:59 2000 by aeb
  28 .\" Modified 1 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  29 .\"     Language clean-ups.
  30 .\"     Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX
  31 .\"     Added note on restart behavior of msgsnd() and msgrcv()
  32 .\"     Formatting clean-ups (argument and field names marked as .I
  33 .\"             instead of .B)
  34 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  35 .\"     Added notes on capability requirements
  36 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  37 .\"     Language and formatting clean-ups
  38 .\"     Added notes on /proc files
  39 .\"
  40 .TH MSGOP 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  41 .SH NAME
  42 msgrcv, msgsnd \- System V message queue operations
  43 .SH SYNOPSIS
  44 .nf
  45 .B #include <sys/msg.h>
  46 .PP
  47 .BI "int msgsnd(int " msqid ", const void *" msgp ", size_t " msgsz \
  48 ", int " msgflg );
  49 .PP
  50 .BI "ssize_t msgrcv(int " msqid ", void *" msgp ", size_t " msgsz \
  51 ", long " msgtyp ,
  52 .BI "               int " msgflg );
  53 .fi
  54 .SH DESCRIPTION
  55 The
  56 .BR msgsnd ()
  57 and
  58 .BR msgrcv ()
  59 system calls are used to send messages to,
  60 and receive messages from, a System\ V message queue.
  61 The calling process must have write permission on the message queue
  62 in order to send a message, and read permission to receive a message.
  63 .PP
  64 The
  65 .I msgp
  66 argument is a pointer to a caller-defined structure
  67 of the following general form:
  68 .PP
  69 .in +4n
  70 .EX
  71 struct msgbuf {
  72     long mtype;       /* message type, must be > 0 */
  73     char mtext[1];    /* message data */
  74 };
  75 .EE
  76 .in
  77 .PP
  78 The
  79 .I mtext
  80 field is an array (or other structure) whose size is specified by
  81 .IR msgsz ,
  82 a nonnegative integer value.
  83 Messages of zero length (i.e., no
  84 .I mtext
  85 field) are permitted.
  86 The
  87 .I mtype
  88 field must have a strictly positive integer value.
  89 This value can be
  90 used by the receiving process for message selection
  91 (see the description of
  92 .BR msgrcv ()
  93 below).
  94 .SS msgsnd()
  95 The
  96 .BR msgsnd ()
  97 system call appends a copy of the message pointed to by
  98 .I msgp
  99 to the message queue whose identifier is specified
 100 by
 101 .IR msqid .
 102 .PP
 103 If sufficient space is available in the queue,
 104 .BR msgsnd ()
 105 succeeds immediately.
 106 The queue capacity is governed by the
 107 .I msg_qbytes
 108 field in the associated data structure for the message queue.
 109 During queue creation this field is initialized to
 110 .B MSGMNB
 111 bytes, but this limit can be modified using
 112 .BR msgctl (2).
 113 A message queue is considered to be full if either of the following
 114 conditions is true:
 115 .IP \(bu 2
 116 Adding a new message to the queue would cause the total number of bytes
 117 in the queue to exceed the queue's maximum size (the
 118 .I msg_qbytes
 119 field).
 120 .IP \(bu
 121 Adding another message to the queue would cause the total number of messages
 122 in the queue to exceed the queue's maximum size (the
 123 .I msg_qbytes
 124 field).
 125 This check is necessary to prevent an unlimited number of zero-length
 126 messages being placed on the queue.
 127 Although such messages contain no data,
 128 they nevertheless consume (locked) kernel memory.
 129 .PP
 130 If insufficient space is available in the queue, then the default
 131 behavior of
 132 .BR msgsnd ()
 133 is to block until space becomes available.
 134 If
 135 .B IPC_NOWAIT
 136 is specified in
 137 .IR msgflg ,
 138 then the call instead fails with the error
 139 .BR EAGAIN .
 140 .PP
 141 A blocked
 142 .BR msgsnd ()
 143 call may also fail if:
 144 .IP \(bu 2
 145 the queue is removed,
 146 in which case the system call fails with
 147 .I errno
 148 set to
 149 .BR EIDRM ;
 150 or
 151 .IP \(bu
 152 a signal is caught, in which case the system call fails
 153 with
 154 .I errno
 155 set to
 156 .BR EINTR ; see
 157 .BR signal (7).
 158 .RB ( msgsnd ()
 159 is never automatically restarted after being interrupted by a
 160 signal handler, regardless of the setting of the
 161 .B SA_RESTART
 162 flag when establishing a signal handler.)
 163 .PP
 164 Upon successful completion the message queue data structure is updated
 165 as follows:
 166 .IP \(bu 2
 167 .I msg_lspid
 168 is set to the process ID of the calling process.
 169 .IP \(bu
 170 .I msg_qnum
 171 is incremented by 1.
 172 .IP \(bu
 173 .I msg_stime
 174 is set to the current time.
 175 .SS msgrcv()
 176 The
 177 .BR msgrcv ()
 178 system call removes a message from the queue specified by
 179 .I msqid
 180 and places it in the buffer
 181 pointed to by
 182 .IR msgp .
 183 .PP
 184 The argument
 185 .I msgsz
 186 specifies the maximum size in bytes for the member
 187 .I mtext
 188 of the structure pointed to by the
 189 .I msgp
 190 argument.
 191 If the message text has length greater than
 192 .IR msgsz ,
 193 then the behavior depends on whether
 194 .B MSG_NOERROR
 195 is specified in
 196 .IR msgflg .
 197 If
 198 .B MSG_NOERROR
 199 is specified, then
 200 the message text will be truncated (and the truncated part will be
 201 lost); if
 202 .B MSG_NOERROR
 203 is not specified, then
 204 the message isn't removed from the queue and
 205 the system call fails returning \-1 with
 206 .I errno
 207 set to
 208 .BR E2BIG .
 209 .PP
 210 Unless
 211 .B MSG_COPY
 212 is specified in
 213 .IR msgflg
 214 (see below),
 215 the
 216 .I msgtyp
 217 argument specifies the type of message requested, as follows:
 218 .IP \(bu 2
 219 If
 220 .I msgtyp
 221 is 0,
 222 then the first message in the queue is read.
 223 .IP \(bu
 224 If
 225 .I msgtyp
 226 is greater than 0,
 227 then the first message in the queue of type
 228 .I msgtyp
 229 is read, unless
 230 .B MSG_EXCEPT
 231 was specified in
 232 .IR msgflg ,
 233 in which case
 234 the first message in the queue of type not equal to
 235 .I msgtyp
 236 will be read.
 237 .IP \(bu
 238 If
 239 .I msgtyp
 240 is less than 0,
 241 then the first message in the queue with the lowest type less than or
 242 equal to the absolute value of
 243 .I msgtyp
 244 will be read.
 245 .PP
 246 The
 247 .I msgflg
 248 argument is a bit mask constructed by ORing together zero or more
 249 of the following flags:
 250 .TP
 251 .B IPC_NOWAIT
 252 Return immediately if no message of the requested type is in the queue.
 253 The system call fails with
 254 .I errno
 255 set to
 256 .BR ENOMSG .
 257 .TP
 258 .BR MSG_COPY " (since Linux 3.8)"
 259 .\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8
 260 Nondestructively fetch a copy of the message at the ordinal position
 261 in the queue specified by
 262 .I msgtyp
 263 (messages are considered to be numbered starting at 0).
 264 .IP
 265 This flag must be specified in conjunction with
 266 .BR IPC_NOWAIT ,
 267 with the result that, if there is no message available at the given position,
 268 the call fails immediately with the error
 269 .BR ENOMSG .
 270 Because they alter the meaning of
 271 .I msgtyp
 272 in orthogonal ways,
 273 .BR MSG_COPY
 274 and
 275 .BR MSG_EXCEPT
 276 may not both be specified in
 277 .IR msgflg .
 278 .IP
 279 The
 280 .BR MSG_COPY
 281 flag was added for the implementation of
 282 the kernel checkpoint-restore facility and
 283 is available only if the kernel was built with the
 284 .B CONFIG_CHECKPOINT_RESTORE
 285 option.
 286 .TP
 287 .B MSG_EXCEPT
 288 Used with
 289 .I msgtyp
 290 greater than 0
 291 to read the first message in the queue with message type that differs
 292 from
 293 .IR msgtyp .
 294 .TP
 295 .B MSG_NOERROR
 296 To truncate the message text if longer than
 297 .I msgsz
 298 bytes.
 299 .PP
 300 If no message of the requested type is available and
 301 .B IPC_NOWAIT
 302 isn't specified in
 303 .IR msgflg ,
 304 the calling process is blocked until one of the following conditions occurs:
 305 .IP \(bu 2
 306 A message of the desired type is placed in the queue.
 307 .IP \(bu
 308 The message queue is removed from the system.
 309 In this case, the system call fails with
 310 .I errno
 311 set to
 312 .BR EIDRM .
 313 .IP \(bu
 314 The calling process catches a signal.
 315 In this case, the system call fails with
 316 .I errno
 317 set to
 318 .BR EINTR .
 319 .RB ( msgrcv ()
 320 is never automatically restarted after being interrupted by a
 321 signal handler, regardless of the setting of the
 322 .B SA_RESTART
 323 flag when establishing a signal handler.)
 324 .PP
 325 Upon successful completion the message queue data structure is updated
 326 as follows:
 327 .IP
 328 .I msg_lrpid
 329 is set to the process ID of the calling process.
 330 .IP
 331 .I msg_qnum
 332 is decremented by 1.
 333 .IP
 334 .I msg_rtime
 335 is set to the current time.
 336 .SH RETURN VALUE
 337 On success,
 338 .BR msgsnd ()
 339 returns 0
 340 and
 341 .BR msgrcv ()
 342 returns the number of bytes actually copied into the
 343 .I mtext
 344 array.
 345 On failure, both functions return \-1, and set
 346 .I errno
 347 to indicate the error.
 348 .SH ERRORS
 349 .BR msgsnd ()
 350 can fail with the following errors:
 351 .TP
 352 .B EACCES
 353 The calling process does not have write permission on the message queue,
 354 and does not have the
 355 .B CAP_IPC_OWNER
 356 capability in the user namespace that governs its IPC namespace.
 357 .TP
 358 .B EAGAIN
 359 The message can't be sent due to the
 360 .I msg_qbytes
 361 limit for the queue and
 362 .B IPC_NOWAIT
 363 was specified in
 364 .IR msgflg .
 365 .TP
 366 .B EFAULT
 367 The address pointed to by
 368 .I msgp
 369 isn't accessible.
 370 .TP
 371 .B EIDRM
 372 The message queue was removed.
 373 .TP
 374 .B EINTR
 375 Sleeping on a full message queue condition, the process caught a signal.
 376 .TP
 377 .B EINVAL
 378 Invalid
 379 .I msqid
 380 value, or nonpositive
 381 .I mtype
 382 value, or
 383 invalid
 384 .I msgsz
 385 value (less than 0 or greater than the system value
 386 .BR MSGMAX ).
 387 .TP
 388 .B ENOMEM
 389 The system does not have enough memory to make a copy of the
 390 message pointed to by
 391 .IR msgp .
 392 .PP
 393 .BR msgrcv ()
 394 can fail with the following errors:
 395 .TP
 396 .B E2BIG
 397 The message text length is greater than
 398 .I msgsz
 399 and
 400 .B MSG_NOERROR
 401 isn't specified in
 402 .IR msgflg .
 403 .TP
 404 .B EACCES
 405 The calling process does not have read permission on the message queue,
 406 and does not have the
 407 .B CAP_IPC_OWNER
 408 capability in the user namespace that governs its IPC namespace.
 409 .TP
 410 .B EFAULT
 411 The address pointed to by
 412 .I msgp
 413 isn't accessible.
 414 .TP
 415 .B EIDRM
 416 While the process was sleeping to receive a message,
 417 the message queue was removed.
 418 .TP
 419 .B EINTR
 420 While the process was sleeping to receive a message,
 421 the process caught a signal; see
 422 .BR signal (7).
 423 .TP
 424 .B EINVAL
 425 .I msqid
 426 was invalid, or
 427 .I msgsz
 428 was less than 0.
 429 .TP
 430 .BR EINVAL " (since Linux 3.14)"
 431 .I msgflg
 432 specified
 433 .BR MSG_COPY ,
 434 but not
 435 .BR IPC_NOWAIT .
 436 .TP
 437 .BR EINVAL " (since Linux 3.14)"
 438 .I msgflg
 439 specified both
 440 .BR MSG_COPY
 441 and
 442 .BR MSG_EXCEPT .
 443 .TP
 444 .B ENOMSG
 445 .B IPC_NOWAIT
 446 was specified in
 447 .I msgflg
 448 and no message of the requested type existed on the message queue.
 449 .TP
 450 .B ENOMSG
 451 .B IPC_NOWAIT
 452 and
 453 .B MSG_COPY
 454 were specified in
 455 .I msgflg
 456 and the queue contains less than
 457 .I msgtyp
 458 messages.
 459 .TP
 460 .BR ENOSYS " (since Linux 3.8)"
 461 Both
 462 .B MSG_COPY
 463 and
 464 .B IPC_NOWAIT
 465 were specified in
 466 .IR msgflg ,
 467 and this kernel was configured without
 468 .BR CONFIG_CHECKPOINT_RESTORE .
 469 .SH CONFORMING TO
 470 POSIX.1-2001, POSIX.1-2008, SVr4.
 471 .PP
 472 The
 473 .B MSG_EXCEPT
 474 and
 475 .B MSG_COPY
 476 flags are Linux-specific;
 477 their definitions can be obtained by defining the
 478 .B _GNU_SOURCE
 479 .\" MSG_COPY since glibc 2.18
 480 feature test macro.
 481 .SH NOTES
 482 The
 483 .I msgp
 484 argument is declared as \fIstruct msgbuf\ *\fP in
 485 glibc 2.0 and 2.1.
 486 It is declared as \fIvoid\ *\fP
 487 in glibc 2.2 and later, as required by SUSv2 and SUSv3.
 488 .PP
 489 The following limits on message queue resources affect the
 490 .BR msgsnd ()
 491 call:
 492 .TP
 493 .B MSGMAX
 494 Maximum size of a message text, in bytes (default value: 8192 bytes).
 495 On Linux, this limit can be read and modified via
 496 .IR /proc/sys/kernel/msgmax .
 497 .TP
 498 .B MSGMNB
 499 Maximum number of bytes that can be held in a message queue
 500 (default value: 16384 bytes).
 501 On Linux, this limit can be read and modified via
 502 .IR /proc/sys/kernel/msgmnb .
 503 A privileged process
 504 (Linux: a process with the
 505 .B CAP_SYS_RESOURCE
 506 capability)
 507 can increase the size of a message queue beyond
 508 .B MSGMNB
 509 using the
 510 .BR msgctl (2)
 511 .B IPC_SET
 512 operation.
 513 .PP
 514 The implementation has no intrinsic system-wide limits on the
 515 number of message headers
 516 .RB ( MSGTQL )
 517 and the number of bytes in the message pool
 518 .RB ( MSGPOOL ).
 519 .SH BUGS
 520 In Linux 3.13 and earlier,
 521 if
 522 .BR msgrcv ()
 523 was called with the
 524 .BR MSG_COPY
 525 flag, but without
 526 .BR IPC_NOWAIT ,
 527 and the message queue contained less than
 528 .I msgtyp
 529 messages, then the call would block until the next message is written
 530 to the queue.
 531 .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
 532 At that point, the call would return a copy of the message,
 533 .I regardless
 534 of whether that message was at the ordinal position
 535 .IR msgtyp .
 536 This bug is fixed
 537 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
 538 in Linux 3.14.
 539 .PP
 540 Specifying both
 541 .B MSG_COPY
 542 and
 543 .B MSC_EXCEPT
 544 in
 545 .I msgflg
 546 is a logical error (since these flags impose different interpretations on
 547 .IR msgtyp ).
 548 In Linux 3.13 and earlier,
 549 .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
 550 this error was not diagnosed by
 551 .BR msgrcv ().
 552 This bug is fixed
 553 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
 554 in Linux 3.14.
 555 .SH EXAMPLES
 556 The program below demonstrates the use of
 557 .BR msgsnd ()
 558 and
 559 .BR msgrcv ().
 560 .PP
 561 The example program is first run with the \fB\-s\fP option to send a
 562 message and then run again with the \fB\-r\fP option to receive a
 563 message.
 564 .PP
 565 The following shell session shows a sample run of the program:
 566 .PP
 567 .in +4n
 568 .EX
 569 .RB "$" " ./a.out \-s"
 570 sent: a message at Wed Mar  4 16:25:45 2015
 571
 572 .RB "$" " ./a.out \-r"
 573 message received: a message at Wed Mar  4 16:25:45 2015
 574 .EE
 575 .in
 576 .SS Program source
 577 \&
 578 .EX
 579 #include <stdio.h>
 580 #include <stdlib.h>
 581 #include <string.h>
 582 #include <time.h>
 583 #include <unistd.h>
 584 #include <errno.h>
 585 #include <sys/types.h>
 586 #include <sys/ipc.h>
 587 #include <sys/msg.h>
 588
 589 struct msgbuf {
 590     long mtype;
 591     char mtext[80];
 592 };
 593
 594 static void
 595 usage(char *prog_name, char *msg)
 596 {
 597     if (msg != NULL)
 598         fputs(msg, stderr);
 599
 600     fprintf(stderr, "Usage: %s [options]\en", prog_name);
 601     fprintf(stderr, "Options are:\en");
 602     fprintf(stderr, "\-s        send message using msgsnd()\en");
 603     fprintf(stderr, "\-r        read message using msgrcv()\en");
 604     fprintf(stderr, "\-t        message type (default is 1)\en");
 605     fprintf(stderr, "\-k        message queue key (default is 1234)\en");
 606     exit(EXIT_FAILURE);
 607 }
 608
 609 static void
 610 send_msg(int qid, int msgtype)
 611 {
 612     struct msgbuf msg;
 613     time_t t;
 614
 615     msg.mtype = msgtype;
 616
 617     time(&t);
 618     snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
 619             ctime(&t));
 620
 621     if (msgsnd(qid, &msg, sizeof(msg.mtext),
 622                 IPC_NOWAIT) == \-1) {
 623         perror("msgsnd error");
 624         exit(EXIT_FAILURE);
 625     }
 626     printf("sent: %s\en", msg.mtext);
 627 }
 628
 629 static void
 630 get_msg(int qid, int msgtype)
 631 {
 632     struct msgbuf msg;
 633
 634     if (msgrcv(qid, &msg, sizeof(msg.mtext), msgtype,
 635                MSG_NOERROR | IPC_NOWAIT) == \-1) {
 636         if (errno != ENOMSG) {
 637             perror("msgrcv");
 638             exit(EXIT_FAILURE);
 639         }
 640         printf("No message available for msgrcv()\en");
 641     } else
 642         printf("message received: %s\en", msg.mtext);
 643 }
 644
 645 int
 646 main(int argc, char *argv[])
 647 {
 648     int qid, opt;
 649     int mode = 0;               /* 1 = send, 2 = receive */
 650     int msgtype = 1;
 651     int msgkey = 1234;
 652
 653     while ((opt = getopt(argc, argv, "srt:k:")) != \-1) {
 654         switch (opt) {
 655         case \(aqs\(aq:
 656             mode = 1;
 657             break;
 658         case \(aqr\(aq:
 659             mode = 2;
 660             break;
 661         case \(aqt\(aq:
 662             msgtype = atoi(optarg);
 663             if (msgtype <= 0)
 664                 usage(argv[0], "\-t option must be greater than 0\en");
 665             break;
 666         case \(aqk\(aq:
 667             msgkey = atoi(optarg);
 668             break;
 669         default:
 670             usage(argv[0], "Unrecognized option\en");
 671         }
 672     }
 673
 674     if (mode == 0)
 675         usage(argv[0], "must use either \-s or \-r option\en");
 676
 677     qid = msgget(msgkey, IPC_CREAT | 0666);
 678
 679     if (qid == \-1) {
 680         perror("msgget");
 681         exit(EXIT_FAILURE);
 682     }
 683
 684     if (mode == 2)
 685         get_msg(qid, msgtype);
 686     else
 687         send_msg(qid, msgtype);
 688
 689     exit(EXIT_SUCCESS);
 690 }
 691 .EE
 692 .SH SEE ALSO
 693 .BR msgctl (2),
 694 .BR msgget (2),
 695 .BR capabilities (7),
 696 .BR mq_overview (7),
 697 .BR sysvipc (7)