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