man/sd_event_add_time.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_event_add_time" conditional="ENABLE_KDBUS">
  28
  29   <refentryinfo>
  30     <title>sd_event_add_time</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_event_add_time</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_event_add_time</refname>
  50     <refname>sd_event_source_get_time</refname>
  51     <refname>sd_event_source_set_time</refname>
  52     <refname>sd_event_source_get_time_accuracy</refname>
  53     <refname>sd_event_source_set_time_accuracy</refname>
  54     <refname>sd_event_source_get_time_clock</refname>
  55
  56     <refpurpose>Add a timer event source to an event loop</refpurpose>
  57   </refnamediv>
  58
  59   <refsynopsisdiv>
  60     <funcsynopsis>
  61       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_event_add_time</function></funcdef>
  65         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  66         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  67         <paramdef>clockid_t <parameter>clock</parameter></paramdef>
  68         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  69         <paramdef>uint64_t <parameter>accuracy</parameter></paramdef>
  70         <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef>
  71         <paramdef>void *<parameter>userdata</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
  76         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  77         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  78         <paramdef>void *<parameter>userdata</parameter></paramdef>
  79       </funcprototype>
  80
  81       <funcprototype>
  82         <funcdef>int <function>sd_event_source_get_time</function></funcdef>
  83         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  84         <paramdef>usec_t *<parameter>usec</parameter></paramdef>
  85       </funcprototype>
  86
  87       <funcprototype>
  88         <funcdef>int <function>sd_event_source_set_time</function></funcdef>
  89         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  90         <paramdef>usec_t <parameter>usec</parameter></paramdef>
  91       </funcprototype>
  92
  93       <funcprototype>
  94         <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef>
  95         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  96         <paramdef>usec_t *<parameter>usec</parameter></paramdef>
  97       </funcprototype>
  98
  99       <funcprototype>
 100         <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef>
 101         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
 102         <paramdef>usec_t <parameter>usec</parameter></paramdef>
 103       </funcprototype>
 104
 105       <funcprototype>
 106         <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef>
 107         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
 108         <paramdef>clockid_t *<parameter>clock</parameter></paramdef>
 109       </funcprototype>
 110
 111     </funcsynopsis>
 112   </refsynopsisdiv>
 113
 114   <refsect1>
 115     <title>Description</title>
 116
 117     <para><function>sd_event_add_time()</function> adds a new timer
 118     event source to an event loop object. The event loop is specified
 119     in <parameter>event</parameter>, the event source is returned in
 120     the <parameter>source</parameter> parameter. The
 121     <parameter>clock</parameter> parameter takes a clock identifier,
 122     one of <constant>CLOCK_REALTIME</constant>,
 123     <constant>CLOCK_MONOTONIC</constant> and
 124     <constant>CLOCK_BOOTTIME_ALARM</constant>. See
 125     <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 126     for details regarding the various types of clocks. The
 127     <parameter>usec</parameter> parameter takes a time value in
 128     microseconds, relative to the clock's epoch specifying when the
 129     timer shall elapse the earliest. The
 130     <parameter>accuracy</parameter> parameter takes an additional
 131     accuracy value in microseconds specifying a time the timer event
 132     may be delayed. Specify 0 for selecting the default accuracy
 133     (250ms). Specify 1 for most accurate timers. Consider specifying
 134     60000000 or larger (1h) for long-running events that may be
 135     delayed substantially. Picking higher accuracy values allows the
 136     system to coalesce timer events more aggressively, thus improving
 137     power efficiency. The <parameter>handler</parameter> shall
 138     reference a function to call when the timer elapses. The handler
 139     function will be passed the <parameter>userdata</parameter>
 140     pointer, which may be chosen freely by the caller. The handler is
 141     also passed the configured time it was triggered, however it might
 142     actually have been called at a slightly later time, subject to the
 143     specified accuracy value, the kernel timer slack (see
 144     <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
 145     and additional scheduling latencies.</para>
 146
 147     <para>By default, the timer will elapse once
 148     (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
 149     with
 150     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 151     If the handler function returns a negative error code, it will be
 152     disabled after the invocation, even if
 153     <constant>SD_EVENT_ON</constant> mode is set.
 154     </para>
 155
 156     <para><function>sd_event_source_get_time()</function> retrieves
 157     the configured time value of a timer event source created
 158     previously with <function>sd_event_add_time()</function>. It takes
 159     the event source object and a pointer to a variable to store the
 160     time in microseconds in.</para>
 161
 162     <para><function>sd_event_source_set_time()</function> changes the
 163     configured time value of a timer event source created previously
 164     with <function>sd_event_add_time()</function>. It takes the event
 165     source object and a time relative to the selected clock's
 166     epoch, in microseconds.</para>
 167
 168     <para><function>sd_event_source_get_time_accuracy()</function>
 169     retrieves the configured accuracy value of a timer event source
 170     created previously with <function>sd_event_add_time()</function>. It
 171     takes the event source object and a pointer to a variable to store
 172     the accuracy in microseconds in.</para>
 173
 174     <para><function>sd_event_source_set_time_accuracy()</function>
 175     changes the configured accuracy of a timer event source created
 176     previously with <function>sd_event_add_time()</function>. It takes
 177     the event source object and an accuracy, in microseconds.</para>
 178
 179     <para><function>sd_event_source_get_time_clock()</function>
 180     retrieves the configured clock of a timer event source created
 181     previously with <function>sd_event_add_time()</function>. It takes
 182     the event source object and a pointer to a variable to store the
 183     clock identifier in.</para>
 184
 185   </refsect1>
 186
 187   <refsect1>
 188     <title>Return Value</title>
 189
 190     <para>On success, these functions return 0 or a positive
 191     integer. On failure, they return a negative errno-style error
 192     code. </para>
 193   </refsect1>
 194
 195   <refsect1>
 196     <title>Errors</title>
 197
 198     <para>Returned errors may indicate the following problems:</para>
 199
 200     <variablelist>
 201       <varlistentry>
 202         <term><constant>-ENOMEM</constant></term>
 203
 204         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><constant>-EINVAL</constant></term>
 209
 210         <listitem><para>An invalid argument has been passed.</para></listitem>
 211
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><constant>-ESTALE</constant></term>
 216
 217         <listitem><para>The event loop is already terminated.</para></listitem>
 218
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term><constant>-ECHILD</constant></term>
 223
 224         <listitem><para>The event loop has been created in a different process.</para></listitem>
 225
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term><constant>-EOPNOTSUPP</constant></term>
 230
 231         <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
 232
 233       </varlistentry>
 234     </variablelist>
 235   </refsect1>
 236
 237   <refsect1>
 238     <title>Notes</title>
 239
 240     <para><function>sd_event_add_time()</function> and the other functions
 241     described here are available as a shared library, which can be
 242     compiled and linked to with the
 243     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 244     file.</para>
 245   </refsect1>
 246
 247   <refsect1>
 248     <title>See Also</title>
 249
 250     <para>
 251       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 252       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 253       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 254       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 256       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 257       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 258       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 259     </para>
 260   </refsect1>
 261
 262 </refentry>