man/sd_event_add_child.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_event_add_child</title>
  13     <productname>systemd</productname>
  14
  15     <authorgroup>
  16       <author>
  17         <contrib>More text</contrib>
  18         <firstname>Zbigniew</firstname>
  19         <surname>Jędrzejewski-Szmek</surname>
  20         <email>zbyszek@in.waw.pl</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>sd_event_add_child</refentrytitle>
  27     <manvolnum>3</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>sd_event_add_child</refname>
  32     <refname>sd_event_source_get_child_pid</refname>
  33     <refname>sd_event_child_handler_t</refname>
  34
  35     <refpurpose>Add a child process state change event source to an event loop</refpurpose>
  36   </refnamediv>
  37
  38   <refsynopsisdiv>
  39     <funcsynopsis>
  40       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  41
  42       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef>
  46         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  47         <paramdef>const siginfo_t *<parameter>si</parameter></paramdef>
  48         <paramdef>void *<parameter>userdata</parameter></paramdef>
  49       </funcprototype>
  50
  51       <funcprototype>
  52         <funcdef>int <function>sd_event_add_child</function></funcdef>
  53         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  54         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  55         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  56         <paramdef>int <parameter>options</parameter></paramdef>
  57         <paramdef>sd_event_child_handler_t <parameter>handler</parameter></paramdef>
  58         <paramdef>void *<parameter>userdata</parameter></paramdef>
  59       </funcprototype>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_event_source_get_child_pid</function></funcdef>
  63         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  64         <paramdef>pid_t *<parameter>pid</parameter></paramdef>
  65       </funcprototype>
  66
  67     </funcsynopsis>
  68   </refsynopsisdiv>
  69
  70   <refsect1>
  71     <title>Description</title>
  72
  73     <para><function>sd_event_add_child()</function> adds a new child
  74     process state change event source to an event loop. The event loop
  75     object is specified in the <parameter>event</parameter> parameter,
  76     the event source object is returned in the
  77     <parameter>source</parameter> parameter. The
  78     <parameter>pid</parameter> parameter specifies the PID of the
  79     process to watch. The <parameter>handler</parameter> must
  80     reference a function to call when the process changes state. The
  81     handler function will be passed the
  82     <parameter>userdata</parameter> pointer, which may be chosen
  83     freely by the caller. The handler also receives a pointer to a
  84     <structname>siginfo_t</structname> structure containing
  85     information about the child process event. The
  86     <parameter>options</parameter> parameter determines which state
  87     changes will be watched for. It must contain an OR-ed mask of
  88     <constant>WEXITED</constant> (watch for the child process
  89     terminating), <constant>WSTOPPED</constant> (watch for the child
  90     process being stopped by a signal), and
  91     <constant>WCONTINUED</constant> (watch for the child process being
  92     resumed by a signal). See <citerefentry
  93     project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  94     for further information.</para>
  95
  96     <para>Only a single handler may be installed for a specific
  97     child process. The handler is enabled for a single event
  98     (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
  99     with
 100     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 101     If the handler function returns a negative error code, it will be
 102     disabled after the invocation, even if the
 103     <constant>SD_EVENT_ON</constant> mode was requested before.
 104     </para>
 105
 106     <para>To destroy an event source object use
 107     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 108     but note that the event source is only removed from the event loop
 109     when all references to the event source are dropped. To make sure
 110     an event source does not fire anymore, even when there's still a
 111     reference to it kept, consider setting the event source to
 112     <constant>SD_EVENT_OFF</constant> with
 113     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 114
 115     <para>If the second parameter of
 116     <function>sd_event_add_child()</function> is passed as NULL no
 117     reference to the event source object is returned. In this case the
 118     event source is considered "floating", and will be destroyed
 119     implicitly when the event loop itself is destroyed.</para>
 120
 121     <para>Note that the <parameter>handler</parameter> function is
 122     invoked at a time where the child process is not reaped yet (and
 123     thus still is exposed as a zombie process by the kernel). However,
 124     the child will be reaped automatically after the function
 125     returns. Child processes for which no child process state change
 126     event sources are installed will not be reaped by the event loop
 127     implementation.</para>
 128
 129     <para>If both a child process state change event source and a
 130     <constant>SIGCHLD</constant> signal event source is installed in
 131     the same event loop, the configured event source priorities decide
 132     which event source is dispatched first. If the signal handler is
 133     processed first, it should leave the child processes for which
 134     child process state change event sources are installed unreaped.</para>
 135
 136     <para><function>sd_event_source_get_child_pid()</function>
 137     retrieves the configured PID of a child process state change event
 138     source created previously with
 139     <function>sd_event_add_child()</function>. It takes the event
 140     source object as the <parameter>source</parameter> parameter and a
 141     pointer to a <type>pid_t</type> variable to return the process ID
 142     in.
 143     </para>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Return Value</title>
 148
 149     <para>On success, these functions return 0 or a positive
 150     integer. On failure, they return a negative errno-style error
 151     code.</para>
 152   </refsect1>
 153
 154   <refsect1>
 155     <title>Errors</title>
 156
 157     <para>Returned errors may indicate the following problems:</para>
 158
 159     <variablelist>
 160       <varlistentry>
 161         <term><constant>-ENOMEM</constant></term>
 162
 163         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><constant>-EINVAL</constant></term>
 168
 169         <listitem><para>An invalid argument has been passed. This includes
 170         specifying an empty mask in <parameter>options</parameter> or a mask
 171         which contains values different than a combination of
 172         <constant>WEXITED</constant>, <constant>WSTOPPED</constant>, and
 173         <constant>WCONTINUED</constant>.
 174         </para></listitem>
 175
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term><constant>-EBUSY</constant></term>
 180
 181         <listitem><para>A handler is already installed for this
 182         child process.</para></listitem>
 183
 184       </varlistentry>
 185
 186       <varlistentry>
 187         <term><constant>-ESTALE</constant></term>
 188
 189         <listitem><para>The event loop is already terminated.</para></listitem>
 190
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><constant>-ECHILD</constant></term>
 195
 196         <listitem><para>The event loop has been created in a different process.</para></listitem>
 197
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><constant>-EDOM</constant></term>
 202
 203         <listitem><para>The passed event source is not a child process event source.</para></listitem>
 204       </varlistentry>
 205
 206     </variablelist>
 207   </refsect1>
 208
 209   <xi:include href="libelogind-pkgconfig.xml" />
 210
 211   <refsect1>
 212     <title>See Also</title>
 213
 214     <para>
 215       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 216       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 217       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 218       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 219       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 220       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 221       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 222       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 223       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 224       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 225       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 226       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 227       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 228       <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 229     </para>
 230   </refsect1>
 231
 232 </refentry>