From b408026b9899c1f9d155ac6d9f7bdc7f5cd3defb Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 6 May 2014 18:51:08 +0200 Subject: [PATCH] man: document sd_event_add_time(3) --- Makefile-man.am | 41 +++++-- man/sd_event_add_time.xml | 245 ++++++++++++++++++++++++++++++++++++++ src/systemd/sd-event.h | 2 +- 3 files changed, 280 insertions(+), 8 deletions(-) create mode 100644 man/sd_event_add_time.xml diff --git a/Makefile-man.am b/Makefile-man.am index f9ca87eba..ca7d209bd 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -703,6 +703,7 @@ MANPAGES += \ man/sd_bus_open_user.3 \ man/sd_bus_path_encode.3 \ man/sd_bus_request_name.3 \ + man/sd_event_add_time.3 \ man/sd_event_new.3 \ man/systemd-bus-proxyd.8 \ man/systemd-bus-proxyd@.service.8 @@ -763,6 +764,11 @@ MANPAGES_ALIAS += \ man/sd_bus_unref.3 \ man/sd_event_default.3 \ man/sd_event_ref.3 \ + man/sd_event_source_get_time.3 \ + man/sd_event_source_get_time_accuracy.3 \ + man/sd_event_source_get_time_clock.3 \ + man/sd_event_source_set_time.3 \ + man/sd_event_source_set_time_accuracy.3 \ man/sd_event_unref.3 \ man/systemd-bus-proxyd.socket.8 man/sd_bus_creds_get_audit_login_uid.3: man/sd_bus_creds_get_pid.3 @@ -821,6 +827,11 @@ man/sd_bus_release_name.3: man/sd_bus_request_name.3 man/sd_bus_unref.3: man/sd_bus_new.3 man/sd_event_default.3: man/sd_event_new.3 man/sd_event_ref.3: man/sd_event_new.3 +man/sd_event_source_get_time.3: man/sd_event_add_time.3 +man/sd_event_source_get_time_accuracy.3: man/sd_event_add_time.3 +man/sd_event_source_get_time_clock.3: man/sd_event_add_time.3 +man/sd_event_source_set_time.3: man/sd_event_add_time.3 +man/sd_event_source_set_time_accuracy.3: man/sd_event_add_time.3 man/sd_event_unref.3: man/sd_event_new.3 man/systemd-bus-proxyd.socket.8: man/systemd-bus-proxyd@.service.8 man/sd_bus_creds_get_audit_login_uid.html: man/sd_bus_creds_get_pid.html @@ -991,6 +1002,21 @@ man/sd_event_default.html: man/sd_event_new.html man/sd_event_ref.html: man/sd_event_new.html $(html-alias) +man/sd_event_source_get_time.html: man/sd_event_add_time.html + $(html-alias) + +man/sd_event_source_get_time_accuracy.html: man/sd_event_add_time.html + $(html-alias) + +man/sd_event_source_get_time_clock.html: man/sd_event_add_time.html + $(html-alias) + +man/sd_event_source_set_time.html: man/sd_event_add_time.html + $(html-alias) + +man/sd_event_source_set_time_accuracy.html: man/sd_event_add_time.html + $(html-alias) + man/sd_event_unref.html: man/sd_event_new.html $(html-alias) @@ -1038,20 +1064,19 @@ endif if ENABLE_NETWORKD MANPAGES += \ - man/systemd-networkd.service.8 \ man/systemd-networkd-wait-online.service.8 \ + man/systemd-networkd.service.8 \ man/systemd.netdev.5 \ man/systemd.network.5 MANPAGES_ALIAS += \ - man/systemd-networkd.8 \ - man/systemd-networkd-wait-online.8 -man/systemd-networkd.8: man/systemd-networkd.service.8 + man/systemd-networkd-wait-online.8 \ + man/systemd-networkd.8 man/systemd-networkd-wait-online.8: man/systemd-networkd-wait-online.service.8 - -man/systemd-networkd.html: man/systemd-networkd.service.html +man/systemd-networkd.8: man/systemd-networkd.service.8 +man/systemd-networkd-wait-online.html: man/systemd-networkd-wait-online.service.html $(html-alias) -man/systemd-networkd-wait-online.html: man/systemd-networkd-wait-online.service.html +man/systemd-networkd.html: man/systemd-networkd.service.html $(html-alias) endif @@ -1480,6 +1505,7 @@ EXTRA_DIST += \ man/sd_bus_open_user.xml \ man/sd_bus_path_encode.xml \ man/sd_bus_request_name.xml \ + man/sd_event_add_time.xml \ man/sd_event_new.xml \ man/sd_get_seats.xml \ man/sd_id128_get_machine.xml \ @@ -1547,6 +1573,7 @@ EXTRA_DIST += \ man/systemd-machine-id-setup.xml \ man/systemd-machined.service.xml \ man/systemd-modules-load.service.xml \ + man/systemd-networkd-wait-online.service.xml \ man/systemd-networkd.service.xml \ man/systemd-notify.xml \ man/systemd-nspawn.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 + + + + diff --git a/src/systemd/sd-event.h b/src/systemd/sd-event.h index 6ed0527ae..75ee3411d 100644 --- a/src/systemd/sd-event.h +++ b/src/systemd/sd-event.h @@ -114,8 +114,8 @@ int sd_event_source_set_io_events(sd_event_source *s, uint32_t events); int sd_event_source_get_io_revents(sd_event_source *s, uint32_t* revents); int sd_event_source_get_time(sd_event_source *s, uint64_t *usec); int sd_event_source_set_time(sd_event_source *s, uint64_t usec); -int sd_event_source_set_time_accuracy(sd_event_source *s, uint64_t usec); int sd_event_source_get_time_accuracy(sd_event_source *s, uint64_t *usec); +int sd_event_source_set_time_accuracy(sd_event_source *s, uint64_t usec); int sd_event_source_get_time_clock(sd_event_source *s, clockid_t *clock); int sd_event_source_get_signal(sd_event_source *s); int sd_event_source_get_child_pid(sd_event_source *s, pid_t *pid); -- 2.30.2