diff options
| -rw-r--r-- | Makefile-man.am | 41 | ||||
| -rw-r--r-- | man/sd_event_add_time.xml | 245 | ||||
| -rw-r--r-- | src/systemd/sd-event.h | 2 |
3 files changed, 280 insertions, 8 deletions
diff --git a/Makefile-man.am b/Makefile-man.am index f9ca87ebaa..ca7d209bdf 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 0000000000..9af8bb9c45 --- /dev/null +++ b/man/sd_event_add_time.xml @@ -0,0 +1,245 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- +This file is part of systemd. + +Copyright 2014 Lennart Poettering + +systemd is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General Public License as published by +the Free Software Foundation; either version 2.1 of the License, or +(at your option) any later version. + +systemd is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public License +along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_add_time" conditional="ENABLE_KDBUS"> + + <refentryinfo> + <title>sd_event_add_time</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_add_time</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_add_time</refname> + <refname>sd_event_source_get_time</refname> + <refname>sd_event_source_set_time</refname> + <refname>sd_event_source_get_time_accuracy</refname> + <refname>sd_event_source_set_time_accuracy</refname> + <refname>sd_event_source_get_time_clock</refname> + + <refpurpose>Add a timer event source to an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_add_time</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>clockid_t <parameter>clock</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + <paramdef>uint64_t <parameter>accuracy</parameter></paramdef> + <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void* <parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>usec_t* <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_time</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>usec_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>usec_t *<parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>usec_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>clockid_t *<parameter>clock</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_add_time()</function> adds a new timer + event source to an event loop object. The event loop is specified + in <parameter>event</parameter>, the event source is returned in + the <parameter>source</parameter> parameter. The + <parameter>clock</parameter> parameter takes a clock identifier, + one of <constant>CLOCK_REALTIME</constant>, + <constant>CLOCK_MONOTONIC</constant> and + <constant>CLOCK_BOOTTIME_ALARM</constant>. See + <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details regarding the various types of clocks. The + <parameter>usec</parameter> parameter takes a time value in + microseconds, relative to the clock's epoch specifying when the + timer shall elapse the earliest. The + <parameter>accuracy</parameter> 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 <parameter>handler</parameter> shall + reference a function to call when the timer elapses. The handler + function will be passed the <parameter>userdata</parameter> + 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 + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>) + and additional scheduling latencies. By default the timer will + elapse once (SD_EVENT_ONESHOT), but this may be changed with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If + the handler function returns a negative error code it will be + disabled after the invocation, even if SD_EVENT_ON mode is set. + </para> + + <para><function>sd_event_source_get_time()</function> retrieves + the configured time value of a timer event source created + previously with <function>sd_event_add_time()</function>. It takes + the event source object and a pointer to a variable to store the + time in microseconds in.</para> + + <para><function>sd_event_source_set_time()</function> changes the + configured time value of a timer event source created previously + with <function>sd_event_add_time()</function>. It takes the event + source object and a time relative to the selected clock's + epoch, in microseconds.</para> + + <para><function>sd_event_source_get_time_accuracy()</function> + retrieves the configured accuracy value of a timer event source + created previously with <function>sd_event_add_time()</function>. It + takes the event source object and a pointer to a variable to store + the accuracy in microseconds in.</para> + + <para><function>sd_event_source_set_time_accuracy()</function> + changes the configured accuracy of a timer event source created + previously with <function>sd_event_add_time()</function>. It takes + the event source object and an accuracy, in microseconds.</para> + + <para><function>sd_event_source_get_time_clock()</function> + retrieves the configured clock of a timer event source created + previously with <function>sd_event_add_time()</function>. It takes + the event source object and a pointer to a variable to store the + clock identifier in.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><varname>-ENOMEM</varname></term> + + <listitem><para>Not enough memory to allocate object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>-EINVAL</varname></term> + + <listitem><para>An invalid argument has been passed.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>-ESTALE</varname></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>-ECHILD</varname></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>-ENOTSUP</varname></term> + + <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_event_add_time()</function> and the other functions + described here are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/systemd/sd-event.h b/src/systemd/sd-event.h index 6ed0527aef..75ee3411db 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); |