# OS_PollEvent*

## Syntax

      #include <nitro/os.h>

      u32 OS_PollEvent( OSEvent* event,
                            u32 pattern,
                            OSEventMode mode );

      u32 OS_PollEventEx( OSEvent* event,
                            u32 pattern,
                            OSEventMode mode,
                            u32 clearBit );

      (Inline functions)
      static inline
      u32 OS_PollEvent_And( OSEvent* event,
                               u32 pattern );

      static inline
      u32 OS_PollEvent_Or( OSEvent* event,
                               u32 pattern );

      static inline
      u32 OS_PollEventEx_And( OSEvent* event,
                               u32 pattern,
                               u32 clearBit );

      static inline
      u32 OS_PollEventEx_Or( OSEvent* event,
                               u32 pattern,
                               u32 clearBit );

## Arguments

event | Pointer to an event structure.
pattern | Event flag bit pattern. Takes the form of the pattern that ends waiting for events.
mode | Matching mode. Indicates the event flag bit pattern's conditions for conformance.
clearBit | Bits to clear from the event flag after the conditions are fulfilled.

## Return Values

If 0, indicates that the conditions have not been met.
A nonzero value indicates that the conditions are met, and it will be the value of the event flag. If clearBit is specified, this function will return the value of the event flag before the bits were cleared.

## Description

Finds out whether the event structure meets the completion conditions that have been set for waiting for events.

event is a pointer to an event structure. This event argument is is initialized by `OS_InitEvent()` and is used to have threads wait for events. In the `OS_PollEvent*` functions, it is also used to find out whether the event completion conditions have been met.

Unlike the function to wait for events (`OS_WaitEvent*()`), control will return from this function immediately regardless of whether the event completion conditions are met. Thread functions are not called, so the system will not switch threads.

The completion conditions are indicated by pattern and mode. For more information, see `OS_WaitEvent*()`.

Returns a nonzero event flag value if the completion conditions have been met, and returns 0 if the conditions have not been met.

In `OS_PollEventEx()`, when the completion conditions have been met, the bits indicated in clearBit will be cleared from the event flag. The return value will be the value of the event flag before it is cleared.

`OS_PollEvent_And( event, pattern )` is the same as `OS_PollEvent( event, pattern, OS_EVENT_MODE_AND )`.

`OS_PollEvent_Or( event, pattern )` is the same as `OS_PollEvent( event, pattern, OS_EVENT_MODE_OR )`.

`OS_PollEventEx_And( event, pattern, clearBit )` is the same as `OS_PollEventEx( event, pattern, OS_EVENT_MODE_AND, clearBit )`.

`OS_PollEventEx_Or( event, pattern, clearBit )` is the same as `OS_PollEventEx( event, pattern, OS_EVENT_MODE_OR, clearBit )`.

## See Also

`OS_InitEvent, OS_WaitEvent*, OS_SignalEvent, OS_Clear*Event, OS Overview (Events)
`

## Revision History

2007/12/04 Initial version.

CONFIDENTIAL