msgrcv(2)
_________________________________________________________________
msgrcv System Call
Receive a message.
_________________________________________________________________
SYNTAX
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgrcv (id, user_msg_ptr, size, type, flag)
int id;
struct msgbuf * user_msg_ptr;
int size;
long type;
int flag;
PARAMETERS
id A message queue identifier.
user_msg_ptr A buffer for the message.
size The size in bytes of the message to be received.
type Message type.
flag 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 <id> and places it in the message
buffer pointed to by <user_msg_ptr>.
<type> is used to select from other queued messages; <size> 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 <size> and the MSG_NOERROR
bit of <flag> is set, the received message is truncated to <size>
bytes. The truncated part of the message is lost and no
indication of the truncation is given to the calling process. If
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
msgrcv(2)
the received message is larger than <size> and the MSG_NOERROR
bit of <flag> is clear, an error is returned.
<type> specifies the type of message requested as follows:
* type == 0: The first message on the queue is received.
* type > 0: The first message of type <type> is received.
* type < 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 <type>.
<Flag> 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 <flag> is set, the calling process
will return immediately.
* If the IPC_NOWAIT bit of <flag> 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,
* <id> 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
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
msgrcv(2)
Read access to the message queue is required.
RETURN VALUE
<actual_size> Completed successfully. The number of bytes
actually placed into mtext.
-1 An error occurred. Errno is set to indicate the
error.
EXCEPTIONS
Errno may be set to one of the following error codes:
EINVAL <id> is not a valid message queue identifier.
EACCES Read permission is denied to the calling process.
EINVAL <size> is less than 0.
E2BIG <user_msg_ptr->mtext> is greater than <size> and
the MSG_NOERROR bit of <flag> is not set.
ENOMSG The queue does not contain a message of the
desired type and the IPC_NOWAIT bit of <flag> is
set.
EFAULT <user_msg_ptr> points to an illegal address.
EIDRM <id> 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
The related system calls: msgctl, msgget, msgsnd, signal.
The related manual section: intro(2).
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)