original/man2/msgop.2

   1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond <esr@thyrsus.com>
  26 .\" Modified Mon Jul 10 21:09:59 2000 by aeb
  27 .\" Modified 1 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\"     Language clean-ups.
  29 .\"     Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX
  30 .\"     Added note on restart behavior of msgsnd() and msgrcv()
  31 .\"     Formatting clean-ups (argument and field names marked as .I
  32 .\"             instead of .B)
  33 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  34 .\"     Added notes on capability requirements
  35 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  36 .\"     Language and formatting clean-ups
  37 .\"     Added notes on /proc files
  38 .\" FIXME . Add example programs to this page.
  39 .\"
  40 .TH MSGOP 2 2014-03-17 "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/types.h>
  46 .B #include <sys/ipc.h>
  47 .B #include <sys/msg.h>
  48 .sp
  49 .BI "int msgsnd(int " msqid ", const void *" msgp ", size_t " msgsz \
  50 ", int " msgflg );
  51 .sp
  52 .BI "ssize_t msgrcv(int " msqid ", void *" msgp ", size_t " msgsz \
  53 ", long " msgtyp ,
  54 .BI "               int " msgflg );
  55 .fi
  56 .SH DESCRIPTION
  57 The
  58 .BR msgsnd ()
  59 and
  60 .BR msgrcv ()
  61 system calls are used, respectively, to send messages to,
  62 and receive messages from, a System V message queue.
  63 The calling process must have write permission on the message queue
  64 in order to send a message, and read permission to receive a message.
  65 .PP
  66 The
  67 .I msgp
  68 argument is a pointer to a caller-defined structure
  69 of the following general form:
  70 .in +4n
  71 .nf
  72
  73 struct msgbuf {
  74     long mtype;       /* message type, must be > 0 */
  75     char mtext[1];    /* message data */
  76 };
  77 .fi
  78 .in
  79 .PP
  80 The
  81 .I mtext
  82 field is an array (or other structure) whose size is specified by
  83 .IR msgsz ,
  84 a nonnegative integer value.
  85 Messages of zero length (i.e., no
  86 .I mtext
  87 field) are permitted.
  88 The
  89 .I mtype
  90 field must have a strictly positive integer value.
  91 This value can be
  92 used by the receiving process for message selection
  93 (see the description of
  94 .BR msgrcv ()
  95 below).
  96 .SS msgsnd()
  97 The
  98 .BR msgsnd ()
  99 system call appends a copy of the message pointed to by
 100 .I msgp
 101 to the message queue whose identifier is specified
 102 by
 103 .IR msqid .
 104 .PP
 105 If sufficient space is available in the queue,
 106 .BR msgsnd ()
 107 succeeds immediately.
 108 (The queue capacity is defined by the
 109 .I msg_qbytes
 110 field in the associated data structure for the message queue.
 111 During queue creation this field is initialized to
 112 .B MSGMNB
 113 bytes, but this limit can be modified using
 114 .BR msgctl (2).)
 115 If insufficient space is available in the queue, then the default
 116 behavior of
 117 .BR msgsnd ()
 118 is to block until space becomes available.
 119 If
 120 .B IPC_NOWAIT
 121 is specified in
 122 .IR msgflg ,
 123 then the call instead fails with the error
 124 .BR EAGAIN .
 125
 126 A blocked
 127 .BR msgsnd ()
 128 call may also fail if:
 129 .IP * 2
 130 the queue is removed,
 131 in which case the system call fails with
 132 .I errno
 133 set to
 134 .BR EIDRM ;
 135 or
 136 .IP *
 137 a signal is caught, in which case the system call fails
 138 with
 139 .I errno
 140 set to
 141 .BR EINTR ; see
 142 .BR signal (7).
 143 .RB ( msgsnd ()
 144 is never automatically restarted after being interrupted by a
 145 signal handler, regardless of the setting of the
 146 .B SA_RESTART
 147 flag when establishing a signal handler.)
 148 .PP
 149 Upon successful completion the message queue data structure is updated
 150 as follows:
 151 .IP
 152 .I msg_lspid
 153 is set to the process ID of the calling process.
 154 .IP
 155 .I msg_qnum
 156 is incremented by 1.
 157 .IP
 158 .I msg_stime
 159 is set to the current time.
 160 .SS msgrcv()
 161 The
 162 .BR msgrcv ()
 163 system call removes a message from the queue specified by
 164 .I msqid
 165 and places it in the buffer
 166 pointed to by
 167 .IR msgp .
 168 .PP
 169 The argument
 170 .I msgsz
 171 specifies the maximum size in bytes for the member
 172 .I mtext
 173 of the structure pointed to by the
 174 .I msgp
 175 argument.
 176 If the message text has length greater than
 177 .IR msgsz ,
 178 then the behavior depends on whether
 179 .B MSG_NOERROR
 180 is specified in
 181 .IR msgflg .
 182 If
 183 .B MSG_NOERROR
 184 is specified, then
 185 the message text will be truncated (and the truncated part will be
 186 lost); if
 187 .B MSG_NOERROR
 188 is not specified, then
 189 the message isn't removed from the queue and
 190 the system call fails returning \-1 with
 191 .I errno
 192 set to
 193 .BR E2BIG .
 194 .PP
 195 Unless
 196 .B MSG_COPY
 197 is specified in
 198 .IR msgflg
 199 (see below),
 200 the
 201 .I msgtyp
 202 argument specifies the type of message requested, as follows:
 203 .IP * 2
 204 If
 205 .I msgtyp
 206 is 0,
 207 then the first message in the queue is read.
 208 .IP *
 209 If
 210 .I msgtyp
 211 is greater than 0,
 212 then the first message in the queue of type
 213 .I msgtyp
 214 is read, unless
 215 .B MSG_EXCEPT
 216 was specified in
 217 .IR msgflg ,
 218 in which case
 219 the first message in the queue of type not equal to
 220 .I msgtyp
 221 will be read.
 222 .IP *
 223 If
 224 .I msgtyp
 225 is less than 0,
 226 then the first message in the queue with the lowest type less than or
 227 equal to the absolute value of
 228 .I msgtyp
 229 will be read.
 230 .PP
 231 The
 232 .I msgflg
 233 argument is a bit mask constructed by ORing together zero or more
 234 of the following flags:
 235 .TP
 236 .B IPC_NOWAIT
 237 Return immediately if no message of the requested type is in the queue.
 238 The system call fails with
 239 .I errno
 240 set to
 241 .BR ENOMSG .
 242 .TP
 243 .BR MSG_COPY " (since Linux 3.8)"
 244 .\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8
 245 Nondestructively fetch a copy of the message at the ordinal position
 246 in the queue specified by
 247 .I msgtyp
 248 (messages are considered to be numbered starting at 0).
 249
 250 This flag must be specified in conjunction with
 251 .BR IPC_NOWAIT ,
 252 with the result that, if there is no message available at the given position,
 253 the call fails immediately with the error
 254 .BR ENOMSG .
 255 Because they alter the meaning of
 256 .I msgtyp
 257 in orthogonal ways,
 258 .BR MSG_COPY
 259 and
 260 .BR MSG_EXCEPT
 261 may not both be specified in
 262 .IR msgflg .
 263
 264 The
 265 .BR MSG_COPY
 266 flag was added for the implementation of
 267 the kernel checkpoint-restore facility and
 268 is available only if the kernel was built with the
 269 .B CONFIG_CHECKPOINT_RESTORE
 270 option.
 271 .TP
 272 .B MSG_EXCEPT
 273 Used with
 274 .I msgtyp
 275 greater than 0
 276 to read the first message in the queue with message type that differs
 277 from
 278 .IR msgtyp .
 279 .TP
 280 .B MSG_NOERROR
 281 To truncate the message text if longer than
 282 .I msgsz
 283 bytes.
 284 .PP
 285 If no message of the requested type is available and
 286 .B IPC_NOWAIT
 287 isn't specified in
 288 .IR msgflg ,
 289 the calling process is blocked until one of the following conditions occurs:
 290 .IP * 2
 291 A message of the desired type is placed in the queue.
 292 .IP *
 293 The message queue is removed from the system.
 294 In this case, the system call fails with
 295 .I errno
 296 set to
 297 .BR EIDRM .
 298 .IP *
 299 The calling process catches a signal.
 300 In this case, the system call fails with
 301 .I errno
 302 set to
 303 .BR EINTR .
 304 .RB ( msgrcv ()
 305 is never automatically restarted after being interrupted by a
 306 signal handler, regardless of the setting of the
 307 .B SA_RESTART
 308 flag when establishing a signal handler.)
 309 .PP
 310 Upon successful completion the message queue data structure is updated
 311 as follows:
 312 .IP
 313 .I msg_lrpid
 314 is set to the process ID of the calling process.
 315 .IP
 316 .I msg_qnum
 317 is decremented by 1.
 318 .IP
 319 .I msg_rtime
 320 is set to the current time.
 321 .SH RETURN VALUE
 322 On failure both functions return \-1
 323 with
 324 .I errno
 325 indicating the error,
 326 otherwise
 327 .BR msgsnd ()
 328 returns 0
 329 and
 330 .BR msgrcv ()
 331 returns the number of bytes actually copied into the
 332 .I mtext
 333 array.
 334 .SH ERRORS
 335 When
 336 .BR msgsnd ()
 337 fails,
 338 .I errno
 339 will be set to one among the following values:
 340 .TP
 341 .B EACCES
 342 The calling process does not have write permission on the message queue,
 343 and does not have the
 344 .B CAP_IPC_OWNER
 345 capability.
 346 .TP
 347 .B EAGAIN
 348 The message can't be sent due to the
 349 .I msg_qbytes
 350 limit for the queue and
 351 .B IPC_NOWAIT
 352 was specified in
 353 .IR msgflg .
 354 .TP
 355 .B EFAULT
 356 The address pointed to by
 357 .I msgp
 358 isn't accessible.
 359 .TP
 360 .B EIDRM
 361 The message queue was removed.
 362 .TP
 363 .B EINTR
 364 Sleeping on a full message queue condition, the process caught a signal.
 365 .TP
 366 .B EINVAL
 367 Invalid
 368 .I msqid
 369 value, or nonpositive
 370 .I mtype
 371 value, or
 372 invalid
 373 .I msgsz
 374 value (less than 0 or greater than the system value
 375 .BR MSGMAX ).
 376 .TP
 377 .B ENOMEM
 378 The system does not have enough memory to make a copy of the
 379 message pointed to by
 380 .IR msgp .
 381 .PP
 382 When
 383 .BR msgrcv ()
 384 fails,
 385 .I errno
 386 will be set to one among the following values:
 387 .TP
 388 .B E2BIG
 389 The message text length is greater than
 390 .I msgsz
 391 and
 392 .B MSG_NOERROR
 393 isn't specified in
 394 .IR msgflg .
 395 .TP
 396 .B EACCES
 397 The calling process does not have read permission on the message queue,
 398 and does not have the
 399 .B CAP_IPC_OWNER
 400 capability.
 401 .TP
 402 .B EAGAIN
 403 No message was available in the queue and
 404 .B IPC_NOWAIT
 405 was specified in
 406 .IR msgflg .
 407 .TP
 408 .B EFAULT
 409 The address pointed to by
 410 .I msgp
 411 isn't accessible.
 412 .TP
 413 .B EIDRM
 414 While the process was sleeping to receive a message,
 415 the message queue was removed.
 416 .TP
 417 .B EINTR
 418 While the process was sleeping to receive a message,
 419 the process caught a signal; see
 420 .BR signal (7).
 421 .TP
 422 .B EINVAL
 423 .I msgqid
 424 was invalid, or
 425 .I msgsz
 426 was less than 0.
 427 .TP
 428 .BR EINVAL " (since Linux 3.14)"
 429 .I msgflg
 430 specified
 431 .BR MSG_COPY ,
 432 but not
 433 .BR IPC_NOWAIT .
 434 .TP
 435 .BR EINVAL " (since Linux 3.14)"
 436 .I msgflg
 437 specified both
 438 .BR MSG_COPY
 439 and
 440 .BR MSG_EXCEPT .
 441 .TP
 442 .B ENOMSG
 443 .B IPC_NOWAIT
 444 was specified in
 445 .I msgflg
 446 and no message of the requested type existed on the message queue.
 447 .TP
 448 .B ENOMSG
 449 .B IPC_NOWAIT
 450 and
 451 .B MSG_COPY
 452 were specified in
 453 .I msgflg
 454 and the queue contains less than
 455 .I msgtyp
 456 messages.
 457 .TP
 458 .BR ENOSYS " (since Linux 3.8)"
 459 .I MSG_COPY
 460 was specified in
 461 .IR msgflg ,
 462 and this kernel was configured without
 463 .BR CONFIG_CHECKPOINT_RESTORE .
 464 .SH CONFORMING TO
 465 SVr4, POSIX.1-2001.
 466
 467 The
 468 .B MSG_EXCEPT
 469 and
 470 .B MSG_COPY
 471 flags are Linux-specific;
 472 their definitions can be obtained by defining the
 473 .B _GNU_SOURCE
 474 .\" MSG_COPY since glibc 2.18
 475 feature test macro.
 476 .SH NOTES
 477 The inclusion of
 478 .I <sys/types.h>
 479 and
 480 .I <sys/ipc.h>
 481 isn't required on Linux or by any version of POSIX.
 482 However,
 483 some old implementations required the inclusion of these header files,
 484 and the SVID also documented their inclusion.
 485 Applications intended to be portable to such old systems may need
 486 to include these header files.
 487 .\" Like Linux, the FreeBSD man pages still document
 488 .\" the inclusion of these header files.
 489
 490 The
 491 .I msgp
 492 argument is declared as \fIstruct msgbuf *\fP with
 493 libc4, libc5, glibc 2.0, glibc 2.1.
 494 It is declared as \fIvoid *\fP
 495 with glibc 2.2 and later, as required by SUSv2 and SUSv3.
 496
 497 The following limits on message queue resources affect the
 498 .BR msgsnd ()
 499 call:
 500 .TP
 501 .B MSGMAX
 502 Maximum size for a message text: 8192 bytes
 503 (on Linux, this limit can be read and modified via
 504 .IR /proc/sys/kernel/msgmax ).
 505 .TP
 506 .B MSGMNB
 507 Default maximum size in bytes of a message queue: 16384 bytes
 508 (on Linux, this limit can be read and modified via
 509 .IR /proc/sys/kernel/msgmnb ).
 510 The superuser can increase the size of a message queue beyond
 511 .B MSGMNB
 512 by a
 513 .BR msgctl (2)
 514 system call.
 515 .PP
 516 The implementation has no intrinsic limits for the system wide maximum
 517 number of message headers
 518 .RB ( MSGTQL )
 519 and for the system wide maximum size in bytes of the message pool
 520 .RB ( MSGPOOL ).
 521 .SH BUGS
 522 In Linux 3.13 and earlier,
 523 if
 524 .BR msgrcv ()
 525 was called with the
 526 .BR MSG_COPY
 527 flag, but without
 528 .BR IPC_NOWAIT ,
 529 and the message queue contained less than
 530 .I msgtyp
 531 messages, then the call would block until the next message is written
 532 to the queue.
 533 .\" FIXME http://marc.info/?l=linux-kernel&m=139048542803605&w=2
 534 At that point, the call would return a copy of the message,
 535 .I regardless
 536 of whether that message was at the ordinal position
 537 .IR msgtyp .
 538 This bug is fixed
 539 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
 540 in Linux 3.14.
 541
 542 Specifying both
 543 .B MSG_COPY
 544 and
 545 .B MSC_EXCEPT
 546 in
 547 .I msgflg
 548 is a logical error (since these flags impose different interpretations on
 549 .IR msgtyp ).
 550 In Linux 3.13 and earlier,
 551 .\" FIXME http://marc.info/?l=linux-kernel&m=139048542803605&w=2
 552 this error was not diagnosed by
 553 .BR msgrcv ().
 554 This bug is fixed
 555 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
 556 in Linux 3.14.
 557 .SH SEE ALSO
 558 .BR msgctl (2),
 559 .BR msgget (2),
 560 .BR capabilities (7),
 561 .BR mq_overview (7),
 562 .BR svipc (7)
 563 .SH COLOPHON
 564 This page is part of release 3.64 of the Linux
 565 .I man-pages
 566 project.
 567 A description of the project,
 568 and information about reporting bugs,
 569 can be found at
 570 \%http://www.kernel.org/doc/man\-pages/.