diff options
Diffstat (limited to 'man/sd_event_add_time.xml')
| -rw-r--r-- | man/sd_event_add_time.xml | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml new file mode 100644 index 0000000000..9af8bb9c45 --- /dev/null +++ b/man/sd_event_add_time.xml @@ -0,0 +1,245 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- +This file is part of systemd. + +Copyright 2014 Lennart Poettering + +systemd is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General Public License as published by +the Free Software Foundation; either version 2.1 of the License, or +(at your option) any later version. + +systemd is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public License +along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_add_time" conditional="ENABLE_KDBUS"> + + <refentryinfo> + <title>sd_event_add_time</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_add_time</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_add_time</refname> + <refname>sd_event_source_get_time</refname> + <refname>sd_event_source_set_time</refname> + <refname>sd_event_source_get_time_accuracy</refname> + <refname>sd_event_source_set_time_accuracy</refname> + <refname>sd_event_source_get_time_clock</refname> + + <refpurpose>Add a timer event source to an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_add_time</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>clockid_t <parameter>clock</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + <paramdef>uint64_t <parameter>accuracy</parameter></paramdef> + <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void* <parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>usec_t* <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_time</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>usec_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>usec_t *<parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>usec_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>clockid_t *<parameter>clock</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_add_time()</function> adds a new timer + event source to an event loop object. The event loop is specified + in <parameter>event</parameter>, the event source is returned in + the <parameter>source</parameter> parameter. The + <parameter>clock</parameter> parameter takes a clock identifier, + one of <constant>CLOCK_REALTIME</constant>, + <constant>CLOCK_MONOTONIC</constant> and + <constant>CLOCK_BOOTTIME_ALARM</constant>. See + <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details regarding the various types of clocks. The + <parameter>usec</parameter> parameter takes a time value in + microseconds, relative to the clock's epoch specifying when the + timer shall elapse the earliest. The + <parameter>accuracy</parameter> 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 <parameter>handler</parameter> shall + reference a function to call when the timer elapses. The handler + function will be passed the <parameter>userdata</parameter> + 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 + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>) + and additional scheduling latencies. By default the timer will + elapse once (SD_EVENT_ONESHOT), but this may be changed with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If + the handler function returns a negative error code it will be + disabled after the invocation, even if SD_EVENT_ON mode is set. + </para> + + <para><function>sd_event_source_get_time()</function> retrieves + the configured time value of a timer event source created + previously with <function>sd_event_add_time()</function>. It takes + the event source object and a pointer to a variable to store the + time in microseconds in.</para> + + <para><function>sd_event_source_set_time()</function> changes the + configured time value of a timer event source created previously + with <function>sd_event_add_time()</function>. It takes the event + source object and a time relative to the selected clock's + epoch, in microseconds.</para> + + <para><function>sd_event_source_get_time_accuracy()</function> + retrieves the configured accuracy value of a timer event source + created previously with <function>sd_event_add_time()</function>. It + takes the event source object and a pointer to a variable to store + the accuracy in microseconds in.</para> + + <para><function>sd_event_source_set_time_accuracy()</function> + changes the configured accuracy of a timer event source created + previously with <function>sd_event_add_time()</function>. It takes + the event source object and an accuracy, in microseconds.</para> + + <para><function>sd_event_source_get_time_clock()</function> + retrieves the configured clock of a timer event source created + previously with <function>sd_event_add_time()</function>. It takes + the event source object and a pointer to a variable to store the + clock identifier in.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><varname>-ENOMEM</varname></term> + + <listitem><para>Not enough memory to allocate object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>-EINVAL</varname></term> + + <listitem><para>An invalid argument has been passed.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>-ESTALE</varname></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>-ECHILD</varname></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>-ENOTSUP</varname></term> + + <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_event_add_time()</function> and the other functions + described here are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |