sd_event_add_time

systemd
Developer Lennart Poettering lennart@poettering.net
sd_event_add_time 3
sd_event_add_time sd_event_source_get_time sd_event_source_set_time sd_event_source_get_time_accuracy sd_event_source_set_time_accuracy sd_event_source_get_time_clock Add a timer event source to an event loop

    #include <systemd/sd-bus.h>

int `sd_event_add_time` sd_event *event sd_event_source **source clockid_t clock uint64_t usec uint64_t accuracy sd_event_time_handler_t handler void *userdata typedef int (*`sd_event_time_handler_t`) sd_event_source *s uint64_t usec void *userdata int `sd_event_source_get_time` sd_event_source *source usec_t *usec int `sd_event_source_set_time` sd_event_source *source usec_t usec int `sd_event_source_get_time_accuracy` sd_event_source *source usec_t *usec int `sd_event_source_set_time_accuracy` sd_event_source *source usec_t usec int `sd_event_source_get_time_clock` sd_event_source *source clockid_t *clock

## Description

`sd_event_add_time()` adds a new timer event source to an event loop object. The event loop is specified in event, the event source is returned in the source parameter. The clock parameter takes a clock identifier, one of `CLOCK_REALTIME`, `CLOCK_MONOTONIC` and `CLOCK_BOOTTIME_ALARM`. See timerfd_create 2 for details regarding the various types of clocks. The usec parameter takes a time value in microseconds, relative to the clock's epoch specifying when the timer shall elapse the earliest. The accuracy parameter takes an additional accuracy value in microseconds specifying a time the timer event may be delayed. Specify 0 for selecting the default accuracy (250ms). Specify 1 for most accurate timers. Consider specifying 60000000 or larger (1h) for long-running events that may be delayed substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, thus improving power efficiency. The handler shall reference a function to call when the timer elapses. The handler function will be passed the userdata pointer, which may be chosen freely by the caller. The handler is also passed the configured time it was triggered, however it might actually have been called at a slightly later time, subject to the specified accuracy value, the kernel timer slack (see prctl 2) and additional scheduling latencies.

By default, the timer will elapse once (`SD_EVENT_ONESHOT`), but this may be changed with sd_event_source_set_enabled 3. If the handler function returns a negative error code, it will be disabled after the invocation, even if `SD_EVENT_ON` mode is set.

`sd_event_source_get_time()` retrieves the configured time value of a timer event source created previously with `sd_event_add_time()`. It takes the event source object and a pointer to a variable to store the time in microseconds in.

`sd_event_source_set_time()` changes the configured time value of a timer event source created previously with `sd_event_add_time()`. It takes the event source object and a time relative to the selected clock's epoch, in microseconds.

`sd_event_source_get_time_accuracy()` retrieves the configured accuracy value of a timer event source created previously with `sd_event_add_time()`. It takes the event source object and a pointer to a variable to store the accuracy in microseconds in.

`sd_event_source_set_time_accuracy()` changes the configured accuracy of a timer event source created previously with `sd_event_add_time()`. It takes the event source object and an accuracy, in microseconds.

`sd_event_source_get_time_clock()` retrieves the configured clock of a timer event source created previously with `sd_event_add_time()`. It takes the event source object and a pointer to a variable to store the clock identifier in.

## Return Value

On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code.

## Errors

Returned errors may indicate the following problems:

`-ENOMEM`

  Not enough memory to allocate an object.

`-EINVAL`

  An invalid argument has been passed.

`-ESTALE`

  The event loop is already terminated.

`-ECHILD`

  The event loop has been created in a different process.

`-EOPNOTSUPP`

  The selected clock is not supported by the event loop implementation.

## Notes

`sd_event_add_time()` and the other functions described here are available as a shared library, which can be compiled and linked to with the `libsystemd` pkg-config 1 file.

## See Also

systemd 1, sd-event 3, sd_event_new 3, sd_event_add_signal 3, sd_event_add_child 3, sd_event_add_defer 3, clock_gettime 2, sd_event_source_set_enabled 3