[ec_asn1.c] Avoid injecting seed when built-in matches
[openssl.git] / util / find-doc-nits
1 #! /usr/bin/env perl
2 # Copyright 2002-2019 The OpenSSL Project Authors. All Rights Reserved.
3 #
4 # Licensed under the Apache License 2.0 (the "License").  You may not use
5 # this file except in compliance with the License.  You can obtain a copy
6 # in the file LICENSE in the source distribution or at
7 # https://www.openssl.org/source/license.html
8
9
10 require 5.10.0;
11 use warnings;
12 use strict;
13
14 use Pod::Checker;
15 use File::Find;
16 use File::Basename;
17 use File::Spec::Functions;
18 use Getopt::Std;
19 use lib catdir(dirname($0), "perl");
20 use OpenSSL::Util::Pod;
21
22 # Set to 1 for debug output
23 my $debug = 0;
24
25 # Options.
26 our($opt_d);
27 our($opt_e);
28 our($opt_s);
29 our($opt_o);
30 our($opt_h);
31 our($opt_l);
32 our($opt_n);
33 our($opt_p);
34 our($opt_u);
35 our($opt_v);
36 our($opt_c);
37
38 # Print usage message and exit.
39 sub help {
40     print <<EOF;
41 Find small errors (nits) in documentation.  Options:
42     -c List undocumented commands and options
43     -d Detailed list of undocumented (implies -u)
44     -e Detailed list of new undocumented (implies -v)
45     -h Print this help message
46     -l Print bogus links
47     -n Print nits in POD pages
48     -o Causes -e/-v to count symbols added since 1.1.1 as new (implies -v)
49     -u Count undocumented functions
50     -v Count new undocumented functions
51 EOF
52     exit;
53 }
54
55 getopts('cdehlnouv');
56
57 help() if $opt_h;
58 $opt_u = 1 if $opt_d;
59 $opt_v = 1 if $opt_o || $opt_e;
60 die "Cannot use both -u and -v"
61     if $opt_u && $opt_v;
62 die "Cannot use both -d and -e"
63     if $opt_d && $opt_e;
64
65 # We only need to check c, l, n, u and v.
66 # Options d, e, o imply one of the above.
67 die "Need one of -[cdehlnouv] flags.\n"
68     unless $opt_c or $opt_l or $opt_n or $opt_u or $opt_v;
69
70
71 my $temp = '/tmp/docnits.txt';
72 my $OUT;
73 my %public;
74 my $status = 0;
75
76 my %mandatory_sections = (
77     '*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
78     1   => [ 'SYNOPSIS', 'OPTIONS' ],
79     3   => [ 'SYNOPSIS', 'RETURN VALUES' ],
80     5   => [ ],
81     7   => [ ]
82 );
83
84
85 # Print error message, set $status.
86 sub err {
87     print join(" ", @_), "\n";
88     $status = 1
89 }
90
91 # Cross-check functions in the NAME and SYNOPSIS section.
92 sub name_synopsis {
93     my $id = shift;
94     my $filename = shift;
95     my $contents = shift;
96
97     # Get NAME section and all words in it.
98     return unless $contents =~ /=head1 NAME(.*)=head1 SYNOPSIS/ms;
99     my $tmp = $1;
100     $tmp =~ tr/\n/ /;
101     err($id, "trailing comma before - in NAME")
102         if $tmp =~ /, *-/;
103     $tmp =~ s/ -.*//g;
104     err($id, "POD markup among the names in NAME")
105         if $tmp =~ /[<>]/;
106     $tmp =~ s/  */ /g;
107     err($id, "missing comma in NAME")
108         if $tmp =~ /[^,] /;
109
110     my $dirname = dirname($filename);
111     my $simplename = basename(basename($filename, ".in"), ".pod");
112     my $foundfilename = 0;
113     my %foundfilenames = ();
114     my %names;
115     foreach my $n ( split ',', $tmp ) {
116         $n =~ s/^\s+//;
117         $n =~ s/\s+$//;
118         err($id, "the name '$n' contains white-space")
119             if $n =~ /\s/;
120         $names{$n} = 1;
121         $foundfilename++ if $n eq $simplename;
122         $foundfilenames{$n} = 1
123             if -f "$dirname/$n.pod" && $n ne $simplename;
124     }
125     err($id, "the following exist as other .pod files:",
126          sort keys %foundfilenames)
127         if %foundfilenames;
128     err($id, "$simplename (filename) missing from NAME section")
129         unless $foundfilename;
130     if ( $filename !~ /internal/ ) {
131         foreach my $n ( keys %names ) {
132             err($id, "$n is not public")
133                 if !defined $public{$n};
134         }
135     }
136
137     # Find all functions in SYNOPSIS
138     return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
139     my $syn = $1;
140     foreach my $line ( split /\n+/, $syn ) {
141         next unless $line =~ /^\s/;
142         my $sym;
143         $line =~ s/STACK_OF\([^)]+\)/int/g;
144         $line =~ s/SPARSE_ARRAY_OF\([^)]+\)/int/g;
145         $line =~ s/__declspec\([^)]+\)//;
146         if ( $line =~ /env (\S*)=/ ) {
147             # environment variable env NAME=...
148             $sym = $1;
149         } elsif ( $line =~ /typedef.*\(\*(\S+)\)\(.*/ ) {
150             # a callback function pointer: typedef ... (*NAME)(...
151             $sym = $1;
152         } elsif ( $line =~ /typedef.* (\S+)\(.*/ ) {
153             # a callback function signature: typedef ... NAME(...
154             $sym = $1;
155         } elsif ( $line =~ /typedef.* (\S+);/ ) {
156             # a simple typedef: typedef ... NAME;
157             $sym = $1;
158         } elsif ( $line =~ /enum (\S*) \{/ ) {
159             # an enumeration: enum ... {
160             $sym = $1;
161         } elsif ( $line =~ /#(?:define|undef) ([A-Za-z0-9_]+)/ ) {
162             $sym = $1;
163         } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) {
164             $sym = $1;
165         }
166         else {
167             next;
168         }
169         err($id, "$sym missing from NAME section")
170             unless defined $names{$sym};
171         $names{$sym} = 2;
172
173         # Do some sanity checks on the prototype.
174         err($id, "prototype missing spaces around commas: $line")
175             if ( $line =~ /[a-z0-9],[^ ]/ );
176     }
177
178     foreach my $n ( keys %names ) {
179         next if $names{$n} == 2;
180         err($id, "$n missing from SYNOPSIS")
181     }
182 }
183
184 # Check if SECTION ($3) is located before BEFORE ($4)
185 sub check_section_location {
186     my $id = shift;
187     my $contents = shift;
188     my $section = shift;
189     my $before = shift;
190
191     return unless $contents =~ /=head1 $section/
192         and $contents =~ /=head1 $before/;
193     err($id, "$section should appear before $before section")
194         if $contents =~ /=head1 $before.*=head1 $section/ms;
195 }
196
197 # Check if a =head1 is duplicated, or a =headX is duplicated within a
198 # =head1.  Treats =head2 =head3 as equivalent -- it doesn't reset the head3
199 # sets if it finds a =head2 -- but that is good enough for now. Also check
200 # for proper capitalization, trailing periods, etc.
201 sub check_head_style {
202     my $id = shift;
203     my $contents = shift;
204     my %head1;
205     my %subheads;
206
207     foreach my $line ( split /\n+/, $contents ) {
208         next unless $line =~ /^=head/;
209         if ( $line =~ /head1/ ) {
210             err($id, "duplicate section $line")
211                 if defined $head1{$line};
212             $head1{$line} = 1;
213             %subheads = ();
214         } else {
215             err($id, "duplicate subsection $line")
216                 if defined $subheads{$line};
217             $subheads{$line} = 1;
218         }
219         err($id, "period in =head")
220             if $line =~ /\.[^\w]/ or $line =~ /\.$/;
221         err($id, "not all uppercase in =head1")
222             if $line =~ /head1.*[a-z]/;
223         err($id, "all uppercase in subhead")
224             if $line =~ /head[234][ A-Z0-9]+$/;
225     }
226 }
227
228 # Because we have options and symbols with extra markup, we need
229 # to take that into account, so we need a regexp that extracts
230 # markup chunks, including recursive markup.
231 # please read up on /(?R)/ in perlre(1)
232 # (note: order is important, (?R) needs to come before .)
233 # (note: non-greedy is important, or something like 'B<foo> and B<bar>'
234 # will be captured as one item)
235 my $markup_re =
236     qr/(                        # Capture group
237            [BIL]<               # The start of what we recurse on
238            (?:(?-1)|.)*?        # recurse the whole regexp (refering to
239                                 # the last opened capture group, i.e. the
240                                 # start of this regexp), or pick next
241                                 # character.  Do NOT be greedy!
242            >                    # The end of what we recurse on
243        )/x;                     # (the x allows this sort of split up regexp)
244
245 # Options must start with a dash, followed by a letter, possibly
246 # followed by letters, digits, dashes and underscores, and the last
247 # character must be a letter or a digit.
248 # We do also accept the single -? or -n, where n is a digit
249 my $option_re =
250     qr/(?:
251             \?                  # Single question mark
252             |
253             \d                  # Single digit
254             |
255             -                   # Single dash (--)
256             |
257             [[:alpha:]](?:[-_[:alnum:]]*?[[:alnum:]])?
258        )/x;
259
260 # Helper function to check if a given $thing is properly marked up
261 # option.  It returns one of these values:
262 #     undef         if it's not an option
263 #     ""            if it's a malformed option
264 #     $unwrapped    the option with the outermost B<> wrapping removed.
265 sub normalise_option {
266     my $id = shift;
267     my $filename = shift;
268     my $thing = shift;
269
270     my $unwrapped = $thing;
271     my $unmarked = $thing;
272
273     # $unwrapped is the option with the outer B<> markup removed
274     $unwrapped =~ s/^B<//;
275     $unwrapped =~ s/>$//;
276     # $unmarked is the option with *all* markup removed
277     $unmarked =~ s/[BIL]<|>//msg;
278
279
280     # If we found an option, check it, collect it
281     if ( $unwrapped =~ /^\s*-/ ) {
282         return $unwrapped       # return option with outer B<> removed
283             if $unmarked =~ /^-${option_re}$/;
284         return "";              # Malformed option
285     }
286     return undef;               # Something else
287 }
288
289 # Checks of command option (man1) formatting.  The man1 checks are
290 # restricted to the SYNOPSIS and OPTIONS sections, the rest is too
291 # free form, we simply cannot be too strict there.
292
293 sub option_check {
294     my $id = shift;
295     my $filename = shift;
296     my $contents = shift;
297
298     my $synopsis = ($contents =~ /=head1\s+SYNOPSIS(.*?)=head1/s, $1);
299
300     # Some pages have more than one OPTIONS section, let's make sure
301     # to get them all
302     my $options = '';
303     while ( $contents =~ /=head1\s+[A-Z ]*?OPTIONS$(.*?)(?==head1)/msg ) {
304         $options .= $1;
305     }
306
307     # Look for options with no or incorrect markup
308     while ( $synopsis =~
309             /(?<![-<[:alnum:]])-(?:$markup_re|.)*(?![->[:alnum:]])/msg ) {
310         err($id, "Malformed option [1] in SYNOPSIS: $&");
311     }
312
313     while ( $synopsis =~ /$markup_re/msg ) {
314         my $found = $&;
315         print STDERR "$id:DEBUG[option_check] SYNOPSIS: found $found\n"
316             if $debug;
317         my $option_uw = normalise_option($id, $filename, $found);
318         err($id, "Malformed option [2] in SYNOPSIS: $found")
319             if defined $option_uw && $option_uw eq '';
320     }
321
322     # In OPTIONS, we look for =item paragraphs.
323     # (?=^\s*$) detects an empty line.
324     while ( $options =~ /=item\s+(.*?)(?=^\s*$)/msg ) {
325         my $item = $&;
326
327         while ( $item =~ /(\[\s*)?($markup_re)/msg ) {
328             my $found = $2;
329             print STDERR "$id:DEBUG[option_check] OPTIONS: found $&\n"
330                 if $debug;
331             err($id, "Unexpected bracket in OPTIONS =item: $item")
332                 if ($1 // '') ne '' && $found =~ /^B<\s*-/;
333
334             my $option_uw = normalise_option($id, $filename, $found);
335             err($id, "Malformed option in OPTIONS: $found")
336                 if defined $option_uw && $option_uw eq '';
337         }
338     }
339 }
340
341 # Normal symbol form
342 my $symbol_re = qr/[[:alpha:]_][_[:alnum:]]*?/;
343
344 # Checks of function name (man3) formatting.  The man3 checks are
345 # easier than the man1 checks, we only check the names followed by (),
346 # and only the names that have POD markup.
347 sub functionname_check {
348     my $id = shift;
349     my $filename = shift;
350     my $contents = shift;
351
352     while ( $contents =~ /($markup_re)\(\)/msg ) {
353         print STDERR "$id:DEBUG[functionname_check] SYNOPSIS: found $&\n"
354             if $debug;
355
356         my $symbol = $1;
357         my $unmarked = $symbol;
358         $unmarked =~ s/[BIL]<|>//msg;
359
360         err($id, "Malformed symbol: $symbol")
361             unless $symbol =~ /^B<.*>$/ && $unmarked =~ /^${symbol_re}$/
362     }
363
364     # We can't do the kind of collecting coolness that option_check()
365     # does, because there are too many things that can't be found in
366     # name repositories like the NAME sections, such as symbol names
367     # with a variable part (typically marked up as B<foo_I<TYPE>_bar>
368 }
369
370 # This is from http://man7.org/linux/man-pages/man7/man-pages.7.html
371 my %preferred_words = (
372     'bitmask'       => 'bit mask',
373     'builtin'       => 'built-in',
374    #'epoch'         => 'Epoch', # handled specially, below
375     'file name'     => 'filename',
376     'file system'   => 'filesystem',
377     'host name'     => 'hostname',
378     'i-node'        => 'inode',
379     'lower case'    => 'lowercase',
380     'lower-case'    => 'lowercase',
381     'non-zero'      => 'nonzero',
382     'path name'     => 'pathname',
383     'pseudo-terminal' => 'pseudoterminal',
384     'reserved port' => 'privileged port',
385     'system port'   => 'privileged port',
386     'realtime'      => 'real-time',
387     'real time'     => 'real-time',
388     'runtime'       => 'run time',
389     'saved group ID'=> 'saved set-group-ID',
390     'saved set-GID' => 'saved set-group-ID',
391     'saved user ID' => 'saved set-user-ID',
392     'saved set-UID' => 'saved set-user-ID',
393     'set-GID'       => 'set-group-ID',
394     'setgid'        => 'set-group-ID',
395     'set-UID'       => 'set-user-ID',
396     'setuid'        => 'set-user-ID',
397     'super user'    => 'superuser',
398     'super-user'    => 'superuser',
399     'super block'   => 'superblock',
400     'super-block'   => 'superblock',
401     'time stamp'    => 'timestamp',
402     'time zone'     => 'timezone',
403     'upper case'    => 'uppercase',
404     'upper-case'    => 'uppercase',
405     'useable'       => 'usable',
406     'userspace'     => 'user space',
407     'user name'     => 'username',
408     'zeroes'        => 'zeros'
409 );
410
411 # Search manpage for words that have a different preferred use.
412 sub wording {
413     my $id = shift;
414     my $contents = shift;
415
416     foreach my $k ( keys %preferred_words ) {
417         # Sigh, trademark
418         next if $k eq 'file system'
419             and $contents =~ /Microsoft Encrypted File System/;
420         err($id, "found '$k' should use '$preferred_words{$k}'")
421             if $contents =~ /\b\Q$k\E\b/i;
422     }
423     err($id, "found 'epoch' should use 'Epoch'")
424         if $contents =~ /\bepoch\b/;
425 }
426
427 # Perform all sorts of nit/error checks on a manpage
428 sub check {
429     my $filename = shift;
430     my $dirname = basename(dirname($filename));
431
432     my $contents = '';
433     {
434         local $/ = undef;
435         open POD, $filename or die "Couldn't open $filename, $!";
436         $contents = <POD>;
437         close POD;
438     }
439
440     my $id = "${filename}:1:";
441     check_head_style($id, $contents);
442
443     # Check ordering of some sections in man3
444     if ( $filename =~ m|man3/| ) {
445         check_section_location($id, $contents, "RETURN VALUES", "EXAMPLES");
446         check_section_location($id, $contents, "SEE ALSO", "HISTORY");
447         check_section_location($id, $contents, "EXAMPLES", "SEE ALSO");
448     }
449
450     unless ( $contents =~ /=for openssl generic/ ) {
451         if ( $filename =~ m|man3/| ) {
452             name_synopsis($id, $filename, $contents);
453             functionname_check($id, $filename, $contents);
454         } elsif ( $filename =~ m|man1/| ) {
455             option_check($id, $filename, $contents)
456         }
457     }
458
459     wording($id, $contents);
460
461     err($id, "doesn't start with =pod")
462         if $contents !~ /^=pod/;
463     err($id, "doesn't end with =cut")
464         if $contents !~ /=cut\n$/;
465     err($id, "more than one cut line.")
466         if $contents =~ /=cut.*=cut/ms;
467     err($id, "EXAMPLE not EXAMPLES section.")
468         if $contents =~ /=head1 EXAMPLE[^S]/;
469     err($id, "WARNING not WARNINGS section.")
470         if $contents =~ /=head1 WARNING[^S]/;
471     err($id, "missing copyright")
472         if $contents !~ /Copyright .* The OpenSSL Project Authors/;
473     err($id, "copyright not last")
474         if $contents =~ /head1 COPYRIGHT.*=head/ms;
475     err($id, "head2 in All uppercase")
476         if $contents =~ /head2\s+[A-Z ]+\n/;
477     err($id, "extra space after head")
478         if $contents =~ /=head\d\s\s+/;
479     err($id, "period in NAME section")
480         if $contents =~ /=head1 NAME.*\.\n.*=head1 SYNOPSIS/ms;
481     err($id, "Duplicate $1 in L<>")
482         if $contents =~ /L<([^>]*)\|([^>]*)>/ && $1 eq $2;
483     err($id, "Bad =over $1")
484         if $contents =~ /=over([^ ][^24])/;
485     err($id, "Possible version style issue")
486         if $contents =~ /OpenSSL version [019]/;
487
488     if ( $contents !~ /=for openssl multiple includes/ ) {
489         # Look for multiple consecutive openssl #include lines
490         # (non-consecutive lines are okay; see man3/MD5.pod).
491         if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) {
492             my $count = 0;
493             foreach my $line ( split /\n+/, $1 ) {
494                 if ( $line =~ m@include <openssl/@ ) {
495                     err($id, "has multiple includes")
496                         if ++$count == 2;
497                 } else {
498                     $count = 0;
499                 }
500             }
501         }
502     }
503
504     open my $OUT, '>', $temp
505         or die "Can't open $temp, $!";
506     podchecker($filename, $OUT);
507     close $OUT;
508     open $OUT, '<', $temp
509         or die "Can't read $temp, $!";
510     while ( <$OUT> ) {
511         next if /\(section\) in.*deprecated/;
512         print;
513     }
514     close $OUT;
515     unlink $temp || warn "Can't remove $temp, $!";
516
517     # Find what section this page is in; assume 3.
518     my $section = 3;
519     $section = $1 if $dirname =~ /man([1-9])/;
520
521     foreach ( (@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}}) ) {
522         err($id, "missing $_ head1 section")
523             if $contents !~ /^=head1\s+${_}\s*$/m;
524     }
525 }
526
527 # Parse libcrypto.num, etc., and return sorted list of what's there.
528 sub parsenum {
529     my $file = shift;
530     my @apis;
531
532     open my $IN, '<', $file
533         or die "Can't open $file, $!, stopped";
534
535     while ( <$IN> ) {
536         next if /^#/;
537         next if /\bNOEXIST\b/;
538         my @fields = split();
539         die "Malformed line $_"
540             if scalar @fields != 2 && scalar @fields != 4;
541         push @apis, $fields[0];
542     }
543
544     close $IN;
545
546     return sort @apis;
547 }
548
549 # Parse all the manpages, getting return map of what they document
550 # (by looking at their NAME sections).
551 sub getdocced
552 {
553     my $dir = shift;
554     my %return;
555     my %dups;
556
557     foreach my $pod ( glob("$dir/*.pod") ) {
558         my %podinfo = extract_pod_info($pod);
559         foreach my $n ( @{$podinfo{names}} ) {
560             $return{$n} = $pod;
561             err("# Duplicate $n in $pod and $dups{$n}")
562                 if defined $dups{$n} && $dups{$n} ne $pod;
563             $dups{$n} = $pod;
564         }
565     }
566
567     return %return;
568 }
569
570 # Map of documented functions; function => manpage
571 my %docced;
572 # Map of links in each POD file; filename => [ "foo(1)", "bar(3)", ... ]
573 my %link_map = ();
574 # Map of names in each POD file; "name(s)" => filename
575 my %name_map = ();
576
577 # Load file of symbol names that we know aren't documented.
578 sub loadmissing($)
579 {
580     my $missingfile = shift;
581     my @missing;
582
583     open FH, $missingfile
584         || die "Can't open $missingfile";
585     while ( <FH> ) {
586         chomp;
587         next if /^#/;
588         push @missing, $_;
589     }
590     close FH;
591
592     return @missing;
593 }
594
595 # Check for undocumented macros; ignore those in the "missing" file
596 # and do simple check for #define in our header files.
597 sub checkmacros {
598     my $count = 0;
599     my %seen;
600     my @missing;
601
602     if ( $opt_o ) {
603         @missing = loadmissing('util/missingmacro111.txt');
604     } elsif ( $opt_v ) {
605         @missing = loadmissing('util/missingmacro.txt');
606     }
607
608     foreach my $f ( glob('include/openssl/*.h') ) {
609         # Skip some internals we don't want to document yet.
610         next if $f eq 'include/openssl/asn1.h';
611         next if $f eq 'include/openssl/asn1t.h';
612         next if $f eq 'include/openssl/err.h';
613         open(IN, $f) || die "Can't open $f, $!";
614         while ( <IN> ) {
615             next unless /^#\s*define\s*(\S+)\(/;
616             my $macro = $1;
617             next if $docced{$macro} || defined $seen{$macro};
618             next if $macro =~ /i2d_/
619                 || $macro =~ /d2i_/
620                 || $macro =~ /DEPRECATEDIN/
621                 || $macro =~ /IMPLEMENT_/
622                 || $macro =~ /DECLARE_/;
623
624             # Skip macros known to be missing
625             next if $opt_v && grep( /^$macro$/, @missing);
626     
627             err("$f:", "macro $macro undocumented")
628                 if $opt_d || $opt_e;
629             $count++;
630             $seen{$macro} = 1;
631         }
632         close(IN);
633     }
634     err("# $count macros undocumented (count is approximate)")
635         if $count > 0;
636 }
637
638 # Find out what is undocumented (filtering out the known missing ones)
639 # and display them.
640 sub printem {
641     my $libname = shift;
642     my $numfile = shift;
643     my $missingfile = shift;
644     my $count = 0;
645     my %seen;
646
647     my @missing = loadmissing($missingfile) if ( $opt_v );
648
649     foreach my $func ( parsenum($numfile) ) {
650         next if $docced{$func} || defined $seen{$func};
651
652         # Skip ASN1 utilities
653         next if $func =~ /^ASN1_/;
654
655         # Skip functions known to be missing
656         next if $opt_v && grep( /^$func$/, @missing);
657
658         err("$libname:", "function $func undocumented")
659             if $opt_d || $opt_e;
660         $count++;
661         $seen{$func} = 1;
662     }
663     err("# $count in $numfile are not documented")
664         if $count > 0;
665 }
666
667 # Collect all the names in a manpage.
668 sub collectnames {
669     my $filename = shift;
670     $filename =~ m|man(\d)/|;
671     my $section = $1;
672     my $simplename = basename($filename, ".pod");
673     my $id = "${filename}:1:";
674
675     my $contents = '';
676     {
677         local $/ = undef;
678         open POD, $filename or die "Couldn't open $filename, $!";
679         $contents = <POD>;
680         close POD;
681     }
682
683     $contents =~ /=head1 NAME([^=]*)=head1 /ms;
684     my $tmp = $1;
685     unless ( defined $tmp ) {
686         err($id, "weird name section");
687         return;
688     }
689     $tmp =~ tr/\n/ /;
690     $tmp =~ s/ -.*//g;
691
692     my @names =
693         map { s|/|-|g; $_ }              # Treat slash as dash
694         map { s/^\s+//g; s/\s+$//g; $_ } # Trim prefix and suffix blanks
695         split(/,/, $tmp);
696     unless ( grep { $simplename eq $_ } @names ) {
697         err($id, "missing $simplename");
698         push @names, $simplename;
699     }
700     foreach my $name (@names) {
701         next if $name eq "";
702         if ( $name =~ /\s/ ) {
703             err($id, "'$name' contains white space")
704         }
705         my $name_sec = "$name($section)";
706         if ( !exists $name_map{$name_sec} ) {
707             $name_map{$name_sec} = $filename;
708         } elsif ( $filename eq $name_map{$name_sec} ) {
709             err($id, "$name_sec repeated in NAME section of",
710                  $name_map{$name_sec});
711         } else {
712             err($id, "$name_sec also in NAME section of",
713                  $name_map{$name_sec});
714         }
715     }
716
717     my @foreign_names =
718         map { map { s/\s+//g; $_ } split(/,/, $_) }
719         $contents =~ /=for\s+comment\s+foreign\s+manuals:\s*(.*)\n\n/;
720     foreach ( @foreign_names ) {
721         $name_map{$_} = undef; # It still exists!
722     }
723
724     my @links = $contents =~ /L<
725                               # if the link is of the form L<something|name(s)>,
726                               # then remove 'something'.  Note that 'something'
727                               # may contain POD codes as well...
728                               (?:(?:[^\|]|<[^>]*>)*\|)?
729                               # we're only interested in references that have
730                               # a one digit section number
731                               ([^\/>\(]+\(\d\))
732                              /gx;
733     $link_map{$filename} = [ @links ];
734 }
735
736 # Look for L<> ("link") references that point to files that do not exist.
737 sub checklinks {
738     foreach my $filename (sort keys %link_map) {
739         foreach my $link (@{$link_map{$filename}}) {
740             err("${filename}:1:", "reference to non-existing $link")
741                 unless exists $name_map{$link};
742         }
743     }
744 }
745
746 # Load the public symbol/macro names
747 sub publicize {
748     foreach my $name ( parsenum('util/libcrypto.num') ) {
749         $public{$name} = 1;
750     }
751     foreach my $name ( parsenum('util/libssl.num') ) {
752         $public{$name} = 1;
753     }
754     foreach my $name ( parsenum('util/other.syms') ) {
755         $public{$name} = 1;
756     }
757 }
758
759 # Cipher/digests to skip if they show up as "not implemented"
760 # because they are, via the "-*" construct.
761 my %skips = (
762     'aes128' => 1,
763     'aes192' => 1,
764     'aes256' => 1,
765     'aria128' => 1,
766     'aria192' => 1,
767     'aria256' => 1,
768     'camellia128' => 1,
769     'camellia192' => 1,
770     'camellia256' => 1,
771     'des' => 1,
772     'des3' => 1,
773     'idea' => 1,
774     'cipher' => 1,
775     'digest' => 1,
776 );
777
778 # Check the flags of a command and see if everything is in the manpage
779 sub checkflags {
780     my $cmd = shift;
781     my $doc = shift;
782     my %cmdopts;
783     my %docopts;
784     my %localskips;
785
786     # Get the list of options in the command.
787     open CFH, "./apps/openssl list --options $cmd|"
788         || die "Can list options for $cmd, $!";
789     while ( <CFH> ) {
790         chop;
791         s/ .$//;
792         $cmdopts{$_} = 1;
793     }
794     close CFH;
795
796     # Get the list of flags from the synopsis
797     open CFH, "<$doc"
798         || die "Can't open $doc, $!";
799     while ( <CFH> ) {
800         chop;
801         last if /DESCRIPTION/;
802         if ( /=for openssl ifdef (.*)/ ) {
803             foreach my $f ( split / /, $1 ) {
804                 $localskips{$f} = 1;
805             }
806             next;
807         }
808         next unless /\[B<-([^ >]+)/;
809         my $opt = $1;
810         $opt = $1 if $opt =~ /I<(.*)/;
811         $docopts{$1} = 1;
812     }
813     close CFH;
814
815     # See what's in the command not the manpage.
816     my @undocced = sort grep { !defined $docopts{$_} } keys %cmdopts;
817     foreach ( @undocced ) {
818         next if /-/; # Skip the -- end-of-flags marker
819         err("$doc: undocumented option -$_");
820     }
821
822     # See what's in the command not the manpage.
823     my @unimpl = sort grep { !defined $cmdopts{$_} } keys %docopts;
824     foreach ( @unimpl ) {
825         next if defined $skips{$_} || defined $localskips{$_};
826         err("$cmd documented but not implemented -$_");
827     }
828 }
829
830 ##
831 ##  MAIN()
832 ##  Do the work requested by the various getopt flags.
833 ##  The flags are parsed in alphabetical order, just because we have
834 ##  to have *some way* of listing them.
835 ##
836
837 if ( $opt_c ) {
838     my @commands = ();
839
840     # Get list of commands.
841     open FH, "./apps/openssl list -1 -commands|"
842         || die "Can't list commands, $!";
843     while ( <FH> ) {
844         chop;
845         push @commands, $_;
846     }
847     close FH;
848
849     # See if each has a manpage.
850     foreach my $cmd ( @commands ) {
851         next if $cmd eq 'help' || $cmd eq 'exit';
852         my $doc = "doc/man1/$cmd.pod";
853         $doc = "doc/man1/openssl-$cmd.pod" if -f "doc/man1/openssl-$cmd.pod";
854         if ( ! -f "$doc" ) {
855             err("$doc does not exist");
856         } else {
857             checkflags($cmd, $doc);
858         }
859     }
860
861     # See what help is missing.
862     open FH, "./apps/openssl list --missing-help |"
863         || die "Can't list missing help, $!";
864     while ( <FH> ) {
865         chop;
866         my ($cmd, $flag) = split;
867         err("$cmd has no help for -$flag");
868     }
869     close FH;
870
871     exit $status;
872 }
873
874 if ( $opt_l ) {
875     foreach ( @ARGV ? @ARGV : glob('doc/*/*.pod doc/internal/*/*.pod') ) {
876         collectnames($_);
877     }
878     checklinks();
879 }
880
881 if ( $opt_n ) {
882     publicize();
883     foreach ( @ARGV ? @ARGV : glob('doc/*/*.pod doc/internal/*/*.pod') ) {
884         check($_);
885     }
886
887     # If not given args, check that all man1 commands are named properly.
888     if ( scalar @ARGV == 0 ) {
889         foreach (glob('doc/man1/*.pod')) {
890             next if /CA.pl/ || /openssl\.pod/ || /tsget\.pod/;
891             err("$_ doesn't start with openssl-") unless /openssl-/;
892         }
893     }
894 }
895
896 if ( $opt_u || $opt_v) {
897     my %temp = getdocced('doc/man3');
898     foreach ( keys %temp ) {
899         $docced{$_} = $temp{$_};
900     }
901     if ( $opt_o ) {
902         printem('crypto', 'util/libcrypto.num', 'util/missingcrypto111.txt');
903         printem('ssl', 'util/libssl.num', 'util/missingssl111.txt');
904     } else {
905         printem('crypto', 'util/libcrypto.num', 'util/missingcrypto.txt');
906         printem('ssl', 'util/libssl.num', 'util/missingssl.txt');
907     }
908     checkmacros();
909 }
910
911 exit $status;