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