Return to msgop.2i CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2

Power 6/32 Unix version 1.21

.TH MSGOP 2
.SH NAME
msgop \- message operations
.SH SYNOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/ipc.h>
.br
.B #include <sys/msg.h>
.PP
.nf
.B int msgsnd (msqid, msgp, msgsz, msgflg)
.B int msqid;
.B struct msgbuf \(**msgp;
.B int msgsz, msgflg;
.PP
.B "int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg)"
.B int msqid;
.B struct msgbuf \(**msgp;
.B int msgsz;
.B long msgtyp;
.B int msgflg;
.fi
.SH DESCRIPTION
Msgsnd is used to send a message to the queue associated with the message
queue identifier specified by
.IR msqid .
.SM {WRITE}
.I Msgp
points to a structure containing the message.
This structure is composed of the following members:
.PP
.RS
.ta 8n 20n
.nf
long	mtype;	/\(** message type \(**/
char	mtext[];	/\(** message text \(**/
.fi
.RE
.PP
.I Mtype
is a positive integer that can be used by the receiving process for
message selection (see
.IR msgrcv " below").
.I Mtext
is any text of length
.I msgsz
bytes.
.I Msgsz
can range from 0 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
.BR msg_qbytes
.RI (see " intro" (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
.RI ( msgflg " & "
.SM
.BR IPC_NOWAIT\*S )
is ``true'', the message will not be sent and the calling process
returns immediately.
.IP
If
.RI ( msgflg " & "
.SM
.BR IPC_NOWAIT\*S )
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
.IR msgctl (2)).
When this occurs,
.I errno
is set equal to
.SM
\%EIDRM\*S,
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
.IR signal (2)).
.RE
.PP
.I Msgsnd
fails and no message is sent if one or more of the following are true:
.TP 15
.SM
\%[EINVAL]
.I Msqid
is not a valid message queue identifier.
.TP
.SM
\%[EACCES]
Operation permission is denied to the calling process (see
.IR intro (2)).
.TP
.SM
\%[EINVAL]
.I Mtype
is less than 1.
.TP
.SM
\%[EAGAIN]
The message cannot be sent for one of the reasons cited above and
.RI ( msgflg " & "
.SM
.BR IPC_NOWAIT\*S )
is ``true''.
.TP
.SM
\%[EINVAL]
.I Msgsz
is less than zero or greater than the system-imposed limit.
.TP
.SM
\%[EFAULT]
.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
.B Msg_qnum
is incremented by 1.
.IP
.B Msg_lspid
is set equal to the process
.SM ID
of the calling process.
.IP
.B Msg_stime
is set equal to the current time.
.PP
.I Msgrcv
reads a message from the queue associated with the message queue identifier
specified by
.IR msqid
and places it in the structure pointed to by
.IR msgp .
.SM {READ}
This structure is composed of the following members:
.PP
.RS
.ta 8n 20n
.nf
long	mtype;	/\(** message type \(**/
char	mtext[];	/\(** message text \(**/
.fi
.RE
.PP
.I Mtype
is the received message's type as specified by the sending process.
.I Mtext
is the text of the message.
.I Msgsz
specifies the size in bytes of
.IR mtext.
The received message is truncated to
.IR msgsz " bytes"
if it is larger than
.I msgsz
and
.RI ( msgflg " &"
.SM
.BR MSG_NOERROR\*S )
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 equal to 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
.RI ( msgflg " & "
.SM
.BR IPC_NOWAIT\*S )
is ``true'', the calling process returns immediately with a return value
of \-1 and
.I errno
set to
.SM
ENOMSG\*S.
.IP
If 
.RI ( msgflg " & "
.SM
.BR IPC_NOWAIT\*S )
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,
.I errno
is set equal to
.SM
\%EIDRM\*S,
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
.IR signal (2)).
.RE
.PP
.I Msgrcv
fails and no message is received if one or more of the following are
true:
.TP 15
.SM
\%[EINVAL]
.I Msqid
is not a valid message queue identifier.
.TP
.SM
\%[EACCES]
Operation permission is denied to the calling process.
.TP
.SM
\%[EINVAL]
.I Msgsz
is less than 0.
.TP
.SM
\%[E2BIG]
Mtext is greater than
.I msgsz
and
.RI ( msgflg " &"
.SM
.BR MSG_NOERROR\*S )
is ``false''.
.TP
.SM
\%[ENOMSG]
The queue does not contain a message of the desired type and
.RI ( msgtyp " & "
.SM
.BR IPC_NOWAIT\*S )
is ``true''.
.TP
.SM
\%[EFAULT]
.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
.B Msg_qnum
is decremented by 1.
.IP
.B Msg_lrpid
is set equal to the process
.SM ID
of the calling process.
.IP
.B Msg_rtime
is set equal to the current time.
.SH RETURN VALUES
.RI If " msgsnd " or " msgrcv"
return due to the receipt of a signal, a value of \-1 is returned to the
calling process and
.I errno
is set to
.SM
\%EINTR\*S.
If they return due to removal of
.I msqid
from the system, a value of \-1 is returned and
.I errno
is set to
.SM
\%EIDRM\*S.
.PP
Upon successful completion, the return value is as follows:
.IP
.I Msgsnd
returns a value of 0.
.IP
.I Msgrcv
returns a value equal to the number of bytes actually placed into
.IR mtext .
.PP
Otherwise, a value of \-1 is returned and
.I errno
is set to indicate the error.
.SH SEE ALSO
intro(2), msgctl(2), msgget(2), signal(2).
.\"	@(#)msgop.2	6.2 of 9/6/83

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.