mirror of https://github.com/mkerrisk/man-pages
427 lines
9.6 KiB
Groff
427 lines
9.6 KiB
Groff
.\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" 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
|
|
.\" Modified 1 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Language clean-ups.
|
|
.\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX
|
|
.\" Added note on restart behavior of msgsnd() and msgrcv()
|
|
.\" Formatting clean-ups (argument and field names marked as .I
|
|
.\" instead of .B)
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Added notes on capability requirements
|
|
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Language and formatting clean-ups
|
|
.\" Added notes on /proc files
|
|
.\"
|
|
.TH MSGOP 2 2006-02-02 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
msgop, msgrcv, msgsnd \- message operations
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/types.h>
|
|
.B #include <sys/ipc.h>
|
|
.B #include <sys/msg.h>
|
|
.sp
|
|
.BI "int msgsnd(int " msqid ", const void *" msgp ", size_t " msgsz \
|
|
", int " msgflg );
|
|
.sp
|
|
.BI "ssize_t msgrcv(int " msqid ", void *" msgp ", size_t " msgsz \
|
|
", long " msgtyp ,
|
|
.BI " int " msgflg );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR msgsnd ()
|
|
and
|
|
.BR msgrcv ()
|
|
system calls are used, respectively, to send messages to,
|
|
and receive messages from, a 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
|
|
of the following general form:
|
|
.in +0.5i
|
|
.nf
|
|
|
|
struct msgbuf {
|
|
long mtype; /* message type, must be > 0 */
|
|
char mtext[1]; /* message data */
|
|
};
|
|
.fi
|
|
.in -0.5i
|
|
.PP
|
|
The
|
|
.I mtext
|
|
field is an array (or other structure) whose size is specified by
|
|
.IR msgsz ,
|
|
a non-negative integer value.
|
|
Messages of zero length (i.e., no
|
|
.I mtext
|
|
field) are permitted.
|
|
The
|
|
.I mtype
|
|
field must have a strictly positive integer value.
|
|
This value can be
|
|
used by the receiving process for message selection
|
|
(see the description of
|
|
.BR msgrcv ()
|
|
below).
|
|
.PP
|
|
The
|
|
.BR msgsnd ()
|
|
system call appends a copy of the message pointed to by
|
|
.I msgp
|
|
to the message queue whose identifier is specified
|
|
by
|
|
.IR msqid .
|
|
.PP
|
|
If sufficient space is available in the queue,
|
|
.BR msgsnd ()
|
|
succeeds immediately.
|
|
(The queue capacity is defined by the
|
|
.I msg_bytes
|
|
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).)
|
|
If insufficient space is available in the queue, then the default
|
|
behavior of
|
|
.BR msgsnd ()
|
|
is to block until space becomes available.
|
|
If
|
|
.B IPC_NOWAIT
|
|
is specified in
|
|
.IR msgflg ,
|
|
then the call instead fails with the error
|
|
.BR EAGAIN .
|
|
|
|
A blocked
|
|
.BR msgsnd ()
|
|
call may also fail if the queue is removed
|
|
(in which case the system call fails with
|
|
.I errno
|
|
set to
|
|
.BR EIDRM ),
|
|
or a signal is caught (in which case the system call fails
|
|
with
|
|
.I errno
|
|
set to
|
|
.BR EINTR ).
|
|
.RB ( msgsnd " and " msgrcv
|
|
are never automatically restarted after being interrupted by a
|
|
signal handler, regardless of the setting of the
|
|
.B SA_RESTART
|
|
flag when establishing a signal handler.)
|
|
.PP
|
|
Upon successful completion the message queue data structure is updated
|
|
as follows:
|
|
.IP
|
|
.I msg_lspid
|
|
is set to the process ID of the calling process.
|
|
.IP
|
|
.I msg_qnum
|
|
is incremented by 1.
|
|
.IP
|
|
.I msg_stime
|
|
is set to the current time.
|
|
.PP
|
|
The system call
|
|
.BR msgrcv ()
|
|
removes a message from the queue specified by
|
|
.I msqid
|
|
and places it in the buffer
|
|
pointed to
|
|
.IR msgp .
|
|
.PP
|
|
The argument
|
|
.I msgsz
|
|
specifies the maximum size in bytes for the member
|
|
.I mtext
|
|
of the structure pointed to by the
|
|
.I msgp
|
|
argument.
|
|
If the message text has length greater than
|
|
.IR msgsz ,
|
|
then the behavior depends on whether
|
|
.BR MSG_NOERROR
|
|
is specified in
|
|
.IR msgflg .
|
|
If
|
|
.BR MSG_NOERROR
|
|
is specified, then
|
|
the message text will be truncated (and the truncated part will be
|
|
lost); if
|
|
.BR MSG_NOERROR
|
|
is not specified, then
|
|
the message isn't removed from the queue and
|
|
the system call fails returning \-1 with
|
|
.I errno
|
|
set to
|
|
.BR E2BIG .
|
|
.PP
|
|
The argument
|
|
.I msgtyp
|
|
specifies the type of message requested as follows:
|
|
.IP
|
|
If
|
|
.I msgtyp
|
|
is 0,
|
|
then the first message in the queue is read.
|
|
.IP
|
|
If
|
|
.I msgtyp
|
|
is greater than 0,
|
|
then the first message in the queue of type
|
|
.I msgtyp
|
|
is read, unless
|
|
.B MSG_EXCEPT
|
|
was specified in
|
|
.IR msgflg ,
|
|
in which case
|
|
the first message in the queue of type not equal to
|
|
.I msgtyp
|
|
will be read.
|
|
.IP
|
|
If
|
|
.I msgtyp
|
|
is less than 0,
|
|
then the first message in the queue with the lowest type less than or
|
|
equal to the absolute value of
|
|
.I msgtyp
|
|
will be read.
|
|
.PP
|
|
The
|
|
.I msgflg
|
|
argument is a bit mask constructed by ORing together zero or more
|
|
of the following flags:
|
|
.TP
|
|
.B IPC_NOWAIT
|
|
Return immediately if no message of the requested type is in the queue.
|
|
The system call fails with
|
|
.I errno
|
|
set to
|
|
.BR ENOMSG .
|
|
.TP
|
|
.B MSG_EXCEPT
|
|
Used with
|
|
.I msgtyp
|
|
greater than 0
|
|
to read the first message in the queue with message type that differs
|
|
from
|
|
.IR msgtyp .
|
|
.TP
|
|
.B MSG_NOERROR
|
|
To truncate the message text if longer than
|
|
.I msgsz
|
|
bytes.
|
|
.PP
|
|
If no message of the requested type is available and
|
|
.B IPC_NOWAIT
|
|
isn't specified in
|
|
.IR msgflg ,
|
|
the calling process is blocked until one of the following conditions occurs:
|
|
.IP
|
|
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
|
|
.I errno
|
|
set to
|
|
.BR EIDRM .
|
|
.IP
|
|
The calling process catches a signal.
|
|
In this case the system call fails with
|
|
.I errno
|
|
set to
|
|
.BR EINTR .
|
|
.PP
|
|
Upon successful completion the message queue data structure is updated
|
|
as follows:
|
|
.IP
|
|
.I msg_lrpid
|
|
is set to the process ID of the calling process.
|
|
.IP
|
|
.I msg_qnum
|
|
is decremented by 1.
|
|
.IP
|
|
.I msg_rtime
|
|
is set to the current time.
|
|
.SH "RETURN VALUE"
|
|
On failure both functions return \-1
|
|
with
|
|
.I errno
|
|
indicating the error,
|
|
otherwise
|
|
.BR msgsnd ()
|
|
returns 0
|
|
and
|
|
.BR msgrcv ()
|
|
returns the number of bytes actually copied into the
|
|
.I mtext
|
|
array.
|
|
.SH ERRORS
|
|
When
|
|
.BR msgsnd ()
|
|
fails,
|
|
.I errno
|
|
will be set to one among the following values:
|
|
.TP 11
|
|
.B EACCES
|
|
The calling process does not have write permission on the message queue,
|
|
and does not have the
|
|
.BR CAP_IPC_OWNER
|
|
capability.
|
|
.TP
|
|
.B EAGAIN
|
|
The message can't be sent due to the
|
|
.I msg_qbytes
|
|
limit for the queue and
|
|
.B IPC_NOWAIT
|
|
was specified in
|
|
.IR msgflg .
|
|
.TP
|
|
.B EFAULT
|
|
The address pointed to by
|
|
.I msgp
|
|
isn't accessible.
|
|
.TP
|
|
.B EIDRM
|
|
The message queue was removed.
|
|
.TP
|
|
.B EINTR
|
|
Sleeping on a full message queue condition, the process caught a signal.
|
|
.TP
|
|
.B EINVAL
|
|
Invalid
|
|
.I msqid
|
|
value, or non-positive
|
|
.I mtype
|
|
value, or
|
|
invalid
|
|
.I msgsz
|
|
value (less than 0 or greater than the system value
|
|
.BR MSGMAX ).
|
|
.TP
|
|
.B ENOMEM
|
|
The system does not have enough memory to make a copy of the
|
|
message pointed to by
|
|
.IR msgp .
|
|
.PP
|
|
When
|
|
.BR msgrcv ()
|
|
fails,
|
|
.I errno
|
|
will be set to one among the following values:
|
|
.TP 11
|
|
.B E2BIG
|
|
The message text length is greater than
|
|
.I msgsz
|
|
and
|
|
.B MSG_NOERROR
|
|
isn't specified in
|
|
.IR msgflg .
|
|
.TP
|
|
.B EACCES
|
|
The calling process does not have read permission on the message queue,
|
|
and does not have the
|
|
.BR CAP_IPC_OWNER
|
|
capability.
|
|
.TP
|
|
.B EAGAIN
|
|
No message was available in the queue and
|
|
.B IPC_NOWAIT
|
|
was specified in
|
|
.IR msgflg .
|
|
.TP
|
|
.B EFAULT
|
|
The address pointed to by
|
|
.I msgp
|
|
isn't accessible.
|
|
.TP
|
|
.B EIDRM
|
|
While the process was sleeping to receive a message,
|
|
the message queue was removed.
|
|
.TP
|
|
.B EINTR
|
|
While the process was sleeping to receive a message,
|
|
the process caught a signal.
|
|
.TP
|
|
.B EINVAL
|
|
.I msgqid
|
|
was invalid, or
|
|
.I msgsz
|
|
was less than 0.
|
|
.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"
|
|
SVr4, POSIX.1-2001.
|
|
.SH NOTES
|
|
The
|
|
.I msgp
|
|
argument is declared as \fIstruct msgbuf *\fP with
|
|
libc4, libc5, glibc 2.0, glibc 2.1.
|
|
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
|
|
.BR msgsnd ()
|
|
call:
|
|
.TP 11
|
|
.B MSGMAX
|
|
Maximum size for a message text: 8192 bytes
|
|
(on Linux, this limit can be read and modified via
|
|
.IR /proc/sys/kernel/msgmax ).
|
|
.TP
|
|
.B MSGMNB
|
|
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
|
|
.B MSGMNB
|
|
by a
|
|
.BR msgctl (2)
|
|
system call.
|
|
.PP
|
|
The implementation has no intrinsic limits for the system wide maximum
|
|
number of message headers
|
|
.RB ( MSGTQL )
|
|
and for the system wide maximum size in bytes of the message pool
|
|
.RB ( MSGPOOL ).
|
|
.SH "SEE ALSO"
|
|
.BR msgctl (2),
|
|
.BR msgget (2),
|
|
.BR msgrcv (2),
|
|
.BR msgsnd (2),
|
|
.BR capabilities (7),
|
|
.BR mq_overview (7),
|
|
.BR svipc (7)
|