From 15e3e402c59089514f590bab8804f0ed60f0fee3 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Tue, 7 May 2024 22:06:36 +0000
Subject:  Add process group support to s6-supervise

Signed-off-by: Laurent Bercot <ska@appnovation.com>
---
 doc/index.html      |  2 +-
 doc/s6-svc.html     | 10 +++++++---
 doc/s6-svstat.html  |  5 ++++-
 doc/servicedir.html | 11 ++++++++---
 doc/upgrade.html    |  9 ++++++++-
 5 files changed, 28 insertions(+), 9 deletions(-)

(limited to 'doc')

diff --git a/doc/index.html b/doc/index.html
index f5afce2..b3bb158 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -115,7 +115,7 @@ want nsswitch-like functionality:
 <h3> Download </h3>
 
 <ul>
- <li> The current released version of s6 is <a href="s6-2.12.0.5.tar.gz">2.12.0.5</a>. </li>
+ <li> The current released version of s6 is <a href="s6-2.13.0.0.tar.gz">2.13.0.0</a>. </li>
  <li> Alternatively, you can checkout a copy of the
 <a href="//git.skarnet.org/cgi-bin/cgit.cgi/s6/">s6
 git repository</a>:
diff --git a/doc/s6-svc.html b/doc/s6-svc.html
index 208ee9c..de25dd0 100644
--- a/doc/s6-svc.html
+++ b/doc/s6-svc.html
@@ -28,7 +28,7 @@ knowing their PIDs, and without using horrible hacks such as .pid files.
 <h2> Interface </h2>
 
 <pre>
-     s6-svc [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -T <em>timeout</em> ] [ -s <em>signal</em> | -abqhkti12pcy ] [ -roduDUxO ] <em>servicedir</em>
+     s6-svc [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -T <em>timeout</em> ] [ -s <em>signal</em> | -abqhkti12pcyrPCK ] [ -oduDUxO ] <em>servicedir</em>
 </pre>
 
 <p>
@@ -58,7 +58,7 @@ supervised process. <em>signal</em> can be given as its name (case-
 insensitive) or its number, but only the signals listed above are
 accepted - you cannot, for instance, manually send a SIGSEGV to the
 supervised process. </li>
-</ul> <br />
+</ul> <br>
 <ul>
  <li> <tt>-o</tt>&nbsp;: once. Equivalent to "-uO". </li>
  <li> <tt>-d</tt>&nbsp;: down. If the supervised process is up, send it
@@ -117,7 +117,11 @@ option had been given instead. </li>
 started or restarted. </li>
  <li> <tt>-wR</tt>&nbsp;: s6-svc will not exit until the service has been
 started or restarted and has notified readiness. </li>
-
+</ul> <br>
+<ul>
+ <li> <tt>-P</tt>&nbsp;: send a SIGSTOP to the <em>process group</em> of the supervised process </li>
+ <li> <tt>-C</tt>&nbsp;: send a SIGCONT to the <em>process group</em> of the supervised process </li>
+ <li> <tt>-K</tt>&nbsp;: send a SIGKILL to the <em>process group</em> of the supervised process </li>
 </ul>
 
 <h2> Usage examples </h2>
diff --git a/doc/s6-svstat.html b/doc/s6-svstat.html
index ba62dbb..20a966a 100644
--- a/doc/s6-svstat.html
+++ b/doc/s6-svstat.html
@@ -27,7 +27,7 @@ summary of the state of a process monitored by
 <h2> Interface </h2>
 
 <pre>
-     s6-svstat [ -uwNrpest | -o up,wantedup,normallyup,ready,paused,pid,exitcode,signal,signum,updownsince,readysince,updownfor,readyfor ] [ -n ] <em>servicedir</em>
+     s6-svstat [ -uwNrpest | -o up,wantedup,normallyup,ready,paused,pid,pgid,exitcode,signal,signum,updownsince,readysince,updownfor,readyfor ] [ -n ] <em>servicedir</em>
 </pre>
 
 <p>
@@ -97,6 +97,8 @@ currently stopped) and <tt>false</tt> if it is not. It is a rare flag, you shoul
 need to use this option. </li>
    <li> <tt>pid</tt>: print the pid of the supervised process. If the service is currently down,
 <tt>-1</tt> is printed instead. </li>
+   <li> <tt>pgid</tt>: print the process group of the supervised process. If the service is
+currently down, print the process group of the last living instance of the service. </li>
    <li> <tt>exitcode</tt>: print the exit code of the last execution of <tt>./run</tt>. If the
 service is currently up, or the last <tt>./run</tt> process was killed by a signal,
 <tt>-1</tt> is printed instead. </li>
@@ -123,6 +125,7 @@ service last became ready (or ready to be started if it's currently not up and r
  <li> <tt>-N</tt>: equivalent to <tt>-o&nbsp;normallyup</tt>. </li>
  <li> <tt>-r</tt>: equivalent to <tt>-o&nbsp;ready</tt>. </li>
  <li> <tt>-p</tt>: equivalent to <tt>-o&nbsp;pid</tt>. </li>
+ <li> <tt>-g</tt>: equivalent to <tt>-o&nbsp;pgid</tt>. </li>
  <li> <tt>-e</tt>: equivalent to <tt>-o&nbsp;exitcode</tt>. </li>
  <li> <tt>-s</tt>: equivalent to <tt>-o&nbsp;signal</tt>. </li>
  <li> <tt>-t</tt>: equivalent to <tt>-o&nbsp;updownfor</tt>. </li>
diff --git a/doc/servicedir.html b/doc/servicedir.html
index a49a38d..f08c3a4 100644
--- a/doc/servicedir.html
+++ b/doc/servicedir.html
@@ -46,7 +46,7 @@ but most of the time it will be a script, called <em>run script</em>.
 This file is the most important one in your service directory: it
 contains the commands that will setup and run your <em>foo</em> service.
  <ul>
-  <li> It is forked and executed by <a href="s6-supervise.html">s6-supervise</a>
+  <li> It is spawned by <a href="s6-supervise.html">s6-supervise</a>
 every time the service must be started, i.e. normally when
 <a href="s6-supervise.html">s6-supervise</a> starts, and whenever
 the service goes down when it is supposed to be up. </li>
@@ -118,11 +118,16 @@ process has been killed. If the <em>foo</em> service is supposed to be up,
 script, not the finish script, should be running; the finish script should really
 be short-lived.) The maximum duration of a <tt>finish</tt> execution can be
 configured via the <tt>timeout-finish</tt> file, see below. </li>
-  <li> The finish script is executed with three arguments:
+  <li> The finish script is executed with four arguments:
    <ol>
     <li> the exit code from the run script (resp. 256 if the run script was killed by a signal) </li>
     <li> an undefined number (resp. the number of the signal that killed the run script) </li>
-    <li> the name of the service directory, the same that has been given to <tt>./run</tt>. </li>
+    <li> the name of the service directory, the same that has been given to <tt>./run</tt> </li>
+    <li> the process group id of the defunct run script. This is useful to clean up
+services that leave children behind: for instance, <tt>if test "$1" -gt 255 ; then kill -9 -- -"$4" ; fi</tt>
+in the finish script will SIGKILL all children processes if the service crashed.
+This is not an entirely reliable mechanism, because an annoying service could spawn
+children processes in a different process group, but it should catch most offenders. </li>
    </ol>
   <li> If the finish script exits 125, then <a href="s6-supervise.html">s6-supervise</a>
 interprets this as a permanent failure for the service, and does not restart it,
diff --git a/doc/upgrade.html b/doc/upgrade.html
index dfd79c6..546dab8 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -18,13 +18,20 @@
 
 <h1> What has changed in s6 </h1>
 
-<h2> in 2.12.0.5 </h2>
+<h2> in 2.13.0.0 </h2>
 
 <ul>
  <li> <a href="//skarnet.org/software/skalibs/">skalibs</a>
 dependency bumped to 2.14.2.0. </li>
  <li> <a href="//skarnet.org/software/execline/">execline</a>
 recommended dependency bumped to 2.9.5.1. </li>
+ <li> <a href="s6-svstat.html">s6-svstat</a> has new options,
+<tt>-g</tt> and <tt>-o pgid</tt>, to print the pgid of the service. </li>
+ <li> <a href="s6-supervise.html">s6-supervise</a> now passes the
+pgid of the defunct service as 4th argument to the finish script. </li>
+ <li> <a href="s6-svc.html">s6-svc</a> can now send SIGSTOP, SIGCONT
+and SIGKILL to the service's process group, via the <tt>-P</tt>, <tt>-C</tt>
+and <tt>-K</tt> options. </li>
 </ul>
 
 <h2> in 2.12.0.4 </h2>
-- 
cgit v1.3.1