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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2014 Lennart Poettering
   9 -->
  10
  11 <refentry id="sd_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude">
  12
  13   <refentryinfo>
  14     <title>sd_event_add_time</title>
  15     <productname>systemd</productname>
  16
  17     <authorgroup>
  18       <author>
  19         <contrib>Developer</contrib>
  20         <firstname>Lennart</firstname>
  21         <surname>Poettering</surname>
  22         <email>lennart@poettering.net</email>
  23       </author>
  24     </authorgroup>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle>sd_event_add_time</refentrytitle>
  29     <manvolnum>3</manvolnum>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname>sd_event_add_time</refname>
  34     <refname>sd_event_source_get_time</refname>
  35     <refname>sd_event_source_set_time</refname>
  36     <refname>sd_event_source_get_time_accuracy</refname>
  37     <refname>sd_event_source_set_time_accuracy</refname>
  38     <refname>sd_event_source_get_time_clock</refname>
  39     <refname>sd_event_time_handler_t</refname>
  40
  41     <refpurpose>Add a timer event source to an event loop</refpurpose>
  42   </refnamediv>
  43
  44   <refsynopsisdiv>
  45     <funcsynopsis>
  46       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  47
  48       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  49
  50       <funcprototype>
  51         <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
  52         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  53         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  54         <paramdef>void *<parameter>userdata</parameter></paramdef>
  55       </funcprototype>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_event_add_time</function></funcdef>
  59         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  60         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  61         <paramdef>clockid_t <parameter>clock</parameter></paramdef>
  62         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  63         <paramdef>uint64_t <parameter>accuracy</parameter></paramdef>
  64         <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef>
  65         <paramdef>void *<parameter>userdata</parameter></paramdef>
  66       </funcprototype>
  67
  68       <funcprototype>
  69         <funcdef>int <function>sd_event_source_get_time</function></funcdef>
  70         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  71         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>int <function>sd_event_source_set_time</function></funcdef>
  76         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  77         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  78       </funcprototype>
  79
  80       <funcprototype>
  81         <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef>
  82         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  83         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  84       </funcprototype>
  85
  86       <funcprototype>
  87         <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef>
  88         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  89         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  90       </funcprototype>
  91
  92       <funcprototype>
  93         <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef>
  94         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  95         <paramdef>clockid_t *<parameter>clock</parameter></paramdef>
  96       </funcprototype>
  97
  98     </funcsynopsis>
  99   </refsynopsisdiv>
 100
 101   <refsect1>
 102     <title>Description</title>
 103
 104     <para><function>sd_event_add_time()</function> adds a new timer event source to an event loop. The event loop
 105     object is specified in the <parameter>event</parameter> parameter, the event source object is returned in the
 106     <parameter>source</parameter> parameter. The <parameter>clock</parameter> parameter takes a clock identifier, one
 107     of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>,
 108     <constant>CLOCK_REALTIME_ALARM</constant>, or <constant>CLOCK_BOOTTIME_ALARM</constant>. See
 109     <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details
 110     regarding the various types of clocks. The <parameter>usec</parameter> parameter specifies the earliest time, in
 111     microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past
 112     is specified (including <constant>0</constant>), this timer source "fires" immediately and is ready to be
 113     dispatched. If the parameter is specified as <constant>UINT64_MAX</constant> the timer event will never elapse,
 114     which may be used as an alternative to explicitly disabling a timer event source with
 115     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
 116     <parameter>accuracy</parameter> parameter specifies an additional accuracy value in µs specifying how much the
 117     timer event may be delayed. Use <constant>0</constant> to select the default accuracy (250ms). Use 1µs for maximum
 118     accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed
 119     substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively,
 120     improving power efficiency. The <parameter>handler</parameter> parameter shall reference a function to call when
 121     the timer elapses. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be
 122     chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called
 123     slightly later, subject to the specified accuracy value, the kernel timer slack (see
 124     <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional
 125     scheduling latencies. To query the actual time the handler was called use
 126     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 127
 128     <para>By default, the timer will elapse once
 129     (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
 130     with
 131     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 132     If the handler function returns a negative error code, it will be
 133     disabled after the invocation, even if the
 134     <constant>SD_EVENT_ON</constant> mode was requested before. Note
 135     that a timer event set to <constant>SD_EVENT_ON</constant> will
 136     fire continuously unless its configured time is updated using
 137     <function>sd_event_source_set_time()</function>.
 138     </para>
 139
 140     <para>To destroy an event source object use
 141     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142     but note that the event source is only removed from the event loop
 143     when all references to the event source are dropped. To make sure
 144     an event source does not fire anymore, even if it is still referenced,
 145     disable the event source using
 146     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 147     with <constant>SD_EVENT_OFF</constant>.</para>
 148
 149     <para>If the second parameter of
 150     <function>sd_event_add_time()</function> is
 151     <constant>NULL</constant> no reference to the event source object
 152     is returned. In this case the event source is considered
 153     "floating", and will be destroyed implicitly when the event loop
 154     itself is destroyed.</para>
 155
 156     <para>If the <parameter>handler</parameter> to
 157     <function>sd_event_add_time()</function> is
 158     <constant>NULL</constant>, and the event source fires, this will
 159     be considered a request to exit the event loop. In this case, the
 160     <parameter>userdata</parameter> parameter, cast to an integer, is
 161     used for the exit code passed to
 162     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 163
 164     <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
 165     <constant>CLOCK_REALTIME_ALARM</constant> to define event sources
 166     that may wake up the system from suspend.</para>
 167
 168     <para>In order to set up relative timers (that is, relative to the
 169     current time), retrieve the current time via
 170     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 171     add the desired timespan to it, and use the result as
 172     the <parameter>usec</parameter> parameter to
 173     <function>sd_event_add_time()</function>.</para>
 174
 175     <para>In order to set up repetitive timers (that is, timers that
 176     are triggered in regular intervals), set up the timer normally,
 177     for the first invocation. Each time the event handler is invoked,
 178     update the timer's trigger time with
 179     <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer
 180     iteration, and reenable the timer using
 181     <function>sd_event_source_set_enabled()</function>. To calculate
 182     the next point in time to pass to
 183     <function>sd_event_source_set_time()</function>, either use as
 184     base the <parameter>usec</parameter> parameter passed to the timer
 185     callback, or the timestamp returned by
 186     <function>sd_event_now()</function>. In the former case timer
 187     events will be regular, while in the latter case the scheduling
 188     latency will keep accumulating on the timer.</para>
 189
 190     <para><function>sd_event_source_get_time()</function> retrieves
 191     the configured time value of an event source created
 192     previously with <function>sd_event_add_time()</function>. It takes
 193     the event source object and a pointer to a variable to store the
 194     time in, relative to the selected clock's epoch, in µs.</para>
 195
 196     <para><function>sd_event_source_set_time()</function> changes the
 197     time of an event source created previously with
 198     <function>sd_event_add_time()</function>. It takes the event
 199     source object and a time relative to the selected clock's epoch,
 200     in µs.</para>
 201
 202     <para><function>sd_event_source_get_time_accuracy()</function>
 203     retrieves the configured accuracy value of an event source
 204     created previously with <function>sd_event_add_time()</function>. It
 205     takes the event source object and a pointer to a variable to store
 206     the accuracy in. The accuracy is specified in µs.</para>
 207
 208     <para><function>sd_event_source_set_time_accuracy()</function>
 209     changes the configured accuracy of a timer event source created
 210     previously with <function>sd_event_add_time()</function>. It takes
 211     the event source object and accuracy, in µs.</para>
 212
 213     <para><function>sd_event_source_get_time_clock()</function>
 214     retrieves the configured clock of an event source created
 215     previously with <function>sd_event_add_time()</function>. It takes
 216     the event source object and a pointer to a variable to store the
 217     clock identifier in.</para>
 218   </refsect1>
 219
 220   <refsect1>
 221     <title>Return Value</title>
 222
 223     <para>On success, these functions return 0 or a positive
 224     integer. On failure, they return a negative errno-style error
 225     code. </para>
 226   </refsect1>
 227
 228   <refsect1>
 229     <title>Errors</title>
 230
 231     <para>Returned values may indicate the following problems:</para>
 232
 233     <variablelist>
 234       <varlistentry>
 235         <term><constant>-ENOMEM</constant></term>
 236
 237         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><constant>-EINVAL</constant></term>
 242
 243         <listitem><para>An invalid argument has been passed.</para></listitem>
 244
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><constant>-ESTALE</constant></term>
 249
 250         <listitem><para>The event loop is already terminated.</para></listitem>
 251
 252       </varlistentry>
 253
 254       <varlistentry>
 255         <term><constant>-ECHILD</constant></term>
 256
 257         <listitem><para>The event loop has been created in a different process.</para></listitem>
 258
 259       </varlistentry>
 260
 261       <varlistentry>
 262         <term><constant>-EOPNOTSUPP</constant></term>
 263
 264         <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
 265
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term><constant>-EDOM</constant></term>
 270
 271         <listitem><para>The passed event source is not a timer event source.</para></listitem>
 272       </varlistentry>
 273     </variablelist>
 274   </refsect1>
 275
 276   <xi:include href="libelogind-pkgconfig.xml" />
 277
 278   <refsect1>
 279     <title>See Also</title>
 280
 281     <para>
 282       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 283       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 284       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 285       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 286       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 287       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 288       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 289       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 290       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 291       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 292       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 293       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 294       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 295       <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 296       <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 297       <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 298     </para>
 299   </refsect1>
 300
 301 </refentry>