--- loncom/Attic/lonc	2002/02/25 20:43:15	1.30
+++ loncom/Attic/lonc	2002/03/03 18:13:07	1.31
@@ -5,7 +5,7 @@
 # provides persistent TCP connections to the other servers in the network
 # through multiplexed domain sockets
 #
-# $Id: lonc,v 1.30 2002/02/25 20:43:15 www Exp $
+# $Id: lonc,v 1.31 2002/03/03 18:13:07 harris41 Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -797,22 +797,116 @@ lonc - LON TCP-MySQL-Server Daemon for h
 
 =head1 SYNOPSIS
 
+Usage: B<lonc>
+
 Should only be run as user=www.  This is a command-line script which
-is invoked by loncron.
+is invoked by B<loncron>.  There is no expectation that a typical user
+will manually start B<lonc> from the command-line.  (In other words,
+DO NOT START B<lonc> YOURSELF.)
 
 =head1 DESCRIPTION
 
 Provides persistent TCP connections to the other servers in the network
 through multiplexed domain sockets
 
- PID in subdir logs/lonc.pid
- kill kills
- HUP restarts
- USR1 tries to open connections again
+B<lonc> forks off children processes that correspond to the other servers
+in the network.  Management of these processes can be done at the
+parent process level or the child process level.
+
+B<logs/lonc.log> is the location of log messages.
+
+The process management is now explained in terms of linux shell commands,
+subroutines internal to this code, and signal assignments:
+
+=over 4
+
+=item *
+
+PID is stored in B<logs/lonc.pid>
+
+This is the process id number of the parent B<lonc> process.
+
+=item *
+
+SIGTERM and SIGINT
+
+Parent signal assignment:
+ $SIG{INT}  = $SIG{TERM} = \&HUNTSMAN;
+
+Child signal assignment:
+ $SIG{INT}  = 'DEFAULT'; (and SIGTERM is DEFAULT also)
+(The child dies and a SIGALRM is sent to parent, awaking parent from slumber
+ to restart a new child.)
+
+Command-line invocations:
+ B<kill> B<-s> SIGTERM I<PID>
+ B<kill> B<-s> SIGINT I<PID>
+
+Subroutine B<HUNTSMAN>:
+ This is only invoked for the B<lonc> parent I<PID>.
+This kills all the children, and then the parent.
+The B<lonc.pid> file is cleared.
+
+=item *
+
+SIGHUP
+
+Current bug:
+ This signal can only be processed the first time
+on the parent process.  Subsequent SIGHUP signals
+have no effect.
+
+Parent signal assignment:
+ $SIG{HUP}  = \&HUPSMAN;
+
+Child signal assignment:
+ none (nothing happens)
+
+Command-line invocations:
+ B<kill> B<-s> SIGHUP I<PID>
+
+Subroutine B<HUPSMAN>:
+ This is only invoked for the B<lonc> parent I<PID>,
+This kills all the children, and then the parent.
+The B<lonc.pid> file is cleared.
+
+=item *
+
+SIGUSR1
+
+Parent signal assignment:
+ $SIG{USR1} = \&USRMAN;
+
+Child signal assignment:
+ $SIG{USR1}= \&logstatus;
+
+Command-line invocations:
+ B<kill> B<-s> SIGUSR1 I<PID>
+
+Subroutine B<USRMAN>:
+ When invoked for the B<lonc> parent I<PID>,
+SIGUSR1 is sent to all the children, and the status of
+each connection is logged.
+
+=item *
+
+SIGCHLD
+
+Parent signal assignment:
+ $SIG{CHLD} = \&REAPER;
+
+Child signal assignment:
+ none
+
+Command-line invocations:
+ B<kill> B<-s> SIGCHLD I<PID>
 
-=head1 README
+Subroutine B<REAPER>:
+ This is only invoked for the B<lonc> parent I<PID>.
+Information pertaining to the child is removed.
+The socket port is cleaned up.
 
-Not yet written.
+=back
 
 =head1 PREREQUISITES