.\" Added notes on /proc files
.\" FIXME . Add example programs to this page.
.\"
-.TH MSGOP 2 2012-05-31 "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
+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 .
.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.
+.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>
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 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.67 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/.
OSDN Git Service
