 |
Index for
Section 2 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
msgrcv(2)
NAME
msgrcv - Receive a message from a message queue
SYNOPSIS
#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.
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.
PARAMETERS
msqid
Specifies the ID of the message queue from which to receive the
message.
msgp
Specifies a pointer to the msgbuf structure that is to receive the
message. See the NOTES section for more information.
msgsz
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.
msgtyp
Specifies the message type to read from the queue.
msgflg
Specifies the action to be taken by the kernel if there are no msgtyp
messages on the queue.
DESCRIPTION
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:
0 (zero)
The process receives the message at the head of the queue.
Greater than 0 (zero)
The process receives the first message of the requested positive-
integer type.
Less than 0 (zero)
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.
NOTES
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().
RETURN VALUES
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.
ERRORS
The msgrcv() function sets errno to the specified values for the following
conditions:
[E2BIG]
The number of bytes to be received in mtext is greater than msgsz and
the MSG_NOERROR flag is not set.
[EACCES]
The calling process does not have permission for the operation.
[EFAULT]
Indicates that the requested address is in some way invalid, for
example, out of bounds.
[EIDRM]
The message queue identified by the msqid parameter has been removed
from the system.
[EINTR]
The operation was interrupted by a signal.
[EINVAL]
The msqid parameter is not a valid message queue ID.
[ENOMSG]
The queue does not contain a message of the requested type and the
IPC_NOWAIT flag is set.
SEE ALSO
Functions: msgctl(2), msgget(2), msgsnd(2), sigaction(2)
Data Structures: msqid_ds(4)
Standards: standards(5)
|
Index for
Section 2 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|