msgxrcv Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

msgxrcv Subroutine

Purpose

Receives an extended message.

Library

Standard C Library (libc.a)

Syntax

For releases prior to AIX 4.3.0:

#include <sys/msg.h>

int msgxrcv (MessageQueueID, MessagePointer, MessageSize, MessageType, MessageFlag) int MessageQueueID, MessageFlag, MessageSize; struct msgxbuf *MessagePointer; long MessageType;

For AIX 4.3.0 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 release 4.1.5 and later releases.
Maximum number of messages per queue is 8192.
Maximum number of message queue IDs is 4096 for AIX releases before 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 release 4.1.5 and later releases.

Note: For a 64-bit process, the mtype field is 64 bits long. However, for compatibility with 32-bit processes, the most significant 32 bits must be 0 and will not be put on the message queue. For a 64-bit receiver process, the mtype will again be extended to 64 bits with the most significant bits 0.

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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The msgctl subroutine, msgget subroutine, msgrcv subroutine, msgsnd subroutine, sigaction subroutine.