Add documentation

1 files changed, 120 insertions, 4 deletions

diff --git a/syslogck b/syslogck
index 9a68544..808dadd 100644
--- a/syslogck
+++ b/syslogck
@@ -7,8 +7,6 @@ use Pod::Usage;
 use Pod::Man;
 use Getopt::Long qw(:config gnu_getopt no_ignore_case);
 
-use Data::Dumper;
-
 use constant {
     EX_OK           => 0,
     EX_USAGE        => 64,
@@ -19,8 +17,126 @@ use constant {
     EX_NOPERM       => 77
 };
 
+=head1 NAME
+
+syslogck - check if syslog properly delivers messages
+
+=head1 SYNOPSIS
+
+B<syslogck> [OPTIONS] [FILE...]
+
+=head1 DESCRIPTION
+
+Sends a test message via syslog and checks if it appears in the destination
+log file.   By default, the message is sent via the B<user.notice> syslog
+facility.  The log file is determined by analyzing the syslog configuration
+file.  If several logs are configured to receive messages in the current
+priority, the first of them that is readable to the current user will be
+examined.
+
+By default, syslog configuration is read from file F</etc/syslog.conf>.  This
+can be changed by supplying the name of the file in the command line.  Multiple
+arguments are allowed.
+
+The configuration parser is very permissive.  It selects only lines that
+can reliably be parsed as traditional syslog selector lines.  This allows to
+use B<syslogck> with any flavor of syslog that allows for traditional
+configuration (e.g. B<rsyslogd>).
+
+On success (test message appeared in the log), B<syslogck> silently exits with
+code B<0>.  If the message did not appear in the log within the time out period,
+the program prints a descriptive diagnostics on the standard error and exits
+with code 74 if the log file remained unmodified, or with code 65 if some
+messages did appear in it, but the test message didn't.  Code 74 most often
+means that B<syslogd> is not running at all, whereas 65 indicates that it is
+misconfigured.  See B<EXIT CODES> for the exhaustive list of exit codes.    
+    
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h>
+
+Display a short option summary.
+
+=item B<--help>
+
+Display detailed manual.
+
+=item B<--usage>
+
+Display terse command line syntax summary.
+
+=item B<-d>, B<--debug>
+
+Print additional debugging information.    
+
+=item B<-p>, B<--priority=>I<FACILITY>[B<.>I<PRIORITY>]
+
+Select the syslog facility and, optionally, priority to use.  Default
+is B<user.notice>.    
+
+=item B<-n>, B<--dry-run>
+
+Verbosely list what is being done (see B<-d>), but don't actually
+send the test message.
+
+=item B<-t>, B<--tag=>I<TAG>
+
+Set syslog tag.
+
+=item B<-T>, B<--timeout=>I<N>
+
+Wait I<N> seconds for the message to appear in the log file.  Default is
+10.    
+    
+=back
+    
+=head1 EXIT CODES
+
+=over 4
+    
+=item 0
+
+Success.  Syslog works properly.
+
+=item 64
+
+Command line usage error.
+
+=item 65
+
+Test message did not appear in the log file, but other messages did.
+This means that syslog is probably working, but misconfigured.    
+    
+=item 66
+
+Can't open the selected log file.
+    
+=item 72
+
+No sutable log files found.  Try another priority.
+
+=item 74
+
+Timed out while waiting for the message to appear in the log file.  Most
+probably, syslog is not running.
+    
+=item 77
+
+None of the selected log files is readable for the current user.  Either
+select another priority (see B<-p>), or run B<syslogck> via B<sudo>.
+
+=back
+    
+=head1 AUTHOR
+
+Sergey Poznyakoff, <gray@gnu.org>
+
+=cut    
+    
 my $progname = basename($0);
-my $progdescr = 'FIXME';
+my $progdescr = 'check if syslog properly delivers messages';
 my $tag = $progname;
 my $timeout = 10;
 
@@ -203,7 +319,7 @@ if (@act) {
 
 exit EX_OK if $dry_run;
 
-abend(EX_OSFILE, "no files") unless @act;
+abend(EX_OSFILE, "no sutable files found (try another priority)") unless @act;
 
 my $file;
 while ($file = shift @act) {