man/sd_event_add_time.xml

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