systemd/0393-man-document-sd_event_add_-defer-post-exit.patch
Zbigniew Jędrzejewski-Szmek 708deb95da Update to latest git
2014-10-07 22:56:19 -04:00

299 lines
12 KiB
Diff
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

From 4dfefc1914bad6a025e2d6738999e45b74715002 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 25 Sep 2014 17:27:40 -0400
Subject: [PATCH] man: document sd_event_add_{defer,post,exit}
---
Makefile-man.am | 12 +++
man/sd_event_add_child.xml | 1 +
man/sd_event_add_defer.xml | 191 ++++++++++++++++++++++++++++++++++++++++++++
man/sd_event_add_signal.xml | 1 +
man/sd_event_add_time.xml | 1 +
5 files changed, 206 insertions(+)
create mode 100644 man/sd_event_add_defer.xml
diff --git a/Makefile-man.am b/Makefile-man.am
index 53e2f2cf17..bd5306e676 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -742,6 +742,7 @@ MANPAGES += \
man/sd_bus_path_encode.3 \
man/sd_bus_request_name.3 \
man/sd_event_add_child.3 \
+ man/sd_event_add_defer.3 \
man/sd_event_add_signal.3 \
man/sd_event_add_time.3 \
man/sd_event_new.3 \
@@ -802,6 +803,8 @@ MANPAGES_ALIAS += \
man/sd_bus_ref.3 \
man/sd_bus_release_name.3 \
man/sd_bus_unref.3 \
+ man/sd_event_add_exit.3 \
+ man/sd_event_add_post.3 \
man/sd_event_default.3 \
man/sd_event_ref.3 \
man/sd_event_source_get_child_pid.3 \
@@ -867,6 +870,8 @@ man/sd_bus_path_decode.3: man/sd_bus_path_encode.3
man/sd_bus_ref.3: man/sd_bus_new.3
man/sd_bus_release_name.3: man/sd_bus_request_name.3
man/sd_bus_unref.3: man/sd_bus_new.3
+man/sd_event_add_exit.3: man/sd_event_add_defer.3
+man/sd_event_add_post.3: man/sd_event_add_defer.3
man/sd_event_default.3: man/sd_event_new.3
man/sd_event_ref.3: man/sd_event_new.3
man/sd_event_source_get_child_pid.3: man/sd_event_add_child.3
@@ -1040,6 +1045,12 @@ man/sd_bus_release_name.html: man/sd_bus_request_name.html
man/sd_bus_unref.html: man/sd_bus_new.html
$(html-alias)
+man/sd_event_add_exit.html: man/sd_event_add_defer.html
+ $(html-alias)
+
+man/sd_event_add_post.html: man/sd_event_add_defer.html
+ $(html-alias)
+
man/sd_event_default.html: man/sd_event_new.html
$(html-alias)
@@ -1555,6 +1566,7 @@ EXTRA_DIST += \
man/sd_bus_path_encode.xml \
man/sd_bus_request_name.xml \
man/sd_event_add_child.xml \
+ man/sd_event_add_defer.xml \
man/sd_event_add_signal.xml \
man/sd_event_add_time.xml \
man/sd_event_new.xml \
diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml
index a3b4d85ac8..f282a5094a 100644
--- a/man/sd_event_add_child.xml
+++ b/man/sd_event_add_child.xml
@@ -198,6 +198,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml
new file mode 100644
index 0000000000..6c937098b2
--- /dev/null
+++ b/man/sd_event_add_defer.xml
@@ -0,0 +1,191 @@
+<?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 Zbigniew Jędrzejewski-Szmek
+
+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_defer" conditional="ENABLE_KDBUS">
+
+ <refentryinfo>
+ <title>sd_event_add_defer</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>More text</contrib>
+ <firstname>Zbigniew</firstname>
+ <surname>Jędrzejewski-Szmek</surname>
+ <email>zbyszek@in.waw.pl</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_event_add_defer</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_event_add_defer</refname>
+ <refname>sd_event_add_post</refname>
+ <refname>sd_event_add_exit</refname>
+
+ <refpurpose>Add static event sources to an event loop</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_event_add_defer</function></funcdef>
+ <paramdef>sd_event *<parameter>event</parameter></paramdef>
+ <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+ <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_event_add_post</function></funcdef>
+ <paramdef>sd_event *<parameter>event</parameter></paramdef>
+ <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+ <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_event_add_exit</function></funcdef>
+ <paramdef>sd_event *<parameter>event</parameter></paramdef>
+ <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+ <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
+ <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>Those three functions add new event sources 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 event sources are
+ enabled statically and will "fire" when the event loop is run and
+ the conditions described below are met. The handler function will
+ be passed the <parameter>userdata</parameter> pointer, which may
+ be chosen freely by the caller.</para>
+
+ <para><function>sd_event_add_defer()</function> adds a new event
+ source that will "fire" the next time the event loop is run. By
+ default, the handler will be called once
+ (<constant>SD_EVENT_ONESHOT</constant>).</para>
+
+ <para><function>sd_event_add_defer()</function> adds a new event
+ source that will "fire" if any event handlers are invoked whenever
+ the event loop is run. By default, the source is enabled
+ permanently (<constant>SD_EVENT_ON</constant>).</para>
+
+ <para><function>sd_event_add_exit()</function> adds a new event
+ source that will "fire" when the event loop is terminated
+ with <function>sd_event_exit()</function>.</para>
+
+ <para>The
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ function may be used to enable the event source permanently
+ (<constant>SD_EVENT_ON</constant>) or to make it fire just once
+ (<constant>SD_EVENT_ONESHOT</constant>). 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>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>On success, this 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 an 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>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <para>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_time</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_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml
index 2b656b67a2..1517c1021c 100644
--- a/man/sd_event_add_signal.xml
+++ b/man/sd_event_add_signal.xml
@@ -190,6 +190,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</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>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml
index e64ed8e207..f16b84f605 100644
--- a/man/sd_event_add_time.xml
+++ b/man/sd_event_add_time.xml
@@ -250,6 +250,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<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>