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