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+ -->
6 <refentry id=
"sd_event_add_time" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>sd_event_add_time
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>sd_event_add_time
</refentrytitle>
15 <manvolnum>3</manvolnum>
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>
27 <refpurpose>Add a timer event source to an event loop
</refpurpose>
32 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
34 <funcsynopsisinfo><token>typedef
</token> struct sd_event_source sd_event_source;
</funcsynopsisinfo>
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>
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>
55 <funcdef>int
<function>sd_event_add_time_relative
</function></funcdef>
56 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
57 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
58 <paramdef>clockid_t
<parameter>clock
</parameter></paramdef>
59 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
60 <paramdef>uint64_t
<parameter>accuracy
</parameter></paramdef>
61 <paramdef>sd_event_time_handler_t
<parameter>handler
</parameter></paramdef>
62 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
66 <funcdef>int
<function>sd_event_source_get_time
</function></funcdef>
67 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
68 <paramdef>uint64_t *
<parameter>usec
</parameter></paramdef>
72 <funcdef>int
<function>sd_event_source_set_time
</function></funcdef>
73 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
74 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
78 <funcdef>int
<function>sd_event_source_set_time_relative
</function></funcdef>
79 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
80 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
84 <funcdef>int
<function>sd_event_source_get_time_accuracy
</function></funcdef>
85 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
86 <paramdef>uint64_t *
<parameter>usec
</parameter></paramdef>
90 <funcdef>int
<function>sd_event_source_set_time_accuracy
</function></funcdef>
91 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
92 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
96 <funcdef>int
<function>sd_event_source_get_time_clock
</function></funcdef>
97 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
98 <paramdef>clockid_t *
<parameter>clock
</parameter></paramdef>
105 <title>Description
</title>
107 <para><function>sd_event_add_time()
</function> adds a new timer event source to an event loop. The event loop
108 object is specified in the
<parameter>event
</parameter> parameter, the event source object is returned in the
109 <parameter>source
</parameter> parameter. The
<parameter>clock
</parameter> parameter takes a clock identifier, one
110 of
<constant>CLOCK_REALTIME
</constant>,
<constant>CLOCK_MONOTONIC
</constant>,
<constant>CLOCK_BOOTTIME
</constant>,
111 <constant>CLOCK_REALTIME_ALARM
</constant>, or
<constant>CLOCK_BOOTTIME_ALARM
</constant>. See
112 <citerefentry><refentrytitle>timerfd_create
</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details
113 regarding the various types of clocks. The
<parameter>usec
</parameter> parameter specifies the earliest time, in
114 microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past
115 is specified (including
<constant>0</constant>), this timer source
"fires" immediately and is ready to be
116 dispatched. If the parameter is specified as
<constant>UINT64_MAX
</constant> the timer event will never elapse,
117 which may be used as an alternative to explicitly disabling a timer event source with
118 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
119 <parameter>accuracy
</parameter> parameter specifies an additional accuracy value in µs specifying how much the
120 timer event may be delayed. Use
<constant>0</constant> to select the default accuracy (
250ms). Use
1µs for maximum
121 accuracy. Consider specifying
60000000µs (
1min) or larger for long-running events that may be delayed
122 substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively,
123 improving power efficiency. The
<parameter>handler
</parameter> parameter shall reference a function to call when
124 the timer elapses. The handler function will be passed the
<parameter>userdata
</parameter> pointer, which may be
125 chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called
126 slightly later, subject to the specified accuracy value, the kernel timer slack (see
127 <citerefentry><refentrytitle>prctl
</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional
128 scheduling latencies. To query the actual time the handler was called use
129 <citerefentry><refentrytitle>sd_event_now
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
131 <para>By default, the timer will elapse once
132 (
<constant>SD_EVENT_ONESHOT
</constant>), but this may be changed
134 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
135 If the handler function returns a negative error code, it will be
136 disabled after the invocation, even if the
137 <constant>SD_EVENT_ON
</constant> mode was requested before. Note
138 that a timer event set to
<constant>SD_EVENT_ON
</constant> will
139 fire continuously unless its configured time is updated using
140 <function>sd_event_source_set_time()
</function>.
143 <para><function>sd_event_add_time_relative()
</function> is like
<function>sd_event_add_time()
</function>,
144 but takes a relative time specification. It's relative to the current time of the event loop iteration,
146 <citerefentry><refentrytitle>sd_event_now
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
148 <para>To destroy an event source object use
149 <citerefentry><refentrytitle>sd_event_source_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
150 but note that the event source is only removed from the event loop
151 when all references to the event source are dropped. To make sure
152 an event source does not fire anymore, even if it is still referenced,
153 disable the event source using
154 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
155 with
<constant>SD_EVENT_OFF
</constant>.
</para>
157 <para>If the second parameter of
158 <function>sd_event_add_time()
</function> is
159 <constant>NULL
</constant> no reference to the event source object
160 is returned. In this case the event source is considered
161 "floating", and will be destroyed implicitly when the event loop
162 itself is destroyed.
</para>
164 <para>If the
<parameter>handler
</parameter> to
165 <function>sd_event_add_time()
</function> is
166 <constant>NULL
</constant>, and the event source fires, this will
167 be considered a request to exit the event loop. In this case, the
168 <parameter>userdata
</parameter> parameter, cast to an integer, is
169 used for the exit code passed to
170 <citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
172 <para>Use
<constant>CLOCK_BOOTTIME_ALARM
</constant> and
173 <constant>CLOCK_REALTIME_ALARM
</constant> to define event sources
174 that may wake up the system from suspend.
</para>
176 <para>In order to set up relative timers (that is, relative to the
177 current time), retrieve the current time via
178 <citerefentry><refentrytitle>sd_event_now
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
179 add the desired timespan to it, and use the result as
180 the
<parameter>usec
</parameter> parameter to
181 <function>sd_event_add_time()
</function>.
</para>
183 <para>In order to set up repetitive timers (that is, timers that
184 are triggered in regular intervals), set up the timer normally,
185 for the first invocation. Each time the event handler is invoked,
186 update the timer's trigger time with
187 <citerefentry><refentrytitle>sd_event_source_set_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer
188 iteration, and reenable the timer using
189 <function>sd_event_source_set_enabled()
</function>. To calculate
190 the next point in time to pass to
191 <function>sd_event_source_set_time()
</function>, either use as
192 base the
<parameter>usec
</parameter> parameter passed to the timer
193 callback, or the timestamp returned by
194 <function>sd_event_now()
</function>. In the former case timer
195 events will be regular, while in the latter case the scheduling
196 latency will keep accumulating on the timer.
</para>
198 <para><function>sd_event_source_get_time()
</function> retrieves the configured time value of an event
199 source created previously with
<function>sd_event_add_time()
</function> or
200 <function>sd_event_add_time_relative()
</function>. It takes the event source object and a pointer to a
201 variable to store the time in, relative to the selected clock's epoch, in µs. The returned value is
202 relative to the epoch, even if the event source was created with a relative time via
203 <function>sd_event_add_time_relative()
</function>.
</para>
205 <para><function>sd_event_source_set_time()
</function> changes the time of an event source created
206 previously with
<function>sd_event_add_time()
</function> or
207 <function>sd_event_add_time_relative()
</function>. It takes the event source object and a time relative
208 to the selected clock's epoch, in µs.
</para>
210 <para><function>sd_event_source_set_time_relative()
</function> is similar to
211 <function>sd_event_source_set_time()
</function>, but takes a time relative to the current time of the
212 event loop iteration, as returned by
<function>sd_event_now()
</function>.
</para>
214 <para><function>sd_event_source_get_time_accuracy()
</function>
215 retrieves the configured accuracy value of an event source
216 created previously with
<function>sd_event_add_time()
</function>. It
217 takes the event source object and a pointer to a variable to store
218 the accuracy in. The accuracy is specified in µs.
</para>
220 <para><function>sd_event_source_set_time_accuracy()
</function>
221 changes the configured accuracy of a timer event source created
222 previously with
<function>sd_event_add_time()
</function>. It takes
223 the event source object and accuracy, in µs.
</para>
225 <para><function>sd_event_source_get_time_clock()
</function>
226 retrieves the configured clock of an event source created
227 previously with
<function>sd_event_add_time()
</function>. It takes
228 the event source object and a pointer to a variable to store the
229 clock identifier in.
</para>
233 <title>Return Value
</title>
235 <para>On success, these functions return
0 or a positive
236 integer. On failure, they return a negative errno-style error
240 <title>Errors
</title>
242 <para>Returned values may indicate the following problems:
</para>
246 <term><constant>-ENOMEM
</constant></term>
248 <listitem><para>Not enough memory to allocate an object.
</para></listitem>
252 <term><constant>-EINVAL
</constant></term>
254 <listitem><para>An invalid argument has been passed.
</para></listitem>
259 <term><constant>-ESTALE
</constant></term>
261 <listitem><para>The event loop is already terminated.
</para></listitem>
266 <term><constant>-ECHILD
</constant></term>
268 <listitem><para>The event loop has been created in a different process.
</para></listitem>
273 <term><constant>-EOPNOTSUPP
</constant></term>
275 <listitem><para>The selected clock is not supported by the event loop implementation.
</para></listitem>
280 <term><constant>-EDOM
</constant></term>
282 <listitem><para>The passed event source is not a timer event source.
</para></listitem>
286 <term><constant>-EOVERFLOW
</constant></term>
288 <listitem><para>The passed relative time is outside of the allowed range for time values (i.e. the
289 specified value added to the current time is outside the
64 bit unsigned integer range).
</para></listitem>
295 <xi:include href=
"libsystemd-pkgconfig.xml" />
298 <title>See Also
</title>
301 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
302 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
303 <citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
304 <citerefentry><refentrytitle>sd_event_now
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
305 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
306 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
307 <citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
308 <citerefentry><refentrytitle>sd_event_add_inotify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
309 <citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
310 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
311 <citerefentry><refentrytitle>sd_event_source_set_priority
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
312 <citerefentry><refentrytitle>sd_event_source_set_userdata
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
313 <citerefentry><refentrytitle>sd_event_source_set_description
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
314 <citerefentry><refentrytitle>sd_event_source_set_floating
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
315 <citerefentry project='man-pages'
><refentrytitle>clock_gettime
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
316 <citerefentry project='man-pages'
><refentrytitle>timerfd_create
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
317 <citerefentry project='man-pages'
><refentrytitle>prctl
</refentrytitle><manvolnum>2</manvolnum></citerefentry>