'\"macro stdmacro
.if n .pH g2.msgop @(#)msgop	41.4 of 5/26/91
.\" Copyright 1991 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990 AT&T
.nr X
.if \nX=0 .ds x} msgop 2 "" "\&"
.if \nX=1 .ds x} msgop 2 ""
.if \nX=2 .ds x} msgop 2 "" "\&"
.if \nX=3 .ds x} msgop "" "" "\&"
.TH \*(x}
.SH NAME
\f4msgop\f1: \f4msgsnd\f1, \f4msgrcv\f1 \- message operations
.SH SYNOPSIS
\f4#include <sys/types.h>\f1
.br
\f4#include <sys/ipc.h>\f1
.br
\f4#include <sys/msg.h>\f1
.PP
.nf
\f4int msgsnd(int msqid, const void \(**msgp,
	size_t msgsz, int msgflg);\f1
.PP
\f4int msgrcv(int msqid, void \(**msgp,
	size_t msgsz, long msgtyp, int msgflg);\f1
.fi
.SH DESCRIPTION
\f4msgsnd\f1 sends a message to the queue associated with the message
queue identifier specified by
.IR msqid .
.I msgp
points to a user defined buffer
that must contain first a field of type long integer that
will specify the type of the message, and then a data portion
that will hold the text of the message.
The following is an example of members that might be in a user defined buffer.
.P
.RS
.nf
.ft 4
    long mtype;    /* message type */
    char mtext[];  /* message text */
.ft 1
.fi
.RE
.P
\f4mtype\f1 is a positive integer that can be used 
by the receiving process for message selection.
\f4mtext\f1 is any text of length \f2msgsz\f1 bytes.
\f2msgsz\f1 can range from \f40\f1 to a system imposed maximum.
.PP
.I msgflg
specifies the action to be taken if one or more of the following are true:
.IP
The number of bytes already on the queue is equal to
\f4msg_qbytes\f1
[see \f4intro\fP(2)].
.IP
The total number of messages on all queues system-wide is equal to the
system-imposed limit.
.PP
These actions are as follows:
.IP
If
(\f2msgflg\f4&IPC_NOWAIT\f1)
is true, the message is not sent and the calling process
returns immediately.
.IP
If
(\f2msgflg\f4&IPC_NOWAIT\f1)
is false,
the calling process suspends execution until one of the following occurs:
.RS 8
.IP
The condition responsible for the suspension no longer exists, in which case
the message is sent.
.IP
.I msqid
is removed from the system [see
\f4msgctl\fP(2)].
When this occurs,
\f4errno\fP
is set to
\f4EIDRM\fP,
and a value of \-1 is returned.
.IP
The calling process receives a signal that is to be caught.
In this case the message is not sent and the calling process resumes
execution in the manner prescribed in
\f4signal\fP(2).
.RE
.PP
\f4msgsnd\fP
fails and sends no message if one or more of the following are true:
.TP 15
\f4EINVAL\fP
.I msqid
is not a valid message queue identifier.
.TP
\f4EACCES\fP
Write permission is denied to the calling process [see
\f4intro\fP(2)].
.TP
\f4EINVAL\fP
.I mtype
is less than 1.
.TP
\f4EAGAIN\fP
The message cannot be sent for one of the reasons cited above and
(\f2msgflg\f4&IPC_NOWAIT\f1)
is true.
.TP
\f4EINVAL\fP
.I msgsz
is less than zero or greater than the system-imposed limit.
.TP
\f4EFAULT\fP
.I msgp
points to an illegal address.
.PP
Upon successful completion, the following actions are taken with respect to
the data structure associated with
.IR msqid
[see intro (2)].
.IP
\f4msg_qnum\f1
is incremented by 1.
.IP
\f4msg_lspid\f1
is set to the process
.SM ID
of the calling process.
.IP
\f4msg_stime\f1
is set to the current time.
.PP
\f4msgrcv\fP
reads a message from the queue associated with the message queue identifier
specified by
.IR msqid
and places it in the user defined structure pointed to by
.IR msgp .
The structure must contain a message type field followed
by the area for the message text (see the structure \f4mymsg\f1 above).
\f4mtype\f1 is the received message's type
as specified by the sending process.
\f4mtext\f1 is the text of the message.
\f2msgsz\f1 specifies the size in bytes of \f(CWmtext\f1.
The received message is truncated to
.I msgsz
bytes if it is larger than
.I msgsz
and
(\f2msgflg\f4&MSG_NOERROR\f1)
is true.
The truncated part of the message is lost and no indication of the truncation is
given to the calling process.
.PP
.I msgtyp
specifies the type of message requested as follows:
.IP
If
.I msgtyp
is 0, the first message on the queue is received.
.IP
If
.I msgtyp
is greater than 0, the first message of type
.I msgtyp
is received.
.IP
If
.I msgtyp
is less than 0,
the first message of the lowest type that is less than or equal
to the absolute value of
.I msgtyp
is received.
.PP
.I msgflg
specifies the action to be taken if a message of the desired type
is not on the queue.
These are as follows:
.IP
If
(\f2msgflg\f4&IPC_NOWAIT\f1)
is true, the calling process returns immediately with a return value
of \-1 and sets
\f4errno\fP
to
\f4ENOMSG\fP.
.IP
If 
(\f2msgflg\f4&IPC_NOWAIT\f1)
is false, the calling process suspends execution until one of the
following occurs:
.RS 8
.IP
A message of the desired type is placed on the queue.
.IP
.I msqid
is removed from the system.
When this occurs,
\f4errno\fP
is set to
\f4EIDRM\fP,
and a value of \-1 is returned.
.IP
The calling process receives a signal that is to be caught.
In this case a message is not received and the calling process resumes
execution in the manner prescribed in
\f4signal\fP(2).
.RE
.PP
\f4msgrcv\fP
fails and receives no message if one or more of the following are
true:
.TP 15
\f4EINVAL\fP
.I msqid
is not a valid message queue identifier.
.\".TP
.\"\f4EINVAL\fP
.\"The Mandatory Access Control
.\"level of the calling process is not equal to the level of \f2msgqid\fP.
.TP
\f4EACCES\fP
Read permission is denied to the calling process.
.TP
\f4EINVAL\fP
.I msgsz
is less than 0.
.TP
\f4E2BIG\fP
The length of
.I mtext
is greater than
.I msgsz
and
(\f2msgflg\f4&MSG_NOERROR\f1)
is false.
.TP
\f4ENOMSG\fP
The queue does not contain a message of the desired type and
(\f2msgtyp\f4&IPC_NOWAIT\f1)
is true.
.TP
\f4EFAULT\fP
.I msgp
points to an illegal address.
.PP
Upon successful completion, the following actions are taken with respect to
the data structure associated with
.IR msqid
[see intro (2)].
.IP
\f4msg_qnum\f1
is decremented by 1.
.IP
\f4msg_lrpid\f1
is set to the process
.SM ID
of the calling process.
.IP
\f4msg_rtime\f1
is set to the current time.
.SH SEE ALSO
\f4intro\fP(2), \f4msgctl\fP(2), \f4msgget\fP(2), \f4signal\fP(2).
.SH DIAGNOSTICS
If \f4msgsnd\fP or \f4msgrcv\fP
return due to the receipt of a signal, a value of \-1 is returned to the
calling process and
\f4errno\fP
is set to
\f4EINTR\fP.
If they return due to removal of
.I msqid
from the system, a value of \-1 is returned and
\f4errno\fP
is set to
\f4EIDRM\fP.
.PP
Upon successful completion, the return value is as follows:
.IP
\f4msgsnd\fP
returns a value of 0.
.IP
\f4msgrcv\fP
returns the number of bytes actually placed into
.IR mtext .
.PP
Otherwise, a value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
.\"	@(#)msgop.2	6.2 of 9/6/83
.Ee