msgrcv - Receive a message from a message queue
#include <sys/msg.h>
ssize_t msgrcv(
int msqid,
void *msgp,
size_t msgsz,
long msgtyp,
int msgflg );
Application developers may want to specify #include statements
for <sys/types.h> and <sys/ipc.h> before the one for
<sys/msg.h> if programs are being developed for multiple
platforms. The additional #include statements are not
required on Tru64 UNIX systems or by ISO or XSH standards,
but may be required on other vendors' systems that conform
to these standards.
Interfaces documented on this reference page conform to
industry standards as follows:
msgrcv(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the ID of the message queue from which to
receive the message. Specifies a pointer to the msgbuf
structure that is to receive the message. See the NOTES
section for more information. Specifies the maximum number
of bytes allowed for the received data. The msgsz
parameter is only used to specify the size of the msgbuf.mtext
field. It cannot include the msgbuf.mtype field
or else the msgbuf buffer is overwritten. Specifies the
message type to read from the queue. Specifies the action
to be taken by the kernel if there are no msgtyp messages
on the queue.
The msgrcv() function receives a message from the queue
associated with the msqid parameter. The function returns
the number of bytes in the received message.
The msgp parameter points to a user-defined msgbuf structure.
This structure receives the message read from the
queue.
The msgsz parameter specifies the maximum size allowed for
the received data. If the message is longer than msgsz,
the following occurs, depending upon the setting of the
MSG_NOERROR flag: If MSG_NOERROR is not set, the kernel
returns an [E2BIG] error to the calling process and leaves
the message on the queue. If MSG_NOERROR is set, the kernel
truncates the message to msgsz and discards the truncated
portion without notifying the calling process.
The msgtyp parameter specifies the message type that the
process expects to receive. Possible values and their
results are as follows: The process receives the message
at the head of the queue. The process receives the first
message of the requested positive-integer type. The process
receives the first message of the lowest type on the
queue. To qualify as the lowest type, the negative-integer
type must be less than or equal to the absolute value of
msgtyp.
The msgflg parameter specifies the action that the kernel
should take if the queue does not contain a message of the
requested type. Either of two kernel actions can be specified,
as follows: If IPC_NOWAIT is set, the function
returns immediately with a return value of (ssize_t)-1 and
sets errno to [ENOMSG]. If IPC_NOWAIT is not set, the
kernel suspends the calling process.
The process remains suspended until one of the following
occurs: A message of the requested type
appears on the queue. In this case, the kernel
wakes the process to receive the message. The
specified message queue ID is removed from the system.
In this case, the kernel sets errno to
[EIDRM] and returns (ssize_t)-1 to the calling process.
The process catches a signal. In this case,
the process does not receive the message and,
instead, resumes execution as directed by the
sigaction() call.
The parameter msgp points to a user-specified buffer that
must contain first a field of type long int that specifies
the type of the message, and then a data portion that
holds the data bytes of the message. For example:
struct msgbuf {
long int mtype;
char mtext[]; }
The mytpe field is set to the message type supplied by the
sender.
The mtext field is set to the message text. Unless
MSG_NOERROR is set, the message size will be less than or
equal to the msgsz specified on the call to msgrcv().
Upon successful completion, the msgrcv() function returns
a value equal to the number of bytes actually stored in
mtext. Also, the kernel updates the msqid_ds structure
associated with the message queue ID as follows: Decrements
msg_qnum by 1. Sets msg_lrpid equal to the process
ID of the calling process. Sets msg_rtime equal to the
current time. [Tru64 UNIX] Decrements msg_cbytes by the
message text size.
When the msgrcv() function fails, it returns a value of
(ssize_t)-1 and sets errno to indicate the error.
The msgrcv() function sets errno to the specified values
for the following conditions: The number of bytes to be
received in mtext is greater than msgsz and the MSG_NOERROR
flag is not set. The calling process does not have
permission for the operation. Indicates that the
requested address is in some way invalid, for example, out
of bounds. The message queue identified by the msqid
parameter has been removed from the system. The operation
was interrupted by a signal. The msqid parameter is not a
valid message queue ID. The queue does not contain a message
of the requested type and the IPC_NOWAIT flag is set.
Functions: msgctl(2), msgget(2), msgsnd(2), sigaction(2)
Data Structures: msqid_ds(4)
Standards: standards(5)
msgrcv(2)
[ Back ] | 