msgrcv
Purpose
Reads a message from a queue.
Syntax
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg)
int msqid;
struct msgbuf *msgp;
int msgsz;
long msgtyp;
int msgflg;
Description
The msgrcv system call reads a message from the queue
specified by the msqid parameter and stores it into the
structure pointed to by the msgp parameter. The current
process must have read permission in order to perform
this operation. The msgbuf structure is defined in the
sys/msg.h header file, and it contains the following
members:
long mtype; /* Message type */
char mtext[1]; /* Beginning of message text */
The mtype field contains the type of the received message
as specified by the sending process. mtext is the text
of the message. If Distributed Services is installed on
your system, messages can be received from either local
or remote queues (see "msgsnd").
The msgsz parameter specifies the size of mtext in bytes.
The received message is truncated to the size specified
by the msgsz parameter if it is longer than the size
specified by the msgsz parameter and if MSG_NOERROR is
set in msgflg. The truncated part of the message is lost
and no indication of the truncation is given to the
calling process. If the message is longer than msgsz
bytes and MSG_NOERROR is not set, then the msgrcv system
call fails and sets errno to E2BIG.
The msgtyp parameter specifies the type of message
requested as follows:
o If the msgtyp parameter is equal to 0, the first
message on the queue is received.
o If the msgtyp parameter is greater than 0, the first
message of the type specified by the msgtyp parameter
is received.
o If the msgtyp parameter is less than 0, the first
message of the lowest type that is less than or equal
to the absolute value of the msgtyp parameter is
received.
The msgflg parameter is either 0, or is constructed by
logically OR-ing one or more of the following values:
MSG_NOERROR Truncates the message if it is longer than
msgsz bytes.
IPC_NOWAIT Specifies the action to take if a message
of the desired type is not on the queue:
o If IPC_NOWAIT is set, then the calling
process returns a value of -1 and sets
errno to ENOMSG.
o If IPC_NOWAIT is not set, then the
calling process suspends execution
until one of the following occurs:
- A message of the desired type is
placed on the queue.
- The message queue identifier spec-
ified by the msqid parameter is
removed from the system. When
this occurs, errno is set to
EIDRM, and a value of -1 is
returned.
- The calling process receives a
signal that is to be caught. In
this case, a message is not
received and the calling process
resumes in the manner described in
"signal."
Return Value
Upon successful completion, msgrcv returns a value equal
to the number of bytes actually stored into mtext and the
following actions are taken with respect to the data
structure associated with the msqid parameter:
o msg_qnum is decremented by 1.
o msg_lrpid is set equal to the process ID of the
calling process.
o msg_rtime is set equal to the current time.
If the msgrcv system call fails, a value of -1 is
returned and errno is set to indicate the error.
Diagnostics
The msgrcv system call fails if one or more of the fol-
lowing are true:
EINVAL msqid is not a valid message queue identifier.
EACCES Operation permission is denied to the calling
process.
EINVAL msgsz is less than 0.
E2BIG mtext is greater than msgsz and MSG_NOERROR is
not set.
ENOMSG The queue does not contain a message of the
desired type and IPC_NOWAIT is set.
EFAULT The msgp parameter &pointsout..
EINTR msgrcv received a signal.
EIDRM The message queue identifier specified by
msqid has been removed from the system.
If Distributed Services is installed on your system,
msgrcv can also fail if one or more of the following are
true:
ESTALE The current boot count of the server is the
same as when the msqid was obtained.
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EDIST The server has a release level of Distrib-
uted Services that cannot communicate with
this node.
EAGAIN The server is too busy to accept the
request.
EPERM The translate tables of the server did not
contain any entry for either the effective
user ID or effective group ID of the
calling process.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
ENOCONNECT An attempt to establish a new network con-
nection with a remote node failed.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "msgctl," "msgget," "msgsnd," "msgxrcv,"
and "signal."