# OS_SetAlarm

## Syntax

      #include <nitro/os.h>

      void OS_SetAlarm(
                   OSAlarm*       alarm,
                   OSTick         tick,
                   OSAlarmHandler handler,
                   void*          arg );

## Arguments

`alarm` | Pointer to an alarm structure that is initialized for this alarm.
`tick` | Tick count until the alarm goes off (the handler is called).
`handler` | Alarm handler.
`arg` | Argument when the handler is called.

## Return Values

None.

## Description

Sets up a one-time alarm.

A `handler` is called after the tick count that is specified by `tick`. The V-Count alarm handler `handler` is an `OSVAlarmHandler` function defined by the following.

> `typedef void (*OSAlarmHandler)( void* );`

When the `handler` is called, it takes `arg` as an argument. The `handler` argument is passed from the OS timer interrupt handler. Therefore, interrupts are prohibited.

One tick count unit is 1/64 of the hardware system clock.

If `alarm` is specified for the pointer to the `OSAlarm` structure in which the alarm has been set, it stops with `OS_Panic`.

In the following example, by setting an alarm, the `handler` function is called 0.5 seconds later, and "`handler called. arg=0x12345678`" is displayed.

> Example:

>     #define COUNT 　OS_MilliSecondsToTicks( 500 )
>     #define ARG　0x12345678
>     OSAlarm 　alarm;

>     main()
>     {
>     		：
>     	OS_InitTick();
>     	OS_InitAlarm();
>     		：
>     	OS_CreateAlarm( &alarm );
>     	OS_SetAlarm( &alarm, COUNT, handler, (void*)ARG );
>     		:
>     }

>     void handler( void* arg )
>     {
>     	OS_Printf( "handler called. arg=0x%x\n", arg );
>     }

## See Also

`OS_InitAlarm`
`OS_CancelAlarm`
`OS_SetPeriodicAlarm`
`OS_SetAlarmTag`
`OS_*SecondsToTicks`

## Revision History

2005/03/08 Standardized the use of the term "interrupt" in Japanese.
2004/12/22 Added a statement about the alarm handler's being called from the timer interrupt handler.
2004/08/30 Added a statement about not being able to use the set alarm structure.
2004/02/25 Changed `systemClock` to `tick`.
2004/02/04 Initial version.

CONFIDENTIAL