# include/sys/time.h File Reference

`#include <event.h>`

## Data Structures
struct | timeval
struct | itimerval
## Defines
#define | _TIME_H 1
## Typedefs
typedef struct timeval | timeval_t
typedef struct itimerval | itimerval_t
## Functions
int16_t | gettimeofday (struct timeval *tv)
int16_t | settimeofday (const struct timeval *tv)
int16_t | timer ()
int16_t | gettitimer (int16_t timerid, itimerval_t *value)
int16_t | setitimer (int16_t timerid, const itimerval_t *value, itimerval_t *old_value, void(*timer_handler)(event_t event, void *cbargs, void *context), void *resource, void *context)

## Define Documentation

#define _TIME_H 1

## Typedef Documentation

typedef struct itimerval itimerval_t

typedef struct timeval timeval_t

## Function Documentation

int16_t gettimeofday | ( | struct timeval * | tv | ) |

A system call to access time of day.

Precondition:
  Do not call this inside the interrupt handler context.

Postcondition:
  If successful, tv contains the system's time of day.

Parameters:

  `[out]` | tv | system fills the time value structure with system's time of the day.

Returns:
  0 if succeed or -1 if fail and errno is set appropriately.

Errors:
  ENOTTIMESYNC suggests the returned time value is not synchronized.

int16_t gettitimer | ( | int16_t | timerid,
|  | itimerval_t * | value |
| ) |  |  |

Get value of an interval timer.

Parameters:

  `[in]` | timerid | a valid timer id return by timer()
  `[out]` | value | to get the value of the timer

Returns:
  0 if succeed or -1 if fail and errno is set appropriately.

Errors:
  EINVAL if invalid parameters are passed

int16_t setitimer | ( | int16_t | timerid,
|  | const itimerval_t * | value,
|  | itimerval_t * | old_value,
|  | void(*)(event_t event, void *cbargs, void *context) | timer_handler,
|  | void * | resource,
|  | void * | context |
| ) |  |  |

Set the value of an interval timer. Setting the value to zero means stopping the current timer.

Parameters:

  `[in]` | timerid | a valid timer id return by timer().
  `[in]` | value | new interval timer value
  `[out]` | old_value | if old timer interval is not zero, it will copied into old_value. Pass NULL if don't care.
  `[in]` | timer_handler | the continuation callback handler that will be fired when value becomes zero. If NULL is passed here, the call will fail.
  `[in]` | resource | no requirement here.
  `[in]` | context | user context

Returns:
  0 if succeed or -1 if fail and errno is set appropriately.

Errors:
  EBUSY if the resource with timerid is busy

  EINVAL if invalid parameters are passed

## Callback Descriptions

### timer_handler

Parameters:

  `[in]` | event | Type is SETITIMER in EventsEnum.
  `[in]` | cbargs | return resource in setitimer().
  `[in]` | context | return context in setitimer().

Returns:
  None.

int16_t settimeofday | ( | const struct timeval * | tv | ) |

A system call to set system's time of day.

Precondition:
  Do not call this inside the interrupt handler context.

Postcondition:
  If successful, system's time of day will be set to that specified in tv.

Parameters:

  `[in]` | tv | the time value structure that the system will take as time of day.

Returns:
  0 if succeed or -1 if fail and errno is set appropriately.

Errors:
  EINVAL invalid argument

int16_t timer | ( |  | ) |

Request a unique resource identifier that enables scheduling timers.

Returns:
  a non-zero resource identifiier if succeed or -1 if fail and errno is set appropriately.

Errors:
  ENFILE all unique resource identifier has been used up