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">
6 This file is part of systemd.
8 Copyright 2014 Lennart Poettering
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.
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.
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/>.
24 <refentry id=
"sd_event_add_time" conditional=
"ENABLE_KDBUS">
27 <title>sd_event_add_time
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Lennart
</firstname>
34 <surname>Poettering
</surname>
35 <email>lennart@poettering.net
</email>
41 <refentrytitle>sd_event_add_time
</refentrytitle>
42 <manvolnum>3</manvolnum>
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>
53 <refpurpose>Add a timer event source to an event loop
</refpurpose>
58 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
61 <funcdef>int
<function>sd_event_add_time
</function></funcdef>
62 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
63 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
64 <paramdef>clockid_t
<parameter>clock
</parameter></paramdef>
65 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
66 <paramdef>uint64_t
<parameter>accuracy
</parameter></paramdef>
67 <paramdef>sd_event_time_handler_t
<parameter>handler
</parameter></paramdef>
68 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
72 <funcdef>typedef int (*
<function>sd_event_time_handler_t
</function>)
</funcdef>
73 <paramdef>sd_event_source *
<parameter>s
</parameter></paramdef>
74 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
75 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
79 <funcdef>int
<function>sd_event_source_get_time
</function></funcdef>
80 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
81 <paramdef>usec_t *
<parameter>usec
</parameter></paramdef>
85 <funcdef>int
<function>sd_event_source_set_time
</function></funcdef>
86 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
87 <paramdef>usec_t
<parameter>usec
</parameter></paramdef>
91 <funcdef>int
<function>sd_event_source_get_time_accuracy
</function></funcdef>
92 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
93 <paramdef>usec_t *
<parameter>usec
</parameter></paramdef>
97 <funcdef>int
<function>sd_event_source_set_time_accuracy
</function></funcdef>
98 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
99 <paramdef>usec_t
<parameter>usec
</parameter></paramdef>
103 <funcdef>int
<function>sd_event_source_get_time_clock
</function></funcdef>
104 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
105 <paramdef>clockid_t *
<parameter>clock
</parameter></paramdef>
112 <title>Description
</title>
114 <para><function>sd_event_add_time()
</function> adds a new timer
115 event source to an event loop object. The event loop is specified
116 in
<parameter>event
</parameter>, the event source is returned in
117 the
<parameter>source
</parameter> parameter. The
118 <parameter>clock
</parameter> parameter takes a clock identifier,
119 one of
<constant>CLOCK_REALTIME
</constant>,
120 <constant>CLOCK_MONOTONIC
</constant> and
121 <constant>CLOCK_BOOTTIME_ALARM
</constant>. See
122 <citerefentry><refentrytitle>timerfd_create
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
123 for details regarding the various types of clocks. The
124 <parameter>usec
</parameter> parameter takes a time value in
125 microseconds, relative to the clock's epoch specifying when the
126 timer shall elapse the earliest. The
127 <parameter>accuracy
</parameter> parameter takes an additional
128 accuracy value in microseconds specifying a time the timer event
129 may be delayed. Specify
0 for selecting the default accuracy
130 (
250ms). Specify
1 for most accurate timers. Consider specifying
131 60000000 or larger (
1h) for long-running events that may be
132 delayed substantially. Picking higher accuracy values allows the
133 system to coalesce timer events more aggressively, thus improving
134 power efficiency. The
<parameter>handler
</parameter> shall
135 reference a function to call when the timer elapses. The handler
136 function will be passed the
<parameter>userdata
</parameter>
137 pointer, which may be chosen freely by the caller. The handler is
138 also passed the configured time it was triggered, however it might
139 actually have been called at a slightly later time, subject to the
140 specified accuracy value, the kernel timer slack (see
141 <citerefentry><refentrytitle>prctl
</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
142 and additional scheduling latencies.
</para>
144 <para>By default, the timer will elapse once
145 (
<constant>SD_EVENT_ONESHOT
</constant>), but this may be changed
147 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
148 If the handler function returns a negative error code, it will be
149 disabled after the invocation, even if
150 <constant>SD_EVENT_ON
</constant> mode is set.
153 <para><function>sd_event_source_get_time()
</function> retrieves
154 the configured time value of a timer event source created
155 previously with
<function>sd_event_add_time()
</function>. It takes
156 the event source object and a pointer to a variable to store the
157 time in microseconds in.
</para>
159 <para><function>sd_event_source_set_time()
</function> changes the
160 configured time value of a timer event source created previously
161 with
<function>sd_event_add_time()
</function>. It takes the event
162 source object and a time relative to the selected clock's
163 epoch, in microseconds.
</para>
165 <para><function>sd_event_source_get_time_accuracy()
</function>
166 retrieves the configured accuracy value of a timer event source
167 created previously with
<function>sd_event_add_time()
</function>. It
168 takes the event source object and a pointer to a variable to store
169 the accuracy in microseconds in.
</para>
171 <para><function>sd_event_source_set_time_accuracy()
</function>
172 changes the configured accuracy of a timer event source created
173 previously with
<function>sd_event_add_time()
</function>. It takes
174 the event source object and an accuracy, in microseconds.
</para>
176 <para><function>sd_event_source_get_time_clock()
</function>
177 retrieves the configured clock of a timer event source created
178 previously with
<function>sd_event_add_time()
</function>. It takes
179 the event source object and a pointer to a variable to store the
180 clock identifier in.
</para>
185 <title>Return Value
</title>
187 <para>On success, these functions return
0 or a positive
188 integer. On failure, they return a negative errno-style error
193 <title>Errors
</title>
195 <para>Returned errors may indicate the following problems:
</para>
199 <term><constant>-ENOMEM
</constant></term>
201 <listitem><para>Not enough memory to allocate an object.
</para></listitem>
205 <term><constant>-EINVAL
</constant></term>
207 <listitem><para>An invalid argument has been passed.
</para></listitem>
212 <term><constant>-ESTALE
</constant></term>
214 <listitem><para>The event loop is already terminated.
</para></listitem>
219 <term><constant>-ECHILD
</constant></term>
221 <listitem><para>The event loop has been created in a different process.
</para></listitem>
226 <term><constant>-ENOTSUP
</constant></term>
228 <listitem><para>The selected clock is not supported by the event loop implementation.
</para></listitem>
237 <para><function>sd_event_add_time()
</function> and the other functions
238 described here are available as a shared library, which can be
239 compiled and linked to with the
240 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
245 <title>See Also
</title>
248 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
249 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
250 <citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
251 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
252 <citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
253 <citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
254 <citerefentry><refentrytitle>clock_gettime
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
255 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>