1 <html><head><meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8"><title>sd_event_add_time
</title><meta name=
"generator" content=
"DocBook XSL Stylesheets V1.78.1"></head><body bgcolor=
"white" text=
"black" link=
"#0000FF" vlink=
"#840084" alink=
"#0000FF"><style>
11 background-color: #c60f0f;
15 h1:hover
> a.headerlink, h2:hover
> a.headerlink, h3:hover
> a.headerlink, dt:hover
> a.headerlink {
18 </style><a href=
"index.html">Index
</a>·
19 <a href=
"systemd.directives.html">Directives
</a>·
20 <a href=
"../python-systemd/index.html">Python
</a>·
21 <a href=
"../libudev/index.html">libudev
</a>·
22 <a href=
"../libudev/index.html">gudev
</a><span style=
"float:right">systemd
220</span><hr><div class=
"refentry"><a name=
"sd_event_add_time"></a><div class=
"titlepage"></div><div class=
"refnamediv"><h2>Name
</h2><p>sd_event_add_time, sd_event_source_get_time, sd_event_source_set_time, sd_event_source_get_time_accuracy, sd_event_source_set_time_accuracy, sd_event_source_get_time_clock — Add a timer event source to an event loop
</p></div><div class=
"refsynopsisdiv"><h2>Synopsis
</h2><div class=
"funcsynopsis"><pre class=
"funcsynopsisinfo">#include
<systemd/sd-bus.h
></pre><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">int
<b class=
"fsfunc">sd_event_add_time
</b>(
</code></td><td>sd_event *
<var class=
"pdparam">event
</var>,
</td></tr><tr><td> </td><td>sd_event_source **
<var class=
"pdparam">source
</var>,
</td></tr><tr><td> </td><td>clockid_t
<var class=
"pdparam">clock
</var>,
</td></tr><tr><td> </td><td>uint64_t
<var class=
"pdparam">usec
</var>,
</td></tr><tr><td> </td><td>uint64_t
<var class=
"pdparam">accuracy
</var>,
</td></tr><tr><td> </td><td>sd_event_time_handler_t
<var class=
"pdparam">handler
</var>,
</td></tr><tr><td> </td><td>void *
<var class=
"pdparam">userdata
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">typedef int (*
<b class=
"fsfunc">sd_event_time_handler_t
</b>)(
</code></td><td>sd_event_source *
<var class=
"pdparam">s
</var>,
</td></tr><tr><td> </td><td>uint64_t
<var class=
"pdparam">usec
</var>,
</td></tr><tr><td> </td><td>void *
<var class=
"pdparam">userdata
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">int
<b class=
"fsfunc">sd_event_source_get_time
</b>(
</code></td><td>sd_event_source *
<var class=
"pdparam">source
</var>,
</td></tr><tr><td> </td><td>usec_t *
<var class=
"pdparam">usec
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">int
<b class=
"fsfunc">sd_event_source_set_time
</b>(
</code></td><td>sd_event_source *
<var class=
"pdparam">source
</var>,
</td></tr><tr><td> </td><td>usec_t
<var class=
"pdparam">usec
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">int
<b class=
"fsfunc">sd_event_source_get_time_accuracy
</b>(
</code></td><td>sd_event_source *
<var class=
"pdparam">source
</var>,
</td></tr><tr><td> </td><td>usec_t *
<var class=
"pdparam">usec
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">int
<b class=
"fsfunc">sd_event_source_set_time_accuracy
</b>(
</code></td><td>sd_event_source *
<var class=
"pdparam">source
</var>,
</td></tr><tr><td> </td><td>usec_t
<var class=
"pdparam">usec
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">int
<b class=
"fsfunc">sd_event_source_get_time_clock
</b>(
</code></td><td>sd_event_source *
<var class=
"pdparam">source
</var>,
</td></tr><tr><td> </td><td>clockid_t *
<var class=
"pdparam">clock
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div></div></div><div class=
"refsect1"><a name=
"idm140178645818976"></a><h2 id=
"Description">Description
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Description">¶
</a></h2><p><code class=
"function">sd_event_add_time()
</code> adds a new timer
23 event source to an event loop object. The event loop is specified
24 in
<em class=
"parameter"><code>event
</code></em>, the event source is returned in
25 the
<em class=
"parameter"><code>source
</code></em> parameter. The
26 <em class=
"parameter"><code>clock
</code></em> parameter takes a clock identifier,
27 one of
<code class=
"constant">CLOCK_REALTIME
</code>,
28 <code class=
"constant">CLOCK_MONOTONIC
</code> and
29 <code class=
"constant">CLOCK_BOOTTIME_ALARM
</code>. See
30 <a href=
"http://man7.org/linux/man-pages/man2/timerfd_create.2.html"><span class=
"citerefentry"><span class=
"refentrytitle">timerfd_create
</span>(
2)
</span></a>
31 for details regarding the various types of clocks. The
32 <em class=
"parameter"><code>usec
</code></em> parameter takes a time value in
33 microseconds, relative to the clock's epoch specifying when the
34 timer shall elapse the earliest. The
35 <em class=
"parameter"><code>accuracy
</code></em> parameter takes an additional
36 accuracy value in microseconds specifying a time the timer event
37 may be delayed. Specify
0 for selecting the default accuracy
38 (
250ms). Specify
1 for most accurate timers. Consider specifying
39 60000000 or larger (
1h) for long-running events that may be
40 delayed substantially. Picking higher accuracy values allows the
41 system to coalesce timer events more aggressively, thus improving
42 power efficiency. The
<em class=
"parameter"><code>handler
</code></em> shall
43 reference a function to call when the timer elapses. The handler
44 function will be passed the
<em class=
"parameter"><code>userdata
</code></em>
45 pointer, which may be chosen freely by the caller. The handler is
46 also passed the configured time it was triggered, however it might
47 actually have been called at a slightly later time, subject to the
48 specified accuracy value, the kernel timer slack (see
49 <a href=
"http://man7.org/linux/man-pages/man2/prctl.2.html"><span class=
"citerefentry"><span class=
"refentrytitle">prctl
</span>(
2)
</span></a>)
50 and additional scheduling latencies.
</p><p>By default, the timer will elapse once
51 (
<code class=
"constant">SD_EVENT_ONESHOT
</code>), but this may be changed
53 <a href=
"sd_event_source_set_enabled.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_event_source_set_enabled
</span>(
3)
</span></a>.
54 If the handler function returns a negative error code, it will be
55 disabled after the invocation, even if
56 <code class=
"constant">SD_EVENT_ON
</code> mode is set.
57 </p><p><code class=
"function">sd_event_source_get_time()
</code> retrieves
58 the configured time value of a timer event source created
59 previously with
<code class=
"function">sd_event_add_time()
</code>. It takes
60 the event source object and a pointer to a variable to store the
61 time in microseconds in.
</p><p><code class=
"function">sd_event_source_set_time()
</code> changes the
62 configured time value of a timer event source created previously
63 with
<code class=
"function">sd_event_add_time()
</code>. It takes the event
64 source object and a time relative to the selected clock's
65 epoch, in microseconds.
</p><p><code class=
"function">sd_event_source_get_time_accuracy()
</code>
66 retrieves the configured accuracy value of a timer event source
67 created previously with
<code class=
"function">sd_event_add_time()
</code>. It
68 takes the event source object and a pointer to a variable to store
69 the accuracy in microseconds in.
</p><p><code class=
"function">sd_event_source_set_time_accuracy()
</code>
70 changes the configured accuracy of a timer event source created
71 previously with
<code class=
"function">sd_event_add_time()
</code>. It takes
72 the event source object and an accuracy, in microseconds.
</p><p><code class=
"function">sd_event_source_get_time_clock()
</code>
73 retrieves the configured clock of a timer event source created
74 previously with
<code class=
"function">sd_event_add_time()
</code>. It takes
75 the event source object and a pointer to a variable to store the
76 clock identifier in.
</p></div><div class=
"refsect1"><a name=
"idm140178645798464"></a><h2 id=
"Return Value">Return Value
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Return%20Value">¶
</a></h2><p>On success, these functions return
0 or a positive
77 integer. On failure, they return a negative errno-style error
78 code.
</p></div><div class=
"refsect1"><a name=
"idm140178645797168"></a><h2 id=
"Errors">Errors
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Errors">¶
</a></h2><p>Returned errors may indicate the following problems:
</p><div class=
"variablelist"><dl class=
"variablelist"><dt id=
"-ENOMEM"><span class=
"term"><code class=
"constant">-ENOMEM
</code></span><a class=
"headerlink" title=
"Permalink to this term" href=
"#-ENOMEM">¶
</a></dt><dd><p>Not enough memory to allocate an object.
</p></dd><dt id=
"-EINVAL"><span class=
"term"><code class=
"constant">-EINVAL
</code></span><a class=
"headerlink" title=
"Permalink to this term" href=
"#-EINVAL">¶
</a></dt><dd><p>An invalid argument has been passed.
</p></dd><dt id=
"-ESTALE"><span class=
"term"><code class=
"constant">-ESTALE
</code></span><a class=
"headerlink" title=
"Permalink to this term" href=
"#-ESTALE">¶
</a></dt><dd><p>The event loop is already terminated.
</p></dd><dt id=
"-ECHILD"><span class=
"term"><code class=
"constant">-ECHILD
</code></span><a class=
"headerlink" title=
"Permalink to this term" href=
"#-ECHILD">¶
</a></dt><dd><p>The event loop has been created in a different process.
</p></dd><dt id=
"-EOPNOTSUPP"><span class=
"term"><code class=
"constant">-EOPNOTSUPP
</code></span><a class=
"headerlink" title=
"Permalink to this term" href=
"#-EOPNOTSUPP">¶
</a></dt><dd><p>The selected clock is not supported by the event loop implementation.
</p></dd></dl></div></div><div class=
"refsect1"><a name=
"idm140178645788592"></a><h2 id=
"Notes">Notes
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Notes">¶
</a></h2><p><code class=
"function">sd_event_add_time()
</code> and the other functions
79 described here are available as a shared library, which can be
80 compiled and linked to with the
81 <code class=
"constant">libsystemd
</code> <a href=
"http://linux.die.net/man/1/pkg-config"><span class=
"citerefentry"><span class=
"refentrytitle">pkg-config
</span>(
1)
</span></a>
82 file.
</p></div><div class=
"refsect1"><a name=
"idm140178645785408"></a><h2 id=
"See Also">See Also
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#See%20Also">¶
</a></h2><p>
83 <a href=
"systemd.html"><span class=
"citerefentry"><span class=
"refentrytitle">systemd
</span>(
1)
</span></a>,
84 <a href=
"sd-event.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd-event
</span>(
3)
</span></a>,
85 <a href=
"sd_event_new.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_event_new
</span>(
3)
</span></a>,
86 <a href=
"sd_event_add_signal.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_event_add_signal
</span>(
3)
</span></a>,
87 <a href=
"sd_event_add_child.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_event_add_child
</span>(
3)
</span></a>,
88 <a href=
"sd_event_add_defer.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_event_add_defer
</span>(
3)
</span></a>,
89 <a href=
"http://man7.org/linux/man-pages/man2/clock_gettime.2.html"><span class=
"citerefentry"><span class=
"refentrytitle">clock_gettime
</span>(
2)
</span></a>,
90 <a href=
"sd_event_source_set_enabled.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_event_source_set_enabled
</span>(
3)
</span></a>
91 </p></div></div></body></html>