Update the docs.

3 files changed, 345 insertions, 25 deletions

diff --git a/doc/config.texi b/doc/config.texi
index 4e8ef8d..b7af0dc 100644
--- a/doc/config.texi
+++ b/doc/config.texi
@@ -446,7 +446,7 @@ print-priority yes;
 @node daemon
 @section Daemon Configuration
 
-  The following statements configure @command{sld} activities in
+  The following statements configure @command{slb} activities in
 daemon mode.
 
 @deffn {Config} daemon bool
@@ -626,7 +626,7 @@ The following functions are supported by SLB version @value{VERSION}:
 @anchor{derivative}
 @deffn {function} d (x)
 Returns the derivative of @var{x}, i.e. the speed of its change per
-second, measured between the two last wakeups of @command{sld}
+second, measured between the two last wakeups of @command{slb}
 (@FIXME-pxref{wakeup}).
 
 Notice, that this function is available only in daemon mode
@@ -849,6 +849,7 @@ Print at most @var{number} entries from the bottom of the table, i.e. the
 @var{number} of the most loaded server entries.
 @end deffn
 
+@anchor{output-file}
 @deffn {Config} output-file string
 Send output to the channel, identified by @var{string}.  Unless
 @var{string} starts with a pipe sign, it is taken as a literal name of
diff --git a/doc/slb.8 b/doc/slb.8
index d63682a..9fb365e 100644
--- a/doc/slb.8
+++ b/doc/slb.8
@@ -13,17 +13,24 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with SLB.  If not, see <http://www.gnu.org/licenses/>.
-.TH SLB "8" "April 20, 2011" "SLB" ""
+.TH SLB "8" "April 25, 2011" "SLB" ""
 .SH NAME
 \fBslb\fR \- Simple Load Balancer
 
 .SH SYNOPSIS
 \fBslb\fR [\-EVehnt] [\-D \fISYMBOL[=VALUE]\fR] [\-I \fIDIR\fR]\
- [\-c \fIFILE\fR] [\-d \fICAT\fR[.\fILEVEL\fR]] [--config-file=\fIFILE\fR]\
+ [\-o \fIFILE\fR] [\-c \fIFILE\fR] [\-d \fICAT\fR[.\fILEVEL\fR]] [--config-file=\fIFILE\fR]\
  [\-\-config-help] [\-\-cron] [\-\-debug=\fICAT\fR[.\fILEVEL\fR]] [\-\-define=\fISYMBOL[=VALUE]\fR]\
  [\-\-dry-run] [\-\-foreground]\
  [\-\-help] [\-\-include-directory=\fIDIR\fR] [\-\-lint] [\-\-no-preprocessor]\
- [\-\-preprocessor=\fICOMMAND\fR] [\-\-stderr] [\-\-syslog] [\-\-usage] [\-\-version]
+ [\-\-output-file=\fIFILE\fR] [\-\-preprocessor=\fICOMMAND\fR] [\-\-stderr]\
+ [\-\-syslog] [\-\-usage] [\-\-version]
+.br
+\fBslb\fR \-\-eval=\fINAME\fR [variable=\fIvalue\fR...]
+.br
+\fBslb\fR \-T [\fIFILE\fR]
+.br
+\fBslb\fR \-\-test [\fIFILE\fR]
 
 .SH DESCRIPTION
 \fBSlb\fR is a tool designed to simplify the task of load balancing
@@ -60,15 +67,43 @@ source.
 
 .SH OPTIONS
 .TP
-\fB\-E\fR
-Preprocess config and exit.
-.TP
 \fB-c\fR \fIFILE\fR, \fB\-\-config-file\fR=\fIFILE\fR
 Read \fIFILE\fR instead of the default configuration file.
 .TP
 \fB\-\-cron\fR
 Cron mode: run load estimation loop once and exit.
 .TP
+\fB\-\-eval\fR=\fINAME\fR
+Evaluate the expression \fINAME\fR, print its result and exit.
+The expression must be defined in the configuration file with
+the \fBexpression\fR statement (see \fBCONFIGURATION FILE\fR below).
+Actual values for the variables used in the expression can be supplied
+in the form of assignments in the command line, e.g.:
+
+  slb --eval=loadavg la1=10 outbytes=1800
+
+Several values can be supplied for a single variable as in:
+in:
+
+  slb --eval=loadavg la1=10,11 outbytes=1800,3000,4500
+
+In this case the expression will be evaluated as many times as the
+maximum number of values, the result of each evaluation being
+printed to the standard output.  In the example above, the expression
+is evaluated three times, with the following values as input:
+
+  la1=10  outbytes=1800
+  la1=11  outbytes=3000
+  la1=11  outbytes=4500
+
+This form is useful if the expression contains the \fBd\fR() function,
+which requires at least a pair of data to compute a meaningful value.
+.TP
+\fB\-E\fR
+Preprocess config and exit.
+.TP
+\fB\
+.TP
 \fB\-\-foreground\fR
 Do not detach from the controlling terminal, run in foreground.
 .TP
@@ -80,6 +115,37 @@ have otherwise been printed on the output file.  This option implies
 .TP
 \fB\-t\fR, \fB\-\-lint\fR
 Parse the configuration file and exit.
+.TP
+\fB-T\fR, \fB\-\-test\fR
+Read SNMP variables and their values from a file and act as if they
+were returned by SNMP.  The output is directed to the standard output,
+unless the \fB\-\-output-file\fR option is also given.
+
+The input file name is taken from the first non-option argument.  If
+it is \fB-\fR (a dash) or if no arguments are given, the standard
+input will be read.
+
+The input file consists of sections separated by exactly one empty
+line.  A section contains assignments to SNMP variables in the style
+of \fBsnmpset(1)\fR.  Such assignments form several server groups, each
+group being preceded by a single word on a line, followed by a
+semicolon.  This word indicates the \fBID\fR of the server to which
+the data in the group belong.  For example:
+
+  srv01:
+  UCD-SNMP-MIB::laLoadFloat.1 F 0.080000
+  IF-MIB::ifOutUcastPkts.3 c 346120120
+  srv02:
+  UCD-SNMP-MIB::laLoadFloat.1 F 0.020000
+  IF-MIB::ifOutUcastPkts.3 c 2357911693
+
+This section supplies data for two servers, named \(aqsrv01\(aq and
+\(aqsrv02\(aq.
+.TP
+\fB\-o\fR, \fB\-\-output-file\fR=\fIFILE\fR
+Direct output to \fIFILE\fR.  This option overrides the
+\fBoutput-file\fR configuration statement (see below).  The format of
+\fIFILE\fR argument is the same as for that statement.
 .SS Logging
 .TP
 \fB-e\fR, \fB--stderr\fR
@@ -298,6 +364,9 @@ Multiplication.
 .TP
 \fB/\fR
 Division.
+.TP
+\fB**\fR
+Power.
 .PP
 A \fBsubexpression reference\fR is a construct in the form:
 
@@ -363,7 +432,7 @@ The following functions are supported:
 .TP
 \fBd\fR(\fIx\fR)
 Returns the derivative of \fIx\fR, i.e. the speed of its change per
-second, measured between the two last wakeups of \fBsld\fR.
+second, measured between the two last wakeups of \fBslb\fR.
 
 Notice, that this function is available only in daemon mode.
 .TP
@@ -444,9 +513,10 @@ value is padded on the right  with blanks, rather than on the left
 with blanks or zeros.  A \fB-\fR overrides a \fB0\fR if both are
 given.        
 .TP
-' ' (a space)
-A blank should be left before a positive number (or empty string)
-produced by conversion.
+.B \(aq \(aq
+(a space) A blank should be left before a positive number
+(or empty string) produced by a conversion.
+
 .SS The field width
 An optional decimal digit string (with non-zero first digit)
 specifying a minimum field width.  If the converted value has fewer
@@ -491,6 +561,55 @@ Expansion of the \fImacro\fR.
 \fB%\fR
 The percent character.
 
+.SH SIGNALS
+The program handles a set of signals.  To send a signal to
+\fBslb\fR use the following command:
+
+  kill -\fBSIGNAL\fR `cat /var/run/slb.pid`
+
+Replace \fI/var/run/slb.pid\fR with the actual pathname to the
+PID-file, if it was set using the \fBpidfile\fR configuration
+statement.
+
+.TP
+.B SIGHUP
+Instructs the running instance of the program
+to restart itself.  It is possible only if \fBslb\fR was started using
+its full pathname.
+.TP
+.BR SIGTERM ", " SIGQUIT ", " \fBSIGINT\fR
+\fBslb\fR terminates gracefully.
+
+.SH EXIT CODES
+The following exit codes are defined:
+.RS
+.PD 0
+.TP 3
+.I 0
+Normal termination.
+.TP 3
+.I 64
+Invalid command line usage.
+.TP 3
+.I 65
+Input data were invalid or malformed.  This error code is returned
+only when \fBslb\fR is used with \fB\-\-test\fR or
+\fB\-\-eval\fR options.
+.TP 3
+.I 69
+Some error occurred.  For example, the program was unable to open
+output file, etc.
+.TP 3
+.I 70
+Internal software error.  This usually means hitting a bug in the
+program, so please report it.
+.TP 3
+.I 98
+Program terminated due to errors in configuration file.
+.PD
+.RE
+If a non-0 code is returned the exact cause of failure is
+reported on the currently selected logging channel.
 
 .SH AUTHORS
 Sergey Poznyakoff
diff --git a/doc/slb.texi b/doc/slb.texi
index 19cdcd0..c16c32d 100644
--- a/doc/slb.texi
+++ b/doc/slb.texi
@@ -76,6 +76,8 @@ documents SLB Version @value{VERSION}.
 * Tutorial::
 * Invocation::              SLB Command Line Syntax.
 * Configuration::           SLB Configuration.
+* Exit Codes::              SLB Exit Codes.
+* Signals::
 
 * Reporting Bugs::          How to Report a Bug.
 
@@ -166,13 +168,102 @@ familiar with the package.
 
 @node Tutorial
 @chapter Tutorial
-@WRITEME
+@UNREVISED
+
+@menu
+* Option Basics::
+* Configuration Basics::
+@end menu
+
+@node Option Basics
+@section Option Basics
+Options start with a dash.  Most of them have two forms, called short and
+long forms.  Both forms are absolutely identical in function; they are
+interchangeable.
+
+@cindex short options
+@cindex options, short
+  The @dfn{short} form is a traditional form for UNIX utilities.
+In this form, the option consists of a single dash, followed by a
+single letter, e.g. @option{-c}.
+
+  Short options which require arguments take their arguments
+immediately following the option letter, optionally separated by white
+space.  For example, you might write @option{-o name}, or @option{-oname}.
+Here, @option{-o} is the option, and @option{name} is its argument.
+
+  Short options' letters may be clumped together, but you are not
+required to do this.  When short options are clumped as a set, use one
+(single) dash for them all, e.g. @option{-ne} is equivalent to @option{-n
+-e}.  However, only options that do not take arguments may be
+clustered this way.  If an option takes an argument, it can only be
+the last option in such a cluster, otherwise it would be impossible to
+specify the argument for it.  Anyway, it is much more readable to
+specify such options separated.
+
+@cindex options, long
+@cindex long options
+  The @dfn{long} options consist of two dashes, followed by a
+multi-letter option name, which is usually selected to be a mnemonics
+for the operation it requests.  Long option names can be abbreviated,
+provided that such an abbreviation is unique among the options
+understood by the program.
+
+  Arguments to long options follow the option name being separated
+from it either by an equal sign, or by any amount of white space
+characters.  For example, the option @option{--eval} with the
+argument @samp{test} can be written either as @option{--eval=test} or
+as @option{--eval test}.
+
+@node Configuration Basics
+@section Configuration Basics
+The @dfn{configuration file} defines most parameters needed for the normal
+operation of @command{slb}.  The program will not start if its
+configuration file does not exist, cannot be read, or contains some errors.
+
+@xopindex{config-file, introduced}
+The configuration file is located in your system configuration
+directory (normally @file{/etc}) and is named @file{slb.conf}.  You
+can place it elsewhere as well, but in this case you will need to
+explicitly inform @command{slb} about its actual location, using the
+@option{--config-file} (@option{-c}) command line option:
+
+@example
+slb --config-file ./new.conf
+@end example
+
+
+For a detailed discussion of configuration format, see
+@ref{Configuration}.
+
 
 @node Invocation
 @chapter SLB Command Line Syntax
-@UNREVISED
+  The format of @command{slb} invocation is:
+
+@example
+slb @var{options} @var{args}
+@end example
+
+@noindent
+where @var{options} are command line options and @var{args} are
+non-optional arguments.
+
+Non-optional arguments are allowed only if either @option{--test}
+or @option{--eval} option is used in @var{options}.
+
+@menu
+* program mode::
+* modifier options::
+* preprocessor control options::
+* logging control options::
+* debugging options::
+* informational options::
+@end menu
+
+@node program mode
+@section Program Mode Options
 
-@subheading Program Mode Options
 @table @option
 @opsummary{config-file}
 @item --config-file=@var{file}
@@ -196,22 +287,48 @@ does not work in this mode.
 @sopindex{n, summary}
 @item --dry-run
 @itemx -n
-Run in foreground mode and print on the standard output what would
-have otherwise been printed on the output file.  This option implies
+Run in foreground mode and print to the standard output what would
+have otherwise been printed to the output file.  This option implies
 @option{--stderr --debug snmp.1 --debug output.1}.  Use additional
 @option{--debug} options to get even more info.
 
 The @samp{pidfile} configuration statement is ignored in dry run mode
 (@pxref{pidfile}).
 
+@opsummary{eval}
+@item --eval=@var{name}
+Evaluate the named expression @var{name}, print its result and exit.
+Arguments for the expression can be supplied in the form of
+assignments in the command line, e.g.:
+
+@example
+slb --eval=loadavg la1=10 x=18
+@end example
+
+@FIXME-xref{eval}, for a detailed discussion of the expression evaluation
+mode.
+
+@opsummary{test}
+@sopindex{T, summary}
+@item --test
+Test mode.  Instead of polling servers via SNMP, @command{slb} reads
+data from the file given as the first non-option argument on the
+command line (or from the standard input, if no arguments are given).
+The output is directed to the standard output, unless the
+@option{--output-file} option is also given.
+
+@FIXME-xref{test mode}, for a detailed information about the test
+mode, including a description of the input format.
+
+Example usage:
+@example
+slb --test input.slb
+@end example
+
 @sopindex{E, summary}
 @item -E
 Show preprocessed configuration and exit.
 
-@opsummary{foreground}
-@item --foreground
-Remain in the foreground.  Useful for debugging purposes.
-
 @opsummary{lint}
 @sopindex{t, summary}
 @item --lint
@@ -220,7 +337,32 @@ Parse configuration file, report any errors on the standard error and
 exit with code 0, if the syntax is OK, and with code 1 otherwise.
 @end table
 
-@subheading Logging Control Options
+@node modifier options
+@section Modifier Options
+
+@table @option
+@opsummary{foreground}
+@item --foreground
+Remain in the foreground.  Useful for debugging purposes.
+
+@opsummary{output-file}
+@sopindex{o, summary}
+@item --output-file=@var{file}
+@itemx -o @var{file}
+Direct output to @var{file}.  This option overrides the
+@samp{output-file} setting in the configuration file.
+@xref{output-file}, for a discussion of @var{file} syntax.
+@end table
+
+@ignore
+@opindex efmt
+@item --efmt=@var{format}
+This option is deliberately left undocumented.  This text is here
+to pacify `make check-options'.
+@end ignore
+
+@node logging control options
+@section Logging Control Options
 @table @option
 @opsummary{stderr}
 @sopindex{e, summary}
@@ -233,7 +375,8 @@ Log to the standard error.
 Log all diagnostics to syslog.
 @end table
 
-@subheading Preprocessor Control Options
+@node preprocessor control options
+@section Preprocessor Control Options
 @table @option
 @opsummary{define}
 @item --define=@var{name}[=@var{value}]
@@ -258,7 +401,8 @@ Disable preprocessor.  @pxref{Preprocessor}.
 Use @var{command} instead of the default preprocessor.  @pxref{Preprocessor}.
 @end table
 
-@subheading Debugging Options
+@node debugging options
+@section Debugging Options
 @table @option
 @opsummary{debug}
 @sopindex{d, summary}
@@ -306,7 +450,8 @@ Configuration file grammar.
 Configuration file lexer.
 @end table
 
-@subheading Informational Options
+@node informational options
+@section Informational Options
 @table @option
 @opsummary{config-help}
 @item --config-help
@@ -331,6 +476,61 @@ Print the program version and exit.
 @chapter SLB Configuration File
 @include config.texi
 
+@node Exit Codes
+@chapter Exit Codes
+@cindex exit code
+When SLB terminates, it reports the result of its invocation in form
+of exit code.  Exit code of 0 indicates normal termination.  Non-zero
+exit codes indicate some kind of error.  In this case the exact cause
+of failure will be reported on the currently selected logging channel.
+
+The exit codes are as follows:
+
+@table @asis
+@item 0 (EX_OK)
+Normal termination.
+
+@item 64 (EX_USAGE)
+The program was invoked incorrectly.
+
+@item 65 EX_DATAERR
+Input data were invalid or malformed.  This error code is returned
+only when @command{slb} is used with @option{--test} or
+@option{--eval} options (@FIXME-pxref{}).
+
+@item 69 EX_UNAVAILABLE
+Some error occurred.  For example, the program was unable to open
+output file, etc.
+
+@item 70 EX_SOFTWARE
+Internal software error.  This usually means hitting a bug in the
+program, so please report it (@pxref{Reporting Bugs}).
+ 
+@item 98 EX_CONFIG
+Program terminated due to errors in configuration file.
+@end table
+
+@node Signals
+@chapter Signals
+
+The program handles a set of signals.  To send a signal to
+@command{slb} use the following command:
+
+@example
+kill -@var{signal} `cat /var/run/slb.pid`
+@end example
+
+Replace @file{/var/run/slb.pid} with the actual pathname of the
+PID-file, if it was set using the @samp{pidfile} configuration
+statement.
+
+The @samp{SIGHUP} signal instructs the running instance of the program
+to restart itself.  It is possible only if @command{slb} was started using
+its full pathname.
+
+The signals @samp{SIGTERM}, @samp{SIGQUIT}, and @samp{SIGINT} cause
+immediate termination of the program.
+
 @node Reporting Bugs
 @chapter How to Report a Bug