msgrcv(2) DG/UX R4.11MU05 msgrcv(2)
NAME
msgrcv - receive a message
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg)
int msqid;
void *msgp;
sizet msgsz;
long msgtyp;
int msgflg;
where:
msqid A message queue identifier
msgp A buffer for the message
msgsz The size in bytes of the message to be received
msgtyp Message type
msgflg A set of flags qualifying the action of msgrcv
DESCRIPTION
Msgrcv reads a message from the queue associated with the message
queue identifier specified by msqid and places it in the message
buffer pointed to by msgp.
Msgtyp is used to select from other queued messages; msgsz bytes of
such a message (only a single message, if any, is selected in a call
to this routine) are returned.
If the received message is larger than msgsz and the MSG_NOERROR bit
of msgflg is set, the received message is truncated to msgsz bytes.
The truncated part of the message is lost and no indication of the
truncation is given to the calling process. If the received message
is larger than msgsz and the MSG_NOERROR bit of msgflg is clear, an
error is returned.
Msgtyp specifies the type of message requested as follows:
· msgtyp == 0: The first message on the queue is received.
· msgtyp > 0: The first message of type msgtyp is received.
· msgtyp < 0: The first message of the lowest type of all
messages on the queue is received provided the type is less
than or equal to the absolute value of msgtyp.
Msgflg specifies the action to be taken if a message of the desired
type is not on the queue. These are as follows:
· If the IPC_NOWAIT bit of msgflg is set, the calling process
will return immediately.
· If the IPC_NOWAIT bit of msgflg is clear, the calling process
will be suspended until:
· A message of the desired type is placed on the queue, in which
case, the operation is successful,
· msqid is removed from the system, in which case, msgrcv will
return with the error condition EIDRM, or
· The calling process receives a signal that is to be caught, in
which case, msgrcv will return with the error condition EINTR.
If msgrcv fails, the message queue will be unchanged. Upon
successful completion, the message queue attributes are changed as
follows:
· The number of messages on the queue (msg_qnum) is decremented.
· The number of bytes on the queue (msg_cbytes) is reduced by
the size of the mtext portion of the received message.
· The process id of the last process performing a msgrcv
operation (msg_lrpid) is set to that of the calling process.
· The most recent time a msgrcv operation was performed
(msg_rtime) is set to the current time.
ACCESS CONTROL
Read access to the message queue is required.
RETURN VALUE
actualsize Completed successfully. The number of bytes actually
placed into mtext.
-1 An error occurred. errno is set to indicate the
error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EINVAL msqid is not a valid message queue identifier.
EACCES Read permission is denied to the calling process.
EINVAL msgsz is less than 0.
E2BIG msgp-mtext> is greater than msgsz and the MSG_NOERROR bit
of msgflg is not set.
ENOMSG The queue does not contain a message of the desired type
and the IPC_NOWAIT bit of msgflg is set.
EFAULT msgp points to an illegal address.
EIDRM msqid was removed from the system while the calling process
was suspended by msgrcv.
EINTR The calling process received a signal that was set to be
caught while suspended by msgrcv.
SEE ALSO
intro(2), ipcrm(1), ipcs(1), msgctl(2), msgget(2), msgsnd(2),
signal(2).
Licensed material--property of copyright holder(s)