2014-11-21 22:44:48 +03:00
<?xml version='1.0'?> <!-- * - Mode: nxml; nxml - child - indent: 2; indent - tabs - mode: nil - * -->
2014-09-26 01:27:33 +04:00
< !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: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<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 < systemd/sd-bus.h> </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>
2014-12-30 19:41:38 +03:00
for further information.</para>
2014-09-26 01:27:33 +04:00
<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 >
2014-09-26 01:27:46 +04:00
<term > <constant > -ENOMEM</constant> </term>
2014-09-26 01:27:33 +04:00
<listitem > <para > Not enough memory to allocate an object.</para> </listitem>
</varlistentry>
<varlistentry >
2014-09-26 01:27:46 +04:00
<term > <constant > -EINVAL</constant> </term>
2014-09-26 01:27:33 +04:00
<listitem > <para > An invalid argument has been passed. This includes
2015-01-26 17:29:14 +03:00
specifying an empty mask in <parameter > options</parameter> or a mask
2014-12-29 12:45:58 +03:00
which contains values different than a combination of
2014-09-26 01:27:33 +04:00
<constant > WEXITED</constant> , <constant > WSTOPPED</constant> , and
<constant > WCONTINUED</constant> .
</para> </listitem>
</varlistentry>
<varlistentry >
2014-09-26 01:27:46 +04:00
<term > <constant > -EBUSY</constant> </term>
2014-09-26 01:27:33 +04:00
<listitem > <para > An handler is already installed for this
child.</para> </listitem>
</varlistentry>
<varlistentry >
2014-09-26 01:27:46 +04:00
<term > <constant > -ESTALE</constant> </term>
2014-09-26 01:27:33 +04:00
<listitem > <para > The event loop is already terminated.</para> </listitem>
</varlistentry>
<varlistentry >
2014-09-26 01:27:46 +04:00
<term > <constant > -ECHILD</constant> </term>
2014-09-26 01:27:33 +04:00
<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> ,
2014-09-26 01:27:40 +04:00
<citerefentry > <refentrytitle > sd_event_add_defer</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2014-09-26 01:27:33 +04:00
<citerefentry > <refentrytitle > sd_event_source_set_enabled</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
</para>
</refsect1>
</refentry>
