sd_event_source_get_time.html 11.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<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>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
Michael Biebl's avatar
Michael Biebl committed
22
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</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 &lt;systemd/sd-bus.h&gt;</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">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="idm214185413552"></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 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
    event source to an event loop object. The event loop is specified
    in <em class="parameter"><code>event</code></em>, the event source is returned in
    the <em class="parameter"><code>source</code></em> parameter. The
    <em class="parameter"><code>clock</code></em> parameter takes a clock identifier,
    one of <code class="constant">CLOCK_REALTIME</code>,
    <code class="constant">CLOCK_MONOTONIC</code> and
    <code class="constant">CLOCK_BOOTTIME_ALARM</code>. See
    <a href="timerfd_create.html"><span class="citerefentry"><span class="refentrytitle">timerfd_create</span>(2)</span></a>
    for details regarding the various types of clocks. The
    <em class="parameter"><code>usec</code></em> parameter takes a time value in
    microseconds, relative to the clock's epoch specifying when the
    timer shall elapse the earliest. The
    <em class="parameter"><code>accuracy</code></em> parameter takes an additional
    accuracy value in microseconds specifying a time the timer event
    may be delayed. Specify 0 for selecting the default accuracy
    (250ms). Specify 1 for most accurate timers. Consider specifying
    60000000 or larger (1h) for long-running events that may be
    delayed substantially. Picking higher accuracy values allows the
    system to coalesce timer events more aggressively, thus improving
    power efficiency. The <em class="parameter"><code>handler</code></em> shall
    reference a function to call when the timer elapses. The handler
    function will be passed the <em class="parameter"><code>userdata</code></em>
    pointer, which may be chosen freely by the caller. The handler is
    also passed the configured time it was triggered, however it might
    actually have been called at a slightly later time, subject to the
    specified accuracy value, the kernel timer slack (see
    <a href="prctl.html"><span class="citerefentry"><span class="refentrytitle">prctl</span>(2)</span></a>)
    and additional scheduling latencies. By default, the timer will
    elapse once (SD_EVENT_ONESHOT), but this may be changed with
    <a href="sd_event_source_set_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_event_source_set_enabled</span>(3)</span></a>. If
    the handler function returns a negative error code, it will be
    disabled after the invocation, even if SD_EVENT_ON mode is set.
    </p><p><code class="function">sd_event_source_get_time()</code> retrieves
    the configured time value of a timer event source created
    previously with <code class="function">sd_event_add_time()</code>. It takes
    the event source object and a pointer to a variable to store the
    time in microseconds in.</p><p><code class="function">sd_event_source_set_time()</code> changes the
    configured time value of a timer event source created previously
    with <code class="function">sd_event_add_time()</code>. It takes the event
    source object and a time relative to the selected clock's
    epoch, in microseconds.</p><p><code class="function">sd_event_source_get_time_accuracy()</code>
    retrieves the configured accuracy value of a timer event source
    created previously with <code class="function">sd_event_add_time()</code>. It
    takes the event source object and a pointer to a variable to store
    the accuracy in microseconds in.</p><p><code class="function">sd_event_source_set_time_accuracy()</code>
    changes the configured accuracy of a timer event source created
    previously with <code class="function">sd_event_add_time()</code>. It takes
    the event source object and an accuracy, in microseconds.</p><p><code class="function">sd_event_source_get_time_clock()</code>
    retrieves the configured clock of a timer event source created
    previously with <code class="function">sd_event_add_time()</code>. It takes
    the event source object and a pointer to a variable to store the
Michael Biebl's avatar
Michael Biebl committed
74
    clock identifier in.</p></div><div class="refsect1"><a name="idm214185385088"></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
75
    integer. On failure, they return a negative errno-style error
Michael Biebl's avatar
Michael Biebl committed
76
    code. </p></div><div class="refsect1"><a name="idm214185383760"></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="varname">-ENOMEM</code></span><a class="headerlink" title="Permalink to this term" href="#-ENOMEM"></a></dt><dd><p>Not enough memory to allocate object.</p></dd><dt id="-EINVAL"><span class="term"><code class="varname">-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="varname">-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="varname">-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="-ENOTSUP"><span class="term"><code class="varname">-ENOTSUP</code></span><a class="headerlink" title="Permalink to this term" href="#-ENOTSUP"></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="idm214180461872"></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
77 78 79
    described here are available as a shared library, which can be
    compiled and linked to with the
    <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
Michael Biebl's avatar
Michael Biebl committed
80
    file.</p></div><div class="refsect1"><a name="idm214180458928"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
81 82 83 84 85 86
      <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
      <a href="sd-event.html"><span class="citerefentry"><span class="refentrytitle">sd-event</span>(3)</span></a>,
      <a href="sd_event_new.html"><span class="citerefentry"><span class="refentrytitle">sd_event_new</span>(3)</span></a>,
      <a href="clock_gettime.html"><span class="citerefentry"><span class="refentrytitle">clock_gettime</span>(2)</span></a>,
      <a href="sd_event_source_set_enabled.html"><span class="citerefentry"><span class="refentrytitle">sd_event_source_set_enabled</span>(3)</span></a>
    </p></div></div></body></html>