297 lines
6.6 KiB
Groff
297 lines
6.6 KiB
Groff
'\"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
|