]>
Commit | Line | Data |
---|---|---|
514094f9 | 1 | <?xml version='1.0'?> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
b408026b | 5 | |
dc83f27a | 6 | <refentry id="sd_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude"> |
b408026b LP |
7 | |
8 | <refentryinfo> | |
9 | <title>sd_event_add_time</title> | |
10 | <productname>systemd</productname> | |
b408026b LP |
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> | |
af8e5714 | 20 | <refname>sd_event_add_time_relative</refname> |
b408026b LP |
21 | <refname>sd_event_source_get_time</refname> |
22 | <refname>sd_event_source_set_time</refname> | |
af8e5714 | 23 | <refname>sd_event_source_set_time_relative</refname> |
b408026b LP |
24 | <refname>sd_event_source_get_time_accuracy</refname> |
25 | <refname>sd_event_source_set_time_accuracy</refname> | |
26 | <refname>sd_event_source_get_time_clock</refname> | |
dc83f27a | 27 | <refname>sd_event_time_handler_t</refname> |
b408026b LP |
28 | |
29 | <refpurpose>Add a timer event source to an event loop</refpurpose> | |
30 | </refnamediv> | |
31 | ||
32 | <refsynopsisdiv> | |
33 | <funcsynopsis> | |
dc83f27a LP |
34 | <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> |
35 | ||
36 | <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> | |
37 | ||
38 | <funcprototype> | |
39 | <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef> | |
40 | <paramdef>sd_event_source *<parameter>s</parameter></paramdef> | |
41 | <paramdef>uint64_t <parameter>usec</parameter></paramdef> | |
42 | <paramdef>void *<parameter>userdata</parameter></paramdef> | |
43 | </funcprototype> | |
b408026b LP |
44 | |
45 | <funcprototype> | |
46 | <funcdef>int <function>sd_event_add_time</function></funcdef> | |
47 | <paramdef>sd_event *<parameter>event</parameter></paramdef> | |
48 | <paramdef>sd_event_source **<parameter>source</parameter></paramdef> | |
49 | <paramdef>clockid_t <parameter>clock</parameter></paramdef> | |
50 | <paramdef>uint64_t <parameter>usec</parameter></paramdef> | |
51 | <paramdef>uint64_t <parameter>accuracy</parameter></paramdef> | |
52 | <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef> | |
3b3d7d06 | 53 | <paramdef>void *<parameter>userdata</parameter></paramdef> |
b408026b LP |
54 | </funcprototype> |
55 | ||
4c5e74f7 LP |
56 | <funcprototype> |
57 | <funcdef>int <function>sd_event_add_time_relative</function></funcdef> | |
58 | <paramdef>sd_event *<parameter>event</parameter></paramdef> | |
59 | <paramdef>sd_event_source **<parameter>source</parameter></paramdef> | |
60 | <paramdef>clockid_t <parameter>clock</parameter></paramdef> | |
61 | <paramdef>uint64_t <parameter>usec</parameter></paramdef> | |
62 | <paramdef>uint64_t <parameter>accuracy</parameter></paramdef> | |
63 | <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef> | |
64 | <paramdef>void *<parameter>userdata</parameter></paramdef> | |
65 | </funcprototype> | |
66 | ||
b408026b LP |
67 | <funcprototype> |
68 | <funcdef>int <function>sd_event_source_get_time</function></funcdef> | |
69 | <paramdef>sd_event_source *<parameter>source</parameter></paramdef> | |
dc83f27a | 70 | <paramdef>uint64_t *<parameter>usec</parameter></paramdef> |
b408026b LP |
71 | </funcprototype> |
72 | ||
73 | <funcprototype> | |
74 | <funcdef>int <function>sd_event_source_set_time</function></funcdef> | |
75 | <paramdef>sd_event_source *<parameter>source</parameter></paramdef> | |
dc83f27a | 76 | <paramdef>uint64_t <parameter>usec</parameter></paramdef> |
b408026b LP |
77 | </funcprototype> |
78 | ||
4c5e74f7 LP |
79 | <funcprototype> |
80 | <funcdef>int <function>sd_event_source_set_time_relative</function></funcdef> | |
81 | <paramdef>sd_event_source *<parameter>source</parameter></paramdef> | |
82 | <paramdef>uint64_t <parameter>usec</parameter></paramdef> | |
83 | </funcprototype> | |
84 | ||
b408026b LP |
85 | <funcprototype> |
86 | <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef> | |
87 | <paramdef>sd_event_source *<parameter>source</parameter></paramdef> | |
dc83f27a | 88 | <paramdef>uint64_t *<parameter>usec</parameter></paramdef> |
b408026b LP |
89 | </funcprototype> |
90 | ||
91 | <funcprototype> | |
92 | <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef> | |
93 | <paramdef>sd_event_source *<parameter>source</parameter></paramdef> | |
dc83f27a | 94 | <paramdef>uint64_t <parameter>usec</parameter></paramdef> |
b408026b LP |
95 | </funcprototype> |
96 | ||
97 | <funcprototype> | |
98 | <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef> | |
99 | <paramdef>sd_event_source *<parameter>source</parameter></paramdef> | |
100 | <paramdef>clockid_t *<parameter>clock</parameter></paramdef> | |
101 | </funcprototype> | |
102 | ||
103 | </funcsynopsis> | |
104 | </refsynopsisdiv> | |
105 | ||
106 | <refsect1> | |
107 | <title>Description</title> | |
108 | ||
393003e1 LP |
109 | <para><function>sd_event_add_time()</function> adds a new timer event source to an event loop. The event loop |
110 | object is specified in the <parameter>event</parameter> parameter, the event source object is returned in the | |
111 | <parameter>source</parameter> parameter. The <parameter>clock</parameter> parameter takes a clock identifier, one | |
112 | of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>, | |
113 | <constant>CLOCK_REALTIME_ALARM</constant>, or <constant>CLOCK_BOOTTIME_ALARM</constant>. See | |
114 | <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details | |
115 | regarding the various types of clocks. The <parameter>usec</parameter> parameter specifies the earliest time, in | |
e503019b | 116 | microseconds (μs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past |
393003e1 | 117 | is specified (including <constant>0</constant>), this timer source "fires" immediately and is ready to be |
595bfe7d | 118 | dispatched. If the parameter is specified as <constant>UINT64_MAX</constant> the timer event will never elapse, |
393003e1 LP |
119 | which may be used as an alternative to explicitly disabling a timer event source with |
120 | <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The | |
e503019b LP |
121 | <parameter>accuracy</parameter> parameter specifies an additional accuracy value in μs specifying how much the |
122 | timer event may be delayed. Use <constant>0</constant> to select the default accuracy (250ms). Use 1μs for maximum | |
123 | accuracy. Consider specifying 60000000μs (1min) or larger for long-running events that may be delayed | |
393003e1 | 124 | substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, |
9809a788 ZJS |
125 | improving power efficiency.</para> |
126 | ||
127 | <para>The <parameter>handler</parameter> is a function to call when the timer elapses or | |
128 | <constant>NULL</constant>. The <parameter>userdata</parameter> pointer will be passed to the handler | |
129 | function, and may be chosen freely by the caller. The configured trigger time is also passed to the | |
130 | handler, even if the call actually happens slightly later, subject to the specified accuracy value, the | |
131 | kernel timer slack (see | |
132 | <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and | |
133 | additional scheduling latencies. To query the actual time the handler was called use | |
134 | <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The | |
135 | handler may return negative to signal an error (see below), other return values are ignored. If | |
136 | <parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls | |
137 | <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be | |
138 | used.</para> | |
139 | ||
140 | <para>By default, the timer will elapse once (<constant>SD_EVENT_ONESHOT</constant>), but this may be | |
141 | changed with | |
3144ebca | 142 | <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. |
9809a788 ZJS |
143 | If the handler function returns a negative error code, it will either be disabled after the invocation, |
144 | even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the loop to | |
145 | terminate, see | |
146 | <citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
147 | Note that a timer event set to <constant>SD_EVENT_ON</constant> will fire continuously unless its | |
148 | configured time is updated using <function>sd_event_source_set_time()</function>.</para> | |
b408026b | 149 | |
4c5e74f7 LP |
150 | <para><function>sd_event_add_time_relative()</function> is like <function>sd_event_add_time()</function>, |
151 | but takes a relative time specification. It's relative to the current time of the event loop iteration, | |
152 | as returned by | |
153 | <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> | |
154 | ||
dc83f27a LP |
155 | <para>To destroy an event source object use |
156 | <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
157 | but note that the event source is only removed from the event loop | |
158 | when all references to the event source are dropped. To make sure | |
f23e83b1 ZJS |
159 | an event source does not fire anymore, even if it is still referenced, |
160 | disable the event source using | |
161 | <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
162 | with <constant>SD_EVENT_OFF</constant>.</para> | |
dc83f27a | 163 | |
7f3fdb7f | 164 | <para>If the second parameter of |
f23e83b1 ZJS |
165 | <function>sd_event_add_time()</function> is |
166 | <constant>NULL</constant> no reference to the event source object | |
167 | is returned. In this case the event source is considered | |
168 | "floating", and will be destroyed implicitly when the event loop | |
169 | itself is destroyed.</para> | |
dc83f27a | 170 | |
b9350e70 LP |
171 | <para>If the <parameter>handler</parameter> parameter to <function>sd_event_add_time()</function> is |
172 | <constant>NULL</constant>, and the event source fires, this will be considered a request to exit the | |
173 | event loop. In this case, the <parameter>userdata</parameter> parameter, cast to an integer, is passed as | |
174 | the exit code parameter to | |
dc83f27a LP |
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>, | |
f23e83b1 | 184 | add the desired timespan to it, and use the result as |
dc83f27a LP |
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 | ||
4c5e74f7 LP |
203 | <para><function>sd_event_source_get_time()</function> retrieves the configured time value of an event |
204 | source created previously with <function>sd_event_add_time()</function> or | |
205 | <function>sd_event_add_time_relative()</function>. It takes the event source object and a pointer to a | |
e503019b | 206 | variable to store the time in, relative to the selected clock's epoch, in μs. The returned value is |
4c5e74f7 LP |
207 | relative to the epoch, even if the event source was created with a relative time via |
208 | <function>sd_event_add_time_relative()</function>.</para> | |
209 | ||
210 | <para><function>sd_event_source_set_time()</function> changes the time of an event source created | |
211 | previously with <function>sd_event_add_time()</function> or | |
212 | <function>sd_event_add_time_relative()</function>. It takes the event source object and a time relative | |
e503019b | 213 | to the selected clock's epoch, in μs.</para> |
b408026b | 214 | |
4c5e74f7 LP |
215 | <para><function>sd_event_source_set_time_relative()</function> is similar to |
216 | <function>sd_event_source_set_time()</function>, but takes a time relative to the current time of the | |
217 | event loop iteration, as returned by <function>sd_event_now()</function>.</para> | |
b408026b LP |
218 | |
219 | <para><function>sd_event_source_get_time_accuracy()</function> | |
037a3ded | 220 | retrieves the configured accuracy value of an event source |
b408026b LP |
221 | created previously with <function>sd_event_add_time()</function>. It |
222 | takes the event source object and a pointer to a variable to store | |
e503019b | 223 | the accuracy in. The accuracy is specified in μs.</para> |
b408026b LP |
224 | |
225 | <para><function>sd_event_source_set_time_accuracy()</function> | |
226 | changes the configured accuracy of a timer event source created | |
227 | previously with <function>sd_event_add_time()</function>. It takes | |
e503019b | 228 | the event source object and accuracy, in μs.</para> |
b408026b LP |
229 | |
230 | <para><function>sd_event_source_get_time_clock()</function> | |
037a3ded | 231 | retrieves the configured clock of an event source created |
b408026b LP |
232 | previously with <function>sd_event_add_time()</function>. It takes |
233 | the event source object and a pointer to a variable to store the | |
234 | clock identifier in.</para> | |
b408026b LP |
235 | </refsect1> |
236 | ||
237 | <refsect1> | |
238 | <title>Return Value</title> | |
239 | ||
240 | <para>On success, these functions return 0 or a positive | |
241 | integer. On failure, they return a negative errno-style error | |
242 | code. </para> | |
b408026b | 243 | |
b1de39de ZJS |
244 | <refsect2> |
245 | <title>Errors</title> | |
b408026b | 246 | |
b1de39de | 247 | <para>Returned values may indicate the following problems:</para> |
b408026b | 248 | |
b1de39de ZJS |
249 | <variablelist> |
250 | <varlistentry> | |
251 | <term><constant>-ENOMEM</constant></term> | |
b408026b | 252 | |
b1de39de ZJS |
253 | <listitem><para>Not enough memory to allocate an object.</para></listitem> |
254 | </varlistentry> | |
b408026b | 255 | |
b1de39de ZJS |
256 | <varlistentry> |
257 | <term><constant>-EINVAL</constant></term> | |
b408026b | 258 | |
b1de39de | 259 | <listitem><para>An invalid argument has been passed.</para></listitem> |
b408026b | 260 | |
b1de39de | 261 | </varlistentry> |
b408026b | 262 | |
b1de39de ZJS |
263 | <varlistentry> |
264 | <term><constant>-ESTALE</constant></term> | |
b408026b | 265 | |
b1de39de | 266 | <listitem><para>The event loop is already terminated.</para></listitem> |
b408026b | 267 | |
b1de39de | 268 | </varlistentry> |
b408026b | 269 | |
b1de39de ZJS |
270 | <varlistentry> |
271 | <term><constant>-ECHILD</constant></term> | |
b408026b | 272 | |
2eeff0f4 | 273 | <listitem><para>The event loop has been created in a different process, library or module instance.</para></listitem> |
b408026b | 274 | |
b1de39de | 275 | </varlistentry> |
b408026b | 276 | |
b1de39de ZJS |
277 | <varlistentry> |
278 | <term><constant>-EOPNOTSUPP</constant></term> | |
b408026b | 279 | |
b1de39de | 280 | <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem> |
b408026b | 281 | |
b1de39de | 282 | </varlistentry> |
b408026b | 283 | |
b1de39de ZJS |
284 | <varlistentry> |
285 | <term><constant>-EDOM</constant></term> | |
b408026b | 286 | |
b1de39de ZJS |
287 | <listitem><para>The passed event source is not a timer event source.</para></listitem> |
288 | </varlistentry> | |
4c5e74f7 LP |
289 | |
290 | <varlistentry> | |
291 | <term><constant>-EOVERFLOW</constant></term> | |
292 | ||
293 | <listitem><para>The passed relative time is outside of the allowed range for time values (i.e. the | |
ec07c3c8 AK |
294 | specified value added to the current time is outside the 64 bit unsigned integer range).</para> |
295 | ||
296 | <xi:include href="version-info.xml" xpointer="v247"/></listitem> | |
4c5e74f7 | 297 | </varlistentry> |
b1de39de ZJS |
298 | </variablelist> |
299 | </refsect2> | |
b408026b LP |
300 | </refsect1> |
301 | ||
dc83f27a LP |
302 | <xi:include href="libsystemd-pkgconfig.xml" /> |
303 | ||
69106f47 AK |
304 | <refsect1> |
305 | <title>History</title> | |
00f95506 AK |
306 | <para><function>sd_event_add_time()</function>, |
307 | <function>sd_event_source_get_time()</function>, | |
308 | <function>sd_event_source_set_time()</function>, | |
309 | <function>sd_event_source_get_time_accuracy()</function>, | |
310 | <function>sd_event_source_set_time_accuracy()</function>, and | |
311 | <function>sd_event_source_get_time_clock()</function> were added in version 213.</para> | |
312 | <para><function>sd_event_time_handler_t()</function> was added in version 217.</para> | |
313 | <para><function>sd_event_add_time_relative()</function> and | |
314 | <function>sd_event_source_set_time_relative()</function> were added in version 247.</para> | |
69106f47 AK |
315 | </refsect1> |
316 | ||
b408026b LP |
317 | <refsect1> |
318 | <title>See Also</title> | |
319 | ||
13a69c12 DT |
320 | <para><simplelist type="inline"> |
321 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
322 | <member><citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
323 | <member><citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
324 | <member><citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
325 | <member><citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
326 | <member><citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
327 | <member><citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
328 | <member><citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
329 | <member><citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
330 | <member><citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
331 | <member><citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
332 | <member><citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
333 | <member><citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
334 | <member><citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
335 | <member><citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry></member> | |
336 | <member><citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry></member> | |
337 | <member><citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry></member> | |
338 | </simplelist></para> | |
b408026b LP |
339 | </refsect1> |
340 | ||
341 | </refentry> |