[CORRECTION] Doc patches for Search::Dict and Sys::Syslog

2 files changed, 115 insertions, 40 deletions

diff --git a/lib/Search/Dict.pm b/lib/Search/Dict.pm
index 10aa4ff583..295da6b31d 100644
--- a/lib/Search/Dict.pm
+++ b/lib/Search/Dict.pm
@@ -5,29 +5,50 @@ require Exporter;
 @ISA = qw(Exporter);
 @EXPORT = qw(look);
 
-# Usage: look(*FILEHANDLE,$key,$dict,$fold)
+=head1 NAME
 
-# Sets file position in FILEHANDLE to be first line greater than or equal
-# (stringwise) to $key.  Pass flags for dictionary order and case folding.
+Search::Dict, look - search for key in dictionary file
+
+=head1 SYNOPSIS
+
+    use Search::Dict;
+    look *FILEHANDLE, $key, $dict, $fold;
+
+=head1 DESCRIPTION
+
+Sets file position in FILEHANDLE to be first line greater than or equal
+(stringwise) to I<$key>.  Returns the new file position, or -1 if an error
+occurs.
+
+The flags specify dictionary order and case folding:
+
+If I<$dict> is true, search by dictionary order (ignore anything but word
+characters and whitespace).
+
+If I<$fold> is true, ignore case.
+
+=cut
 
 sub look {
     local(*FH,$key,$dict,$fold) = @_;
-    local($max,$min,$mid,$_);
-    local($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime,
-       $blksize,$blocks) = stat(FH);
-    $blksize = 8192 unless $blksize;
+    local($_);
+    my(@stat) = stat(FH)
+	or return -1;
+    my($size, $blksize) = @stat[7,11];
+    $blksize ||= 8192;
     $key =~ s/[^\w\s]//g if $dict;
     $key =~ tr/A-Z/a-z/ if $fold;
-    $max = int($size / $blksize);
+    my($min, $max, $mid) = (0, int($size / $blksize));
     while ($max - $min > 1) {
 	$mid = int(($max + $min) / 2);
-	seek(FH,$mid * $blksize,0);
-	$_ = <FH> if $mid;		# probably a partial line
+	seek(FH, $mid * $blksize, 0)
+	    or return -1;
+	<FH> if $mid;			# probably a partial line
 	$_ = <FH>;
 	chop;
 	s/[^\w\s]//g if $dict;
 	tr/A-Z/a-z/ if $fold;
-	if ($_ lt $key) {
+	if (defined($_) && $_ lt $key) {
 	    $min = $mid;
 	}
 	else {
@@ -35,18 +56,20 @@ sub look {
 	}
     }
     $min *= $blksize;
-    seek(FH,$min,0);
+    seek(FH,$min,0)
+	or return -1;
     <FH> if $min;
-    while (<FH>) {
+    for (;;) {
+	$min = tell(FH);
+	$_ = <FH>
+	    or last;
 	chop;
 	s/[^\w\s]//g if $dict;
 	y/A-Z/a-z/ if $fold;
 	last if $_ ge $key;
-	$min = tell(FH);
     }
     seek(FH,$min,0);
     $min;
 }
 
 1;
-
diff --git a/lib/Sys/Syslog.pm b/lib/Sys/Syslog.pm
index bd8f07cc79..32d2e4ad0d 100644
--- a/lib/Sys/Syslog.pm
+++ b/lib/Sys/Syslog.pm
@@ -9,33 +9,86 @@ use Carp;
 use Socket;
 use Sys::Hostname;
 
+# adapted from syslog.pl
 #
-# syslog.pl
-#
-# $Log:	syslog.pl,v $
-# 
-# tom christiansen <tchrist@convex.com>
+# Tom Christiansen <tchrist@convex.com>
 # modified to use sockets by Larry Wall <lwall@jpl-devvax.jpl.nasa.gov>
 # NOTE: openlog now takes three arguments, just like openlog(3)
-#
-# call syslog() with a string priority and a list of printf() args
-# like syslog(3)
-#
-#  usage: use Syslog;
-#
-#  then (put these all in a script to test function)
-#		
-#	openlog($program,'cons,pid','user');
-#	syslog('info','this is another test');
-#	syslog('mail|warning','this is a better test: %d', time);
-#	closelog();
-#	
-#	syslog('debug','this is the last test');
-#	openlog("$program $$",'ndelay','user');
-#	syslog('notice','fooprogram: this is really done');
-#
-#	$! = 55;
-#	syslog('info','problem was %m'); # %m == $! in syslog(3)
+
+=head1 NAME
+
+Sys::Syslog, openlog, closelog, setlogmask, syslog - Perl interface to the UNIX syslog(3) calls
+
+=head1 SYNOPSIS
+
+    use Sys::Syslog;
+
+    openlog $ident, $logopt, $facility;
+    syslog $priority, $mask, $format, @args;
+    $oldmask = setlogmask $mask_priority;
+    closelog;
+
+=head1 DESCRIPTION
+
+Sys::Syslog is an interface to the UNIX C<syslog(3)> program.
+Call C<syslog()> with a string priority and a list of C<printf()> args
+just like C<syslog(3)>.
+
+Syslog provides the functions:
+
+=over
+
+=item openlog $ident, $logopt, $facility
+
+I<$ident> is prepended to every message.
+I<$logopt> contains one or more of the words I<pid>, I<ndelay>, I<cons>, I<nowait>.
+I<$facility> specifies the part of the system
+
+=item syslog $priority, $mask, $format, @args
+
+If I<$priority> and I<$mask> permit, logs I<($format, @args)>
+printed as by C<printf(3V)>, with the addition that I<%m>
+is replaced with C<"$!"> (the latest error message).
+
+=item setlogmask $mask_priority
+
+Sets log mask I<$mask_priority> and returns the old mask.
+
+=item closelog
+
+Closes the log file.
+
+=back
+
+Note that C<openlog> now takes three arguments, just like C<openlog(3)>.
+
+=head1 EXAMPLES
+
+    openlog($program, 'cons,pid', 'user');
+    syslog('info', 'this is another test');
+    syslog('mail|warning', 'this is a better test: %d', time);
+    closelog();
+
+    syslog('debug', 'this is the last test');
+    openlog("$program $$", 'ndelay', 'user');
+    syslog('notice', 'fooprogram: this is really done');
+
+    $! = 55;
+    syslog('info', 'problem was %m'); # %m == $! in syslog(3)
+
+=head1 DEPENDENCIES
+
+B<Sys::Syslog> needs F<syslog.ph>, which can be created with C<h2ph>.
+
+=head1 SEE ALSO
+
+L<syslog(3)>
+
+=head1 AUTHOR
+
+Tom Christiansen E<lt>F<tchrist@perl.com>E<gt> and Larry Wall E<lt>F<lwall@sems.com>E<gt>
+
+=cut
 
 $host = hostname() unless $host;	# set $Syslog::host to change
 
@@ -163,4 +216,3 @@ sub disconnect {
 }
 
 1;
-