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