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 2012-05-31 "Linux" "Linux Programmer's Manual"
  41 .SH NAME
  42 msgrcv, msgsnd \- message 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 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 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 The argument
 196 .I msgtyp
 197 specifies the type of message requested as follows:
 198 .IP * 2
 199 If
 200 .I msgtyp
 201 is 0,
 202 then the first message in the queue is read.
 203 .IP *
 204 If
 205 .I msgtyp
 206 is greater than 0,
 207 then the first message in the queue of type
 208 .I msgtyp
 209 is read, unless
 210 .B MSG_EXCEPT
 211 was specified in
 212 .IR msgflg ,
 213 in which case
 214 the first message in the queue of type not equal to
 215 .I msgtyp
 216 will be read.
 217 .IP *
 218 If
 219 .I msgtyp
 220 is less than 0,
 221 then the first message in the queue with the lowest type less than or
 222 equal to the absolute value of
 223 .I msgtyp
 224 will be read.
 225 .PP
 226 The
 227 .I msgflg
 228 argument is a bit mask constructed by ORing together zero or more
 229 of the following flags:
 230 .TP
 231 .B IPC_NOWAIT
 232 Return immediately if no message of the requested type is in the queue.
 233 The system call fails with
 234 .I errno
 235 set to
 236 .BR ENOMSG .
 237 .TP
 238 .B MSG_EXCEPT
 239 Used with
 240 .I msgtyp
 241 greater than 0
 242 to read the first message in the queue with message type that differs
 243 from
 244 .IR msgtyp .
 245 .TP
 246 .B MSG_NOERROR
 247 To truncate the message text if longer than
 248 .I msgsz
 249 bytes.
 250 .PP
 251 If no message of the requested type is available and
 252 .B IPC_NOWAIT
 253 isn't specified in
 254 .IR msgflg ,
 255 the calling process is blocked until one of the following conditions occurs:
 256 .IP * 2
 257 A message of the desired type is placed in the queue.
 258 .IP *
 259 The message queue is removed from the system.
 260 In this case the system call fails with
 261 .I errno
 262 set to
 263 .BR EIDRM .
 264 .IP *
 265 The calling process catches a signal.
 266 In this case the system call fails with
 267 .I errno
 268 set to
 269 .BR EINTR .
 270 .RB ( msgrcv ()
 271 is never automatically restarted after being interrupted by a
 272 signal handler, regardless of the setting of the
 273 .B SA_RESTART
 274 flag when establishing a signal handler.)
 275 .PP
 276 Upon successful completion the message queue data structure is updated
 277 as follows:
 278 .IP
 279 .I msg_lrpid
 280 is set to the process ID of the calling process.
 281 .IP
 282 .I msg_qnum
 283 is decremented by 1.
 284 .IP
 285 .I msg_rtime
 286 is set to the current time.
 287 .SH RETURN VALUE
 288 On failure both functions return \-1
 289 with
 290 .I errno
 291 indicating the error,
 292 otherwise
 293 .BR msgsnd ()
 294 returns 0
 295 and
 296 .BR msgrcv ()
 297 returns the number of bytes actually copied into the
 298 .I mtext
 299 array.
 300 .SH ERRORS
 301 When
 302 .BR msgsnd ()
 303 fails,
 304 .I errno
 305 will be set to one among the following values:
 306 .TP
 307 .B EACCES
 308 The calling process does not have write permission on the message queue,
 309 and does not have the
 310 .B CAP_IPC_OWNER
 311 capability.
 312 .TP
 313 .B EAGAIN
 314 The message can't be sent due to the
 315 .I msg_qbytes
 316 limit for the queue and
 317 .B IPC_NOWAIT
 318 was specified in
 319 .IR msgflg .
 320 .TP
 321 .B EFAULT
 322 The address pointed to by
 323 .I msgp
 324 isn't accessible.
 325 .TP
 326 .B EIDRM
 327 The message queue was removed.
 328 .TP
 329 .B EINTR
 330 Sleeping on a full message queue condition, the process caught a signal.
 331 .TP
 332 .B EINVAL
 333 Invalid
 334 .I msqid
 335 value, or nonpositive
 336 .I mtype
 337 value, or
 338 invalid
 339 .I msgsz
 340 value (less than 0 or greater than the system value
 341 .BR MSGMAX ).
 342 .TP
 343 .B ENOMEM
 344 The system does not have enough memory to make a copy of the
 345 message pointed to by
 346 .IR msgp .
 347 .PP
 348 When
 349 .BR msgrcv ()
 350 fails,
 351 .I errno
 352 will be set to one among the following values:
 353 .TP
 354 .B E2BIG
 355 The message text length is greater than
 356 .I msgsz
 357 and
 358 .B MSG_NOERROR
 359 isn't specified in
 360 .IR msgflg .
 361 .TP
 362 .B EACCES
 363 The calling process does not have read permission on the message queue,
 364 and does not have the
 365 .B CAP_IPC_OWNER
 366 capability.
 367 .TP
 368 .B EAGAIN
 369 No message was available in the queue and
 370 .B IPC_NOWAIT
 371 was specified in
 372 .IR msgflg .
 373 .TP
 374 .B EFAULT
 375 The address pointed to by
 376 .I msgp
 377 isn't accessible.
 378 .TP
 379 .B EIDRM
 380 While the process was sleeping to receive a message,
 381 the message queue was removed.
 382 .TP
 383 .B EINTR
 384 While the process was sleeping to receive a message,
 385 the process caught a signal; see
 386 .BR signal (7).
 387 .TP
 388 .B EINVAL
 389 .I msgqid
 390 was invalid, or
 391 .I msgsz
 392 was less than 0.
 393 .TP
 394 .B ENOMSG
 395 .B IPC_NOWAIT
 396 was specified in
 397 .I msgflg
 398 and no message of the requested type existed on the message queue.
 399 .SH CONFORMING TO
 400 SVr4, POSIX.1-2001.
 401 .SH NOTES
 402 The inclusion of
 403 .I <sys/types.h>
 404 and
 405 .I <sys/ipc.h>
 406 isn't required on Linux or by any version of POSIX.
 407 However,
 408 some old implementations required the inclusion of these header files,
 409 and the SVID also documented their inclusion.
 410 Applications intended to be portable to such old systems may need
 411 to include these header files.
 412 .\" Like Linux, the FreeBSD man pages still document
 413 .\" the inclusion of these header files.
 414
 415 The
 416 .I msgp
 417 argument is declared as \fIstruct msgbuf *\fP with
 418 libc4, libc5, glibc 2.0, glibc 2.1.
 419 It is declared as \fIvoid *\fP
 420 with glibc 2.2 and later, as required by SUSv2 and SUSv3.
 421
 422 The following limits on message queue resources affect the
 423 .BR msgsnd ()
 424 call:
 425 .TP
 426 .B MSGMAX
 427 Maximum size for a message text: 8192 bytes
 428 (on Linux, this limit can be read and modified via
 429 .IR /proc/sys/kernel/msgmax ).
 430 .TP
 431 .B MSGMNB
 432 Default maximum size in bytes of a message queue: 16384 bytes
 433 (on Linux, this limit can be read and modified via
 434 .IR /proc/sys/kernel/msgmnb ).
 435 The superuser can increase the size of a message queue beyond
 436 .B MSGMNB
 437 by a
 438 .BR msgctl (2)
 439 system call.
 440 .PP
 441 The implementation has no intrinsic limits for the system wide maximum
 442 number of message headers
 443 .RB ( MSGTQL )
 444 and for the system wide maximum size in bytes of the message pool
 445 .RB ( MSGPOOL ).
 446 .SH SEE ALSO
 447 .BR msgctl (2),
 448 .BR msgget (2),
 449 .BR capabilities (7),
 450 .BR mq_overview (7),
 451 .BR svipc (7)