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@gmx.net>
  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@gmx.net>
  32 .\"     Added notes on capability requirements
  33 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
  34 .\"     Language and formatting clean-ups
  35 .\"     Added notes on /proc files
  36 .\"
  37 .TH MSGOP 2 2006-02-02 "Linux" "Linux Programmer's Manual"
  38 .SH NAME
  39 msgop, msgrcv, msgsnd \- message operations
  40 .SH SYNOPSIS
  41 .nf
  42 .B #include <sys/types.h>
  43 .B #include <sys/ipc.h>
  44 .B #include <sys/msg.h>
  45 .sp
  46 .BI "int msgsnd(int " msqid ", const void *" msgp ", size_t " msgsz \
  47 ", int " msgflg );
  48 .sp
  49 .BI "ssize_t msgrcv(int " msqid ", void *" msgp ", size_t " msgsz \
  50 ", long " msgtyp ,
  51 .BI "               int " msgflg );
  52 .fi
  53 .SH DESCRIPTION
  54 The
  55 .BR msgsnd ()
  56 and
  57 .BR msgrcv ()
  58 system calls are used, respectively, to send messages to,
  59 and receive messages from, a message queue.
  60 The calling process must have write permission on the message queue
  61 in order to send a message, and read permission to receive a message.
  62 .PP
  63 The
  64 .I msgp
  65 argument is a pointer to caller-defined structure
  66 of the following general form:
  67 .in +0.5i
  68 .nf
  69
  70 struct msgbuf {
  71     long mtype;       /* message type, must be > 0 */
  72     char mtext[1];    /* message data */
  73 };
  74 .fi
  75 .in -0.5i
  76 .PP
  77 The
  78 .I mtext
  79 field is an array (or other structure) whose size is specified by
  80 .IR msgsz ,
  81 a non-negative integer value.
  82 Messages of zero length (i.e., no
  83 .I mtext
  84 field) are permitted.
  85 The
  86 .I mtype
  87 field must have a strictly positive integer value.
  88 This value can be
  89 used by the receiving process for message selection
  90 (see the description of
  91 .BR msgrcv ()
  92 below).
  93 .PP
  94 The
  95 .BR msgsnd ()
  96 system call appends a copy of the message pointed to by
  97 .I msgp
  98 to the message queue whose identifier is specified
  99 by
 100 .IR msqid .
 101 .PP
 102 If sufficient space is available in the queue,
 103 .BR msgsnd ()
 104 succeeds immediately.
 105 (The queue capacity is defined by the
 106 .I msg_bytes
 107 field in the associated data structure for the message queue.
 108 During queue creation this field is initialized to
 109 .B MSGMNB
 110 bytes, but this limit can be modified using
 111 .BR msgctl (2).)
 112 If insufficient space is available in the queue, then the default
 113 behavior of
 114 .BR msgsnd ()
 115 is to block until space becomes available.
 116 If
 117 .B IPC_NOWAIT
 118 is specified in
 119 .IR msgflg ,
 120 then the call instead fails with the error
 121 .BR EAGAIN .
 122
 123 A blocked
 124 .BR msgsnd ()
 125 call may also fail if the queue is removed
 126 (in which case the system call fails with
 127 .I errno
 128 set to
 129 .BR EIDRM ),
 130 or a signal is caught (in which case the system call fails
 131 with
 132 .I errno
 133 set to
 134 .BR EINTR ).
 135 .RB ( msgsnd " and " msgrcv
 136 are never automatically restarted after being interrupted by a
 137 signal handler, regardless of the setting  of the
 138 .B SA_RESTART
 139 flag when establishing a signal handler.)
 140 .PP
 141 Upon successful completion the message queue data structure is updated
 142 as follows:
 143 .IP
 144 .I msg_lspid
 145 is set to the process ID of the calling process.
 146 .IP
 147 .I msg_qnum
 148 is incremented by 1.
 149 .IP
 150 .I msg_stime
 151 is set to the current time.
 152 .PP
 153 The system call
 154 .BR msgrcv ()
 155 removes a message from the queue specified by
 156 .I msqid
 157 and places it in the buffer
 158 pointed to
 159 .IR msgp .
 160 .PP
 161 The argument
 162 .I msgsz
 163 specifies the maximum size in bytes for the member
 164 .I mtext
 165 of the structure pointed to by the
 166 .I msgp
 167 argument.
 168 If the message text has length greater than
 169 .IR msgsz ,
 170 then the behavior depends on whether
 171 .BR MSG_NOERROR
 172 is specified in
 173 .IR msgflg .
 174 If
 175 .BR MSG_NOERROR
 176 is specified, then
 177 the message text will be truncated (and the truncated part will be
 178 lost); if
 179 .BR MSG_NOERROR
 180 is not specified, then
 181 the message isn't removed from the queue and
 182 the system call fails returning \-1 with
 183 .I errno
 184 set to
 185 .BR E2BIG .
 186 .PP
 187 The argument
 188 .I msgtyp
 189 specifies the type of message requested as follows:
 190 .IP
 191 If
 192 .I msgtyp
 193 is 0,
 194 then the first message in the queue is read.
 195 .IP
 196 If
 197 .I msgtyp
 198 is greater than 0,
 199 then the first message in the queue of type
 200 .I msgtyp
 201 is read, unless
 202 .B MSG_EXCEPT
 203 was specified in
 204 .IR msgflg ,
 205 in which case
 206 the first message in the queue of type not equal to
 207 .I msgtyp
 208 will be read.
 209 .IP
 210 If
 211 .I msgtyp
 212 is less than 0,
 213 then the first message in the queue with the lowest type less than or
 214 equal to the absolute value of
 215 .I msgtyp
 216 will be read.
 217 .PP
 218 The
 219 .I msgflg
 220 argument is a bit mask constructed by ORing together zero or more
 221 of the following flags:
 222 .TP
 223 .B IPC_NOWAIT
 224 Return immediately if no message of the requested type is in the queue.
 225 The system call fails with
 226 .I errno
 227 set to
 228 .BR ENOMSG .
 229 .TP
 230 .B MSG_EXCEPT
 231 Used with
 232 .I msgtyp
 233 greater than 0
 234 to read the first message in the queue with message type that differs
 235 from
 236 .IR msgtyp .
 237 .TP
 238 .B MSG_NOERROR
 239 To truncate the message text if longer than
 240 .I msgsz
 241 bytes.
 242 .PP
 243 If no message of the requested type is available and
 244 .B IPC_NOWAIT
 245 isn't specified in
 246 .IR msgflg ,
 247 the calling process is blocked until one of the following conditions occurs:
 248 .IP
 249 A message of the desired type is placed in the queue.
 250 .IP
 251 The message queue is removed from the system.
 252 In this case the system call fails with
 253 .I errno
 254 set to
 255 .BR EIDRM .
 256 .IP
 257 The calling process catches a signal.
 258 In this case the system call fails with
 259 .I errno
 260 set to
 261 .BR EINTR .
 262 .PP
 263 Upon successful completion the message queue data structure is updated
 264 as follows:
 265 .IP
 266 .I msg_lrpid
 267 is set to the process ID of the calling process.
 268 .IP
 269 .I msg_qnum
 270 is decremented by 1.
 271 .IP
 272 .I msg_rtime
 273 is set to the current time.
 274 .SH "RETURN VALUE"
 275 On failure both functions return \-1
 276 with
 277 .I errno
 278 indicating the error,
 279 otherwise
 280 .BR msgsnd ()
 281 returns 0
 282 and
 283 .BR msgrcv ()
 284 returns the number of bytes actually copied into the
 285 .I mtext
 286 array.
 287 .SH ERRORS
 288 When
 289 .BR msgsnd ()
 290 fails,
 291 .I errno
 292 will be set to one among the following values:
 293 .TP 11
 294 .B EACCES
 295 The calling process does not have write permission on the message queue,
 296 and does not have the
 297 .BR CAP_IPC_OWNER
 298 capability.
 299 .TP
 300 .B EAGAIN
 301 The message can't be sent due to the
 302 .I msg_qbytes
 303 limit for the queue and
 304 .B IPC_NOWAIT
 305 was specified in
 306 .IR msgflg .
 307 .TP
 308 .B EFAULT
 309 The address pointed to by
 310 .I msgp
 311 isn't accessible.
 312 .TP
 313 .B EIDRM
 314 The message queue was removed.
 315 .TP
 316 .B EINTR
 317 Sleeping on a full message queue condition, the process caught a signal.
 318 .TP
 319 .B EINVAL
 320 Invalid
 321 .I msqid
 322 value, or non-positive
 323 .I mtype
 324 value, or
 325 invalid
 326 .I msgsz
 327 value (less than 0 or greater than the system value
 328 .BR MSGMAX ).
 329 .TP
 330 .B ENOMEM
 331 The system does not have enough memory to make a copy of the
 332 message pointed to by
 333 .IR msgp .
 334 .PP
 335 When
 336 .BR msgrcv ()
 337 fails,
 338 .I errno
 339 will be set to one among the following values:
 340 .TP 11
 341 .B E2BIG
 342 The message text length is greater than
 343 .I msgsz
 344 and
 345 .B MSG_NOERROR
 346 isn't specified in
 347 .IR msgflg .
 348 .TP
 349 .B EACCES
 350 The calling process does not have read permission on the message queue,
 351 and does not have the
 352 .BR CAP_IPC_OWNER
 353 capability.
 354 .TP
 355 .B EAGAIN
 356 No message was available in the queue and
 357 .B IPC_NOWAIT
 358 was specified in
 359 .IR msgflg .
 360 .TP
 361 .B EFAULT
 362 The address pointed to by
 363 .I msgp
 364 isn't accessible.
 365 .TP
 366 .B EIDRM
 367 While the process was sleeping to receive a message,
 368 the message queue was removed.
 369 .TP
 370 .B EINTR
 371 While the process was sleeping to receive a message,
 372 the process caught a signal.
 373 .TP
 374 .B EINVAL
 375 .I msgqid
 376 was invalid, or
 377 .I msgsz
 378 was less than 0.
 379 .TP
 380 .B ENOMSG
 381 .B IPC_NOWAIT
 382 was specified in
 383 .I msgflg
 384 and no message of the requested type existed on the message queue.
 385 .SH "CONFORMING TO"
 386 SVr4, POSIX.1-2001.
 387 .SH NOTES
 388 The
 389 .I msgp
 390 argument is declared as \fIstruct msgbuf *\fP with
 391 libc4, libc5, glibc 2.0, glibc 2.1.
 392 It is declared as \fIvoid *\fP
 393 with glibc 2.2 and later, as required by SUSv2 and SUSv3.
 394
 395 The following limits on message queue resources affect the
 396 .BR msgsnd ()
 397 call:
 398 .TP 11
 399 .B MSGMAX
 400 Maximum size for a message text: 8192 bytes
 401 (on Linux, this limit can be read and modified via
 402 .IR /proc/sys/kernel/msgmax ).
 403 .TP
 404 .B MSGMNB
 405 Default maximum size in bytes of a message queue: 16384 bytes
 406 (on Linux, this limit can be read and modified via
 407 .IR /proc/sys/kernel/msgmnb ).
 408 The superuser can increase the size of a message queue beyond
 409 .B MSGMNB
 410 by a
 411 .BR msgctl (2)
 412 system call.
 413 .PP
 414 The implementation has no intrinsic limits for the system wide maximum
 415 number of message headers
 416 .RB ( MSGTQL )
 417 and for the system wide maximum size in bytes of the message pool
 418 .RB ( MSGPOOL ).
 419 .SH "SEE ALSO"
 420 .BR msgctl (2),
 421 .BR msgget (2),
 422 .BR msgrcv (2),
 423 .BR msgsnd (2),
 424 .BR capabilities (7),
 425 .BR mq_overview (7),
 426 .BR svipc (7)