From 5ca99dfabda20927a0d47e5f19339d1b48f82f7a Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Wed, 5 Jan 2022 15:04:06 +0100
Subject: [PATCH] man: add example of sd_event_add_child()

The thing with blocking SIGCHLD is rather annoying. I think we could/should
make this automatic.
---
 man/event-quick-child.c    | 42 ++++++++++++++++++++++++++++++++++++++
 man/sd_event_add_child.xml | 10 +++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 man/event-quick-child.c

diff --git a/man/event-quick-child.c b/man/event-quick-child.c
new file mode 100644
index 00000000000..16cc6cf3a4c
--- /dev/null
+++ b/man/event-quick-child.c
@@ -0,0 +1,42 @@
+/* SPDX-License-Identifier: CC0-1.0 */
+
+#include <assert.h>
+#include <stdio.h>
+#include <unistd.h>
+#include <sd-event.h>
+
+int main(int argc, char **argv) {
+  pid_t pid = fork();
+  assert(pid >= 0);
+
+  /* SIGCHLD signal must be blocked for sd_event_add_child to work */
+  sigset_t ss;
+  sigemptyset(&ss);
+  sigaddset(&ss, SIGCHLD);
+  sigprocmask(SIG_BLOCK, &ss, NULL);
+
+  if (pid == 0)  /* child */
+    sleep(1);
+
+  else {         /* parent */
+    sd_event *e = NULL;
+    int r;
+
+    /* Create the default event loop */
+    sd_event_default(&e);
+    assert(e);
+
+    /* We create a floating child event source (attached to 'e').
+     * The default handler will be called with 666 as userdata, which
+     * will become the exit value of the loop. */
+    r = sd_event_add_child(e, NULL, pid, WEXITED, NULL, (void*) 666);
+    assert(r >= 0);
+
+    r = sd_event_loop(e);
+    assert(r == 666);
+
+    sd_event_unref(e);
+  }
+
+  return 0;
+}
diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml
index 621efad8d3f..fec754d2dde 100644
--- a/man/sd_event_add_child.xml
+++ b/man/sd_event_add_child.xml
@@ -311,6 +311,16 @@
 
   <xi:include href="libsystemd-pkgconfig.xml" />
 
+  <refsect1>
+    <title>Example</title>
+
+    <example>
+      <title>Exit loop when the child terminates</title>
+
+      <programlisting><xi:include href="event-quick-child.c" parse="text" /></programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
 
-- 
2.47.3