msgxrcv
Purpose
Receives an extended message.
Syntax
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgxrcv (msqid, msgp, msgsz, msgtyp, msgflg)
int msqid;
struct msgxbuf *msgp;
int msgsz, msgflg;
long msgtyp;
Description
The msgxrcv system call reads a message from the queue
specified by the msqid parameter and stores it into the
extended message receive buffer pointed to by the msgp
parameter. The current process must have read permission
in order to perform this operation. The msgxbuf struc-
ture is defined in the sys/msg.h header file, and it con-
tains the following members:
time_t mtime; /* Time and date message was sent */
short muid; /* Sender's effective user ID */
short mgid; /* Sender's effective group ID */
long mnid; /* Sender's node ID */
short mpid; /* Sender's process ID */
long mtype; /* Message type */
char mtext[1]; /* Beginning of message text */
The msgsz parameter specifies the size of mtext in bytes.
The receive message is truncated to the size specified by
the msgsz parameter if it is larger than the msgsz param-
eter and MSG_NOERROR is true. The truncated part of the
message is lost and no indication of the truncation is
given to the calling process.
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 larger 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 prescribed
in "signal."
If Distributed Services is installed on your system, the
msgxrcv call works with both local and remote queues.
Return Value
Upon successful completion, msgxrcv 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 msgxrcv system call fails, a value of -1 is
returned and errno is set to indicate the error.
Diagnostics
The msgxrcv 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 msgxrcv received a signal.
EIDRM The message queue identifier specified by
msqid is removed from the system.
If Distributed Services is installed on your system,
msgxrcv 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," and "msgrcv."