From ae97e8065a0e3be60d16c0d9e158afc697aa94e5 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Thu, 5 Apr 2018 09:42:37 +0000
Subject:  Add note about SIGINT in s6-svscan and s6-supervise doc

---
 doc/s6-supervise.html | 11 +++++++++++
 doc/s6-svscan.html    | 15 ++++++++++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/s6-supervise.html b/doc/s6-supervise.html
index b2a83d5..d9852b5 100644
--- a/doc/s6-supervise.html
+++ b/doc/s6-supervise.html
@@ -171,6 +171,17 @@ better to have a collection of <a href="servicedir.html">service directories</a>
 single <a href="scandir.html">scan directory</a>, and just run
 <a href="s6-svscan.html">s6-svscan</a> on that scan directory. s6-svscan will spawn
 the necessary s6-supervise processes, and will also take care of logged services. </li>
+ <li> s6-supervise is not supposed to have a controlling terminal: it's generally
+launched by a <a href="s6-svscan.html">s6-svscan</a> process that itself does not
+have a controlling terminal. If you run s6-supervise from an interactive shell, be
+warned that typing ^C in the controlling terminal (which sends a SIGINT to
+all processes in the foreground process group in the terminal) will terminate
+s6-supervise, but not the supervised processes - so, the daemon will keep running
+as an orphan. This is by design: supervised processes should be as resilient as
+possible, even when their supervisors die. However, if you want to launch
+s6-supervise from an interactive shell and need your service to die when you ^C it,
+you can obtain this behaviour by creating a <tt>./nosetsid</tt> file in the
+<a href="servicedir.html">service directory</a>. </li>
  <li> You can use <a href="s6-svc.html">s6-svc</a> to send commands to the s6-supervise
 process; mostly to change the service state and send signals to the monitored
 process. </li>
diff --git a/doc/s6-svscan.html b/doc/s6-svscan.html
index 7649abd..4bb943b 100644
--- a/doc/s6-svscan.html
+++ b/doc/s6-svscan.html
@@ -200,7 +200,7 @@ uses <a href="s6-svscanctl.html">s6-svscanctl -n</a>), but inactive
 s6-supervise processes will not be restarted if they die.
 </p>
 
-<h2> Implementation notes </h2>
+<h2> Notes </h2>
 
 <ul>
  <li> s6-svscan is designed to run until the machine is shut down. It is
@@ -220,6 +220,19 @@ to guarantee that s6-svscan does not use heap memory at all.</small> </li>
  <li> When run with the <tt>-t0</tt> option, s6-svscan <em>never polls</em>,
 it only wakes up on notifications, just like s6-supervise. The s6 supervision
 tree can be used in energy-critical environments. </li>
+ <li> The supervision tree (i.e. the tree of processes made of s6-svscan and
+all its scions) is not supposed to have a controlling terminal; s6-svscan
+generally is either process 1 or a child of process 1, not something that is
+launched from a terminal. If you run s6-svscan from an interactive shell, be
+warned that typing ^C in the controlling terminal (which sends a SIGINT to
+all processes in the foreground process group in the terminal) will terminate
+the supervision tree, but not the supervised processes - so, the supervised
+processes will keep running as orphans. This is by design: supervised
+processes should be as resilient as possible, even when their supervisors
+die. However, if you want to launch s6-svscan from an interactive shell and
+need your services to die with the supervision tree when you ^C it, you can
+obtain this behaviour by creating <tt>./nosetsid</tt> files in every
+<a href="servicedir.html">service directory</a>. </li>
 </ul>
 
 </body>
-- 
cgit v1.3.1