man/sd_event_add_time.xml

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