From 19f4f86bfed21c5326ed2acebe1163f3a83e832b Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 04:25:50 +0200 Subject: Adding upstream version 241. Signed-off-by: Daniel Baumann --- man/sd_event_add_time.xml | 290 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 290 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 0000000..e6dbd15 --- /dev/null +++ b/man/sd_event_add_time.xml @@ -0,0 +1,290 @@ + + + + + + + + + sd_event_add_time + systemd + + + + 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 + sd_event_time_handler_t + + Add a timer event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_time_handler_t) + sd_event_source *s + uint64_t usec + void *userdata + + + + 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 + uint64_t *usec + + + + int sd_event_source_set_time + sd_event_source *source + uint64_t usec + + + + int sd_event_source_get_time_accuracy + sd_event_source *source + uint64_t *usec + + + + int sd_event_source_set_time_accuracy + sd_event_source *source + uint64_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. The event loop + object is specified in the event parameter, the event source object is returned in the + source parameter. The clock parameter takes a clock identifier, one + of CLOCK_REALTIME, CLOCK_MONOTONIC, CLOCK_BOOTTIME, + CLOCK_REALTIME_ALARM, or CLOCK_BOOTTIME_ALARM. See + timerfd_create2 for details + regarding the various types of clocks. The usec parameter specifies the earliest time, in + microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past + is specified (including 0), this timer source "fires" immediately and is ready to be + dispatched. If the parameter is specified as UINT64_MAX the timer event will never elapse, + which may be used as an alternative to explicitly disabling a timer event source with + sd_event_source_set_enabled3. The + accuracy parameter specifies an additional accuracy value in µs specifying how much the + timer event may be delayed. Use 0 to select the default accuracy (250ms). Use 1µs for maximum + accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed + substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, + improving power efficiency. The handler parameter 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 trigger time, even if it is actually called + slightly later, subject to the specified accuracy value, the kernel timer slack (see + prctl2), and additional + scheduling latencies. To query the actual time the handler was called use + sd_event_now3. + + 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 the + SD_EVENT_ON mode was requested before. Note + that a timer event set to SD_EVENT_ON will + fire continuously unless its configured time is updated using + sd_event_source_set_time(). + + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_time() is + NULL no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed. + + If the handler to + sd_event_add_time() is + NULL, and the event source fires, this will + be considered a request to exit the event loop. In this case, the + userdata parameter, cast to an integer, is + used for the exit code passed to + sd_event_exit3. + + Use CLOCK_BOOTTIME_ALARM and + CLOCK_REALTIME_ALARM to define event sources + that may wake up the system from suspend. + + In order to set up relative timers (that is, relative to the + current time), retrieve the current time via + sd_event_now3, + add the desired timespan to it, and use the result as + the usec parameter to + sd_event_add_time(). + + In order to set up repetitive timers (that is, timers that + are triggered in regular intervals), set up the timer normally, + for the first invocation. Each time the event handler is invoked, + update the timer's trigger time with + sd_event_source_set_time3 for the next timer + iteration, and reenable the timer using + sd_event_source_set_enabled(). To calculate + the next point in time to pass to + sd_event_source_set_time(), either use as + base the usec parameter passed to the timer + callback, or the timestamp returned by + sd_event_now(). In the former case timer + events will be regular, while in the latter case the scheduling + latency will keep accumulating on the timer. + + sd_event_source_get_time() retrieves + the configured time value of an 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, relative to the selected clock's epoch, in µs. + + sd_event_source_set_time() changes the + time of an 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 µs. + + sd_event_source_get_time_accuracy() + retrieves the configured accuracy value of an 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. The accuracy is specified in µs. + + 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 accuracy, in µs. + + sd_event_source_get_time_clock() + retrieves the configured clock of an 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 values 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. + + + + + -EDOM + + The passed event source is not a timer event source. + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_inotify3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + clock_gettime2, + timerfd_create2, + prctl2 + + + + -- cgit v1.2.3