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