681eb9cf2b
In particular, use /lib/systemd instead of /usr/lib/systemd in distributions like Debian which still have not adopted a /usr merge setup. Use XML entities from man/custom-entities.ent to replace configured paths while doing XSLT processing of the original XML files. There was precedent of some files (such as systemd.generator.xml) which were already using this approach. This addresses most of the (manual) fixes from this patch: http://anonscm.debian.org/cgit/pkg-systemd/systemd.git/tree/debian/patches/Fix-paths-in-man-pages.patch?h=experimental-220 The idea of using generic XML entities was presented here: http://lists.freedesktop.org/archives/systemd-devel/2015-May/032240.html This patch solves almost all the issues, with the exception of: - Path to /bin/mount and /bin/umount. - Generic statements about preference of /lib over /etc. These will be handled separately by follow up patches. Tested: - With default configure settings, ran "make install" to two separate directories and compared the output to confirm they matched exactly. - Used a set of configure flags including $CONFFLAGS from Debian: http://anonscm.debian.org/cgit/pkg-systemd/systemd.git/tree/debian/rules Installed the tree and confirmed the paths use /lib/systemd instead of /usr/lib/systemd and that no other unexpected differences exist. - Confirmed that `make distcheck` still passes.
263 lines
11 KiB
XML
263 lines
11 KiB
XML
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
||
%entities;
|
||
]>
|
||
|
||
<!--
|
||
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>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
|
||
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
|
||
<paramdef>uint64_t <parameter>usec</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.</para>
|
||
|
||
<para>By default, the timer will elapse once
|
||
(<constant>SD_EVENT_ONESHOT</constant>), 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
|
||
<constant>SD_EVENT_ON</constant> 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><constant>-ENOMEM</constant></term>
|
||
|
||
<listitem><para>Not enough memory to allocate an object.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><constant>-EINVAL</constant></term>
|
||
|
||
<listitem><para>An invalid argument has been passed.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><constant>-ESTALE</constant></term>
|
||
|
||
<listitem><para>The event loop is already terminated.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><constant>-ECHILD</constant></term>
|
||
|
||
<listitem><para>The event loop has been created in a different process.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><constant>-EOPNOTSUPP</constant></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 project='die-net'><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>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>sd_event_add_defer</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>
|