X-Git-Url: http://dolda2000.com/gitweb/?a=blobdiff_plain;f=doc%2Fhtparser.doc;h=928e642c9a241c87376820f98c81588dea4262e4;hb=HEAD;hp=9bace5b1c4f7f92725064e0712cec39fa78e7533;hpb=2824afabef34b9bd0aa41644c7da1858d1532da8;p=ashd.git

diff --git a/doc/htparser.doc b/doc/htparser.doc
index 9bace5b..f400a62 100644
--- a/doc/htparser.doc
+++ b/doc/htparser.doc
@@ -24,7 +24,8 @@ all the 'ARGS' as command-line arguments. Only after that will
 *htparser* do any daemonizing or chrooting as specified by options.
 
 The root handler must be a persistent program as specified in
-*ashd*(7). If the handler program exits, *htparser* will exit too.
+*ashd*(7). If the handler program exits, *htparser* will exit too,
+following the procedure described below under SIGNALS.
 
 PORT SPECIFICATION
 ------------------
@@ -80,6 +81,45 @@ OPTIONS
 	After having daemonized, write the PID of the new process to
 	'PIDFILE'.
 
+If the *-u*, *-r* or *-p* option is presented with an empty argument,
+it will be treated as if the option had not been given.
+
+SIGNALS
+-------
+
+SIGTERM, SIGINT::
+
+	Upon first reception, `htparser` closes all listening ports
+	and the socket to the root handler, but continues to serve all
+	currently ongoing requests until none remain, not keeping the
+	connections open for keep-alive. Upon second reception,
+	`htparser` shuts down completely.
+
+PID-FILE PROTOCOL
+-----------------
+
+If the *-p* option is used to create a PID file, `htparser` will
+follow a simple protocol to allow state monitoring for clean shutdown
+purposes. When `htparser` is signalled to terminate, as described
+under SIGNALS, then it appends a single newline at the end of the PID
+file. Once all outstanding connections have been terminated, then
+`htparser` will truncate the PID file to zero size just prior to
+exiting. Thus, init scripts or other state-monitoring tools can know
+that `htparser` is serving remaining connections as long as the PID
+file contains two lines (the last of which is empty).
+
+Further, when `htparser` starts, it does not overwrite the contents of
+an existing PID file, but rather creates a new file, replacing the old
+file. Thus, if a new instance of `htparser` is started while a
+previous instance is still running (or serving remaining connections),
+the PID file for the new instance will not be truncated when the
+previous instance terminates.
+
+The reason for the somewhat unorthodox protocol is that it works by
+simply keeping the PID file open in the running process, allowing the
+protocol to work without pathnames, and therefore even if `htparser`
+is instructed to change root directory with the *-r* option.
+
 EXAMPLES
 --------