|
Packit |
7cfc04 |
.\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond <esr@thyrsus.com>
|
|
Packit |
7cfc04 |
.\" Modified Mon Jul 10 21:09:59 2000 by aeb
|
|
Packit |
7cfc04 |
.\" Modified 1 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Language clean-ups.
|
|
Packit |
7cfc04 |
.\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX
|
|
Packit |
7cfc04 |
.\" Added note on restart behavior of msgsnd() and msgrcv()
|
|
Packit |
7cfc04 |
.\" Formatting clean-ups (argument and field names marked as .I
|
|
Packit |
7cfc04 |
.\" instead of .B)
|
|
Packit |
7cfc04 |
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Added notes on capability requirements
|
|
Packit |
7cfc04 |
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Language and formatting clean-ups
|
|
Packit |
7cfc04 |
.\" Added notes on /proc files
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH MSGOP 2 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
msgrcv, msgsnd \- System V message queue operations
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <sys/types.h>
|
|
Packit |
7cfc04 |
.B #include <sys/ipc.h>
|
|
Packit |
7cfc04 |
.B #include <sys/msg.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int msgsnd(int " msqid ", const void *" msgp ", size_t " msgsz \
|
|
Packit |
7cfc04 |
", int " msgflg );
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "ssize_t msgrcv(int " msqid ", void *" msgp ", size_t " msgsz \
|
|
Packit |
7cfc04 |
", long " msgtyp ,
|
|
Packit |
7cfc04 |
.BI " int " msgflg );
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR msgrcv ()
|
|
Packit |
7cfc04 |
system calls are used, respectively, to send messages to,
|
|
Packit |
7cfc04 |
and receive messages from, a System\ V message queue.
|
|
Packit |
7cfc04 |
The calling process must have write permission on the message queue
|
|
Packit |
7cfc04 |
in order to send a message, and read permission to receive a message.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I msgp
|
|
Packit |
7cfc04 |
argument is a pointer to a caller-defined structure
|
|
Packit |
7cfc04 |
of the following general form:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct msgbuf {
|
|
Packit |
7cfc04 |
long mtype; /* message type, must be > 0 */
|
|
Packit |
7cfc04 |
char mtext[1]; /* message data */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I mtext
|
|
Packit |
7cfc04 |
field is an array (or other structure) whose size is specified by
|
|
Packit |
7cfc04 |
.IR msgsz ,
|
|
Packit |
7cfc04 |
a nonnegative integer value.
|
|
Packit |
7cfc04 |
Messages of zero length (i.e., no
|
|
Packit |
7cfc04 |
.I mtext
|
|
Packit |
7cfc04 |
field) are permitted.
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I mtype
|
|
Packit |
7cfc04 |
field must have a strictly positive integer value.
|
|
Packit |
7cfc04 |
This value can be
|
|
Packit |
7cfc04 |
used by the receiving process for message selection
|
|
Packit |
7cfc04 |
(see the description of
|
|
Packit |
7cfc04 |
.BR msgrcv ()
|
|
Packit |
7cfc04 |
below).
|
|
Packit |
7cfc04 |
.SS msgsnd()
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
system call appends a copy of the message pointed to by
|
|
Packit |
7cfc04 |
.I msgp
|
|
Packit |
7cfc04 |
to the message queue whose identifier is specified
|
|
Packit |
7cfc04 |
by
|
|
Packit |
7cfc04 |
.IR msqid .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If sufficient space is available in the queue,
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
succeeds immediately.
|
|
Packit |
7cfc04 |
The queue capacity is governed by the
|
|
Packit |
7cfc04 |
.I msg_qbytes
|
|
Packit |
7cfc04 |
field in the associated data structure for the message queue.
|
|
Packit |
7cfc04 |
During queue creation this field is initialized to
|
|
Packit |
7cfc04 |
.B MSGMNB
|
|
Packit |
7cfc04 |
bytes, but this limit can be modified using
|
|
Packit |
7cfc04 |
.BR msgctl (2).
|
|
Packit |
7cfc04 |
A message queue is considered to be full if either of the following
|
|
Packit |
7cfc04 |
conditions is true:
|
|
Packit |
7cfc04 |
.IP * 2
|
|
Packit |
7cfc04 |
Adding a new message to the queue would cause the total number of bytes
|
|
Packit |
7cfc04 |
in the queue to exceed the queue's maximum size (the
|
|
Packit |
7cfc04 |
.I msg_qbytes
|
|
Packit |
7cfc04 |
field).
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
Adding another message to the queue would cause the total number of messages
|
|
Packit |
7cfc04 |
in the queue to exceed the queue's maximum size (the
|
|
Packit |
7cfc04 |
.I msg_qbytes
|
|
Packit |
7cfc04 |
field).
|
|
Packit |
7cfc04 |
This check is necessary to prevent an unlimited number of zero-length
|
|
Packit |
7cfc04 |
messages being placed on the queue.
|
|
Packit |
7cfc04 |
Although such messages contain no data,
|
|
Packit |
7cfc04 |
they nevertheless consume (locked) kernel memory.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If insufficient space is available in the queue, then the default
|
|
Packit |
7cfc04 |
behavior of
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
is to block until space becomes available.
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.B IPC_NOWAIT
|
|
Packit |
7cfc04 |
is specified in
|
|
Packit |
7cfc04 |
.IR msgflg ,
|
|
Packit |
7cfc04 |
then the call instead fails with the error
|
|
Packit |
7cfc04 |
.BR EAGAIN .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
A blocked
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
call may also fail if:
|
|
Packit |
7cfc04 |
.IP * 2
|
|
Packit |
7cfc04 |
the queue is removed,
|
|
Packit |
7cfc04 |
in which case the system call fails with
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
set to
|
|
Packit |
7cfc04 |
.BR EIDRM ;
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
a signal is caught, in which case the system call fails
|
|
Packit |
7cfc04 |
with
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
set to
|
|
Packit |
7cfc04 |
.BR EINTR ; see
|
|
Packit |
7cfc04 |
.BR signal (7).
|
|
Packit |
7cfc04 |
.RB ( msgsnd ()
|
|
Packit |
7cfc04 |
is never automatically restarted after being interrupted by a
|
|
Packit |
7cfc04 |
signal handler, regardless of the setting of the
|
|
Packit |
7cfc04 |
.B SA_RESTART
|
|
Packit |
7cfc04 |
flag when establishing a signal handler.)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Upon successful completion the message queue data structure is updated
|
|
Packit |
7cfc04 |
as follows:
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
.I msg_lspid
|
|
Packit |
7cfc04 |
is set to the process ID of the calling process.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
.I msg_qnum
|
|
Packit |
7cfc04 |
is incremented by 1.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
.I msg_stime
|
|
Packit |
7cfc04 |
is set to the current time.
|
|
Packit |
7cfc04 |
.SS msgrcv()
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR msgrcv ()
|
|
Packit |
7cfc04 |
system call removes a message from the queue specified by
|
|
Packit |
7cfc04 |
.I msqid
|
|
Packit |
7cfc04 |
and places it in the buffer
|
|
Packit |
7cfc04 |
pointed to by
|
|
Packit |
7cfc04 |
.IR msgp .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I msgsz
|
|
Packit |
7cfc04 |
specifies the maximum size in bytes for the member
|
|
Packit |
7cfc04 |
.I mtext
|
|
Packit |
7cfc04 |
of the structure pointed to by the
|
|
Packit |
7cfc04 |
.I msgp
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
If the message text has length greater than
|
|
Packit |
7cfc04 |
.IR msgsz ,
|
|
Packit |
7cfc04 |
then the behavior depends on whether
|
|
Packit |
7cfc04 |
.B MSG_NOERROR
|
|
Packit |
7cfc04 |
is specified in
|
|
Packit |
7cfc04 |
.IR msgflg .
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.B MSG_NOERROR
|
|
Packit |
7cfc04 |
is specified, then
|
|
Packit |
7cfc04 |
the message text will be truncated (and the truncated part will be
|
|
Packit |
7cfc04 |
lost); if
|
|
Packit |
7cfc04 |
.B MSG_NOERROR
|
|
Packit |
7cfc04 |
is not specified, then
|
|
Packit |
7cfc04 |
the message isn't removed from the queue and
|
|
Packit |
7cfc04 |
the system call fails returning \-1 with
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
set to
|
|
Packit |
7cfc04 |
.BR E2BIG .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Unless
|
|
Packit |
7cfc04 |
.B MSG_COPY
|
|
Packit |
7cfc04 |
is specified in
|
|
Packit |
7cfc04 |
.IR msgflg
|
|
Packit |
7cfc04 |
(see below),
|
|
Packit |
7cfc04 |
the
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
argument specifies the type of message requested, as follows:
|
|
Packit |
7cfc04 |
.IP * 2
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
is 0,
|
|
Packit |
7cfc04 |
then the first message in the queue is read.
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
is greater than 0,
|
|
Packit |
7cfc04 |
then the first message in the queue of type
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
is read, unless
|
|
Packit |
7cfc04 |
.B MSG_EXCEPT
|
|
Packit |
7cfc04 |
was specified in
|
|
Packit |
7cfc04 |
.IR msgflg ,
|
|
Packit |
7cfc04 |
in which case
|
|
Packit |
7cfc04 |
the first message in the queue of type not equal to
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
will be read.
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
is less than 0,
|
|
Packit |
7cfc04 |
then the first message in the queue with the lowest type less than or
|
|
Packit |
7cfc04 |
equal to the absolute value of
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
will be read.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I msgflg
|
|
Packit |
7cfc04 |
argument is a bit mask constructed by ORing together zero or more
|
|
Packit |
7cfc04 |
of the following flags:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B IPC_NOWAIT
|
|
Packit |
7cfc04 |
Return immediately if no message of the requested type is in the queue.
|
|
Packit |
7cfc04 |
The system call fails with
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
set to
|
|
Packit |
7cfc04 |
.BR ENOMSG .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MSG_COPY " (since Linux 3.8)"
|
|
Packit |
7cfc04 |
.\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8
|
|
Packit |
7cfc04 |
Nondestructively fetch a copy of the message at the ordinal position
|
|
Packit |
7cfc04 |
in the queue specified by
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
(messages are considered to be numbered starting at 0).
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
This flag must be specified in conjunction with
|
|
Packit |
7cfc04 |
.BR IPC_NOWAIT ,
|
|
Packit |
7cfc04 |
with the result that, if there is no message available at the given position,
|
|
Packit |
7cfc04 |
the call fails immediately with the error
|
|
Packit |
7cfc04 |
.BR ENOMSG .
|
|
Packit |
7cfc04 |
Because they alter the meaning of
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
in orthogonal ways,
|
|
Packit |
7cfc04 |
.BR MSG_COPY
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR MSG_EXCEPT
|
|
Packit |
7cfc04 |
may not both be specified in
|
|
Packit |
7cfc04 |
.IR msgflg .
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR MSG_COPY
|
|
Packit |
7cfc04 |
flag was added for the implementation of
|
|
Packit |
7cfc04 |
the kernel checkpoint-restore facility and
|
|
Packit |
7cfc04 |
is available only if the kernel was built with the
|
|
Packit |
7cfc04 |
.B CONFIG_CHECKPOINT_RESTORE
|
|
Packit |
7cfc04 |
option.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MSG_EXCEPT
|
|
Packit |
7cfc04 |
Used with
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
greater than 0
|
|
Packit |
7cfc04 |
to read the first message in the queue with message type that differs
|
|
Packit |
7cfc04 |
from
|
|
Packit |
7cfc04 |
.IR msgtyp .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MSG_NOERROR
|
|
Packit |
7cfc04 |
To truncate the message text if longer than
|
|
Packit |
7cfc04 |
.I msgsz
|
|
Packit |
7cfc04 |
bytes.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If no message of the requested type is available and
|
|
Packit |
7cfc04 |
.B IPC_NOWAIT
|
|
Packit |
7cfc04 |
isn't specified in
|
|
Packit |
7cfc04 |
.IR msgflg ,
|
|
Packit |
7cfc04 |
the calling process is blocked until one of the following conditions occurs:
|
|
Packit |
7cfc04 |
.IP * 2
|
|
Packit |
7cfc04 |
A message of the desired type is placed in the queue.
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
The message queue is removed from the system.
|
|
Packit |
7cfc04 |
In this case, the system call fails with
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
set to
|
|
Packit |
7cfc04 |
.BR EIDRM .
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
The calling process catches a signal.
|
|
Packit |
7cfc04 |
In this case, the system call fails with
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
set to
|
|
Packit |
7cfc04 |
.BR EINTR .
|
|
Packit |
7cfc04 |
.RB ( msgrcv ()
|
|
Packit |
7cfc04 |
is never automatically restarted after being interrupted by a
|
|
Packit |
7cfc04 |
signal handler, regardless of the setting of the
|
|
Packit |
7cfc04 |
.B SA_RESTART
|
|
Packit |
7cfc04 |
flag when establishing a signal handler.)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Upon successful completion the message queue data structure is updated
|
|
Packit |
7cfc04 |
as follows:
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
.I msg_lrpid
|
|
Packit |
7cfc04 |
is set to the process ID of the calling process.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
.I msg_qnum
|
|
Packit |
7cfc04 |
is decremented by 1.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
.I msg_rtime
|
|
Packit |
7cfc04 |
is set to the current time.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
On failure both functions return \-1
|
|
Packit |
7cfc04 |
with
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
indicating the error,
|
|
Packit |
7cfc04 |
otherwise
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
returns 0
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR msgrcv ()
|
|
Packit |
7cfc04 |
returns the number of bytes actually copied into the
|
|
Packit |
7cfc04 |
.I mtext
|
|
Packit |
7cfc04 |
array.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
When
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
fails,
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
will be set to one among the following values:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EACCES
|
|
Packit |
7cfc04 |
The calling process does not have write permission on the message queue,
|
|
Packit |
7cfc04 |
and does not have the
|
|
Packit |
7cfc04 |
.B CAP_IPC_OWNER
|
|
Packit |
7cfc04 |
capability.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EAGAIN
|
|
Packit |
7cfc04 |
The message can't be sent due to the
|
|
Packit |
7cfc04 |
.I msg_qbytes
|
|
Packit |
7cfc04 |
limit for the queue and
|
|
Packit |
7cfc04 |
.B IPC_NOWAIT
|
|
Packit |
7cfc04 |
was specified in
|
|
Packit |
7cfc04 |
.IR msgflg .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EFAULT
|
|
Packit |
7cfc04 |
The address pointed to by
|
|
Packit |
7cfc04 |
.I msgp
|
|
Packit |
7cfc04 |
isn't accessible.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EIDRM
|
|
Packit |
7cfc04 |
The message queue was removed.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINTR
|
|
Packit |
7cfc04 |
Sleeping on a full message queue condition, the process caught a signal.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
Invalid
|
|
Packit |
7cfc04 |
.I msqid
|
|
Packit |
7cfc04 |
value, or nonpositive
|
|
Packit |
7cfc04 |
.I mtype
|
|
Packit |
7cfc04 |
value, or
|
|
Packit |
7cfc04 |
invalid
|
|
Packit |
7cfc04 |
.I msgsz
|
|
Packit |
7cfc04 |
value (less than 0 or greater than the system value
|
|
Packit |
7cfc04 |
.BR MSGMAX ).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOMEM
|
|
Packit |
7cfc04 |
The system does not have enough memory to make a copy of the
|
|
Packit |
7cfc04 |
message pointed to by
|
|
Packit |
7cfc04 |
.IR msgp .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
When
|
|
Packit |
7cfc04 |
.BR msgrcv ()
|
|
Packit |
7cfc04 |
fails,
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
will be set to one among the following values:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B E2BIG
|
|
Packit |
7cfc04 |
The message text length is greater than
|
|
Packit |
7cfc04 |
.I msgsz
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B MSG_NOERROR
|
|
Packit |
7cfc04 |
isn't specified in
|
|
Packit |
7cfc04 |
.IR msgflg .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EACCES
|
|
Packit |
7cfc04 |
The calling process does not have read permission on the message queue,
|
|
Packit |
7cfc04 |
and does not have the
|
|
Packit |
7cfc04 |
.B CAP_IPC_OWNER
|
|
Packit |
7cfc04 |
capability in the user namespace that governs its IPC namespace.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EFAULT
|
|
Packit |
7cfc04 |
The address pointed to by
|
|
Packit |
7cfc04 |
.I msgp
|
|
Packit |
7cfc04 |
isn't accessible.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EIDRM
|
|
Packit |
7cfc04 |
While the process was sleeping to receive a message,
|
|
Packit |
7cfc04 |
the message queue was removed.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINTR
|
|
Packit |
7cfc04 |
While the process was sleeping to receive a message,
|
|
Packit |
7cfc04 |
the process caught a signal; see
|
|
Packit |
7cfc04 |
.BR signal (7).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.I msqid
|
|
Packit |
7cfc04 |
was invalid, or
|
|
Packit |
7cfc04 |
.I msgsz
|
|
Packit |
7cfc04 |
was less than 0.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINVAL " (since Linux 3.14)"
|
|
Packit |
7cfc04 |
.I msgflg
|
|
Packit |
7cfc04 |
specified
|
|
Packit |
7cfc04 |
.BR MSG_COPY ,
|
|
Packit |
7cfc04 |
but not
|
|
Packit |
7cfc04 |
.BR IPC_NOWAIT .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINVAL " (since Linux 3.14)"
|
|
Packit |
7cfc04 |
.I msgflg
|
|
Packit |
7cfc04 |
specified both
|
|
Packit |
7cfc04 |
.BR MSG_COPY
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR MSG_EXCEPT .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOMSG
|
|
Packit |
7cfc04 |
.B IPC_NOWAIT
|
|
Packit |
7cfc04 |
was specified in
|
|
Packit |
7cfc04 |
.I msgflg
|
|
Packit |
7cfc04 |
and no message of the requested type existed on the message queue.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOMSG
|
|
Packit |
7cfc04 |
.B IPC_NOWAIT
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B MSG_COPY
|
|
Packit |
7cfc04 |
were specified in
|
|
Packit |
7cfc04 |
.I msgflg
|
|
Packit |
7cfc04 |
and the queue contains less than
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
messages.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOSYS " (since Linux 3.8)"
|
|
Packit |
7cfc04 |
.I MSG_COPY
|
|
Packit |
7cfc04 |
was specified in
|
|
Packit |
7cfc04 |
.IR msgflg ,
|
|
Packit |
7cfc04 |
and this kernel was configured without
|
|
Packit |
7cfc04 |
.BR CONFIG_CHECKPOINT_RESTORE .
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
POSIX.1-2001, POSIX.1-2008, SVr4.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.B MSG_EXCEPT
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B MSG_COPY
|
|
Packit |
7cfc04 |
flags are Linux-specific;
|
|
Packit |
7cfc04 |
their definitions can be obtained by defining the
|
|
Packit |
7cfc04 |
.B _GNU_SOURCE
|
|
Packit |
7cfc04 |
.\" MSG_COPY since glibc 2.18
|
|
Packit |
7cfc04 |
feature test macro.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
The inclusion of
|
|
Packit |
7cfc04 |
.I <sys/types.h>
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I <sys/ipc.h>
|
|
Packit |
7cfc04 |
isn't required on Linux or by any version of POSIX.
|
|
Packit |
7cfc04 |
However,
|
|
Packit |
7cfc04 |
some old implementations required the inclusion of these header files,
|
|
Packit |
7cfc04 |
and the SVID also documented their inclusion.
|
|
Packit |
7cfc04 |
Applications intended to be portable to such old systems may need
|
|
Packit |
7cfc04 |
to include these header files.
|
|
Packit |
7cfc04 |
.\" Like Linux, the FreeBSD man pages still document
|
|
Packit |
7cfc04 |
.\" the inclusion of these header files.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I msgp
|
|
Packit |
7cfc04 |
argument is declared as \fIstruct msgbuf\ *\fP in
|
|
Packit |
7cfc04 |
glibc 2.0 and 2.1.
|
|
Packit |
7cfc04 |
It is declared as \fIvoid\ *\fP
|
|
Packit |
7cfc04 |
in glibc 2.2 and later, as required by SUSv2 and SUSv3.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The following limits on message queue resources affect the
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
call:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MSGMAX
|
|
Packit |
7cfc04 |
Maximum size of a message text, in bytes (default value: 8192 bytes).
|
|
Packit |
7cfc04 |
On Linux, this limit can be read and modified via
|
|
Packit |
7cfc04 |
.IR /proc/sys/kernel/msgmax .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MSGMNB
|
|
Packit |
7cfc04 |
Maximum number of bytes that can be held in a message queue
|
|
Packit |
7cfc04 |
(default value: 16384 bytes).
|
|
Packit |
7cfc04 |
On Linux, this limit can be read and modified via
|
|
Packit |
7cfc04 |
.IR /proc/sys/kernel/msgmnb .
|
|
Packit |
7cfc04 |
A privileged process
|
|
Packit |
7cfc04 |
(Linux: a process with the
|
|
Packit |
7cfc04 |
.B CAP_SYS_RESOURCE
|
|
Packit |
7cfc04 |
capability)
|
|
Packit |
7cfc04 |
can increase the size of a message queue beyond
|
|
Packit |
7cfc04 |
.B MSGMNB
|
|
Packit |
7cfc04 |
using the
|
|
Packit |
7cfc04 |
.BR msgctl (2)
|
|
Packit |
7cfc04 |
.B IPC_SET
|
|
Packit |
7cfc04 |
operation.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The implementation has no intrinsic system-wide limits on the
|
|
Packit |
7cfc04 |
number of message headers
|
|
Packit |
7cfc04 |
.RB ( MSGTQL )
|
|
Packit |
7cfc04 |
and the number of bytes in the message pool
|
|
Packit |
7cfc04 |
.RB ( MSGPOOL ).
|
|
Packit |
7cfc04 |
.SH BUGS
|
|
Packit |
7cfc04 |
In Linux 3.13 and earlier,
|
|
Packit |
7cfc04 |
if
|
|
Packit |
7cfc04 |
.BR msgrcv ()
|
|
Packit |
7cfc04 |
was called with the
|
|
Packit |
7cfc04 |
.BR MSG_COPY
|
|
Packit |
7cfc04 |
flag, but without
|
|
Packit |
7cfc04 |
.BR IPC_NOWAIT ,
|
|
Packit |
7cfc04 |
and the message queue contained less than
|
|
Packit |
7cfc04 |
.I msgtyp
|
|
Packit |
7cfc04 |
messages, then the call would block until the next message is written
|
|
Packit |
7cfc04 |
to the queue.
|
|
Packit |
7cfc04 |
.\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
|
|
Packit |
7cfc04 |
At that point, the call would return a copy of the message,
|
|
Packit |
7cfc04 |
.I regardless
|
|
Packit |
7cfc04 |
of whether that message was at the ordinal position
|
|
Packit |
7cfc04 |
.IR msgtyp .
|
|
Packit |
7cfc04 |
This bug is fixed
|
|
Packit |
7cfc04 |
.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
|
|
Packit |
7cfc04 |
in Linux 3.14.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Specifying both
|
|
Packit |
7cfc04 |
.B MSG_COPY
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B MSC_EXCEPT
|
|
Packit |
7cfc04 |
in
|
|
Packit |
7cfc04 |
.I msgflg
|
|
Packit |
7cfc04 |
is a logical error (since these flags impose different interpretations on
|
|
Packit |
7cfc04 |
.IR msgtyp ).
|
|
Packit |
7cfc04 |
In Linux 3.13 and earlier,
|
|
Packit |
7cfc04 |
.\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
|
|
Packit |
7cfc04 |
this error was not diagnosed by
|
|
Packit |
7cfc04 |
.BR msgrcv ().
|
|
Packit |
7cfc04 |
This bug is fixed
|
|
Packit |
7cfc04 |
.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
|
|
Packit |
7cfc04 |
in Linux 3.14.
|
|
Packit |
7cfc04 |
.SH EXAMPLE
|
|
Packit |
7cfc04 |
The program below demonstrates the use of
|
|
Packit |
7cfc04 |
.BR msgsnd ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR msgrcv ().
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The example program is first run with the \fB\-s\fP option to send a
|
|
Packit |
7cfc04 |
message and then run again with the \fB\-r\fP option to receive a
|
|
Packit |
7cfc04 |
message.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The following shell session shows a sample run of the program:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
.RB "$" " ./a.out \-s"
|
|
Packit |
7cfc04 |
sent: a message at Wed Mar 4 16:25:45 2015
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.RB "$" " ./a.out \-r"
|
|
Packit |
7cfc04 |
message received: a message at Wed Mar 4 16:25:45 2015
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.SS Program source
|
|
Packit |
7cfc04 |
\&
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
#include <stdio.h>
|
|
Packit |
7cfc04 |
#include <stdlib.h>
|
|
Packit |
7cfc04 |
#include <string.h>
|
|
Packit |
7cfc04 |
#include <time.h>
|
|
Packit |
7cfc04 |
#include <unistd.h>
|
|
Packit |
7cfc04 |
#include <errno.h>
|
|
Packit |
7cfc04 |
#include <sys/types.h>
|
|
Packit |
7cfc04 |
#include <sys/ipc.h>
|
|
Packit |
7cfc04 |
#include <sys/msg.h>
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
struct msgbuf {
|
|
Packit |
7cfc04 |
long mtype;
|
|
Packit |
7cfc04 |
char mtext[80];
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
static void
|
|
Packit |
7cfc04 |
usage(char *prog_name, char *msg)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
if (msg != NULL)
|
|
Packit |
7cfc04 |
fputs(msg, stderr);
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
fprintf(stderr, "Usage: %s [options]\\n", prog_name);
|
|
Packit |
7cfc04 |
fprintf(stderr, "Options are:\\n");
|
|
Packit |
7cfc04 |
fprintf(stderr, "\-s send message using msgsnd()\\n");
|
|
Packit |
7cfc04 |
fprintf(stderr, "\-r read message using msgrcv()\\n");
|
|
Packit |
7cfc04 |
fprintf(stderr, "\-t message type (default is 1)\\n");
|
|
Packit |
7cfc04 |
fprintf(stderr, "\-k message queue key (default is 1234)\\n");
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
static void
|
|
Packit |
7cfc04 |
send_msg(int qid, int msgtype)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
struct msgbuf msg;
|
|
Packit |
7cfc04 |
time_t t;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
msg.mtype = msgtype;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
time(&t);
|
|
Packit |
7cfc04 |
snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
|
|
Packit |
7cfc04 |
ctime(&t);;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
if (msgsnd(qid, (void *) &msg, sizeof(msg.mtext),
|
|
Packit |
7cfc04 |
IPC_NOWAIT) == \-1) {
|
|
Packit |
7cfc04 |
perror("msgsnd error");
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
printf("sent: %s\\n", msg.mtext);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
static void
|
|
Packit |
7cfc04 |
get_msg(int qid, int msgtype)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
struct msgbuf msg;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
if (msgrcv(qid, (void *) &msg, sizeof(msg.mtext), msgtype,
|
|
Packit |
7cfc04 |
MSG_NOERROR | IPC_NOWAIT) == \-1) {
|
|
Packit |
7cfc04 |
if (errno != ENOMSG) {
|
|
Packit |
7cfc04 |
perror("msgrcv");
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
printf("No message available for msgrcv()\\n");
|
|
Packit |
7cfc04 |
} else
|
|
Packit |
7cfc04 |
printf("message received: %s\\n", msg.mtext);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
int
|
|
Packit |
7cfc04 |
main(int argc, char *argv[])
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
int qid, opt;
|
|
Packit |
7cfc04 |
int mode = 0; /* 1 = send, 2 = receive */
|
|
Packit |
7cfc04 |
int msgtype = 1;
|
|
Packit |
7cfc04 |
int msgkey = 1234;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
while ((opt = getopt(argc, argv, "srt:k:")) != \-1) {
|
|
Packit |
7cfc04 |
switch (opt) {
|
|
Packit |
7cfc04 |
case \(aqs\(aq:
|
|
Packit |
7cfc04 |
mode = 1;
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
case \(aqr\(aq:
|
|
Packit |
7cfc04 |
mode = 2;
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
case \(aqt\(aq:
|
|
Packit |
7cfc04 |
msgtype = atoi(optarg);
|
|
Packit |
7cfc04 |
if (msgtype <= 0)
|
|
Packit |
7cfc04 |
usage(argv[0], "\-t option must be greater than 0\\n");
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
case \(aqk\(aq:
|
|
Packit |
7cfc04 |
msgkey = atoi(optarg);
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
default:
|
|
Packit |
7cfc04 |
usage(argv[0], "Unrecognized option\\n");
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
if (mode == 0)
|
|
Packit |
7cfc04 |
usage(argv[0], "must use either \-s or \-r option\\n");
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
qid = msgget(msgkey, IPC_CREAT | 0666);
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
if (qid == \-1) {
|
|
Packit |
7cfc04 |
perror("msgget");
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
if (mode == 2)
|
|
Packit |
7cfc04 |
get_msg(qid, msgtype);
|
|
Packit |
7cfc04 |
else
|
|
Packit |
7cfc04 |
send_msg(qid, msgtype);
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
exit(EXIT_SUCCESS);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR msgctl (2),
|
|
Packit |
7cfc04 |
.BR msgget (2),
|
|
Packit |
7cfc04 |
.BR capabilities (7),
|
|
Packit |
7cfc04 |
.BR mq_overview (7),
|
|
Packit |
7cfc04 |
.BR svipc (7)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|