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>int <function>sd_event_source_get_time</function></funcdef>
  73         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  74         <paramdef>usec_t *<parameter>usec</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int <function>sd_event_source_set_time</function></funcdef>
  79         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  80         <paramdef>usec_t <parameter>usec</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef>
  85         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  86         <paramdef>usec_t *<parameter>usec</parameter></paramdef>
  87       </funcprototype>
  88
  89       <funcprototype>
  90         <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef>
  91         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  92         <paramdef>usec_t <parameter>usec</parameter></paramdef>
  93       </funcprototype>
  94
  95       <funcprototype>
  96         <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef>
  97         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  98         <paramdef>clockid_t *<parameter>clock</parameter></paramdef>
  99       </funcprototype>
 100
 101     </funcsynopsis>
 102   </refsynopsisdiv>
 103
 104   <refsect1>
 105     <title>Description</title>
 106
 107     <para><function>sd_event_add_time()</function> adds a new timer
 108     event source to an event loop object. The event loop is specified
 109     in <parameter>event</parameter>, the event source is returned in
 110     the <parameter>source</parameter> parameter. The
 111     <parameter>clock</parameter> parameter takes a clock identifier,
 112     one of <constant>CLOCK_REALTIME</constant>,
 113     <constant>CLOCK_MONOTONIC</constant> and
 114     <constant>CLOCK_BOOTTIME_ALARM</constant>. See
 115     <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 116     for details regarding the various types of clocks. The
 117     <parameter>usec</parameter> parameter takes a time value in
 118     microseconds, relative to the clock's epoch specifying when the
 119     timer shall elapse the earliest. The
 120     <parameter>accuracy</parameter> parameter takes an additional
 121     accuracy value in microseconds specifying a time the timer event
 122     may be delayed. Specify 0 for selecting the default accuracy
 123     (250ms). Specify 1 for most accurate timers. Consider specifying
 124     60000000 or larger (1h) for long-running events that may be
 125     delayed substantially. Picking higher accuracy values allows the
 126     system to coalesce timer events more aggressively, thus improving
 127     power efficiency. The <parameter>handler</parameter> shall
 128     reference a function to call when the timer elapses. The handler
 129     function will be passed the <parameter>userdata</parameter>
 130     pointer, which may be chosen freely by the caller. The handler is
 131     also passed the configured time it was triggered, however it might
 132     actually have been called at a slightly later time, subject to the
 133     specified accuracy value, the kernel timer slack (see
 134     <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
 135     and additional scheduling latencies. By default, the timer will
 136     elapse once (SD_EVENT_ONESHOT), but this may be changed with
 137     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
 138     the handler function returns a negative error code, it will be
 139     disabled after the invocation, even if SD_EVENT_ON mode is set.
 140     </para>
 141
 142     <para><function>sd_event_source_get_time()</function> retrieves
 143     the configured time value of a timer event source created
 144     previously with <function>sd_event_add_time()</function>. It takes
 145     the event source object and a pointer to a variable to store the
 146     time in microseconds in.</para>
 147
 148     <para><function>sd_event_source_set_time()</function> changes the
 149     configured time value of a timer event source created previously
 150     with <function>sd_event_add_time()</function>. It takes the event
 151     source object and a time relative to the selected clock's
 152     epoch, in microseconds.</para>
 153
 154     <para><function>sd_event_source_get_time_accuracy()</function>
 155     retrieves the configured accuracy value of a timer event source
 156     created previously with <function>sd_event_add_time()</function>. It
 157     takes the event source object and a pointer to a variable to store
 158     the accuracy in microseconds in.</para>
 159
 160     <para><function>sd_event_source_set_time_accuracy()</function>
 161     changes the configured accuracy of a timer event source created
 162     previously with <function>sd_event_add_time()</function>. It takes
 163     the event source object and an accuracy, in microseconds.</para>
 164
 165     <para><function>sd_event_source_get_time_clock()</function>
 166     retrieves the configured clock of a timer event source created
 167     previously with <function>sd_event_add_time()</function>. It takes
 168     the event source object and a pointer to a variable to store the
 169     clock identifier in.</para>
 170
 171   </refsect1>
 172
 173   <refsect1>
 174     <title>Return Value</title>
 175
 176     <para>On success, these functions return 0 or a positive
 177     integer. On failure, they return a negative errno-style error
 178     code. </para>
 179   </refsect1>
 180
 181   <refsect1>
 182     <title>Errors</title>
 183
 184     <para>Returned errors may indicate the following problems:</para>
 185
 186     <variablelist>
 187       <varlistentry>
 188         <term><varname>-ENOMEM</varname></term>
 189
 190         <listitem><para>Not enough memory to allocate object.</para></listitem>
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><varname>-EINVAL</varname></term>
 195
 196         <listitem><para>An invalid argument has been passed.</para></listitem>
 197
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><varname>-ESTALE</varname></term>
 202
 203         <listitem><para>The event loop is already terminated.</para></listitem>
 204
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><varname>-ECHILD</varname></term>
 209
 210         <listitem><para>The event loop has been created in a different process.</para></listitem>
 211
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><varname>-ENOTSUP</varname></term>
 216
 217         <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
 218
 219       </varlistentry>
 220     </variablelist>
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>Notes</title>
 225
 226     <para><function>sd_event_add_time()</function> and the other functions
 227     described here are available as a shared library, which can be
 228     compiled and linked to with the
 229     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 230     file.</para>
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>See Also</title>
 235
 236     <para>
 237       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 238       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 239       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 240       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 241       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 242     </para>
 243   </refsect1>
 244
 245 </refentry>