Cross Reference: /systemd/man/sd_event_add_time.xml
sd_event_add_time.xml revision 7f3fdb7f19a109fa3d1be92926bfe4cea1817da5
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering<!--
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek This file is part of systemd.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Copyright 2014 Lennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek (at your option) any later version.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering-->
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<refentry id="sd_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude">
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refentryinfo>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <title>sd_event_add_time</title>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <productname>systemd</productname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <authorgroup>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <author>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <contrib>Developer</contrib>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <firstname>Lennart</firstname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <surname>Poettering</surname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <email>lennart@poettering.net</email>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </author>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </authorgroup>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refentryinfo>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refmeta>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refentrytitle>sd_event_add_time</refentrytitle>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <manvolnum>3</manvolnum>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refmeta>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refnamediv>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_add_time</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_get_time</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_set_time</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_get_time_accuracy</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_set_time_accuracy</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refname>sd_event_source_get_time_clock</refname>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refname>sd_event_time_handler_t</refname>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refpurpose>Add a timer event source to an event loop</refpurpose>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refnamediv>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refsynopsisdiv>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcsynopsis>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>uint64_t <parameter>usec</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>void *<parameter>userdata</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_add_time</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event *<parameter>event</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>clockid_t <parameter>clock</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>uint64_t <parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>uint64_t <parameter>accuracy</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef>
3b3d7d069d10d53336dbada1c67f739e3492b218Jan Engelhardt <paramdef>void *<parameter>userdata</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_get_time</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_set_time</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>uint64_t <parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>uint64_t <parameter>usec</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <paramdef>clockid_t *<parameter>clock</parameter></paramdef>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcprototype>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </funcsynopsis>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refsynopsisdiv>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refsect1>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <title>Description</title>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_add_time()</function> adds a new timer
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering event source to an event loop. The event loop object is specified
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering in the <parameter>event</parameter> parameter, the event source
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering object is returned in the <parameter>source</parameter>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering parameter. The <parameter>clock</parameter> parameter takes a
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering clock identifier, one of <constant>CLOCK_REALTIME</constant>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>CLOCK_MONOTONIC</constant>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>CLOCK_BOOTTIME</constant>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>CLOCK_REALTIME_ALARM</constant> or
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <constant>CLOCK_BOOTTIME_ALARM</constant>. See
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering for details regarding the various types of clocks. The
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <parameter>usec</parameter> parameter takes a time value in
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering microseconds (µs), relative to the clock's epoch, specifying when
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the timer shall elapse the earliest. If a time that already lies
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering in the past is specified (including 0), the timer source is
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering dispatched immediately in the next event loop iterations. The
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <parameter>accuracy</parameter> parameter takes an additional
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering accuracy value in µs specifying a time the timer event may be
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering delayed. Specify 0 for selecting the default accuracy
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering (250ms). Specify 1µs for most accurate timers. Consider specifying
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering 60000000µs or larger (1min) for long-running events that may be
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering delayed substantially. Picking higher accuracy values allows the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering system to coalesce timer events more aggressively, thus improving
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering power efficiency. The <parameter>handler</parameter> parameter
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering shall reference a function to call when the timer elapses. The
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering handler function will be passed the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <parameter>userdata</parameter> pointer, which may be chosen
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering freely by the caller. The handler is also passed the configured
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering time it was triggered, however it might actually have been called
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering at a slightly later time, subject to the specified accuracy value,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the kernel timer slack (see
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering and additional scheduling latencies. To query the actual time the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering handler was called use
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
3144ebcad37422dd85220915d37e7e9eea36564aZbigniew Jędrzejewski-Szmek
3144ebcad37422dd85220915d37e7e9eea36564aZbigniew Jędrzejewski-Szmek <para>By default, the timer will elapse once
3144ebcad37422dd85220915d37e7e9eea36564aZbigniew Jędrzejewski-Szmek (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
3144ebcad37422dd85220915d37e7e9eea36564aZbigniew Jędrzejewski-Szmek with
3144ebcad37422dd85220915d37e7e9eea36564aZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
3144ebcad37422dd85220915d37e7e9eea36564aZbigniew Jędrzejewski-Szmek If the handler function returns a negative error code, it will be
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering disabled after the invocation, even if the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>SD_EVENT_ON</constant> mode was requested before. Note
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering that a timer event set to <constant>SD_EVENT_ON</constant> will
7f3fdb7f19a109fa3d1be92926bfe4cea1817da5Jakub Wilk fire continuously unless its configured time is updated using
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_source_set_time()</function>.
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>To destroy an event source object use
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering but note that the event source is only removed from the event loop
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering when all references to the event source are dropped. To make sure
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering an event source does not fire anymore, even when there's still a
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering reference to it kept, consider setting the event source to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>SD_EVENT_OFF</constant> with
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
7f3fdb7f19a109fa3d1be92926bfe4cea1817da5Jakub Wilk <para>If the second parameter of
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_add_time()</function> is passed as NULL no
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering reference to the event source object is returned. In this case the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering event source is considered "floating", and will be destroyed
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering implicitly when the event loop itself is destroyed.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>If the <parameter>handler</parameter> to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_add_time()</function> is passed as NULL, and
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the event source fires, this will be considered a request to exit
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the event loop. In this case, the <parameter>userdata</parameter>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering parameter, cast to an integer is used for the exit code passed to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>CLOCK_REALTIME_ALARM</constant> to define event sources
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering that may wake up the system from suspend.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>In order to set up relative timers (that is, relative to the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering current time), retrieve the current time via
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering add the desired timespan to sleep to it, and pass the result as
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the <parameter>usec</parameter> parameter to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_add_time()</function>.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>In order to set up repetitive timers (that is, timers that
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering are triggered in regular intervals), set up the timer normally,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering for the first invocation. Each time the event handler is invoked,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering update the timer's trigger time with
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering iteration, and reenable the timer using
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_source_set_enabled()</function>. To calculate
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the next point in time to pass to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_source_set_time()</function>, either use as
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering base the <parameter>usec</parameter> parameter passed to the timer
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering callback, or the timestamp returned by
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_now()</function>. In the former case timer
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering events will be regular, while in the latter case the scheduling
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering latency will keep accumulating on the timer.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_get_time()</function> retrieves
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the configured time value of a timer event source created
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering previously with <function>sd_event_add_time()</function>. It takes
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the event source object and a pointer to a variable to store the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering time, relative to the selected clock's epoch, in µs in.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_set_time()</function> changes the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering configured time value of a timer event source created previously
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering with <function>sd_event_add_time()</function>. It takes the event
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering source object and a time relative to the selected clock's
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering epoch, in µs.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_get_time_accuracy()</function>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering retrieves the configured accuracy value of a timer event source
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering created previously with <function>sd_event_add_time()</function>. It
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering takes the event source object and a pointer to a variable to store
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the accuracy in µs in.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_set_time_accuracy()</function>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering changes the configured accuracy of a timer event source created
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering previously with <function>sd_event_add_time()</function>. It takes
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the event source object and an accuracy, in µs.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para><function>sd_event_source_get_time_clock()</function>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering retrieves the configured clock of a timer event source created
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering previously with <function>sd_event_add_time()</function>. It takes
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering the event source object and a pointer to a variable to store the
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering clock identifier in.</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refsect1>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refsect1>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <title>Return Value</title>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para>On success, these functions return 0 or a positive
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering integer. On failure, they return a negative errno-style error
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering code. </para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refsect1>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refsect1>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <title>Errors</title>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para>Returned errors may indicate the following problems:</para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <variablelist>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ENOMEM</constant></term>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
3144ebcad37422dd85220915d37e7e9eea36564aZbigniew Jędrzejewski-Szmek <listitem><para>Not enough memory to allocate an object.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-EINVAL</constant></term>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>An invalid argument has been passed.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ESTALE</constant></term>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>The event loop is already terminated.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ECHILD</constant></term>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>The event loop has been created in a different process.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <varlistentry>
15411c0cb1192799b37ec8f25d6f30e8d7292fc6David Herrmann <term><constant>-EOPNOTSUPP</constant></term>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </varlistentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <term><constant>-EDOM</constant></term>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>The passed event source is not a timer event source.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </variablelist>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refsect1>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <xi:include href="libsystemd-pkgconfig.xml" />
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <refsect1>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <title>See Also</title>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
3144ebcad37422dd85220915d37e7e9eea36564aZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
edf2573743b25273bee020230a60f1a054b8ec60Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </para>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering </refsect1>
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering
b408026b9899c1f9d155ac6d9f7bdc7f5cd3defbLennart Poettering</refentry>