# OS_ReadMessage

## C Specification

      #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 up in `flags`, the thread that called this function will be paused if the queue is empty. The thread resumes once the message is sent to the queue. If another receiving thread with a higher priority is present, those threads are executed first so be aware of the point at which messages are removed. If the message queue is empty when this thread is executed, it will be paused again until another message is sent to the queue.

If `OS_MESSAGE_NOBLOCK` is set up in `flags`, the process immediately returns to the thread that was called. 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

03/12/2004 Initial Version

CONFIDENTIAL