From 4d157070b438574bb7c5c30cb62a135f056b4289 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sun, 7 Feb 2021 11:08:11 +0000
Subject:  Document an unintuitive case in s6-svc

---
 doc/s6-svc.html       | 14 +++++++++++++-
 doc/s6-svlisten1.html |  2 +-
 2 files changed, 14 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/s6-svc.html b/doc/s6-svc.html
index c4bd40a..62e93f9 100644
--- a/doc/s6-svc.html
+++ b/doc/s6-svc.html
@@ -134,7 +134,8 @@ is ready. Exit 1 if it is still not ready after 5 seconds.
 <p>
  Send a SIGTERM to the ftpd server; wait for
 <a href="s6-supervise.html">s6-supervise</a> to restart it, and block
-until it has notified that it is ready to serve again.
+until it has notified that it is ready to serve again. See the NOTES
+section below for a caveat.
 </p>
 
 <pre> s6-svc -a /service/httpd/log </pre>
@@ -156,5 +157,16 @@ that will send the commands to the service. Any error message written during
 the waiting period will mention it is being written by s6-svlisten1; this is normal. </li>
 </ul>
 
+<h2> Notes </h2>
+
+<ul>
+ <li> The <tt>-t</tt> and <tt>-r</tt> options make <a href="s6-supervise.html">s6-supervise</a>
+send a signal to the service if it is up; but if the service is currently down,
+they do nothing, and in particular they do not instruct s6-supervise to bring the
+service up. Consequently, <tt>s6-svc -rwr <em>servicedir</em></tt> may wait forever
+for the service to be up, if it is currently wanted down. To avoid that, make sure
+your service is wanted up by using <tt>s6-svc -ruwr <em>servicedir</em></tt> instead. </li>
+</ul>
+
 </body>
 </html>
diff --git a/doc/s6-svlisten1.html b/doc/s6-svlisten1.html
index 91c8625..adb0ddd 100644
--- a/doc/s6-svlisten1.html
+++ b/doc/s6-svlisten1.html
@@ -71,7 +71,7 @@ See the explanation on <a href="notifywhenup.html">this page</a>. </li>
  <li> <tt>-D</tt>&nbsp;: really down. s6-svlisten1 will wait until the
 service is down and the cleanup script in <tt><em>servicedir</em>/finish</tt>
 has finished executing (or has timed out and been killed). </li>
- <li> <tt>-r</tt>&nbsp;: restart. s6-svlisteni1 will wait until
+ <li> <tt>-r</tt>&nbsp;: restart. s6-svlisten1 will wait until
 the service has been started or restarted, i.e. they have been in the
 down state, then the up state. </li>
  <li> <tt>-R</tt>&nbsp;: restart and ready. s6-svlisten1 will wait until
-- 
cgit v1.2.3