# OS_SetAlarm

## C Specification

      #include <nitro/os.h>

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

## Arguments

alarm | Pointer to an alarm structure that will be initialized for this alarm.
tick | The tick count until the alarm is actuated (the handler is called).
handler | The alarm handler.
arg | The argument when the handler is called.

## Return Values

None.

## Description

This function sets up a one-shot alarm.

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

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

When the `handler` is called, it takes `arg` as an argument. `handler` is called 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 the alarm, the `handle` is called 0.5 seconds later, and then "`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

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

CONFIDENTIAL