msgrcv Subroutine

Purpose

Reads a message from a queue.

Library

Standard C Library (libc.a)

Syntax

#include <sys/msg.h>
int msgrcv (MessageQueueID, MessagePointer,MessageSize,MessageType, MessageFlag)
int  MessageQueueID,  MessageFlag;
void * MessagePointer;
size_t  MessageSize;
long int  MessageType;

Description

The msgrcv subroutine reads a message from the queue specified by the MessageQueueID parameter and stores it into the structure pointed to by the MessagePointer parameter. The current process must have read permission in order to perform this operation.

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.

Limits on message size and number of messages in the queue can be found in General Programming Concepts: Writing and Debugging Programs.

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

Item Description
MessageQueueID Specifies the message queue identifier.
MessagePointer Points to a msgbuf structure containing the message. The msgbuf structure is defined in the sys/msg.h file and contains the following fields: 
mtyp_t   mtype;        /* Message type */
char     mtext[1];     /* Beginning of message text */

The mtype field contains the type of the received message as specified by the sending process. The mtext field is the text of the message.
MessageSize Specifies the size of the mtext field in bytes. The received message is truncated to the size specified by the MessageSize parameter if it is longer than the size specified by the MessageSize parameter and if the MSG_NOERROR value is set in the MessageFlag parameter. The truncated part of the message is lost and no indication of the truncation is given to the calling process.
MessageType Specifies the type of message requested as follows:
  • If equal to the value of 0, the first message on the queue is received.
  • If greater than 0, the first message of the type specified by the MessageType parameter is received.
  • If 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 either a value of 0 or is constructed by logically ORing one or more of the following values:
MSG_NOERROR
Truncates the message if it is longer than 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 described in the sigaction subroutine.

Return Values

Upon successful completion, the msgrcv 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 fields of 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 msgrcv subroutine is unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The msgrcv subroutine is unsuccessful if any of the following conditions is true:

Item Description
EINVAL The MessageQueueID parameter is not a valid message queue identifier.
EACCES The calling process is denied permission for the specified operation.
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 allocated address space of the process.
EINTR The msgrcv subroutine is interrupted by a signal.
EIDRM The message queue identifier specified by the MessageQueueID parameter has been removed from the system.