systemd/0392-man-add-sd_event_add_child-3.patch
Zbigniew Jędrzejewski-Szmek 62fe9450da Update to latest git
2014-10-07 15:51:56 -04:00

295 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 edf2573743b25273bee020230a60f1a054b8ec60 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:33 -0400
Subject: [PATCH] man: add sd_event_add_child(3)
---
Makefile-man.am | 7 ++
man/sd_event_add_child.xml | 205 ++++++++++++++++++++++++++++++++++++++++++++
man/sd_event_add_signal.xml | 1 +
man/sd_event_add_time.xml | 1 +
4 files changed, 214 insertions(+)
create mode 100644 man/sd_event_add_child.xml
diff --git a/Makefile-man.am b/Makefile-man.am
index 85a3612f39..53e2f2cf17 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -741,6 +741,7 @@ MANPAGES += \
man/sd_bus_open_user.3 \
man/sd_bus_path_encode.3 \
man/sd_bus_request_name.3 \
+ man/sd_event_add_child.3 \
man/sd_event_add_signal.3 \
man/sd_event_add_time.3 \
man/sd_event_new.3 \
@@ -803,6 +804,7 @@ MANPAGES_ALIAS += \
man/sd_bus_unref.3 \
man/sd_event_default.3 \
man/sd_event_ref.3 \
+ man/sd_event_source_get_child_pid.3 \
man/sd_event_source_get_signal.3 \
man/sd_event_source_get_time.3 \
man/sd_event_source_get_time_accuracy.3 \
@@ -867,6 +869,7 @@ 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_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
man/sd_event_source_get_signal.3: man/sd_event_add_signal.3
man/sd_event_source_get_time.3: man/sd_event_add_time.3
man/sd_event_source_get_time_accuracy.3: man/sd_event_add_time.3
@@ -1043,6 +1046,9 @@ man/sd_event_default.html: man/sd_event_new.html
man/sd_event_ref.html: man/sd_event_new.html
$(html-alias)
+man/sd_event_source_get_child_pid.html: man/sd_event_add_child.html
+ $(html-alias)
+
man/sd_event_source_get_signal.html: man/sd_event_add_signal.html
$(html-alias)
@@ -1548,6 +1554,7 @@ EXTRA_DIST += \
man/sd_bus_open_user.xml \
man/sd_bus_path_encode.xml \
man/sd_bus_request_name.xml \
+ man/sd_event_add_child.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
new file mode 100644
index 0000000000..a3b4d85ac8
--- /dev/null
+++ b/man/sd_event_add_child.xml
@@ -0,0 +1,205 @@
+<?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_child" conditional="ENABLE_KDBUS">
+
+ <refentryinfo>
+ <title>sd_event_add_child</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_child</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_event_add_child</refname>
+ <refname>sd_event_source_get_child_pid</refname>
+
+ <refpurpose>Add a child state change event source to an event loop</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_event_add_child</function></funcdef>
+ <paramdef>sd_event *<parameter>event</parameter></paramdef>
+ <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+ <paramdef>pid_t <parameter>pid</parameter></paramdef>
+ <paramdef>int <parameter>options</parameter></paramdef>
+ <paramdef>sd_event_child_handler_t <parameter>handler</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef>
+ <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+ <paramdef>const siginfo_t *<parameter>si</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_event_source_get_child_pid</function></funcdef>
+ <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+ <paramdef>pid_t *<parameter>pid</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_event_add_child()</function> adds a new child
+ state change 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>pid</parameter> parameter specifies the process to
+ watch. The <parameter>handler</parameter> must reference a
+ function to call when the process changes state. The handler
+ function will be passed the <parameter>userdata</parameter>
+ pointer, which may be chosen freely by the caller. The handler
+ also receives a pointer to a <structname>const
+ siginfo_t</structname> structure containing the information about
+ the event. The <parameter>options</parameter> parameter determines
+ which state changes will be watched for. It must contain an OR-ed
+ mask of <constant>WEXITED</constant> (watch for the child
+ terminating), <constant>WSTOPPED</constant> (watch for the child
+ being stopped by a signal), and <constant>WCONTINUED</constant>
+ (watch for the child being resumed by a signal). See
+ <citerefentry><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ for futher information.</para>
+
+ <para>Only a single handler may be installed for a specific
+ child. The handler is enabled
+ for a single event (<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_child_pid()</function>
+ retrieves the configured <parameter>pid</parameter> of a child
+ state change event source created previously with
+ <function>sd_event_add_child()</function>. It takes the event
+ source object as the <parameter>source</parameter> parameter and a
+ pointer to <type>pid_t</type> to return the result 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 an object.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+
+ <listitem><para>An invalid argument has been passed. This includes
+ specyfing an empty mask in <parameter>options</parameter> or a mask
+ which constains values different than a combination of
+ <constant>WEXITED</constant>, <constant>WSTOPPED</constant>, and
+ <constant>WCONTINUED</constant>.
+ </para></listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EBUSY</varname></term>
+
+ <listitem><para>An handler is already installed for this
+ child.</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><function>sd_event_add_child()</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_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_signal</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 2344fb3c02..2b656b67a2 100644
--- a/man/sd_event_add_signal.xml
+++ b/man/sd_event_add_signal.xml
@@ -189,6 +189,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<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_child</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 d3775e5d5f..e64ed8e207 100644
--- a/man/sd_event_add_time.xml
+++ b/man/sd_event_add_time.xml
@@ -249,6 +249,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<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>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>