1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
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.
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.
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
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
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
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.
38 .TH MSGOP 2 2012-05-31 "Linux" "Linux Programmer's Manual"
40 msgrcv, msgsnd \- message operations
43 .B #include <sys/types.h>
44 .B #include <sys/ipc.h>
45 .B #include <sys/msg.h>
47 .BI "int msgsnd(int " msqid ", const void *" msgp ", size_t " msgsz \
50 .BI "ssize_t msgrcv(int " msqid ", void *" msgp ", size_t " msgsz \
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.
66 argument is a pointer to caller-defined structure
67 of the following general form:
72 long mtype; /* message type, must be > 0 */
73 char mtext[1]; /* message data */
80 field is an array (or other structure) whose size is specified by
82 a nonnegative integer value.
83 Messages of zero length (i.e., no
88 field must have a strictly positive integer value.
90 used by the receiving process for message selection
91 (see the description of
97 system call appends a copy of the message pointed to by
99 to the message queue whose identifier is specified
103 If sufficient space is available in the queue,
105 succeeds immediately.
106 (The queue capacity is defined by the
108 field in the associated data structure for the message queue.
109 During queue creation this field is initialized to
111 bytes, but this limit can be modified using
113 If insufficient space is available in the queue, then the default
116 is to block until space becomes available.
121 then the call instead fails with the error
126 call may also fail if:
128 the queue is removed,
129 in which case the system call fails with
135 a signal is caught, in which case the system call fails
142 is never automatically restarted after being interrupted by a
143 signal handler, regardless of the setting of the
145 flag when establishing a signal handler.)
147 Upon successful completion the message queue data structure is updated
151 is set to the process ID of the calling process.
157 is set to the current time.
161 system call removes a message from the queue specified by
163 and places it in the buffer
169 specifies the maximum size in bytes for the member
171 of the structure pointed to by the
174 If the message text has length greater than
176 then the behavior depends on whether
183 the message text will be truncated (and the truncated part will be
186 is not specified, then
187 the message isn't removed from the queue and
188 the system call fails returning \-1 with
195 specifies the type of message requested as follows:
200 then the first message in the queue is read.
205 then the first message in the queue of type
212 the first message in the queue of type not equal to
219 then the first message in the queue with the lowest type less than or
220 equal to the absolute value of
226 argument is a bit mask constructed by ORing together zero or more
227 of the following flags:
230 Return immediately if no message of the requested type is in the queue.
231 The system call fails with
240 to read the first message in the queue with message type that differs
245 To truncate the message text if longer than
249 If no message of the requested type is available and
253 the calling process is blocked until one of the following conditions occurs:
255 A message of the desired type is placed in the queue.
257 The message queue is removed from the system.
258 In this case the system call fails with
263 The calling process catches a signal.
264 In this case the system call fails with
269 is never automatically restarted after being interrupted by a
270 signal handler, regardless of the setting of the
272 flag when establishing a signal handler.)
274 Upon successful completion the message queue data structure is updated
278 is set to the process ID of the calling process.
284 is set to the current time.
286 On failure both functions return \-1
289 indicating the error,
295 returns the number of bytes actually copied into the
303 will be set to one among the following values:
306 The calling process does not have write permission on the message queue,
307 and does not have the
312 The message can't be sent due to the
314 limit for the queue and
320 The address pointed to by
325 The message queue was removed.
328 Sleeping on a full message queue condition, the process caught a signal.
333 value, or nonpositive
338 value (less than 0 or greater than the system value
342 The system does not have enough memory to make a copy of the
343 message pointed to by
350 will be set to one among the following values:
353 The message text length is greater than
361 The calling process does not have read permission on the message queue,
362 and does not have the
367 No message was available in the queue and
373 The address pointed to by
378 While the process was sleeping to receive a message,
379 the message queue was removed.
382 While the process was sleeping to receive a message,
383 the process caught a signal; see
396 and no message of the requested type existed on the message queue.
404 isn't required on Linux or by any version of POSIX.
406 some old implementations required the inclusion of these header files,
407 and the SVID also documented their inclusion.
408 Applications intended to be portable to such old systems may need
409 to include these header files.
410 .\" Like Linux, the FreeBSD man pages still document
411 .\" the inclusion of these header files.
415 argument is declared as \fIstruct msgbuf *\fP with
416 libc4, libc5, glibc 2.0, glibc 2.1.
417 It is declared as \fIvoid *\fP
418 with glibc 2.2 and later, as required by SUSv2 and SUSv3.
420 The following limits on message queue resources affect the
425 Maximum size for a message text: 8192 bytes
426 (on Linux, this limit can be read and modified via
427 .IR /proc/sys/kernel/msgmax ).
430 Default maximum size in bytes of a message queue: 16384 bytes
431 (on Linux, this limit can be read and modified via
432 .IR /proc/sys/kernel/msgmnb ).
433 The superuser can increase the size of a message queue beyond
439 The implementation has no intrinsic limits for the system wide maximum
440 number of message headers
442 and for the system wide maximum size in bytes of the message pool
447 .BR capabilities (7),