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