From b1b5cca013c200014799953dd40d0b9e2ea88e63 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Wed, 22 Oct 2025 03:03:53 +0000
Subject:  Add some doc, improve s6-background-watch

---
 doc/servicedir.html | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

(limited to 'doc/servicedir.html')

diff --git a/doc/servicedir.html b/doc/servicedir.html
index 5cc2fe0..4ef16f5 100644
--- a/doc/servicedir.html
+++ b/doc/servicedir.html
@@ -151,7 +151,7 @@ automatically start it until it receives a <tt>s6-svc -u</tt> command. If no
  <li style="margin-bottom:1em"> An optional regular file named <tt>notification-fd</tt>. If such a file
 exists, it means that the service supports
 <a href="notifywhenup.html">readiness notification</a>. The file must only
- contain an unsigned integer, which is the number of the file descriptor that
+ contain a nonzero unsigned integer, which is the number of the file descriptor that
 the service writes its readiness notification to. (For instance, it should
 be 1 if the daemon is <a href="s6-ipcserverd.html">s6-ipcserverd</a> run with the
 <tt>-1</tt> option.)
@@ -164,7 +164,7 @@ notification from the service and broadcast readiness, i.e. any
 triggered. </li>
 
  <li style="margin-bottom:1em"> An optional regular file named <tt>lock-fd</tt>. If such a file
-exists, it must contain an unsigned integer, representing a file descriptor that
+exists, it must contain a nonzero unsigned integer, representing a file descriptor that
 will be open in the service. The service <em>should not write to that descriptor</em>
 and <em>should not close it</em>. In other words, it should totally ignore it. That
 file descriptor holds a lock, that will naturally be released when the service dies.
@@ -221,6 +221,30 @@ be very bad.) </li>
   </ul>
 </li>
 
+ <li style="margin-bottom:1em"> An optional regular file named <tt>pidfile</tt>.
+Creating such a file is not recommended, but is a workaround &mdash; and <em>only</em>
+a workaround &mdash; for daemons that background themselves. If this file
+exists, it must contain the path (either absolute or relative to the service
+directory) to a <em>pid file</em>, followed by a newline; the path must be shorter than
+512 bytes. The following behaviour is then expected:
+  <ul>
+   <li> On startup, the daemon must fork. </li>
+   <li> The child then becomes the long-running process. </li>
+   <li> The parent must write the pid of the child, followed by a newline, to the
+<em>pid file</em> whose path is written in the <tt>pidfile</tt> file in the service
+directory. For instance, if the daemon writes its pid to <tt>/var/run/foo.pid</tt>,
+then you would configure s6-supervise with <code> echo <tt>/var/run/foo.pid</tt>
+&gt; pidfile</code>. </li>
+   <li> After writing the pid file, the parent must exit 0. </li>
+   <li> If the <tt>notification-fd</tt> file is present in the service directory,
+<a href="s6-supervise.html">s6-supervise</a> will report the daemon to be <em>ready</em>
+once the parent has exited. </li>
+   <li> <a href="s6-supervise.html">s6-supervise</a> will then supervise the child
+as if it had not forked. </li>
+  </ul>
+If the file does not exist, <a href="s6-supervise.html">s6-supervise</a> only
+supervises daemons that do not background themselves, which is the normal case. </li>
+
  <li style="margin-bottom:1em"> A <a href="fifodir.html">fifodir</a> named <tt>event</tt>. It is automatically
 created by <a href="s6-supervise.html">s6-supervise</a> if it does not exist.
 <em>foo</em><tt>/event</tt>
-- 
cgit v1.3.1