# OS_ReadMessage

## Syntax

      #include <nitro/os.h>

      BOOL OS_ReadMessage(
           OSMessageQueue*   mq,
           OSMessage*        msg,
           s32             flags);

## Arguments

mq | Pointer to the message queue
msg | Viewed message
flags | If `OS_MESSAGE_BLOCK` is set up, `OS_ReceiveMessage` blocks empty queues. If `OS_MESSAGE_NOBLOCK` is set up, `OS_ReceiveMessage` returns immediately whether or not the queue is empty.

## Return Values

Returns `TRUE` if the message was removed without any problems. If `OS_MESSAGE_NOBLOCK` was specified and the queue was empty, FALSE is returned.

## Description

Copies the starting message of the message queue The status of the message queue does not change. This function differs from `OS_ReceiveMessage()` in that a wait status thread is not activated to send a message to this queue. In a manner of speaking, `OS_ReadMessage()` is a function for looking at the starting message of the message queue.

If `OS_MESSAGE_BLOCK` is set in `flags`, the thread that called this function will be suspended if the queue is empty. The thread resumes immediately when message(s) are sent to the queue. If there are other receiving threads with higher priority, those are executed first, so be aware of the fact that they may remove the messages. If the message queue is empty when this thread comes to be executed, it will suspend again until another message is sent to the queue.

If `OS_MESSAGE_NOBLOCK` is set in `flags`, control immediately returns to the calling thread. If the queue is not empty, `TRUE` is returned. If it is empty, `FALSE` is returned.

## See Also

`OS_InitMessageQueue`, `OS_SendMessage`, `OS_ReceiveMessage`

## Revision History

2004/03/12 Initial version.

CONFIDENTIAL