Add s6-notify-fd-from-socket and s6-notify-socket-from-fd

 Also add .gitkeep files, remove old include-local/s6lockd.h,
update a little bit of doc, make s6-ftrigrd pipe-only

4 files changed, 275 insertions, 25 deletions

diff --git a/doc/index.html b/doc/index.html
index 721c5f1..bb1d762 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -162,7 +162,7 @@ ports the s6 documentation to a set of man pages.
 Short-lived commands exit 0 on success.
 </p>
 
-<h4> Supervision system </h4>
+<h4 id="supervision"> Supervision system </h4>
 
 <p>
  <a href="s6-svscan.html">s6-svscan</a> and <a href="s6-supervise.html">s6-supervise</a>
@@ -180,17 +180,24 @@ a user interface to control those processes and monitor service states.
 <li><a href="s6-svperms.html">The <tt>s6-svperms</tt> program</a></li>
 <li><a href="s6-svlink.html">The <tt>s6-svlink</tt> program</a></li>
 <li><a href="s6-svunlink.html">The <tt>s6-svunlink</tt> program</a></li>
-<li><a href="s6-svwait.html">The <tt>s6-svwait</tt> program</a></li>
-<li><a href="s6-svlisten1.html">The <tt>s6-svlisten1</tt> program</a></li>
-<li><a href="s6-svlisten.html">The <tt>s6-svlisten</tt> program</a></li>
-<li><a href="s6-notifyoncheck.html">The <tt>s6-notifyoncheck</tt> program</a></li>
 <li><a href="s6-svdt.html">The <tt>s6-svdt</tt> program</a></li>
 <li><a href="s6-svdt-clear.html">The <tt>s6-svdt-clear</tt> program</a></li>
 <li><a href="s6-permafailon.html">The <tt>s6-permafailon</tt> program</a></li>
 <li><a href="s6-background-watch.html">The <tt>s6-background-watch</tt> program</a></li>
 </ul>
 
-<h4> Daemontools-like utilities </h4>
+<h4 id="notification"> Readiness notification for supervised services </h4>
+
+<ul>
+ <li><a href="s6-svwait.html">The <tt>s6-svwait</tt> program</a></li>
+ <li><a href="s6-svlisten1.html">The <tt>s6-svlisten1</tt> program</a></li>
+ <li><a href="s6-svlisten.html">The <tt>s6-svlisten</tt> program</a></li>
+ <li><a href="s6-notifyoncheck.html">The <tt>s6-notifyoncheck</tt> program</a></li>
+ <li><a href="s6-notify-fd-from-socket.html">The <tt>s6-notify-fd-from-socket</tt> program</a></li>
+ <li><a href="s6-notify-socket-from-fd.html">The <tt>s6-notify-socket-from-fd</tt> program</a></li>
+</ul>
+
+<h4 id="daemontools"> Misc utilities for run scripts </h4>
 
 <p>
  These programs are a rewrite of the corresponding utilities from
@@ -211,14 +218,13 @@ a few extras.
 <li><a href="s6-tai64nlocal.html">The <tt>s6-tai64nlocal</tt> program</a></li>
 </ul>
 
-<h4> Fifodir management, notification and subscription </h4>
+<h4 id="fifodir"> Fifodir management, notification and subscription </h4>
 
 <p>
-These programs are a clean rewrite of the obsolete "pipe-tools" package; they
-are now based on a properly designed notification library.
-They provide a command-line interface to
+These programs provide a command-line interface to
 <a href="ftrig.html#notification">inter-process notification and
-synchronization</a>.
+synchronization</a>. They're a generalized interface to the same
+mechanisms used by tools like <a href="s6-svwait.html">s6-svwait</a>.
 </p>
 
 <ul>
@@ -237,7 +243,7 @@ synchronization</a>.
 <li><a href="libs6/s6-ftrigrd.html">The <tt>s6-ftrigrd</tt> internal program</a></li>
 </ul>
 
-<h4> Local service management and access control </h4>
+<h4 id="unixsocket"> Unix domain super-server, local service management and access control </h4>
 
 <ul>
 <li><a href="s6-ipcclient.html">The <tt>s6-ipcclient</tt> program</a></li>
@@ -255,7 +261,7 @@ synchronization</a>.
 <li><a href="s6-accessrules-fs-from-cdb.html">The <tt>s6-accessrules-fs-from-cdb</tt> program</a></li>
 </ul>
 
-<h4> suidless privilege gain </h4>
+<h4 id="nosuid"> suidless privilege gain </h4>
 
 <ul>
 <li><a href="s6-sudo.html">The <tt>s6-sudo</tt> program</a></li>
@@ -263,7 +269,7 @@ synchronization</a>.
 <li><a href="s6-sudod.html">The <tt>s6-sudod</tt> program</a></li>
 </ul>
 
-<h4> Logging </h4>
+<h4 id="log"> Logging </h4>
 
 <ul>
 <li><a href="s6-log.html">The <tt>s6-log</tt> program</a></li>
@@ -271,13 +277,13 @@ synchronization</a>.
 <li><a href="ucspilogd.html">The <tt>ucspilogd</tt> program</a></li>
 </ul>
 
-<h4> Management of user supervision trees </h4>
+<h4 id="usertree"> Management of user supervision trees </h4>
 
 <ul>
 <li><a href="s6-usertree-maker.html">The <tt>s6-usertree-maker</tt> program</a></li>
 </ul>
 
-<h4> Management of dynamic instances </h4>
+<h4 id="instance"> Management of dynamic instances </h4>
 
 <ul>
 <li>An <a href="instances.html">overview</a> of dynamic instantiation in s6</li>
@@ -289,7 +295,7 @@ synchronization</a>.
 <li><a href="s6-instance-list.html">The <tt>s6-instance-list</tt> program</a></li>
 </ul>
 
-<h4> fd-holding, a.k.a. the sensible part of socket activation </h4>
+<h4 id="fdholder"> fd-holding, a.k.a. the sensible part of socket activation </h4>
 
 <ul>
 <li><a href="s6-fdholder-daemon.html">The <tt>s6-fdholder-daemon</tt> program</a></li>
@@ -334,10 +340,9 @@ synchronization</a>.
 <h3> s6 manual pages </h3>
 
 <ul>
- <li> <a href="https://github.com/flexibeast">flexibeast</a> is doing the ungrateful
-but valuable work of
-<a href="https://github.com/flexibeast/s6-man-pages">providing the s6 documentation
-as a set of man pages</a>. </li>
+ <li> <a href="https://git.sr.ht/~humm/">Lennart Jablonka</a> is doing the ungrateful
+but valuable work of providing the s6 documentation
+<a href="https://git.sr.ht/~humm/s6-man-pages">as a set of man pages</a>. </li>
 </ul>
 
 <h3> Other components for s6-based init systems </h3>
@@ -346,10 +351,13 @@ as a set of man pages</a>. </li>
  <li> <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>
 is a package to help you create a <tt>/sbin/init</tt> binary booting a
 Linux system with s6-svscan as process 1. </li>
- <li> <a href="https://github.com/just-containers/s6-overlay">s6-overlay</a>
-is a project that automates integration of s6 into Docker images. </li>
  <li> <a href="//skarnet.org/software/s6-rc/">s6-rc</a> is a
 dependency-based service manager for s6. </li>
+ <li> <a href="//skarnet.org/software/s6-frontend/">s6-frontend</a> is
+a friendlier user interface to address the complete s6 ecosystem (this
+package, s6-linux-init and s6-rc). </li>
+ <li> <a href="https://github.com/just-containers/s6-overlay">s6-overlay</a>
+is a project that automates integration of s6 into Docker images. </li>
  <li> <a href="https://jjacky.com/anopa">anopa</a> is another dependency-based
 service manager for s6. </li>
  <li> <a href="https://web.obarun.org/software/66/latest/">66</a> is another
@@ -362,8 +370,8 @@ service manager working on top of s6. </li>
 <ul>
  <li> <tt>s6</tt> is discussed on the
 <a href="//skarnet.org/lists/#supervision">supervision</a> mailing-list. </li>
- <li> There is a <tt>#s6</tt> IRC channel on OFTC. Sometimes people are there
-and answer questions. </li>
+ <li> There is a <tt>#s6</tt> IRC channel on OFTC. It hosts most discussions
+around supervision topics, and skaware in general. </li>
 </ul>
 
 <h3> Similar work </h3>
diff --git a/doc/s6-notify-fd-from-socket.html b/doc/s6-notify-fd-from-socket.html
new file mode 100644
index 0000000..2a8ea62
--- /dev/null
+++ b/doc/s6-notify-fd-from-socket.html
@@ -0,0 +1,110 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="dark light" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6: the s6-notify-fd-from-socket program</title>
+    <meta name="Description" content="s6: the s6-notify-fd-from-socket program" />
+    <meta name="Keywords" content="s6 command s6-notify-fd-from-socket NOTIFY_SOCKET systemd notification service check" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The s6-notify-fd-from-socket </h1>
+
+<p>
+<tt>s6-notify-fd-from-socket</tt> is meant to be used in a run script,
+when you want to use s6 to supervise a program that follows systemd's
+<a href="https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html">NOTIFY_SOCKET</a>
+protocol. It converts a readiness notification sent via that protocol
+into s6's <a href="notifywhenup.html">native format</a>.
+</p>
+
+<h2 id="interface"> Interface </h2>
+
+<pre>
+     s6-notify-fd-from-socket [ -3 <em>fd</em> ] [ -f ] [ -t <em>timeout</em> ] <em>prog...</em>
+</pre>
+
+<ul>
+ <li> <tt>s6-notify-fd-from-socket</tt> doubleforks and runs as the grandchild;
+the parent immediately execs into <em>prog...</em>, which is expected to use the
+NOTIFY_SOCKET protocol. </li>
+ <li> If <em>prog</em> dies before sending its notification, or if the timeout
+(if any) expires, <tt>s6-notify-fd-from-socket</tt> just exits. </li>
+ <li> If <em>prog</em> notifies readiness, <tt>s6-notify-fd-from-socket</tt>
+writes a newline to the file descriptor configured for the service,
+then it exits. </li>
+</ul>
+
+<h2 id="exitcodes"> Exit codes </h2>
+
+<p>
+ <tt>s6-notify-fd-from-socket</tt> can exit before executing into <em>prog</em>:
+</p>
+
+<ul>
+ <li> 100: wrong usage </li>
+ <li> 111: system call failed </li>
+</ul>
+
+<p>
+ After forking, <tt>s6-notify-fd-from-socket</tt> (running as a child or
+grandchild) can
+exit with the following exit codes, but those are meaningless
+because no process will, or should, check them. They are only
+differentiated for clarity in the source code:
+</p>
+
+<ul>
+ <li> 0: service readiness achieved and notification sent </li>
+ <li> 99: timed out before readiness was achieved </li>
+ <li> 111: system call failed </li>
+</ul>
+
+<h2 id="options"> Options </h2>
+
+<dl>
+ <dt> <tt>-3 <em>fd</em></tt>, <tt>--notification-fd=<em>fd</em></tt> </dt>
+ <dd> Force writing the readiness notification to descriptor <em>fd</em>. By default,
+the notification is sent to the descriptor written in the <tt>notification-fd</tt>
+file of the service directory, and it is an error if this file does not exist
+(because the <a href="s6-supervise.html">supervisor</a> needs to be prepared to
+receive the notification). </dd>
+
+ <dt> <tt>-t <em>timeout</em></tt>, <tt>--timeout=<em>timeout</em></tt> </dt>
+ <dd> Exit without notifying the supervisor if <em>prog</em> hasn't notified
+readiness after <em>timeout</em> milliseconds. Default is <strong>0</strong>,
+meaning infinite: <tt>s6-notify-fd-from-socket</tt> will wait forever for
+a notification, up to when <em>prog</em> exits. </dd>
+
+ <dt> <tt>-f</tt>, <tt>--no-doublefork</tt> </dt>
+ <dd> Make <tt>s6-notify-fd-from-socket</tt> live as a direct child of
+<em>prog</em> rather than doubleforking. It is less costly (it might
+save a millisecond), but it will leave a zombie around if <em>prog</em>
+does not know how to reap its bastards (children it doesn't know it has).
+If <em>prog</em> reaps everything, you can safely use this option;
+otherwise, leave it alone. </dd>
+</dl>
+
+<h2 id="notes"> Notes </h2>
+
+<ul>
+ <li> <tt>s6-notify-fd-from-socket</tt> is for daemons using the systemd
+protocol that you want to run under s6. If you want to do the opposite, i.e.
+run under systemd a daemon that uses the s6 notification protocol, use the
+<a href="s6-notify-socket-from-fd.html">s6-notify-socket-from-fd</a> program
+instead. </li>
+</ul>
+
+
+
+</body>
+</html>
diff --git a/doc/s6-notify-socket-from-fd.html b/doc/s6-notify-socket-from-fd.html
new file mode 100644
index 0000000..ec2a57a
--- /dev/null
+++ b/doc/s6-notify-socket-from-fd.html
@@ -0,0 +1,129 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="dark light" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6: the s6-notify-socket-from-fd program</title>
+    <meta name="Description" content="s6: the s6-notify-socket-from-fd program" />
+    <meta name="Keywords" content="s6 command s6-notify-socket-from-fd NOTIFY_SOCKET systemd notification service check" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The s6-notify-socket-from-fd program </h1>
+
+<p>
+<tt>s6-notify-socket-from-fd</tt> is different from other chainloading
+tools in s6, in as it's not meant to be used in s6 run scripts. Instead,
+it's meant to be used when you're <em>not</em> using s6, but another
+service manager that does not support the
+<a href="notifywhenup.html">s6 readiness notification protocol</a>,
+but supports the
+<a href="https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html">NOTIFY_SOCKET</a>
+protocol.
+</p>
+
+<p>
+ Typically, you would use it if you have a daemon <tt>foobard</tt> that
+uses the s6 readiness notification protocol, but need to run that daemon
+under systemd. Instead of running it with <tt>ExecStart=foobard</tt> and
+having to use <tt>Type=main</tt>, losing the benefit of notification, you
+can use <tt>ExecStart="s6-notify-socket-from-fd foobard"</tt> and
+<tt>Type=notify</tt>, and systemd will handle readiness correctly.
+</p>
+
+<h2 id="interface"> Interface </h2>
+
+<pre>
+     s6-notify-socket-from-fd [ -d <em>fd</em> ] [ -f ] [ -t <em>timeout</em> ] [ -k ] <em>prog...</em>
+</pre>
+
+<ul>
+ <li> If the <tt>NOTIFY_SOCKET</tt> environment variable isn't defined,
+it means that <tt>s6-notify-socket-from-fd</tt> is not running under a
+supervisor expecting a systemd-style readiness notification. So it does nothing
+and just execs into <em>prog...</em>. If the variable is defined, the
+following points apply. </li>
+ <li> <tt>s6-notify-socket-from-fd</tt> doubleforks and runs as the grandchild;
+the parent immediately execs into <em>prog...</em>, which is expected to use the
+s6 readiness notification protocol. </li>
+ <li> If <em>prog</em> dies before sending its notification, or if the timeout
+(if any) expires, <tt>s6-notify-socket-from-fd</tt> just exits. </li>
+ <li> If <em>prog</em> notifies readiness, <tt>s6-notify-socket-from-fd</tt>
+sends a systemd-style notification to the supervisor listening to the socket
+given in <tt>NOTIFY_SOCKET</tt>, then it exits. </li>
+</ul>
+
+<h2 id="exitcodes"> Exit codes </h2>
+
+<p>
+ <tt>s6-notify-socket-from-fd</tt> can exit before executing into <em>prog</em>:
+</p>
+
+<ul>
+ <li> 100: wrong usage </li>
+ <li> 111: system call failed </li>
+</ul>
+
+<p>
+ After forking, <tt>s6-notify-socket-from-fd</tt> (running as a child or
+grandchild) can
+exit with the following exit codes, but those are meaningless
+because no process will, or should, check them. They are only
+differentiated for clarity in the source code:
+</p>
+
+<ul>
+ <li> 0: service readiness achieved and notification sent </li>
+ <li> 99: timed out before readiness was achieved </li>
+ <li> 111: system call failed </li>
+</ul>
+
+<h2 id="options"> Options </h2>
+
+<dl>
+ <dt> <tt>-d <em>fd</em></tt>, <tt>--notification-fd=<em>fd</em></tt> </dt>
+ <dd> Expect <em>prog...</em> to send its notification on descriptor <em>fd</em>.
+Default is <strong>1</strong>. </dd>
+
+ <dt> <tt>-t <em>timeout</em></tt>, <tt>--timeout=<em>timeout</em></tt> </dt>
+ <dd> Exit without notifying the supervisor if <em>prog</em> hasn't notified
+readiness after <em>timeout</em> milliseconds. Default is <strong>0</strong>,
+meaning infinite: <tt>s6-notify-socket-from-fd</tt> will wait forever for
+a notification, up to when <em>prog</em> exits. </dd>
+
+ <dt> <tt>-f</tt>, <tt>--no-doublefork</tt> </dt>
+ <dd> Make <tt>s6-notify-socket-from-fd</tt> live as a direct child of
+<em>prog</em> rather than doubleforking. It is less costly (it might
+save a millisecond), but it will leave a zombie around if <em>prog</em>
+does not know how to reap its bastards (children it doesn't know it has).
+If <em>prog</em> reaps everything, you can safely use this option;
+otherwise, leave it alone. </dd>
+
+ <dt> <tt>-k</tt>, <tt>--keep-environment</tt> </dt>
+ <dd> Keep the <tt>NOTIFY_SOCKET</tt> environment variable in <em>prog</em>'s
+environment. By default, the variable is removed from it, because <em>prog</em>,
+not using the systemd notification protocol, normally has no use for it. </dd>
+</dl>
+
+<h2 id="notes"> Notes </h2>
+
+<ul>
+ <li> This program was previously available on skarnet.org outside of any
+package, under the name <tt>sdnotify-wrapper</tt>. </li>
+ <li> <tt>s6-notify-socket-from-fd</tt> is for s6-style daemons that you
+want to run under systemd. If you want to do the opposite, i.e. run under
+s6 a daemon that uses the systemd protocol, use the
+<a href="s6-notify-fd-from-socket.html">s6-notify-fd-from-socket</a> program
+instead. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/upgrade.html b/doc/upgrade.html
index c31b001..e8cedc5 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -38,6 +38,9 @@ s6-ftrigrd now always runs as a child of the client </li>
    <li> The API of the <a href="libs6/ftrigr.html">ftrigr library</a>
 is somewhat different. </li>.
   </ul> </li>
+ <li> New binaries:
+<a href="s6-notify-fd-from-socket.html">s6-notify-fd-from-socket</a>,
+<a href="s6-notify-socket-from-fd.html">s6-notify-socket-from-fd</a>. </li>
 </ul>