diff options
Diffstat (limited to 'contrib/openpam/misc')
-rw-r--r-- | contrib/openpam/misc/gendoc.pl | 231 |
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); } |