From b408026b9899c1f9d155ac6d9f7bdc7f5cd3defb Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 6 May 2014 18:51:08 +0200 Subject: man: document sd_event_add_time(3) --- man/sd_event_add_time.xml | 245 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 man/sd_event_add_time.xml (limited to 'man/sd_event_add_time.xml') diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml new file mode 100644 index 000000000..9af8bb9c4 --- /dev/null +++ b/man/sd_event_add_time.xml @@ -0,0 +1,245 @@ + + + + + + + + + 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 + + + + 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_create2 + 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 + prctl2) + and additional scheduling latencies. By default the timer will + elapse once (SD_EVENT_ONESHOT), but this may be changed with + sd_event_source_set_enabled3. 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 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. + + + + + -ENOTSUP + + 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-config1 + file. + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + clock_gettime2, + sd_event_source_set_enabled3 + + + + -- cgit v1.2.3