[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 1
msgxrcv Subroutine
Purpose
Receives an extended message.
Library
Standard C Library (libc.a)
Syntax
For releases prior to AIX 4.3:
#include <sys/msg.h>
int msgxrcv (MessageQueueID, MessagePointer, MessageSize, MessageType, MessageFlag)
int MessageQueueID, MessageFlag, MessageSize;
struct msgxbuf * MessagePointer;
long MessageType;
For AIX 4.3 and later releases:
#include <sys/msg.h>
int msgxrcv (MessageQueueID, MessagePointer, MessageSize, MessageType, MessageFlag)
int MessageQueueID, MessageFlag;
size_t MessageSize;
struct msgxbuf
* MessagePointer;
long MessageType;
Description
The msgxrcv subroutine reads a message from the
queue specified by the MessageQueueID parameter and
stores it into the extended message receive buffer pointed to by the MessagePointer parameter. The current process must have
read permission in order to perform this operation. The msgxbuf structure is defined in the sys/msg.h
file.
Note
The routine may coredump instead of returning EFAULT when
an invalid pointer is passed in case of 64-bit application calling 32-bit
kernel interface.
The following limits apply to the message queue:
- Maximum message size is 65,535 bytes for releases prior
to AIX 4.1.5 and is 4 Megabytes for AIX 4.1.5 and later releases.
- Maximum number of messages per queue is 8192.
- Maximum number of message queue IDs is 4096 for releases
before AIX 4.3.2 and 131072 for AIX 4.3.2 and following.
- Maximum number of bytes in a queue is 4 65,535 for releases
prior to AIX 4.1.5 and is 4 Megabytes for AIX 4.1.5 later releases.
Note
For a 64-bit process, the mtype field
is 64 bits long. However, for compatibility with 32-bit processes, the mtype field must be a 32-bit signed value that is sign-extended
to 64 bits. The most significant 32 bits are not put on the message queue.
For a 64-bit process, the mtype field is again sign-extended
to 64 bits.
Parameters
MessageQueueID |
Specifies the message queue identifier. |
MessagePointer |
Specifies a pointer to an extended message receive buffer where a
message is stored. |
MessageSize |
Specifies the size of the mtext field
in bytes. The receive message is truncated to the size specified by the MessageSize parameter if it is larger than the MessageSize parameter and the MSG_NOERROR value
is true. 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
the number of bytes specified by the MessageSize parameter
and the MSG_NOERROR value is not set, the msgxrcv subroutine is unsuccessful and sets the errno global variable to the E2BIG error code. |
MessageType |
Specifies the type of message requested as follows:
- If the MessageType parameter is
equal to 0, the first message on the queue is received.
- If the MessageType parameter
is greater than 0, the first message of the type specified by the MessageType parameter is received.
- If the MessageType parameter
is less than 0, the first message of the lowest type that is less than or
equal to the absolute value of the MessageType parameter
is received.
|
MessageFlag |
Specifies a value of 0 or a value constructed by logically ORing
one or more of the following values:
- MSG_NOERROR
- Truncates the message if it is longer than the number of bytes specified
by the MessageSize parameter.
- IPC_NOWAIT
- Specifies the action to take if a message of the desired type is not
on the queue:
- If the IPC_NOWAIT value is set, the
calling process returns a value of -1 and sets the errno global variable to the ENOMSG error code.
- If the IPC_NOWAIT value is not
set, 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 specified by the MessageQueueID parameter is removed from the system. When
this occurs, the errno global variable is set to the EIDRM error code, 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 the sigaction subroutine.
|
Return Values
Upon successful completion, the msgxrcv subroutine returns a value equal to the number of bytes actually
stored into the mtext field, and the following
actions are taken with respect to the data structure associated with the MessageQueueID parameter:
- The msg_qnum field is decremented
by 1.
- The msg_lrpid field is set equal
to the process ID of the calling process.
- The msg_rtime field is set equal
to the current time.
If the msgxrcv subroutine is
unsuccessful, a value of -1 is returned and the errno
global variable is set to indicate the error.
Error Codes
The msgxrcv subroutine is unsuccessful
if any of the following conditions is true:
EINVAL |
The MessageQueueID parameter is not a valid
message queue identifier. |
EACCES |
The calling process is denied permission for the specified operation. |
EINVAL |
The MessageSize parameter is less than 0. |
E2BIG |
The mtext field is greater than the MessageSize parameter, and the MSG_NOERROR value is not set. |
ENOMSG |
The queue does not contain a message of the desired type and the IPC_NOWAIT value is set. |
EFAULT |
The MessagePointer parameter points outside
of the process address space. |
EINTR |
The msgxrcv subroutine was interrupted by a
signal. |
EIDRM |
The message queue identifier specified by the MessageQueueID parameter is removed from the system. |
Related Information
The msgctl (msgctl Subroutine)
subroutine, msgget (msgget Subroutine) subroutine, msgrcv (msgrcv Subroutine) subroutine, msgsnd (msgsnd Subroutine) subroutine, sigaction subroutine.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]