.\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified Mon Jul 10 21:09:59 2000 by aeb
.\" Added notes on /proc files
.\" FIXME . Add example programs to this page.
.\"
-.TH MSGOP 2 2008-04-23 "Linux" "Linux Programmer's Manual"
+.TH MSGOP 2 2014-05-16 "Linux" "Linux Programmer's Manual"
.SH NAME
-msgrcv, msgsnd \- message operations
+msgrcv, msgsnd \- System V message queue operations
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
and
.BR msgrcv ()
system calls are used, respectively, to send messages to,
-and receive messages from, a message queue.
+and receive messages from, a System\ V message queue.
The calling process must have write permission on the message queue
in order to send a message, and read permission to receive a message.
.PP
The
.I msgp
-argument is a pointer to caller-defined structure
+argument is a pointer to a caller-defined structure
of the following general form:
.in +4n
.nf
If sufficient space is available in the queue,
.BR msgsnd ()
succeeds immediately.
-(The queue capacity is defined by the
-.I msg_bytes
+The queue capacity is governed by the
+.I msg_qbytes
field in the associated data structure for the message queue.
During queue creation this field is initialized to
.B MSGMNB
bytes, but this limit can be modified using
-.BR msgctl (2).)
+.BR msgctl (2).
+A message queue is considered to be full if either of the following
+conditions is true:
+.IP * 2
+Adding a new message to the queue would cause the total number of bytes
+in the queue to exceed the queue's maximum size (the
+.I msg_qbytes
+field).
+.IP *
+Adding another message to the queue would cause the total number of messages
+in the queue to exceed the queue's maximum size (the
+.I msg_qbytes
+field).
+This check is necessary to prevent an unlimited number of zero-length
+messages being placed on the queue.
+Although such messages contain no data,
+they nevertheless consume (locked) kernel memory.
+.PP
If insufficient space is available in the queue, then the default
behavior of
.BR msgsnd ()
set to
.BR E2BIG .
.PP
-The argument
+Unless
+.B MSG_COPY
+is specified in
+.IR msgflg
+(see below),
+the
.I msgtyp
-specifies the type of message requested as follows:
+argument specifies the type of message requested, as follows:
.IP * 2
If
.I msgtyp
set to
.BR ENOMSG .
.TP
+.BR MSG_COPY " (since Linux 3.8)"
+.\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8
+Nondestructively fetch a copy of the message at the ordinal position
+in the queue specified by
+.I msgtyp
+(messages are considered to be numbered starting at 0).
+
+This flag must be specified in conjunction with
+.BR IPC_NOWAIT ,
+with the result that, if there is no message available at the given position,
+the call fails immediately with the error
+.BR ENOMSG .
+Because they alter the meaning of
+.I msgtyp
+in orthogonal ways,
+.BR MSG_COPY
+and
+.BR MSG_EXCEPT
+may not both be specified in
+.IR msgflg .
+
+The
+.BR MSG_COPY
+flag was added for the implementation of
+the kernel checkpoint-restore facility and
+is available only if the kernel was built with the
+.B CONFIG_CHECKPOINT_RESTORE
+option.
+.TP
.B MSG_EXCEPT
Used with
.I msgtyp
A message of the desired type is placed in the queue.
.IP *
The message queue is removed from the system.
-In this case the system call fails with
+In this case, the system call fails with
.I errno
set to
.BR EIDRM .
.IP *
The calling process catches a signal.
-In this case the system call fails with
+In this case, the system call fails with
.I errno
set to
.BR EINTR .
.IP
.I msg_rtime
is set to the current time.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
On failure both functions return \-1
with
.I errno
.I msgsz
was less than 0.
.TP
+.BR EINVAL " (since Linux 3.14)"
+.I msgflg
+specified
+.BR MSG_COPY ,
+but not
+.BR IPC_NOWAIT .
+.TP
+.BR EINVAL " (since Linux 3.14)"
+.I msgflg
+specified both
+.BR MSG_COPY
+and
+.BR MSG_EXCEPT .
+.TP
.B ENOMSG
.B IPC_NOWAIT
was specified in
.I msgflg
and no message of the requested type existed on the message queue.
-.SH "CONFORMING TO"
+.TP
+.B ENOMSG
+.B IPC_NOWAIT
+and
+.B MSG_COPY
+were specified in
+.I msgflg
+and the queue contains less than
+.I msgtyp
+messages.
+.TP
+.BR ENOSYS " (since Linux 3.8)"
+.I MSG_COPY
+was specified in
+.IR msgflg ,
+and this kernel was configured without
+.BR CONFIG_CHECKPOINT_RESTORE .
+.SH CONFORMING TO
SVr4, POSIX.1-2001.
+
+The
+.B MSG_EXCEPT
+and
+.B MSG_COPY
+flags are Linux-specific;
+their definitions can be obtained by defining the
+.B _GNU_SOURCE
+.\" MSG_COPY since glibc 2.18
+feature test macro.
.SH NOTES
+The inclusion of
+.I <sys/types.h>
+and
+.I <sys/ipc.h>
+isn't required on Linux or by any version of POSIX.
+However,
+some old implementations required the inclusion of these header files,
+and the SVID also documented their inclusion.
+Applications intended to be portable to such old systems may need
+to include these header files.
+.\" Like Linux, the FreeBSD man pages still document
+.\" the inclusion of these header files.
+
The
.I msgp
-argument is declared as \fIstruct msgbuf *\fP with
+argument is declared as \fIstruct msgbuf\ *\fP with
libc4, libc5, glibc 2.0, glibc 2.1.
-It is declared as \fIvoid *\fP
+It is declared as \fIvoid\ *\fP
with glibc 2.2 and later, as required by SUSv2 and SUSv3.
The following limits on message queue resources affect the
Default maximum size in bytes of a message queue: 16384 bytes
(on Linux, this limit can be read and modified via
.IR /proc/sys/kernel/msgmnb ).
-The superuser can increase the size of a message queue beyond
+A privileged process
+(Linux: a process with the
+.B CAP_SYS_RESOURCE
+capability)
+can increase the size of a message queue beyond
.B MSGMNB
by a
.BR msgctl (2)
system call.
.PP
-The implementation has no intrinsic limits for the system wide maximum
+The implementation has no intrinsic system-wide limits on the
number of message headers
.RB ( MSGTQL )
-and for the system wide maximum size in bytes of the message pool
+and the number of bytes in the message pool
.RB ( MSGPOOL ).
-.SH "SEE ALSO"
+.SH BUGS
+In Linux 3.13 and earlier,
+if
+.BR msgrcv ()
+was called with the
+.BR MSG_COPY
+flag, but without
+.BR IPC_NOWAIT ,
+and the message queue contained less than
+.I msgtyp
+messages, then the call would block until the next message is written
+to the queue.
+.\" FIXME http://marc.info/?l=linux-kernel&m=139048542803605&w=2
+At that point, the call would return a copy of the message,
+.I regardless
+of whether that message was at the ordinal position
+.IR msgtyp .
+This bug is fixed
+.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
+in Linux 3.14.
+
+Specifying both
+.B MSG_COPY
+and
+.B MSC_EXCEPT
+in
+.I msgflg
+is a logical error (since these flags impose different interpretations on
+.IR msgtyp ).
+In Linux 3.13 and earlier,
+.\" FIXME http://marc.info/?l=linux-kernel&m=139048542803605&w=2
+this error was not diagnosed by
+.BR msgrcv ().
+This bug is fixed
+.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
+in Linux 3.14.
+.SH SEE ALSO
.BR msgctl (2),
.BR msgget (2),
.BR capabilities (7),
.BR mq_overview (7),
.BR svipc (7)
+.SH COLOPHON
+This page is part of release 3.68 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.