Vendor import of OpenPAM Citronella.

1 files changed, 173 insertions, 58 deletions

diff --git a/contrib/openpam/misc/gendoc.pl b/contrib/openpam/misc/gendoc.pl
index cb4c69d..b22468f 100644
--- a/contrib/openpam/misc/gendoc.pl
+++ b/contrib/openpam/misc/gendoc.pl
@@ -4,9 +4,9 @@
 # All rights reserved.
 #
 # This software was developed for the FreeBSD Project by ThinkSec AS and
-# NAI Labs, the Security Research Division of Network Associates, Inc.
-# under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
-# DARPA CHATS research program.
+# Network Associates Laboratories, the Security Research Division of
+# Network Associates, Inc.  under DARPA/SPAWAR contract N66001-01-C-8035
+# ("CBOSS"), as part of the DARPA CHATS research program.
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
@@ -32,14 +32,51 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 #
-# $P4: //depot/projects/openpam/misc/gendoc.pl#14 $
+# $P4: //depot/projects/openpam/misc/gendoc.pl#18 $
 #
 
 use strict;
 use Fcntl;
+use Getopt::Std;
 use POSIX qw(strftime);
 use vars qw($COPYRIGHT $TODAY %FUNCTIONS %PAMERR);
 
+$COPYRIGHT = ".\\\"-
+.\\\" Copyright (c) 2002 Networks Associates Technology, Inc.
+.\\\" All rights reserved.
+.\\\"
+.\\\" This software was developed for the FreeBSD Project by ThinkSec AS and
+.\\\" Network Associates Laboratories, the Security Research Division of
+.\\\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
+.\\\" (\"CBOSS\"), as part of the DARPA CHATS research program.
+.\\\"
+.\\\" Redistribution and use in source and binary forms, with or without
+.\\\" modification, are permitted provided that the following conditions
+.\\\" are met:
+.\\\" 1. Redistributions of source code must retain the above copyright
+.\\\"    notice, this list of conditions and the following disclaimer.
+.\\\" 2. Redistributions in binary form must reproduce the above copyright
+.\\\"    notice, this list of conditions and the following disclaimer in the
+.\\\"    documentation and/or other materials provided with the distribution.
+.\\\" 3. The name of the author may not be used to endorse or promote
+.\\\"    products derived from this software without specific prior written
+.\\\"    permission.
+.\\\"
+.\\\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\\\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\\\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\\\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\\\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\\\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\\\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\\\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\\\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\\\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\\\" SUCH DAMAGE.
+.\\\"
+.\\\" \$" . "P4" . "\$
+.\\\"";
+
 %PAMERR = (
     PAM_SUCCESS			=> "Success",
     PAM_OPEN_ERR		=> "Failed to load module",
@@ -91,7 +128,7 @@ sub parse_source($) {
 
     if ($fn !~ m,\.c$,) {
 	warn("$fn: not C source, ignoring\n");
-	return;
+	return undef;
     }
 
     sysopen(FILE, $fn, O_RDONLY)
@@ -99,19 +136,14 @@ sub parse_source($) {
     $source = join('', <FILE>);
     close(FILE);
 
-    return if ($source =~ m/^ \* NOPARSE\s*$/m);
+    return undef
+	if ($source =~ m/^ \* NOPARSE\s*$/m);
 
-    if (!defined($COPYRIGHT) && $source =~ m,^(/\*-\n.*?)\s*\*/,s) {
-	$COPYRIGHT = $1;
-	$COPYRIGHT =~ s,^.\*,.\\\",gm;
-	$COPYRIGHT =~ s,(\$(?:)P4).*?\$,$1\$,;
-	$COPYRIGHT .= "\n.\\\"";
-    }
     $func = $fn;
     $func =~ s,^(?:.*/)?([^/]+)\.c$,$1,;
     if ($source !~ m,\n \* ([\S ]+)\n \*/\n\n([\S ]+)\n$func\((.*?)\)\n\{,s) {
 	warn("$fn: can't find $func\n");
-	return;
+	return undef;
     }
     ($descr, $type, $args) = ($1, $2, $3);
     $descr =~ s,^([A-Z][a-z]),lc($1),e;
@@ -156,7 +188,7 @@ sub parse_source($) {
 		if ($inliteral) {
 		    $man .= "\0\n";
 		} elsif ($inlist) {
-		    $man .= ".El\n";
+		    $man .= ".El\n.Pp\n";
 		    $inlist = 0;
 		} else {
 		    $man .= ".Pp\n";
@@ -182,7 +214,7 @@ sub parse_source($) {
 	    $man .= "$_\n";
 	    next;
 	} elsif ($inlist && m/^\S/) {
-	    $man .= ".El\n";
+	    $man .= ".El\n.Pp\n";
 	    $inlist = 0;
 	} elsif ($inliteral && m/^\S/) {
 	    $man .= ".Ed\n";
@@ -231,6 +263,7 @@ sub parse_source($) {
     }
 
     $FUNCTIONS{$func} = {
+	'source'	=> $fn,
 	'name'		=> $func,
 	'descr'		=> $descr,
 	'type'		=> $type,
@@ -249,6 +282,8 @@ sub parse_source($) {
     if ($source !~ m/^ \* XSSO \d/m) {
 	$FUNCTIONS{$func}->{'openpam'} = 1;
     }
+    expand_errors($FUNCTIONS{$func});
+    return $FUNCTIONS{$func};
 }
 
 sub expand_errors($);
@@ -256,6 +291,8 @@ sub expand_errors($) {
     my $func = shift;		# Ref to function hash
 
     my %errors;
+    my $ref;
+    my $fn;
 
     if (defined($func->{'recursed'})) {
 	warn("$func->{'name'}(): loop in error spec\n");
@@ -273,11 +310,17 @@ sub expand_errors($) {
 	} elsif (m/^!(PAM_[A-Z_]+)$/) {
 	    # treat negations separately
 	} elsif (m/^=([a-z_]+)$/) {
-	    if (!defined($FUNCTIONS{$1})) {
-		warn("$func->{'name'}(): reference to unknown $1()\n");
+	    $ref = $1;
+	    if (!defined($FUNCTIONS{$ref})) {
+		$fn = $func->{'source'};
+		$fn =~ s/$func->{'name'}/$ref/;
+		parse_source($fn);
+	    }
+	    if (!defined($FUNCTIONS{$ref})) {
+		warn("$func->{'name'}(): reference to unknown $ref()\n");
 		next;
 	    }
-	    foreach (expand_errors($FUNCTIONS{$1})) {
+	    foreach (@{$FUNCTIONS{$ref}->{'errors'}}) {
 		$errors{$_} = 1;
 	    }
 	} else {
@@ -290,7 +333,7 @@ sub expand_errors($) {
 	}
     }
     delete($func->{'recursed'});
-    return (sort(keys(%errors)));
+    $func->{'errors'} = [ sort(keys(%errors)) ];
 }
 
 sub gendoc($) {
@@ -332,7 +375,7 @@ The
 function returns one of the following values:
 .Bl -tag -width 18n
 ";
-	my @errors = expand_errors($func);
+	my @errors = @{$func->{'errors'}};
 	warn("$func->{'name'}(): no error specification\n")
 	    unless(@errors);
 	foreach (@errors) {
@@ -372,8 +415,9 @@ function is an OpenPAM extension.
 The
 .Nm
 function and this manual page were developed for the FreeBSD Project
-by ThinkSec AS and NAI Labs, the Security Research Division of Network
-Associates, Inc.  under DARPA/SPAWAR contract N66001-01-C-8035
+by ThinkSec AS and Network Associates Laboratories, the Security
+Research Division of Network Associates, Inc.  under DARPA/SPAWAR
+contract N66001-01-C-8035
 .Pq Dq CBOSS ,
 as part of the DARPA CHATS research program.
 ";
@@ -387,73 +431,144 @@ as part of the DARPA CHATS research program.
     }
 }
 
-sub gensummary() {
+sub readproto($) {
+    my $fn = shift;		# File name
+
+    local *FILE;
+    my %func;
+
+    sysopen(FILE, $fn, O_RDONLY)
+	or die("$fn: open(): $!\n");
+    while (<FILE>) {
+	if (m/^\.Nm ((?:open)?pam_.*?)\s*$/) {
+	    $func{'Nm'} = $func{'Nm'} || $1;
+	} elsif (m/^\.Ft (\S.*?)\s*$/) {
+	    $func{'Ft'} = $func{'Ft'} || $1;
+	} elsif (m/^\.Fn (\S.*?)\s*$/) {
+	    $func{'Fn'} = $func{'Fn'} || $1;
+	}
+    }
+    close(FILE);
+    if ($func{'Nm'}) {
+	$FUNCTIONS{$func{'Nm'}} = \%func;
+    } else {
+	warn("No function found\n");
+    }
+}
+
+sub gensummary($) {
+    my $page = shift;		# Which page to produce
 
+    local *FILE;
+    my $upage;
     my $func;
+    my %xref;
+
+    sysopen(FILE, "$page.3", O_RDWR|O_CREAT|O_TRUNC)
+	or die("$page.3: $!\n");
 
-    print "$COPYRIGHT
+    $upage = uc($page);
+    print FILE "$COPYRIGHT
 .Dd $TODAY
-.Dt PAM 3
+.Dt $upage 3
 .Os
 .Sh NAME
 ";
     my @funcs = sort(keys(%FUNCTIONS));
     while ($func = shift(@funcs)) {
-	next if (defined($FUNCTIONS{$func}->{'nolist'}));
-	print ".Nm $func". (@funcs ? " ,\n" : "\n");
+	print FILE ".Nm $FUNCTIONS{$func}->{'Nm'}";
+	print FILE " ,"
+		if (@funcs);
+	print FILE "\n";
     }
-    print ".Nd Pluggable Authentication Modules Library
+    print FILE ".Nd Pluggable Authentication Modules Library
 .Sh LIBRARY
 .Lb libpam
-.Sh SYNOPSIS
-.In security/pam_appl.h
-";
+.Sh SYNOPSIS\n";
+    if ($page eq 'pam') {
+	print FILE ".In security/pam_appl.h\n";
+    } else {
+	print FILE ".In security/openpam.h\n";
+    }
     foreach $func (sort(keys(%FUNCTIONS))) {
-	next if (defined($FUNCTIONS{$func}->{'nolist'}));
-	print ".Ft $FUNCTIONS{$func}->{'type'}\n";
-	print ".Fn $func $FUNCTIONS{$func}->{'args'}\n";
+	print FILE ".Ft $FUNCTIONS{$func}->{'Ft'}\n";
+	print FILE ".Fn $FUNCTIONS{$func}->{'Fn'}\n";
     }
-    print ".Sh DESCRIPTION
-.Sh RETURN VALUES
-The following return codes are defined in the
-.In security/pam_constants.h
-header:
+    while (<STDIN>) {
+	if (m/^\.Xr (\S+)\s*(\d)\s*$/) {
+	    $xref{$1} = $2;
+        }
+	print FILE $_;
+    }
+
+    if ($page eq 'pam') {
+	print FILE ".Sh RETURN VALUES
+The following return codes are defined by
+.Aq Pa security/pam_constants.h :
 .Bl -tag -width 18n
 ";
-    foreach (sort(keys(%PAMERR))) {
-	print ".It Bq Er $_\n$PAMERR{$_}.\n";
+	foreach (sort(keys(%PAMERR))) {
+	    print FILE ".It Bq Er $_\n$PAMERR{$_}.\n";
+	}
+	print FILE ".El\n";
     }
-    print ".El
-.Sh SEE ALSO
+    print FILE ".Sh SEE ALSO
 ";
-    foreach $func (sort(keys(%FUNCTIONS))) {
-	next if (defined($FUNCTIONS{$func}->{'nolist'}));
-	print ".Xr $func 3 ,\n";
+    print FILE ".Xr openpam 3\n"
+	if ($page eq 'pam');
+    foreach $func (keys(%FUNCTIONS)) {
+        $xref{$func} = 3;
+    }
+    my @refs = sort(keys(%xref));
+    while ($_ = shift(@refs)) {
+	print FILE ".Xr $_ $xref{$_}";
+        print FILE " ,"
+	    if (@refs);
+        print FILE "\n";
     }
-    print ".Xr pam.conf 5
-.Sh STANDARDS
+    print FILE ".Sh STANDARDS
 .Rs
 .%T \"X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules\"
 .%D \"June 1997\"
 .Re
 .Sh AUTHORS
 The OpenPAM library and this manual page were developed for the
-FreeBSD Project by ThinkSec AS and NAI Labs, the Security Research
-Division of Network Associates, Inc.  under DARPA/SPAWAR contract
-N66001-01-C-8035
+FreeBSD Project by ThinkSec AS and Network Associates Laboratories,
+the Security Research Division of Network Associates, Inc.  under
+DARPA/SPAWAR contract N66001-01-C-8035
 .Pq Dq CBOSS ,
 as part of the DARPA CHATS research program.
-"
+";
+    close(FILE);
+}
+
+sub usage() {
+
+    print(STDERR "usage: gendoc [-s] source [...]\n");
+    exit(1);
 }
 
 MAIN:{
+    my %opts;
+
+    usage()
+	unless (@ARGV && getopts("op", \%opts));
     $TODAY = strftime("%B %e, %Y", localtime(time()));
     $TODAY =~ s,\s+, ,g;
-    foreach my $fn (@ARGV) {
-	parse_source($fn);
-    }
-    foreach my $func (values(%FUNCTIONS)) {
-	gendoc($func);
+    if ($opts{'o'} || $opts{'p'}) {
+	foreach my $fn (@ARGV) {
+	    readproto($fn);
+	}
+	gensummary('openpam')
+	    if ($opts{'o'});
+	gensummary('pam')
+	    if ($opts{'p'});
+    } else {
+	foreach my $fn (@ARGV) {
+	    my $func = parse_source($fn);
+	    gendoc($func)
+		if (defined($func));
+	}
     }
-    gensummary();
+    exit(0);
 }