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
   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" xmlns:xi="http://www.w3.org/2001/XInclude">
  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     <refname>sd_event_time_handler_t</refname>
  53
  54     <refpurpose>Add a timer event source to an event loop</refpurpose>
  55   </refnamediv>
  56
  57   <refsynopsisdiv>
  58     <funcsynopsis>
  59       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  60
  61       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  62
  63       <funcprototype>
  64         <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
  65         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  66         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  67         <paramdef>void *<parameter>userdata</parameter></paramdef>
  68       </funcprototype>
  69
  70       <funcprototype>
  71         <funcdef>int <function>sd_event_add_time</function></funcdef>
  72         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  73         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  74         <paramdef>clockid_t <parameter>clock</parameter></paramdef>
  75         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  76         <paramdef>uint64_t <parameter>accuracy</parameter></paramdef>
  77         <paramdef>sd_event_time_handler_t <parameter>handler</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>uint64_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>uint64_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>uint64_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>uint64_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. The event loop object is specified
 119     in the <parameter>event</parameter> parameter, the event source
 120     object is returned in the <parameter>source</parameter>
 121     parameter. The <parameter>clock</parameter> parameter takes a
 122     clock identifier, one of <constant>CLOCK_REALTIME</constant>,
 123     <constant>CLOCK_MONOTONIC</constant>,
 124     <constant>CLOCK_BOOTTIME</constant>,
 125     <constant>CLOCK_REALTIME_ALARM</constant> or
 126     <constant>CLOCK_BOOTTIME_ALARM</constant>. See
 127     <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 128     for details regarding the various types of clocks. The
 129     <parameter>usec</parameter> parameter takes a time value in
 130     microseconds (µs), relative to the clock's epoch, specifying when
 131     the timer shall elapse the earliest. If a time that already lies
 132     in the past is specified (including 0), the timer source is
 133     dispatched immediately in the next event loop iterations. The
 134     <parameter>accuracy</parameter> parameter takes an additional
 135     accuracy value in µs specifying a time the timer event may be
 136     delayed. Specify 0 for selecting the default accuracy
 137     (250ms). Specify 1µs for most accurate timers. Consider specifying
 138     60000000µs or larger (1min) for long-running events that may be
 139     delayed substantially. Picking higher accuracy values allows the
 140     system to coalesce timer events more aggressively, thus improving
 141     power efficiency. The <parameter>handler</parameter> parameter
 142     shall reference a function to call when the timer elapses. The
 143     handler function will be passed the
 144     <parameter>userdata</parameter> pointer, which may be chosen
 145     freely by the caller. The handler is also passed the configured
 146     time it was triggered, however it might actually have been called
 147     at a slightly later time, subject to the specified accuracy value,
 148     the kernel timer slack (see
 149     <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
 150     and additional scheduling latencies. To query the actual time the
 151     handler was called use
 152     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 153
 154     <para>By default, the timer will elapse once
 155     (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
 156     with
 157     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 158     If the handler function returns a negative error code, it will be
 159     disabled after the invocation, even if the
 160     <constant>SD_EVENT_ON</constant> mode was requested before. Note
 161     that a timer event set to <constant>SD_EVENT_ON</constant> will
 162     fire continously unless its configured time is updated using
 163     <function>sd_event_source_set_time()</function>.
 164     </para>
 165
 166     <para>To destroy an event source object use
 167     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 168     but note that the event source is only removed from the event loop
 169     when all references to the event source are dropped. To make sure
 170     an event source does not fire anymore, even when there's still a
 171     reference to it kept, consider setting the event source to
 172     <constant>SD_EVENT_OFF</constant> with
 173     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 174
 175     <para>If the the second parameter of
 176     <function>sd_event_add_time()</function> is passed as NULL no
 177     reference to the event source object is returned. In this case the
 178     event source is considered "floating", and will be destroyed
 179     implicitly when the event loop itself is destroyed.</para>
 180
 181     <para>If the <parameter>handler</parameter> to
 182     <function>sd_event_add_time()</function> is passed as NULL, and
 183     the event source fires, this will be considered a request to exit
 184     the event loop. In this case, the <parameter>userdata</parameter>
 185     parameter, cast to an integer is used for the exit code passed to
 186     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 187
 188     <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
 189     <constant>CLOCK_REALTIME_ALARM</constant> to define event sources
 190     that may wake up the system from suspend.</para>
 191
 192     <para>In order to set up relative timers (that is, relative to the
 193     current time), retrieve the current time via
 194     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 195     add the desired timespan to sleep to it, and pass the result as
 196     the <parameter>usec</parameter> parameter to
 197     <function>sd_event_add_time()</function>.</para>
 198
 199     <para>In order to set up repetitive timers (that is, timers that
 200     are triggered in regular intervals), set up the timer normally,
 201     for the first invocation. Each time the event handler is invoked,
 202     update the timer's trigger time with
 203     <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer
 204     iteration, and reenable the timer using
 205     <function>sd_event_source_set_enabled()</function>. To calculate
 206     the next point in time to pass to
 207     <function>sd_event_source_set_time()</function>, either use as
 208     base the <parameter>usec</parameter> parameter passed to the timer
 209     callback, or the timestamp returned by
 210     <function>sd_event_now()</function>. In the former case timer
 211     events will be regular, while in the latter case the scheduling
 212     latency will keep accumulating on the timer.</para>
 213
 214     <para><function>sd_event_source_get_time()</function> retrieves
 215     the configured time value of a timer event source created
 216     previously with <function>sd_event_add_time()</function>. It takes
 217     the event source object and a pointer to a variable to store the
 218     time, relative to the selected clock's epoch, in µs in.</para>
 219
 220     <para><function>sd_event_source_set_time()</function> changes the
 221     configured time value of a timer event source created previously
 222     with <function>sd_event_add_time()</function>. It takes the event
 223     source object and a time relative to the selected clock's
 224     epoch, in µs.</para>
 225
 226     <para><function>sd_event_source_get_time_accuracy()</function>
 227     retrieves the configured accuracy value of a timer event source
 228     created previously with <function>sd_event_add_time()</function>. It
 229     takes the event source object and a pointer to a variable to store
 230     the accuracy in µs in.</para>
 231
 232     <para><function>sd_event_source_set_time_accuracy()</function>
 233     changes the configured accuracy of a timer event source created
 234     previously with <function>sd_event_add_time()</function>. It takes
 235     the event source object and an accuracy, in µs.</para>
 236
 237     <para><function>sd_event_source_get_time_clock()</function>
 238     retrieves the configured clock of a timer event source created
 239     previously with <function>sd_event_add_time()</function>. It takes
 240     the event source object and a pointer to a variable to store the
 241     clock identifier in.</para>
 242   </refsect1>
 243
 244   <refsect1>
 245     <title>Return Value</title>
 246
 247     <para>On success, these functions return 0 or a positive
 248     integer. On failure, they return a negative errno-style error
 249     code. </para>
 250   </refsect1>
 251
 252   <refsect1>
 253     <title>Errors</title>
 254
 255     <para>Returned errors may indicate the following problems:</para>
 256
 257     <variablelist>
 258       <varlistentry>
 259         <term><constant>-ENOMEM</constant></term>
 260
 261         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 262       </varlistentry>
 263
 264       <varlistentry>
 265         <term><constant>-EINVAL</constant></term>
 266
 267         <listitem><para>An invalid argument has been passed.</para></listitem>
 268
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><constant>-ESTALE</constant></term>
 273
 274         <listitem><para>The event loop is already terminated.</para></listitem>
 275
 276       </varlistentry>
 277
 278       <varlistentry>
 279         <term><constant>-ECHILD</constant></term>
 280
 281         <listitem><para>The event loop has been created in a different process.</para></listitem>
 282
 283       </varlistentry>
 284
 285       <varlistentry>
 286         <term><constant>-EOPNOTSUPP</constant></term>
 287
 288         <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
 289
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><constant>-EDOM</constant></term>
 294
 295         <listitem><para>The passed event source is not a timer event source.</para></listitem>
 296       </varlistentry>
 297     </variablelist>
 298   </refsect1>
 299
 300   <xi:include href="libsystemd-pkgconfig.xml" />
 301
 302   <refsect1>
 303     <title>See Also</title>
 304
 305     <para>
 306       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 307       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 308       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 309       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 311       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 312       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 313       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 314       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 315       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 316       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 317       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 318       <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 319       <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 320       <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 321     </para>
 322   </refsect1>
 323
 324 </refentry>