sd_event_add_time

Index · Directives · Python · libudev · gudev systemd 220

## Name

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

## Synopsis

    #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)