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 specifies the earliest time,
 130     in microseconds (µs), relative to the clock's epoch, when
 131     the timer shall be triggered. If a time already in the past is
 132     specified (including <constant>0</constant>), this timer source
 133     "fires" immediately and is ready to be dispatched. The
 134     <parameter>accuracy</parameter> parameter specifies an additional
 135     accuracy value in µs specifying how much the timer event may be
 136     delayed. Use <constant>0</constant> to select the default accuracy
 137     (250ms). Use 1µs for maximum accuracy. Consider specifying
 138     60000000µs (1min) or larger for long-running events that may be
 139     delayed substantially. Picking higher accuracy values allows the
 140     system to coalesce timer events more aggressively, 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     trigger time, even if it is actually called
 147     slightly later, 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 continuously 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 if it is still referenced,
 171     disable the event source using
 172     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 173     with <constant>SD_EVENT_OFF</constant>.</para>
 174
 175     <para>If the second parameter of
 176     <function>sd_event_add_time()</function> is
 177     <constant>NULL</constant> no reference to the event source object
 178     is returned. In this case the event source is considered
 179     "floating", and will be destroyed implicitly when the event loop
 180     itself is destroyed.</para>
 181
 182     <para>If the <parameter>handler</parameter> to
 183     <function>sd_event_add_time()</function> is
 184     <constant>NULL</constant>, and the event source fires, this will
 185     be considered a request to exit the event loop. In this case, the
 186     <parameter>userdata</parameter> parameter, cast to an integer, is
 187     used for the exit code passed to
 188     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 189
 190     <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
 191     <constant>CLOCK_REALTIME_ALARM</constant> to define event sources
 192     that may wake up the system from suspend.</para>
 193
 194     <para>In order to set up relative timers (that is, relative to the
 195     current time), retrieve the current time via
 196     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 197     add the desired timespan to it, and use the result as
 198     the <parameter>usec</parameter> parameter to
 199     <function>sd_event_add_time()</function>.</para>
 200
 201     <para>In order to set up repetitive timers (that is, timers that
 202     are triggered in regular intervals), set up the timer normally,
 203     for the first invocation. Each time the event handler is invoked,
 204     update the timer's trigger time with
 205     <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer
 206     iteration, and reenable the timer using
 207     <function>sd_event_source_set_enabled()</function>. To calculate
 208     the next point in time to pass to
 209     <function>sd_event_source_set_time()</function>, either use as
 210     base the <parameter>usec</parameter> parameter passed to the timer
 211     callback, or the timestamp returned by
 212     <function>sd_event_now()</function>. In the former case timer
 213     events will be regular, while in the latter case the scheduling
 214     latency will keep accumulating on the timer.</para>
 215
 216     <para><function>sd_event_source_get_time()</function> retrieves
 217     the configured time value of an event source created
 218     previously with <function>sd_event_add_time()</function>. It takes
 219     the event source object and a pointer to a variable to store the
 220     time in, relative to the selected clock's epoch, in µs.</para>
 221
 222     <para><function>sd_event_source_set_time()</function> changes the
 223     time of an event source created previously with
 224     <function>sd_event_add_time()</function>. It takes the event
 225     source object and a time relative to the selected clock's epoch,
 226     in µs.</para>
 227
 228     <para><function>sd_event_source_get_time_accuracy()</function>
 229     retrieves the configured accuracy value of a event source
 230     created previously with <function>sd_event_add_time()</function>. It
 231     takes the event source object and a pointer to a variable to store
 232     the accuracy in. The accuracy is specified in µs.</para>
 233
 234     <para><function>sd_event_source_set_time_accuracy()</function>
 235     changes the configured accuracy of a timer event source created
 236     previously with <function>sd_event_add_time()</function>. It takes
 237     the event source object and accuracy, in µs.</para>
 238
 239     <para><function>sd_event_source_get_time_clock()</function>
 240     retrieves the configured clock of a event source created
 241     previously with <function>sd_event_add_time()</function>. It takes
 242     the event source object and a pointer to a variable to store the
 243     clock identifier in.</para>
 244   </refsect1>
 245
 246   <refsect1>
 247     <title>Return Value</title>
 248
 249     <para>On success, these functions return 0 or a positive
 250     integer. On failure, they return a negative errno-style error
 251     code. </para>
 252   </refsect1>
 253
 254   <refsect1>
 255     <title>Errors</title>
 256
 257     <para>Returned values may indicate the following problems:</para>
 258
 259     <variablelist>
 260       <varlistentry>
 261         <term><constant>-ENOMEM</constant></term>
 262
 263         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><constant>-EINVAL</constant></term>
 268
 269         <listitem><para>An invalid argument has been passed.</para></listitem>
 270
 271       </varlistentry>
 272
 273       <varlistentry>
 274         <term><constant>-ESTALE</constant></term>
 275
 276         <listitem><para>The event loop is already terminated.</para></listitem>
 277
 278       </varlistentry>
 279
 280       <varlistentry>
 281         <term><constant>-ECHILD</constant></term>
 282
 283         <listitem><para>The event loop has been created in a different process.</para></listitem>
 284
 285       </varlistentry>
 286
 287       <varlistentry>
 288         <term><constant>-EOPNOTSUPP</constant></term>
 289
 290         <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
 291
 292       </varlistentry>
 293
 294       <varlistentry>
 295         <term><constant>-EDOM</constant></term>
 296
 297         <listitem><para>The passed event source is not a timer event source.</para></listitem>
 298       </varlistentry>
 299     </variablelist>
 300   </refsect1>
 301
 302   <xi:include href="libsystemd-pkgconfig.xml" />
 303
 304   <refsect1>
 305     <title>See Also</title>
 306
 307     <para>
 308       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 309       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 311       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 312       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 313       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 314       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 315       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 316       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 317       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 318       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 319       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 320       <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 321       <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 322       <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 323     </para>
 324   </refsect1>
 325
 326 </refentry>