RE: Customised control help

[Charlie Brady <charlieb-supervision@budge.apana.org.au>]

On Wed, 2 Jan 2008, rehan khan wrote:

> :( Don't let my confusion upset you so. I'm just not an expert on these things and there is a lot to take in.
>
> I think that the following section makes it a little confusing
>
> 'before interpreting the command. If the program exits with return code 0'
>
> It might be a little clearer, language-wise, if the text stays with 
> using script instead of using command and program interchangeably with 
> script (they are different, are they not?).

'script' is a subset of program. 'scripts' are programs, but not all 
'programs' are scripts. 'command' is a one byte character written into the 
control fifo.

> Separating out the exceptions would also highlight them. So the text 
> would be something like:
>
> Customise Control
>
> For each control character c sent to the control pipe, runsv first 
> checks if service/control/c exists and is executable. If so, it starts 
> service/control/c and waits for it to terminate, before interpreting the 
> result (return code) of the script.

Reference here to 'script' is incorrect. service/control/c is a program 
(and only might be a script).

I think it would be better to just end the sentence with "and waits for it 
to terminate". The existing "before interpreting the command" appears to 
be confusing, and "before interpreting the result (return code) of the 
script" may also be confusing. At any rate it is an unnnecessary phrase, 
as "If the script exits with return code 0" most definitely implies that 
runsv interprets the return code.

> If the script exits with return code 0, runsv refrains from sending the 
> service the corresponding signal. If the script exits with a return code 
> greater than 0 the corresponding signal is sent to the service.

You are assuming that return codes are not less than zero.

> Notes for Customised Control:
> The command o is always considered as command u.
> On command d first service/control/t is checked, and then service/control/d.
> On command x first service/control/t is checked, and then service/control/x.
> The control of the optional log service cannot be customized.

I wonder whether it would make things clearer if the sections Control and 
Customize Control were combined. viz:

Control

The named pipes service/supervise/control, and (optionally) 
service/log/supervise/control are provided to give commands to runsv. You 
can use sv(8) to control the service or just write one of the following 
characters to the named pipe:

...
d
     Down. If the service is not running, do nothing. If ./control/t
     exists, and is executable, execute it and wait for it to terminate.
     If ./control/t does not exist, but ./service/control/d exists and
     is executable, execute it and wait for it to terminate. If neither
     program exists, or the program exits with non-zero status, then
     send the service a TERM signal, and then a CONT signal. If ./run
     exits, start ./finish if it exists. After it stops, do not restart
     service.
...