# OS_SetAlarm

## C Specification

      #include <nitro/os.h>

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

## Description

This function sets up a one-shot alarm.

A `handler` is called after the tick count that is specified by `tick`. The `handler` is an `OSAlarmHandler` function type defined as the following.

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

When the `handler` is called, it takes `arg` as an argument. 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 );
> }`

## Arguments

`alarm` | Pointer to the alarm structure that sets up an 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

## See Also

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

## Revision History

08/30/2004 Added the description that the alarm structure that has been set is not usable.
02/25/2004 Changed systemClock->tick
02/04/2004 Initial Version