Update to OpenPAM Micrampelis.

1 files changed, 91 insertions, 30 deletions

diff --git a/contrib/openpam/misc/gendoc.pl b/contrib/openpam/misc/gendoc.pl
index 7b76672..4ce2d39 100644
--- a/contrib/openpam/misc/gendoc.pl
+++ b/contrib/openpam/misc/gendoc.pl
@@ -33,7 +33,7 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 #
-# $Id: gendoc.pl 465 2011-11-02 20:34:26Z des $
+# $Id: gendoc.pl 599 2012-04-14 15:06:41Z des $
 #
 
 use strict;
@@ -81,12 +81,15 @@ $COPYRIGHT = ".\\\"-
 .\\\"";
 
 %AUTHORS = (
-    THINKSEC => "ThinkSec AS and Network Associates Laboratories, the
+    THINKSEC => "developed for the
+.Fx
+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.",
-    DES => ".An Dag-Erling Sm\\(/orgrav Aq des\@FreeBSD.org .",
+    DES => "developed by
+.An Dag-Erling Sm\\(/orgrav Aq des\@des.no .",
 );
 
 %PAMERR = (
@@ -136,6 +139,9 @@ sub parse_source($) {
     my $inlist;
     my $intaglist;
     my $inliteral;
+    my $customrv;
+    my $deprecated;
+    my $experimental;
     my %xref;
     my @errors;
     my $author;
@@ -154,10 +160,18 @@ sub parse_source($) {
 	if ($source =~ m/^ \* NOPARSE\s*$/m);
 
     $author = 'THINKSEC';
-    if ($source =~ s/^ \* AUTHOR\s+(.*?)\s*$//m) {
+    if ($source =~ s/^ \* AUTHOR\s+(\w*)\s*$//m) {
 	$author = $1;
     }
 
+    if ($source =~ s/^ \* DEPRECATED\s*(\w*)\s*$//m) {
+	$deprecated = $1 // 0;
+    }
+
+    if ($source =~ s/^ \* EXPERIMENTAL\s*$//m) {
+	$experimental = 1;
+    }
+
     $func = $fn;
     $func =~ s,^(?:.*/)?([^/]+)\.c$,$1,;
     if ($source !~ m,\n \* ([\S ]+)\n \*/\n\n([\S ]+)\n$func\((.*?)\)\n\{,s) {
@@ -195,7 +209,7 @@ sub parse_source($) {
     # separate argument names with |
     $argnames =~ s/\" \"/|/g;
     # and surround with ()
-    $argnames =~ s/^\"(.*)\"$/($1)/;
+    $argnames =~ s/^\"(.*)\"$/$1/;
     # $argnames is now a regexp that matches argument names
     $inliteral = $inlist = $intaglist = 0;
     foreach (split("\n", $source)) {
@@ -211,12 +225,19 @@ sub parse_source($) {
 	s/\\(.)/$1/gs;
 	if (m/^$/) {
 	    # paragraph separator
+	    if ($inlist || $intaglist) {
+		# either a blank line between list items, or a blank
+		# line after the final list item.  The latter case
+		# will be handled further down.
+		next;
+	    }
+	    if ($man =~ m/\n\.Sh [^\n]+\n$/s) {
+		# a blank line after a section header
+		next;
+	    }
 	    if ($man ne "" && $man !~ m/\.Pp\n$/s) {
 		if ($inliteral) {
 		    $man .= "\0\n";
-		} elsif ($inlist || $intaglist) {
-		    $man .= ".El\n.Pp\n";
-		    $inlist = $intaglist = 0;
 		} else {
 		    $man .= ".Pp\n";
 		}
@@ -229,6 +250,14 @@ sub parse_source($) {
 	    ++$xref{$sect}->{$page};
 	    next;
 	}
+	if (s/^([A-Z][0-9A-Z -]+)$/.Sh $1/) {
+	    if ($1 eq "RETURN VALUES") {
+		$customrv = $1;
+	    }
+	    $man =~ s/\n\.Pp$/\n/s;
+	    $man .= "$_\n";
+	    next;
+	}
 	if (s/^\s+-\s+//) {
 	    # item in bullet list
 	    if ($inliteral) {
@@ -286,11 +315,12 @@ sub parse_source($) {
 	    $man .= "$_\n";
 	    next;
 	}
-	s/\s*=$func\b\s*/\n.Nm\n/gs;
-	s/\s*=$argnames\b\s*/\n.Fa $1\n/gs;
+	s/\s*=($func)\b\s*/\n.Fn $1\n/gs;
+	s/\s*=($argnames)\b\s*/\n.Fa $1\n/gs;
 	s/\s*=(struct \w+(?: \*)?)\b\s*/\n.Vt $1\n/gs;
 	s/\s*:([a-z_]+)\b\s*/\n.Va $1\n/gs;
 	s/\s*;([a-z_]+)\b\s*/\n.Dv $1\n/gs;
+	s/\s*=!([a-z_]+)\b\s*/\n.Xr $1 3\n/gs;
 	while (s/\s*=([a-z_]+)\b\s*/\n.Xr $1 3\n/s) {
 	    ++$xref{3}->{$1};
 	}
@@ -311,7 +341,7 @@ sub parse_source($) {
 	    $inliteral = 0;
 	}
 	$man =~ s/\%/\\&\%/gs;
-	$man =~ s/(\n\.[A-Z][a-z] [\w ]+)\n([\.,:;-]\S*)\s*/$1 $2\n/gs;
+	$man =~ s/(\n\.[A-Z][a-z] [\w ]+)\n([.,:;-])\s+/$1 $2\n/gs;
 	$man =~ s/\s*$/\n/gm;
 	$man =~ s/\n+/\n/gs;
 	$man =~ s/\0//gs;
@@ -331,6 +361,9 @@ sub parse_source($) {
 	'xref'		=> \%xref,
 	'errors'	=> \@errors,
 	'author'	=> $author,
+	'customrv'	=> $customrv,
+	'deprecated'	=> $deprecated,
+	'experimental'	=> $experimental,
     };
     if ($source =~ m/^ \* NODOC\s*$/m) {
 	$FUNCTIONS{$func}->{'nodoc'} = 1;
@@ -437,49 +470,75 @@ sub gendoc($) {
 .Lb libpam
 .Sh SYNOPSIS
 .In sys/types.h
-.In security/pam_appl.h
+";
+    if ($func->{'args'} =~ m/\bFILE \*\b/) {
+	$mdoc .= ".In stdio.h\n";
+    }
+    $mdoc .= ".In security/pam_appl.h
 ";
     if ($func->{'name'} =~ m/_sm_/) {
-	$mdoc .= ".In security/pam_modules.h\n"
+	$mdoc .= ".In security/pam_modules.h\n";
     }
     if ($func->{'name'} =~ m/openpam/) {
-	$mdoc .= ".In security/openpam.h\n"
+	$mdoc .= ".In security/openpam.h\n";
     }
     $mdoc .= ".Ft \"$func->{'type'}\"
 .Fn $func->{'name'} $func->{'args'}
 .Sh DESCRIPTION
-$func->{'man'}
 ";
-    if ($func->{'type'} eq "int") {
+    if (defined($func->{'deprecated'})) {
+	$mdoc .= ".Bf Sy\n" .
+	    "This function is deprecated and may be removed " .
+	    "in a future release without further warning.\n";
+	if ($func->{'deprecated'}) {
+	    $mdoc .= "The\n.Fn $func->{'deprecated'}\nfunction " .
+		"may be used to achieve similar results.\n";
+	}
+	$mdoc .= ".Ef\n.Pp\n";
+    }
+    if ($func->{'experimental'}) {
+	$mdoc .= ".Bf Sy\n" .
+	    "This function is experimental and may be modified or removed " .
+	    "in a future release without further warning.\n";
+	$mdoc .= ".Ef\n.Pp\n";
+    }
+    $mdoc .= "$func->{'man'}\n";
+    my @errors = @{$func->{'errors'}};
+    if ($func->{'customrv'}) {
+	# leave it
+    } elsif ($func->{'type'} eq "int" && @errors) {
 	$mdoc .= ".Sh RETURN VALUES
 The
-.Nm
+.Fn $func->{'name'}
 function returns one of the following values:
 .Bl -tag -width 18n
 ";
-	my @errors = @{$func->{'errors'}};
-	warn("$func->{'name'}(): no error specification\n")
-	    unless(@errors);
 	foreach (@errors) {
 	    $mdoc .= ".It Bq Er $_\n$PAMERR{$_}.\n";
 	}
 	$mdoc .= ".El\n";
-    } else {
-	if ($func->{'type'} =~ m/\*$/) {
-	    $mdoc .= ".Sh RETURN VALUES
+    } elsif ($func->{'type'} eq "int") {
+	$mdoc .= ".Sh RETURN VALUES
+The
+.Fn $func->{'name'}
+function returns 0 on success and -1 on failure.
+";
+    } elsif ($func->{'type'} =~ m/\*$/) {
+	$mdoc .= ".Sh RETURN VALUES
 The
-.Nm
+.Fn $func->{'name'}
 function returns
 .Dv NULL
 on failure.
 ";
-	}
+    } elsif ($func->{'type'} ne "void") {
+	warn("$func->{'name'}(): no error specification\n");
     }
     $mdoc .= ".Sh SEE ALSO\n" . genxref($func->{'xref'});
     $mdoc .= ".Sh STANDARDS\n";
     if ($func->{'openpam'}) {
 	$mdoc .= "The
-.Nm
+.Fn $func->{'name'}
 function is an OpenPAM extension.
 ";
     } else {
@@ -491,10 +550,9 @@ function is an OpenPAM extension.
     }
     $mdoc .= ".Sh AUTHORS
 The
-.Nm
-function and this manual page were developed for the
-.Fx
-Project by\n" . $AUTHORS{$func->{'author'} // 'THINKSEC_DARPA'} . "\n";
+.Fn $func->{'name'}
+function and this manual page were\n";
+    $mdoc .= $AUTHORS{$func->{'author'} // 'THINKSEC_DARPA'} . "\n";
     $fn = "$func->{'name'}.3";
     if (open(FILE, ">", $fn)) {
 	print(FILE $mdoc);
@@ -608,6 +666,9 @@ 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.
+.Pp
+The OpenPAM library is maintained by
+.An Dag-Erling Sm\\(/orgrav Aq des\@des.no .
 ";
     close(FILE);
 }