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

@@ -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;
+}

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>