sd_event_add_time.xml revision b408026b9899c1f9d155ac6d9f7bdc7f5cd3defb
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart PoetteringThis file is part of systemd.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart PoetteringCopyright 2014 Lennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poetteringsystemd is free software; you can redistribute it and/or modify it
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poetteringunder the terms of the GNU Lesser General Public License as published by
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poetteringthe Free Software Foundation; either version 2.1 of the License, or
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering(at your option) any later version.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poetteringsystemd is distributed in the hope that it will be useful, but
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart PoetteringWITHOUT ANY WARRANTY; without even the implied warranty of
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart PoetteringMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart PoetteringLesser General Public License for more details.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart PoetteringYou should have received a copy of the GNU Lesser General Public License
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poetteringalong with systemd; If not, see <http://www.gnu.org/licenses/>.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering<refentry id="sd_event_add_time" conditional="ENABLE_KDBUS">
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refentryinfo>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </authorgroup>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refentryinfo>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refentrytitle>sd_event_add_time</refentrytitle>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_get_time</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_set_time</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_get_time_accuracy</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_set_time_accuracy</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_get_time_clock</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refpurpose>Add a timer event source to an event loop</refpurpose>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refsynopsisdiv>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcsynopsis>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_add_time</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event *<parameter>event</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>clockid_t <parameter>clock</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>uint64_t <parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>uint64_t <parameter>accuracy</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>void* <parameter>userdata</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_get_time</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>usec_t* <parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_set_time</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>usec_t <parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>usec_t *<parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>usec_t <parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>clockid_t *<parameter>clock</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcsynopsis>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refsynopsisdiv>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_add_time()</function> adds a new timer
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering event source to an event loop object. The event loop is specified
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering in <parameter>event</parameter>, the event source is returned in
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the <parameter>source</parameter> parameter. The
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <parameter>clock</parameter> parameter takes a clock identifier,
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering one of <constant>CLOCK_REALTIME</constant>,
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <constant>CLOCK_BOOTTIME_ALARM</constant>. See
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering for details regarding the various types of clocks. The
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <parameter>usec</parameter> parameter takes a time value in
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering microseconds, relative to the clock's epoch specifying when the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering timer shall elapse the earliest. The
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <parameter>accuracy</parameter> parameter takes an additional
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering accuracy value in microseconds specifying a time the timer event
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering may be delayed. Specify 0 for selecting the default accuracy
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering (250ms). Specify 1 for most accurate timers. Consider specifying
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering 60000000 or larger (1h) for long running events that may be
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering delayed substantially. Picking higher accuracy values allows the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering system to coalesce timer events more aggressively, thus improving
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering power efficiency. The <parameter>handler</parameter> shall
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering reference a function to call when the timer elapses. The handler
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering function will be passed the <parameter>userdata</parameter>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering pointer, which may be chosen freely by the caller. The handler is
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering also passed the configured time it was triggered, however it might
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering actually have been called at a slightly later time, subject to the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering specified accuracy value, the kernel timer slack (see
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering and additional scheduling latencies. By default the timer will
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering elapse once (SD_EVENT_ONESHOT), but this may be changed with
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the handler function returns a negative error code it will be
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering disabled after the invocation, even if SD_EVENT_ON mode is set.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_get_time()</function> retrieves
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the configured time value of a timer event source created
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering previously with <function>sd_event_add_time()</function>. It takes
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the event source object and a pointer to a variable to store the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering time in microseconds in.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_set_time()</function> changes the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering configured time value of a timer event source created previously
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering with <function>sd_event_add_time()</function>. It takes the event
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering source object and a time relative to the selected clock's
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering epoch, in microseconds.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_get_time_accuracy()</function>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering retrieves the configured accuracy value of a timer event source
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering created previously with <function>sd_event_add_time()</function>. It
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering takes the event source object and a pointer to a variable to store
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the accuracy in microseconds in.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_set_time_accuracy()</function>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering changes the configured accuracy of a timer event source created
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering previously with <function>sd_event_add_time()</function>. It takes
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the event source object and an accuracy, in microseconds.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_get_time_clock()</function>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering retrieves the configured clock of a timer event source created
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering previously with <function>sd_event_add_time()</function>. It takes
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the event source object and a pointer to a variable to store the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering clock identifier in.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para>On success, these functions return 0 or a positive
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering integer. On failure, they return a negative errno-style error
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para>Returned errors may indicate the following problems:</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <variablelist>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>Not enough memory to allocate object.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>An invalid argument has been passed.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>The event loop is already terminated.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>The event loop has been created in a different process.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </variablelist>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_add_time()</function> and the other functions
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering described here are available as a shared library, which can be
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering compiled and linked to with the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>