chiark / gitweb /
man: updates to the passive target section
[elogind.git] / man / sd_event_add_time.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
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" conditional="ENABLE_KDBUS">
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
53     <refpurpose>Add a timer event source to an event loop</refpurpose>
54   </refnamediv>
55
56   <refsynopsisdiv>
57     <funcsynopsis>
58       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
59
60       <funcprototype>
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>
69       </funcprototype>
70
71       <funcprototype>
72         <funcdef>int <function>sd_event_source_get_time</function></funcdef>
73         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
74         <paramdef>usec_t *<parameter>usec</parameter></paramdef>
75       </funcprototype>
76
77       <funcprototype>
78         <funcdef>int <function>sd_event_source_set_time</function></funcdef>
79         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
80         <paramdef>usec_t <parameter>usec</parameter></paramdef>
81       </funcprototype>
82
83       <funcprototype>
84         <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef>
85         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
86         <paramdef>usec_t *<parameter>usec</parameter></paramdef>
87       </funcprototype>
88
89       <funcprototype>
90         <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef>
91         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
92         <paramdef>usec_t <parameter>usec</parameter></paramdef>
93       </funcprototype>
94
95       <funcprototype>
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>
99       </funcprototype>
100
101     </funcsynopsis>
102   </refsynopsisdiv>
103
104   <refsect1>
105     <title>Description</title>
106
107     <para><function>sd_event_add_time()</function> adds a new timer
108     event source to an event loop object. The event loop is specified
109     in <parameter>event</parameter>, the event source is returned in
110     the <parameter>source</parameter> parameter. The
111     <parameter>clock</parameter> parameter takes a clock identifier,
112     one of <constant>CLOCK_REALTIME</constant>,
113     <constant>CLOCK_MONOTONIC</constant> and
114     <constant>CLOCK_BOOTTIME_ALARM</constant>. See
115     <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
116     for details regarding the various types of clocks. The
117     <parameter>usec</parameter> parameter takes a time value in
118     microseconds, relative to the clock's epoch specifying when the
119     timer shall elapse the earliest. The
120     <parameter>accuracy</parameter> parameter takes an additional
121     accuracy value in microseconds specifying a time the timer event
122     may be delayed. Specify 0 for selecting the default accuracy
123     (250ms). Specify 1 for most accurate timers. Consider specifying
124     60000000 or larger (1h) for long-running events that may be
125     delayed substantially. Picking higher accuracy values allows the
126     system to coalesce timer events more aggressively, thus improving
127     power efficiency. The <parameter>handler</parameter> shall
128     reference a function to call when the timer elapses. The handler
129     function will be passed the <parameter>userdata</parameter>
130     pointer, which may be chosen freely by the caller. The handler is
131     also passed the configured time it was triggered, however it might
132     actually have been called at a slightly later time, subject to the
133     specified accuracy value, the kernel timer slack (see
134     <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
135     and additional scheduling latencies. By default, the timer will
136     elapse once (SD_EVENT_ONESHOT), but this may be changed with
137     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
138     the handler function returns a negative error code, it will be
139     disabled after the invocation, even if SD_EVENT_ON mode is set.
140     </para>
141
142     <para><function>sd_event_source_get_time()</function> retrieves
143     the configured time value of a timer event source created
144     previously with <function>sd_event_add_time()</function>. It takes
145     the event source object and a pointer to a variable to store the
146     time in microseconds in.</para>
147
148     <para><function>sd_event_source_set_time()</function> changes the
149     configured time value of a timer event source created previously
150     with <function>sd_event_add_time()</function>. It takes the event
151     source object and a time relative to the selected clock's
152     epoch, in microseconds.</para>
153
154     <para><function>sd_event_source_get_time_accuracy()</function>
155     retrieves the configured accuracy value of a timer event source
156     created previously with <function>sd_event_add_time()</function>. It
157     takes the event source object and a pointer to a variable to store
158     the accuracy in microseconds in.</para>
159
160     <para><function>sd_event_source_set_time_accuracy()</function>
161     changes the configured accuracy of a timer event source created
162     previously with <function>sd_event_add_time()</function>. It takes
163     the event source object and an accuracy, in microseconds.</para>
164
165     <para><function>sd_event_source_get_time_clock()</function>
166     retrieves the configured clock of a timer event source created
167     previously with <function>sd_event_add_time()</function>. It takes
168     the event source object and a pointer to a variable to store the
169     clock identifier in.</para>
170
171   </refsect1>
172
173   <refsect1>
174     <title>Return Value</title>
175
176     <para>On success, these functions return 0 or a positive
177     integer. On failure, they return a negative errno-style error
178     code. </para>
179   </refsect1>
180
181   <refsect1>
182     <title>Errors</title>
183
184     <para>Returned errors may indicate the following problems:</para>
185
186     <variablelist>
187       <varlistentry>
188         <term><varname>-ENOMEM</varname></term>
189
190         <listitem><para>Not enough memory to allocate object.</para></listitem>
191       </varlistentry>
192
193       <varlistentry>
194         <term><varname>-EINVAL</varname></term>
195
196         <listitem><para>An invalid argument has been passed.</para></listitem>
197
198       </varlistentry>
199
200       <varlistentry>
201         <term><varname>-ESTALE</varname></term>
202
203         <listitem><para>The event loop is already terminated.</para></listitem>
204
205       </varlistentry>
206
207       <varlistentry>
208         <term><varname>-ECHILD</varname></term>
209
210         <listitem><para>The event loop has been created in a different process.</para></listitem>
211
212       </varlistentry>
213
214       <varlistentry>
215         <term><varname>-ENOTSUP</varname></term>
216
217         <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
218
219       </varlistentry>
220     </variablelist>
221   </refsect1>
222
223   <refsect1>
224     <title>Notes</title>
225
226     <para><function>sd_event_add_time()</function> and the other functions
227     described here are available as a shared library, which can be
228     compiled and linked to with the
229     <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
230     file.</para>
231   </refsect1>
232
233   <refsect1>
234     <title>See Also</title>
235
236     <para>
237       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
238       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
239       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
240       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
241       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
242     </para>
243   </refsect1>
244
245 </refentry>