original/man2/msgop.2

   1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond <esr@thyrsus.com>
  24 .\" Modified Mon Jul 10 21:09:59 2000 by aeb
  25 .\" Modified 1 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  26 .\"     Language clean-ups.
  27 .\"     Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX
  28 .\"     Added note on restart behavior of msgsnd() and msgrcv()
  29 .\"     Formatting clean-ups (argument and field names marked as .I
  30 .\"             instead of .B)
  31 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  32 .\"     Added notes on capability requirements
  33 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  34 .\"     Language and formatting clean-ups
  35 .\"     Added notes on /proc files
  36 .\" FIXME . Add example programs to this page.
  37 .\"
  38 .TH MSGOP 2 2008-04-23 "Linux" "Linux Programmer's Manual"
  39 .SH NAME
  40 msgrcv, msgsnd \- message operations
  41 .SH SYNOPSIS
  42 .nf
  43 .B #include <sys/types.h>
  44 .B #include <sys/ipc.h>
  45 .B #include <sys/msg.h>
  46 .sp
  47 .BI "int msgsnd(int " msqid ", const void *" msgp ", size_t " msgsz \
  48 ", int " msgflg );
  49 .sp
  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, respectively, to send messages to,
  60 and receive messages from, a 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 caller-defined structure
  67 of the following general form:
  68 .in +4n
  69 .nf
  70
  71 struct msgbuf {
  72     long mtype;       /* message type, must be > 0 */
  73     char mtext[1];    /* message data */
  74 };
  75 .fi
  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 defined by the
 107 .I msg_bytes
 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 If insufficient space is available in the queue, then the default
 114 behavior of
 115 .BR msgsnd ()
 116 is to block until space becomes available.
 117 If
 118 .B IPC_NOWAIT
 119 is specified in
 120 .IR msgflg ,
 121 then the call instead fails with the error
 122 .BR EAGAIN .
 123
 124 A blocked
 125 .BR msgsnd ()
 126 call may also fail if:
 127 .IP * 2
 128 the queue is removed,
 129 in which case the system call fails with
 130 .I errno
 131 set to
 132 .BR EIDRM ;
 133 or
 134 .IP *
 135 a signal is caught, in which case the system call fails
 136 with
 137 .I errno
 138 set to
 139 .BR EINTR ; see
 140 .BR signal (7).
 141 .RB ( msgsnd ()
 142 is never automatically restarted after being interrupted by a
 143 signal handler, regardless of the setting of the
 144 .B SA_RESTART
 145 flag when establishing a signal handler.)
 146 .PP
 147 Upon successful completion the message queue data structure is updated
 148 as follows:
 149 .IP
 150 .I msg_lspid
 151 is set to the process ID of the calling process.
 152 .IP
 153 .I msg_qnum
 154 is incremented by 1.
 155 .IP
 156 .I msg_stime
 157 is set to the current time.
 158 .SS msgrcv()
 159 The
 160 .BR msgrcv ()
 161 system call removes a message from the queue specified by
 162 .I msqid
 163 and places it in the buffer
 164 pointed to by
 165 .IR msgp .
 166 .PP
 167 The argument
 168 .I msgsz
 169 specifies the maximum size in bytes for the member
 170 .I mtext
 171 of the structure pointed to by the
 172 .I msgp
 173 argument.
 174 If the message text has length greater than
 175 .IR msgsz ,
 176 then the behavior depends on whether
 177 .B MSG_NOERROR
 178 is specified in
 179 .IR msgflg .
 180 If
 181 .B MSG_NOERROR
 182 is specified, then
 183 the message text will be truncated (and the truncated part will be
 184 lost); if
 185 .B MSG_NOERROR
 186 is not specified, then
 187 the message isn't removed from the queue and
 188 the system call fails returning \-1 with
 189 .I errno
 190 set to
 191 .BR E2BIG .
 192 .PP
 193 The argument
 194 .I msgtyp
 195 specifies the type of message requested as follows:
 196 .IP * 2
 197 If
 198 .I msgtyp
 199 is 0,
 200 then the first message in the queue is read.
 201 .IP *
 202 If
 203 .I msgtyp
 204 is greater than 0,
 205 then the first message in the queue of type
 206 .I msgtyp
 207 is read, unless
 208 .B MSG_EXCEPT
 209 was specified in
 210 .IR msgflg ,
 211 in which case
 212 the first message in the queue of type not equal to
 213 .I msgtyp
 214 will be read.
 215 .IP *
 216 If
 217 .I msgtyp
 218 is less than 0,
 219 then the first message in the queue with the lowest type less than or
 220 equal to the absolute value of
 221 .I msgtyp
 222 will be read.
 223 .PP
 224 The
 225 .I msgflg
 226 argument is a bit mask constructed by ORing together zero or more
 227 of the following flags:
 228 .TP
 229 .B IPC_NOWAIT
 230 Return immediately if no message of the requested type is in the queue.
 231 The system call fails with
 232 .I errno
 233 set to
 234 .BR ENOMSG .
 235 .TP
 236 .B MSG_EXCEPT
 237 Used with
 238 .I msgtyp
 239 greater than 0
 240 to read the first message in the queue with message type that differs
 241 from
 242 .IR msgtyp .
 243 .TP
 244 .B MSG_NOERROR
 245 To truncate the message text if longer than
 246 .I msgsz
 247 bytes.
 248 .PP
 249 If no message of the requested type is available and
 250 .B IPC_NOWAIT
 251 isn't specified in
 252 .IR msgflg ,
 253 the calling process is blocked until one of the following conditions occurs:
 254 .IP * 2
 255 A message of the desired type is placed in the queue.
 256 .IP *
 257 The message queue is removed from the system.
 258 In this case the system call fails with
 259 .I errno
 260 set to
 261 .BR EIDRM .
 262 .IP *
 263 The calling process catches a signal.
 264 In this case the system call fails with
 265 .I errno
 266 set to
 267 .BR EINTR .
 268 .RB ( msgrcv ()
 269 is never automatically restarted after being interrupted by a
 270 signal handler, regardless of the setting of the
 271 .B SA_RESTART
 272 flag when establishing a signal handler.)
 273 .PP
 274 Upon successful completion the message queue data structure is updated
 275 as follows:
 276 .IP
 277 .I msg_lrpid
 278 is set to the process ID of the calling process.
 279 .IP
 280 .I msg_qnum
 281 is decremented by 1.
 282 .IP
 283 .I msg_rtime
 284 is set to the current time.
 285 .SH "RETURN VALUE"
 286 On failure both functions return \-1
 287 with
 288 .I errno
 289 indicating the error,
 290 otherwise
 291 .BR msgsnd ()
 292 returns 0
 293 and
 294 .BR msgrcv ()
 295 returns the number of bytes actually copied into the
 296 .I mtext
 297 array.
 298 .SH ERRORS
 299 When
 300 .BR msgsnd ()
 301 fails,
 302 .I errno
 303 will be set to one among the following values:
 304 .TP
 305 .B EACCES
 306 The calling process does not have write permission on the message queue,
 307 and does not have the
 308 .B CAP_IPC_OWNER
 309 capability.
 310 .TP
 311 .B EAGAIN
 312 The message can't be sent due to the
 313 .I msg_qbytes
 314 limit for the queue and
 315 .B IPC_NOWAIT
 316 was specified in
 317 .IR msgflg .
 318 .TP
 319 .B EFAULT
 320 The address pointed to by
 321 .I msgp
 322 isn't accessible.
 323 .TP
 324 .B EIDRM
 325 The message queue was removed.
 326 .TP
 327 .B EINTR
 328 Sleeping on a full message queue condition, the process caught a signal.
 329 .TP
 330 .B EINVAL
 331 Invalid
 332 .I msqid
 333 value, or nonpositive
 334 .I mtype
 335 value, or
 336 invalid
 337 .I msgsz
 338 value (less than 0 or greater than the system value
 339 .BR MSGMAX ).
 340 .TP
 341 .B ENOMEM
 342 The system does not have enough memory to make a copy of the
 343 message pointed to by
 344 .IR msgp .
 345 .PP
 346 When
 347 .BR msgrcv ()
 348 fails,
 349 .I errno
 350 will be set to one among the following values:
 351 .TP
 352 .B E2BIG
 353 The message text length is greater than
 354 .I msgsz
 355 and
 356 .B MSG_NOERROR
 357 isn't specified in
 358 .IR msgflg .
 359 .TP
 360 .B EACCES
 361 The calling process does not have read permission on the message queue,
 362 and does not have the
 363 .B CAP_IPC_OWNER
 364 capability.
 365 .TP
 366 .B EAGAIN
 367 No message was available in the queue and
 368 .B IPC_NOWAIT
 369 was specified in
 370 .IR msgflg .
 371 .TP
 372 .B EFAULT
 373 The address pointed to by
 374 .I msgp
 375 isn't accessible.
 376 .TP
 377 .B EIDRM
 378 While the process was sleeping to receive a message,
 379 the message queue was removed.
 380 .TP
 381 .B EINTR
 382 While the process was sleeping to receive a message,
 383 the process caught a signal; see
 384 .BR signal (7).
 385 .TP
 386 .B EINVAL
 387 .I msgqid
 388 was invalid, or
 389 .I msgsz
 390 was less than 0.
 391 .TP
 392 .B ENOMSG
 393 .B IPC_NOWAIT
 394 was specified in
 395 .I msgflg
 396 and no message of the requested type existed on the message queue.
 397 .SH "CONFORMING TO"
 398 SVr4, POSIX.1-2001.
 399 .SH NOTES
 400 The
 401 .I msgp
 402 argument is declared as \fIstruct msgbuf *\fP with
 403 libc4, libc5, glibc 2.0, glibc 2.1.
 404 It is declared as \fIvoid *\fP
 405 with glibc 2.2 and later, as required by SUSv2 and SUSv3.
 406
 407 The following limits on message queue resources affect the
 408 .BR msgsnd ()
 409 call:
 410 .TP
 411 .B MSGMAX
 412 Maximum size for a message text: 8192 bytes
 413 (on Linux, this limit can be read and modified via
 414 .IR /proc/sys/kernel/msgmax ).
 415 .TP
 416 .B MSGMNB
 417 Default maximum size in bytes of a message queue: 16384 bytes
 418 (on Linux, this limit can be read and modified via
 419 .IR /proc/sys/kernel/msgmnb ).
 420 The superuser can increase the size of a message queue beyond
 421 .B MSGMNB
 422 by a
 423 .BR msgctl (2)
 424 system call.
 425 .PP
 426 The implementation has no intrinsic limits for the system wide maximum
 427 number of message headers
 428 .RB ( MSGTQL )
 429 and for the system wide maximum size in bytes of the message pool
 430 .RB ( MSGPOOL ).
 431 .SH "SEE ALSO"
 432 .BR msgctl (2),
 433 .BR msgget (2),
 434 .BR capabilities (7),
 435 .BR mq_overview (7),
 436 .BR svipc (7)