Lines Matching +full:if +full:- +full:no +full:- +full:files +full:- +full:found
2 # Copyright 2002-2025 The OpenSSL Project Authors. All Rights Reserved.
50 -c List undocumented commands, undocumented options and unimplemented options.
51 -d Detailed list of undocumented (implies -u)
52 -e Detailed list of new undocumented (implies -v)
53 -h Print this help message
54 -l Print bogus links
55 -m Name(s) of manuals to focus on. Default: man1,man3,man5,man7
56 -n Print nits in POD pages
57 -o Causes -e/-v to count symbols added since 1.1.1 as new (implies -v)
58 -i Checks for history entries available for symbols added since 3.0.0 as new
59 -u Count undocumented functions
60 -v Count new undocumented functions
67 help() if $opt_h;
68 $opt_u = 1 if $opt_d;
69 $opt_v = 1 if $opt_o || $opt_e;
70 die "Cannot use both -u and -v"
71 if $opt_u && $opt_v;
72 die "Cannot use both -d and -e"
73 if $opt_d && $opt_e;
77 die "Need one of -[cdehlnouv] flags.\n"
86 die "Argument of -m option may contain only man1, man3, man5, and/or man7"
118 # Collect all POD files, both internal and public, and regardless of location
122 my %files = ();
123 # We collect files names on the fly, on known tag basis
128 # files OPTIONS
132 # files(TAGS => 'manual');
133 # files(TAGS => [ 'manual', 'man1' ]);
135 # This function returns an array of files corresponding to a set of tags
138 # selectors. Inclusive selectors are used to add one more set of files to
139 # the returned array, while exclusive selectors limit the set of files added
142 # 'public_manual' - inclusive selector, adds public manuals to the
143 # returned array of files.
144 # 'internal_manual' - inclusive selector, adds internal manuals to the
145 # returned array of files.
146 # 'manual' - inclusive selector, adds any manual to the returned
147 # array of files. This is really a shorthand for
149 # 'public_header' - inclusive selector, adds public headers to the
150 # returned array of files.
151 # 'header' - inclusive selector, adds any header file to the
152 # returned array of files. Since we currently only
158 # - exclusive selectors, only applicable together with
159 # any of the manual selectors. If any of these are
161 # will be included. If none of these are present,
164 # All returned manual files come from configdata.pm.
165 # All returned header files come from looking inside
168 sub files { subroutine
171 $opts{TAGS} = [ $opts{TAGS} ] if ref($opts{TAGS}) eq '';
173 croak "No tags given, or not an array"
178 if $tags{manual} && ($tags{public} // !$tags{internal});
180 if $tags{manual} && ($tags{internal} // !$tags{public});
182 if $tags{header} && ($tags{public} // !$tags{internal});
190 cluck "DEBUG[files]: This is how we got here!" if $debug;
191 print STDERR "DEBUG[files]: tags: $tags_as_key\n" if $debug;
197 if ($tags_to_collect{public_manual}) {
198 print STDERR "DEBUG[files]: collecting public manuals\n"
199 if $debug;
202 # contains lists of man files, and in turn, $unified_info{depends}
204 # files depend on. We use that information to find the POD files,
207 foreach ( map { @{$unified_info{depends}->{$_}} }
208 @{$unified_info{mandocs}->{$mansect}} ) {
209 $files{$_} = { $mansect => 1, public_manual => 1 };
215 if ($tags_to_collect{internal_manual}) {
216 print STDERR "DEBUG[files]: collecting internal manuals\n"
217 if $debug;
224 $files{$_} = { $mansect => 1, internal_manual => 1 };
230 if ($tags_to_collect{public_header}) {
231 print STDERR "DEBUG[files]: collecting public headers\n"
232 if $debug;
236 $files{$_} = { public_header => 1 };
242 if (!@result) {
247 # If caller asked for specific sections, we care about sections.
256 grep { $files{$_}->{$type} && $files{$_}->{$section} }
257 keys %files );
260 if ($tags{public_header}) {
263 grep { $files{$_}->{public_header} }
264 keys %files );
267 if ($debug) {
268 print STDERR "DEBUG[files]: result:\n";
269 print STDERR "DEBUG[files]: $_\n" foreach @result;
285 # Cross-check functions in the NAME and SYNOPSIS section.
295 err($id, "Trailing comma before - in NAME")
296 if $tmp =~ /, *-/;
297 $tmp =~ s/ -.*//g;
299 if $tmp =~ /[<>]/;
302 if $tmp =~ /[^,] /;
313 err($id, "The name '$n' contains white-space")
314 if $n =~ /\s/;
316 $foundfilename++ if $n eq $simplename;
318 if ( ( grep { basename($_) eq "$n.pod" }
319 files(TAGS => [ 'manual', $section ]) )
322 err($id, "The following exist as other .pod files:",
324 if %foundfilenames;
331 my $ignore_until = undef; # If defined, this is a regexp
332 # Remove all non-code lines
341 if ( $syn !~ /^ \s*(env .*?|#.*?|.*?;)\s*$/ms ) {
348 print STDERR "DEBUG[name_synopsis] \$line = '$line'\n" if $debug;
351 if ( defined $ignore_until) {
352 next if $line !~ /$ignore_until/;
356 if ( $line =~ /^\s*(?:typedef\s+)?struct(?:\s+\S+)\s*\{/ ) {
374 #if ( $line =~ /typedef.*\(\*?\S+\)\s+\(/ ) {
381 if ( $line =~ /env (\S*)=/ ) {
412 print STDERR "DEBUG[name_synopsis] \$sym = '$sym'\n" if $debug;
420 if $is_prototype && $line =~ /[a-z0-9],[^\s]/;
424 next if $names{$n} == 2;
429 # Check if SECTION ($3) is located before BEFORE ($4)
439 if $contents =~ /=head1 $before.*=head1 $section/ms;
442 # Check if HISTORY section is present and functionname ($2) is present in it
450 if (not $rest) {
451 # No HISTORY section is a clear error now
456 if (index($histsect, $functionname) == -1) {
459 return 0 if (not $histsect =~ /unction.*added.*/g);
465 # Check if a =head1 is duplicated, or a =headX is duplicated within a
466 # =head1. Treats =head2 =head3 as equivalent -- it doesn't reset the head3
467 # sets if it finds a =head2 -- but that is good enough for now. Also check
477 if ( $line =~ /head1/ ) {
479 if defined $head1{$line};
484 if defined $subheads{$line};
488 if $line =~ /\.[^\w]/ or $line =~ /\.$/;
490 if $line =~ /head1.*[a-z]/;
492 if $line =~ /head[234][ A-Z0-9]+$/;
501 # (note: non-greedy is important, or something like 'B<foo> and B<bar>'
506 (?:(?-1)|.)*? # recurse the whole regexp (referring to
516 # We do also accept the single -? or -n, where n is a digit
523 - # Single dash (--)
525 [[:alpha:]](?:[-_[:alnum:]]*?[[:alnum:]])?
528 # Helper function to check if a given $thing is properly marked up
530 # undef if it's not an option
531 # "" if it's a malformed option
548 # If we found an option, check it, collect it
549 if ( $unwrapped =~ /^\s*-/ ) {
551 if $unmarked =~ /^-${option_re}$/;
568 $nodups = 0 if $synopsis =~ /=for\s+openssl\s+duplicate\s+options/s;
573 while ( $contents =~ /=head1\s+[A-Z ]*?OPTIONS$(.*?)(?==head1)/msg ) {
577 # Look for options with no or incorrect markup
579 /(?<![-<[:alnum:]])-(?:$markup_re|.)*(?![->[:alnum:]])/msg ) {
586 my $found = $&;
587 push @synopsis, $found if $found =~ /^B<-/;
588 print STDERR "$id:DEBUG[option_check] SYNOPSIS: found $found\n"
589 if $debug;
590 my $option_uw = normalise_option($id, $filename, $found);
591 if ( defined $option_uw ) {
592 err($id, "Malformed option [2] in SYNOPSIS: $found")
593 if $option_uw eq '';
595 if $nodups && defined $listed{$option_uw};
608 my $found = $2;
609 print STDERR "$id:DEBUG[option_check] OPTIONS: found $&\n"
610 if $debug;
612 if ($1 // '') ne '' && $found =~ /^B<\s*-/;
614 my $option_uw = normalise_option($id, $filename, $found);
615 if ( defined $option_uw ) {
616 err($id, "Malformed option in OPTIONS: $found")
617 if $option_uw eq '';
619 if $nodups && defined $described{$option_uw};
622 if ($found =~ /^B<-/) {
623 push @options, $found;
624 err($id, "OPTIONS entry $found missing from SYNOPSIS")
625 unless (grep /^\Q$found\E$/, @synopsis)
626 || $id =~ /(openssl|-options)\.pod:1:$/;
649 print STDERR "$id:DEBUG[functionname_check] SYNOPSIS: found $&\n"
650 if $debug;
661 # does, because there are too many things that can't be found in
666 # This is from http://man7.org/linux/man-pages/man7/man-pages.7.html
668 '16bit' => '16-bit',
671 'builtin' => 'built-in',
673 'fall-back' => 'fallback',
677 'i-node' => 'inode',
679 'lower-case' => 'lowercase',
681 'non-blocking' => 'nonblocking',
682 'non-default' => 'nondefault',
683 'non-empty' => 'nonempty',
684 'non-negative' => 'nonnegative',
685 'non-zero' => 'nonzero',
687 'pre-allocated' => 'preallocated',
688 'pseudo-terminal' => 'pseudoterminal',
689 'real time' => 'real-time',
690 'realtime' => 'real-time',
693 'saved group ID'=> 'saved set-group-ID',
694 'saved set-GID' => 'saved set-group-ID',
695 'saved set-UID' => 'saved set-user-ID',
696 'saved user ID' => 'saved set-user-ID',
697 'set-GID' => 'set-group-ID',
698 'set-UID' => 'set-user-ID',
699 'setgid' => 'set-group-ID',
700 'setuid' => 'set-user-ID',
701 'sub-system' => 'subsystem',
703 'super-block' => 'superblock',
705 'super-user' => 'superuser',
710 'upper-case' => 'uppercase',
724 next if $k eq 'file system'
726 err($id, "Found '$k' should use '$preferred_words{$k}'")
727 if $contents =~ /\b\Q$k\E\b/i;
729 err($id, "Found 'epoch' should use 'Epoch'")
730 if $contents =~ /\bepoch\b/;
731 if ( $id =~ m@man1/@ ) {
732 err($id, "found 'tool' in NAME, should use 'command'")
733 if $contents =~ /=head1 NAME.*\btool\b.*=head1 SYNOPSIS/s;
734 err($id, "found 'utility' in NAME, should use 'command'")
735 if $contents =~ /NAME.*\butility\b.*=head1 SYNOPSIS/s;
749 $mansect = $1 if $filename =~ /man([1-9])/;
755 if ( $mansect == 3 ) {
764 next unless $target =~ /^L<(.*)>$/; # Skip if not L<...>
768 next if $target eq ''; # Skip if links within page, or
769 next if $target =~ /::/; # links to a Perl module, or
770 next if $target =~ /^https?:/; # is a URL link, or
771 next if $target =~ /\([1357]\)$/; # it has a section
777 next if $target =~ /openssl-?/;
778 next if ( grep { basename($_) eq "$target.pod" }
779 files(TAGS => [ 'manual', 'man1' ]) );
780 next if $target =~ /ps|apropos|sha1sum|procmail|perl/;
781 err($id, "Bad command link L<$target(1)>") if grep /man1/, @sections;
783 # Check for proper in-man-3 API links.
791 if ( $mansect == 3 ) {
802 if $contents !~ /^=pod/;
804 if $contents !~ /=cut\n$/;
806 if $contents =~ /=cut.*=cut/ms;
808 if $contents =~ /=head1 EXAMPLE[^S]/;
810 if $contents =~ /=head1 WARNING[^S]/;
812 if $contents !~ /Copyright .* The OpenSSL Project Authors/;
814 if $contents =~ /head1 COPYRIGHT.*=head/ms;
816 if $contents =~ /head2\s+[A-Z ]+\n/;
818 if $contents =~ /=head\d\s\s+/;
820 if $contents =~ /=head1 NAME.*\.\n.*=head1 SYNOPSIS/ms;
822 if $contents =~ /L<([^>]*)\|([^>]*)>/ && $1 eq $2;
824 if $contents =~ /=over([^ ][^24])/;
826 if $contents =~ /OpenSSL version [019]/;
828 if ( $contents !~ /=for openssl multiple includes/ ) {
830 # (non-consecutive lines are okay; see man3/MD5.pod).
831 if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) {
834 if ( $line =~ m@include <openssl/@ ) {
836 if ++$count == 2;
847 if podchecker($filename, $OUT) != 0;
852 next if /\(section\) in.*deprecated/;
860 $section = $1 if $dirname =~ /man([1-9])/;
864 if $contents !~ /^=head1\s+${_}\s*$/m;
872 # Map of names in each POD file or from "missing" files; possible values are:
873 # If found in a POD files, "name(s)" => filename
874 # If found in a "missing" file or external, "name(s)" => ''
877 # State of man-page names.
907 next if /^#/;
908 next if /\bNOEXIST\b/;
910 if ($type && ($type eq "crypto" || $type eq "ssl")) {
912 if (not $fields[2] eq "3_0_0") {
917 if scalar @fields != 2 && scalar @fields != 4;
933 next if /^#/;
941 # Collect all known names, no matter where they come from
946 next if ( $name_map{$_} // '') eq '' || $_ =~ /$ignored/;
948 # If a man-page isn't recorded public or if it's recorded missing
953 # If a man-page isn't recorded internal or if it's recorded missing
960 if ( $declared_public && $name_map{$_} =~ /\/internal\// );
962 if ( $declared_internal && $name_map{$_} !~ /\/internal\// );
967 # and do simple check for #define in our header files.
972 foreach my $f ( files(TAGS => 'public_header') ) {
975 next if $b eq 'asn1.h';
976 next if $b eq 'asn1t.h';
977 next if $b eq 'err.h';
983 next if defined $name_map{$macro}
989 if $opt_d || $opt_e;
996 if $count > 0;
1007 if ($opt_i && defined $history{$func});
1008 next if defined $name_map{$func}
1012 if $opt_d || $opt_e;
1016 if $count > 0;
1034 next if $name eq "";
1036 if $name =~ /\s/;
1038 if ( !defined $name_map{$name_sec} ) {
1040 if ($history{$name_sec}) {
1044 if (find_functionname_in_history_section($contents, $funcname)) {
1045 # mark this function as found/no longer of interest
1051 if $is_generic;
1061 if ( $podinfo{contents} =~ /=for openssl foreign manual (.*)\n/ ) {
1072 # that the markup that was found is indeed a link.
1074 # if the link is of the form L<something|name(s)>,
1085 if ($x =~ $linkre) {
1092 # Look for L<> ("link") references that point to files that do not exist.
1096 err("${filename}:1:", "reference to non-existing $link")
1099 if ( ( ($state{$link} // '') eq 'internal'
1106 # Cipher/digests to skip if they show up as "not implemented"
1107 # because they are, via the "-*" construct.
1127 # Check the flags of a command and see if everything is in the manpage
1141 if ($active) {
1142 last if m/^\s*};/;
1143 if ($expect_helpstr ne "") {
1144 next if m/^\s*#\s*if/;
1145 err("$cmd does not implement help for -$expect_helpstr") unless m/^\s*"/;
1148 if (m/\{\s*"([^"]+)"\s*,\s*OPT_[A-Z0-9_]+\s*,\s*('[-\/:<>cAEfFlMnNpsuU]'|0)(.*)$/
1152 $expect_helpstr = "" if $3 =~ m/^\s*,\s*"/;
1153 } elsif (m/[\s,](OPT_[A-Z]+_OPTIONS?)\s*(,|$)/) {
1167 last if /DESCRIPTION/;
1169 if ( /\[B<-([^ >]+)/ ) {
1171 } elsif ( /^B<-([^ >]+)/ ) {
1176 $opt = $1 if $opt =~ /I<(.*)/;
1184 err("$doc: undocumented $cmd option -$_");
1190 next if $_ eq "-"; # Skip the -- end-of-flags marker
1191 next if defined $skips{$_};
1192 err("$doc: $cmd does not implement -$_");
1203 if ( $opt_c ) {
1212 push @{ $genopts{$active} }, $1 if $active ne "" && m/^\s+\{\s*"([^"]+)"\s*,\s*OPT_/;
1213 $active = $1 if m/^\s*#\s*define\s+(OPT_[A-Z]+_OPTIONS?)\s*\\\s*$/;
1214 $active = "" if m/^\s*$/;
1223 # See if each has a manpage.
1226 next if $cmd eq 'progs' || $cmd eq 'vms_decc_init';
1227 my @doc = ( grep { basename($_) eq "openssl-$cmd.pod"
1230 files(TAGS => [ 'manual', 'man1' ]) );
1232 if ($num > 1) {
1235 err("no manual for 'openssl $cmd'");
1246 loadnum('util/other-internal.syms');
1247 if ( $opt_o ) {
1255 loadmissing('util/missingcrypto-internal.txt');
1256 loadmissing('util/missingssl-internal.txt');
1259 if ( $opt_n || $opt_l || $opt_u || $opt_v ) {
1260 my @files_to_read = ( $opt_n && @ARGV ) ? @ARGV : files(TAGS => 'manual');
1266 if ( $opt_l || $opt_u || $opt_v );
1269 if ( $opt_n );
1273 if ( $opt_l ) {
1277 if ( $opt_n ) {
1278 # If not given args, check that all man1 commands are named properly.
1279 if ( scalar @ARGV == 0 && grep /man1/, @sections ) {
1280 foreach ( files(TAGS => [ 'public_manual', 'man1' ]) ) {
1281 next if /openssl\.pod/
1283 err("$_ doesn't start with openssl-") unless /openssl-/;
1290 if ( $opt_u || $opt_v) {