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 event source to an event loop. The event loop
 118     object is specified in the <parameter>event</parameter> parameter, the event source object is returned in the
 119     <parameter>source</parameter> parameter. The <parameter>clock</parameter> parameter takes a clock identifier, one
 120     of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>,
 121     <constant>CLOCK_REALTIME_ALARM</constant>, or <constant>CLOCK_BOOTTIME_ALARM</constant>. See
 122     <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details
 123     regarding the various types of clocks. The <parameter>usec</parameter> parameter specifies the earliest time, in
 124     microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past
 125     is specified (including <constant>0</constant>), this timer source "fires" immediately and is ready to be
 126     dispatched. If the parameter is specified as <constant>UINT64_MAX</constant> the timer event will never elapse,
 127     which may be used as an alternative to explicitly disabling a timer event source with
 128     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
 129     <parameter>accuracy</parameter> parameter specifies an additional accuracy value in µs specifying how much the
 130     timer event may be delayed. Use <constant>0</constant> to select the default accuracy (250ms). Use 1µs for maximum
 131     accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed
 132     substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively,
 133     improving power efficiency. The <parameter>handler</parameter> parameter shall reference a function to call when
 134     the timer elapses. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be
 135     chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called
 136     slightly later, subject to the specified accuracy value, the kernel timer slack (see
 137     <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional
 138     scheduling latencies. To query the actual time the handler was called use
 139     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 140
 141     <para>By default, the timer will elapse once
 142     (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
 143     with
 144     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 145     If the handler function returns a negative error code, it will be
 146     disabled after the invocation, even if the
 147     <constant>SD_EVENT_ON</constant> mode was requested before. Note
 148     that a timer event set to <constant>SD_EVENT_ON</constant> will
 149     fire continuously unless its configured time is updated using
 150     <function>sd_event_source_set_time()</function>.
 151     </para>
 152
 153     <para>To destroy an event source object use
 154     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 155     but note that the event source is only removed from the event loop
 156     when all references to the event source are dropped. To make sure
 157     an event source does not fire anymore, even if it is still referenced,
 158     disable the event source using
 159     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 160     with <constant>SD_EVENT_OFF</constant>.</para>
 161
 162     <para>If the second parameter of
 163     <function>sd_event_add_time()</function> is
 164     <constant>NULL</constant> no reference to the event source object
 165     is returned. In this case the event source is considered
 166     "floating", and will be destroyed implicitly when the event loop
 167     itself is destroyed.</para>
 168
 169     <para>If the <parameter>handler</parameter> to
 170     <function>sd_event_add_time()</function> is
 171     <constant>NULL</constant>, and the event source fires, this will
 172     be considered a request to exit the event loop. In this case, the
 173     <parameter>userdata</parameter> parameter, cast to an integer, is
 174     used for the exit code passed to
 175     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 176
 177     <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
 178     <constant>CLOCK_REALTIME_ALARM</constant> to define event sources
 179     that may wake up the system from suspend.</para>
 180
 181     <para>In order to set up relative timers (that is, relative to the
 182     current time), retrieve the current time via
 183     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184     add the desired timespan to it, and use the result as
 185     the <parameter>usec</parameter> parameter to
 186     <function>sd_event_add_time()</function>.</para>
 187
 188     <para>In order to set up repetitive timers (that is, timers that
 189     are triggered in regular intervals), set up the timer normally,
 190     for the first invocation. Each time the event handler is invoked,
 191     update the timer's trigger time with
 192     <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer
 193     iteration, and reenable the timer using
 194     <function>sd_event_source_set_enabled()</function>. To calculate
 195     the next point in time to pass to
 196     <function>sd_event_source_set_time()</function>, either use as
 197     base the <parameter>usec</parameter> parameter passed to the timer
 198     callback, or the timestamp returned by
 199     <function>sd_event_now()</function>. In the former case timer
 200     events will be regular, while in the latter case the scheduling
 201     latency will keep accumulating on the timer.</para>
 202
 203     <para><function>sd_event_source_get_time()</function> retrieves
 204     the configured time value of an event source created
 205     previously with <function>sd_event_add_time()</function>. It takes
 206     the event source object and a pointer to a variable to store the
 207     time in, relative to the selected clock's epoch, in µs.</para>
 208
 209     <para><function>sd_event_source_set_time()</function> changes the
 210     time of an event source created previously with
 211     <function>sd_event_add_time()</function>. It takes the event
 212     source object and a time relative to the selected clock's epoch,
 213     in µs.</para>
 214
 215     <para><function>sd_event_source_get_time_accuracy()</function>
 216     retrieves the configured accuracy value of an event source
 217     created previously with <function>sd_event_add_time()</function>. It
 218     takes the event source object and a pointer to a variable to store
 219     the accuracy in. The accuracy is specified in µs.</para>
 220
 221     <para><function>sd_event_source_set_time_accuracy()</function>
 222     changes the configured accuracy of a timer event source created
 223     previously with <function>sd_event_add_time()</function>. It takes
 224     the event source object and accuracy, in µs.</para>
 225
 226     <para><function>sd_event_source_get_time_clock()</function>
 227     retrieves the configured clock of an event source created
 228     previously with <function>sd_event_add_time()</function>. It takes
 229     the event source object and a pointer to a variable to store the
 230     clock identifier in.</para>
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>Return Value</title>
 235
 236     <para>On success, these functions return 0 or a positive
 237     integer. On failure, they return a negative errno-style error
 238     code. </para>
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>Errors</title>
 243
 244     <para>Returned values may indicate the following problems:</para>
 245
 246     <variablelist>
 247       <varlistentry>
 248         <term><constant>-ENOMEM</constant></term>
 249
 250         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 251       </varlistentry>
 252
 253       <varlistentry>
 254         <term><constant>-EINVAL</constant></term>
 255
 256         <listitem><para>An invalid argument has been passed.</para></listitem>
 257
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term><constant>-ESTALE</constant></term>
 262
 263         <listitem><para>The event loop is already terminated.</para></listitem>
 264
 265       </varlistentry>
 266
 267       <varlistentry>
 268         <term><constant>-ECHILD</constant></term>
 269
 270         <listitem><para>The event loop has been created in a different process.</para></listitem>
 271
 272       </varlistentry>
 273
 274       <varlistentry>
 275         <term><constant>-EOPNOTSUPP</constant></term>
 276
 277         <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
 278
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term><constant>-EDOM</constant></term>
 283
 284         <listitem><para>The passed event source is not a timer event source.</para></listitem>
 285       </varlistentry>
 286     </variablelist>
 287   </refsect1>
 288
 289   <xi:include href="libelogind-pkgconfig.xml" />
 290
 291   <refsect1>
 292     <title>See Also</title>
 293
 294     <para>
 295       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 296       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 297       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 298       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 299       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 300       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 301       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 302       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 303       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 304       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 305       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 306       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 307       <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 308       <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 309       <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 310     </para>
 311   </refsect1>
 312
 313 </refentry>