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