From 84b2c1858a5ef26bfa40a01fe57ed3cf0a1ada03 Mon Sep 17 00:00:00 2001
From: "C. McEnroe" <june@causal.agency>
Date: Mon, 17 Aug 2020 01:11:44 -0400
Subject: Flesh out documentation and improve examples

---
 catsitd.8 | 67 ++++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 38 insertions(+), 29 deletions(-)

(limited to 'catsitd.8')

diff --git a/catsitd.8 b/catsitd.8
index e5e7290..ae89531 100644
--- a/catsitd.8
+++ b/catsitd.8
@@ -47,7 +47,7 @@ daemon spawns processes for a list of
 redirects their output to syslog,
 and restarts the processes when they exit
 according to their exit status.
-Exponential backoff is applied to restarts.
+Exponential backoff is applied to automatic restarts.
 .
 .Pp
 The list of services is defined in a
@@ -60,9 +60,9 @@ through a named pipe.
 The
 .Xr catsit 8
 utility is a wrapper
-around the named pipe,
+for writing to the named pipe,
 and its manual page
-describes the control command format.
+describes the control command syntax.
 .
 .Pp
 The arguments are as follows:
@@ -76,10 +76,12 @@ By default the working directory is
 .
 .It Fl c Ar control
 Set the path of the named pipe
-used for control.
+used for service control.
 .
 .It Fl d
 Do not run as a daemon.
+Log to standard error
+as well as syslog.
 .
 .It Fl f Ar config
 Set the path of the
@@ -92,7 +94,7 @@ Change group to
 before starting services.
 If
 .Fl u
-is used,
+is set,
 the default group is the user's group.
 .
 .It Fl p Ar pidfile
@@ -118,11 +120,12 @@ The default list contains the values of
 .Dv EX_USAGE ,
 .Dv EX_DATAERR ,
 .Dv EX_NOINPUT ,
-.Dv EX_OSFILE ,
+.Dv EX_OSFILE
+and
 .Dv EX_CANTCREAT
 defined in
 .Xr sysexits 3 .
-The exit statuses 127 and 126
+The exit statuses 126 and 127
 are always treated as stop exits.
 .
 .It Fl t Ar restart
@@ -137,36 +140,42 @@ The default interval is 1 second.
 Change user to
 .Ar user
 before starting services.
+Services which are
+.Em privileged
+are started without changing user.
+The
+.Xr catsit.conf 5
+manual page
+describes privileged services.
 .El
 .
 .Pp
-When the
+The
 .Nm
-daemon receives the
-.Dv HUP
-signal,
-the
+daemon takes the following actions
+in response to signals:
+.Bl -tag -width Ds
+.It Dv HUP
+The
 .Xr catsit.conf 5
 file is reloaded.
-Modified services
-are not automatically restarted,
-newly added services
-are not automatically started,
-and removed services
-are not automatically stopped.
-.
-.Pp
-When the
-.Nm
-daemon receives the
-.Dv TERM
-signal,
-the named pipe is closed,
-all services are stopped,
-and
+Services are not automatically
+started, stopped or restarted.
+Removed services can be dropped with
+.Xr catsit 8 .
+.
+.It Dv TERM
+The named pipe used for service control
+is closed and unlinked.
+All services are stopped,
+after which
 .Nm
 exits.
 .
+.It Dv INFO
+The current status of all services is logged.
+.El
+.
 .Sh ENVIRONMENT
 Services are started
 with empty environments
@@ -196,7 +205,7 @@ The default path of the
 file.
 .It Pa /var/run/catsitd.pipe
 The default path of the named pipe
-used for control.
+used for service control.
 .El
 .
 .Sh SEE ALSO
-- 
cgit 1.4.1