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