From 441d0e0499d5c1310edb613d7c457db00b2fefa7 Mon Sep 17 00:00:00 2001 From: schwarze Date: Fri, 19 Nov 2021 09:15:35 +0000 Subject: [PATCH] Very quick and dirty script to help me check that the symbols in one of the public openssl/ header files are all documented. Before attempting to read this code, make sure that you are fully vaccinated against leaning toothpick syndrome. Example usage: ./check_complete.pl x509_vfy ./check_complete.pl -v x509 | less Intentionally not linked to the build. jsing@ agrees with the general direction. --- regress/lib/libcrypto/man/check_complete.pl | 266 ++++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100755 regress/lib/libcrypto/man/check_complete.pl diff --git a/regress/lib/libcrypto/man/check_complete.pl b/regress/lib/libcrypto/man/check_complete.pl new file mode 100755 index 00000000000..1086fd8627d --- /dev/null +++ b/regress/lib/libcrypto/man/check_complete.pl @@ -0,0 +1,266 @@ +#!/usr/bin/perl +# +# Copyright (c) 2021 Ingo Schwarze +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +use strict; +use warnings; + +my @obsolete = qw( + d2i_PBEPARAM d2i_PBE2PARAM d2i_PBKDF2PARAM + i2d_PBEPARAM i2d_PBE2PARAM i2d_PBKDF2PARAM + PBEPARAM PBEPARAM_free PBEPARAM_new + PBE2PARAM PBE2PARAM_free PBE2PARAM_new + PBKDF2PARAM PBKDF2PARAM_free PBKDF2PARAM_new + PKCS5_pbe_set PKCS5_pbe_set0_algor + PKCS5_pbe2_set PKCS5_pbe2_set_iv + PKCS5_pbkdf2_set + X509_EX_V_INIT + X509_EXT_PACK_STRING X509_EXT_PACK_UNKNOWN +); + +my $MANW = 'man -M /usr/share/man -w'; +my $srcdir = '/usr/src/lib/libcrypto/man'; +my $hfile = '/usr/include/openssl'; + +my $in_cplusplus = 0; +my $in_comment = 0; +my $in_define = 0; +my $in_function = 0; +my $in_struct = 0; +my $in_typedef_struct = 0; +my $verbose = 0; + +if (defined $ARGV[0] && $ARGV[0] eq '-v') { + $verbose = 1; + shift @ARGV; +} +$#ARGV == 0 or die "usage: $0 [-v] headername"; +$hfile .= "/$ARGV[0].h"; +open my $in_fh, '<', $hfile or die "$hfile: $!"; + +while (<$in_fh>) { +try_again: + chomp; + my $line = $_; + + # C language comments. + + if ($in_comment) { + unless (s/.*?\*\///) { + print "-- $line\n" if $verbose; + next; + } + $in_comment = 0; + } + while (/\/\*/) { + s/\/\*.*?\*\/// and next; + s/\/\*.*// and $in_comment = 1; + } + + # End C++ stuff. + + if ($in_cplusplus) { + /^#endif$/ and $in_cplusplus = 0; + print "-- $line\n" if $verbose; + next; + } + + # End declarations of structs. + + if ($in_struct) { + unless (s/^\s*\}//) { + print "-s $line\n" if $verbose; + next; + } + $in_struct = 0; + unless ($in_typedef_struct) { + /^\s*;$/ or die "at end of struct: $_"; + print "-s $line\n" if $verbose; + next; + } + $in_typedef_struct = 0; + my ($id) = /^\s*(\w+);$/ + or die "at end of typedef struct: $_"; + unless (system "$MANW -k Vt=$id > /dev/null 2>&1") { + print "Vt $line\n" if $verbose; + next; + } + if ($id =~ /NETSCAPE/) { + print "V- $line\n" if $verbose; + next; + } + if (grep { $_ eq $id } @obsolete) { + print "V- $line\n" if $verbose; + next; + } + if ($verbose) { + print "XX $line\n"; + } else { + warn "not found: typedef struct $id"; + } + next; + } + + # End macro definitions. + + if ($in_define) { + /\\$/ or $in_define = 0; + print "-d $line\n" if $verbose; + next; + } + + # End function declarations. + + if ($in_function) { + /^\s/ or die "function arguments not indented: $_"; + /\);$/ and $in_function = 0; + print "-f $line\n" if $verbose; + next; + } + + # Begin C++ stuff. + + if (/^#ifdef\s+__cplusplus$/) { + $in_cplusplus = 1; + print "-- $line\n" if $verbose; + next; + } + + # Uninteresting lines. + + if (/^\s*$/ || + /^DECLARE_STACK_OF\(\w+\)$/ || + /^#define HEADER_\w+_H$/ || + /^#endif$/ || + /^extern\s+const\s+ASN1_ITEM\s+\w+_it;$/ || + /^#include\s/ || + /^#ifn?def\s/) { + print "-- $line\n" if $verbose; + next; + } + + # Begin declarations of structs. + + if (/^(typedef )?(?:struct|enum)(?: \w+)? \{$/) { + $in_struct = 1; + $1 and $in_typedef_struct = 1; + print "-s $line\n" if $verbose; + next; + } + + if (my ($id) = /^#define\s+(\w+)\s+\S/) { + /\\$/ and $in_define = 1; + unless (system "$MANW -k Dv=$id > /dev/null 2>&1") { + print "Dv $line\n" if $verbose; + next; + } + unless (system "$MANW $id > /dev/null 2>&1") { + print "Fn $line\n" if $verbose; + next; + } + unless (system qw/grep -qR/, '^\.\\\\" ' . $id . '\>', + "$srcdir/") { + print "D- $line\n" if $verbose; + next; + } + if ($id =~ /NETSCAPE/) { + print "D- $line\n" if $verbose; + next; + } + if ($id =~ /^X509_[FR]_\w+$/) { + print "D- $line\n" if $verbose; + next; + } + if ($id =~ /^X509_V_ERR_\w+$/) { + print "D- $line\n" if $verbose; + next; + } + if (grep { $_ eq $id } @obsolete) { + print "D- $line\n" if $verbose; + next; + } + if ($verbose) { + print "XX $line\n"; + } else { + warn "not found: #define $id"; + } + next; + } + if (my ($id) = /^#define\s+(\w+)\(/) { + /\\$/ and $in_define = 1; + unless (system "$MANW $id > /dev/null 2>&1") { + print "Fn $line\n" if $verbose; + next; + } + unless (system qw/grep -qR/, '^\.\\\\" .*' . $id . '(3)', + "$srcdir/") { + print "F- $line\n" if $verbose; + next; + } + if ($verbose) { + print "XX $line\n"; + } else { + warn "not found: #define $id()"; + } + next; + } + if (/^typedef\s+(?:struct\s+)?\S+\s+(\w+);$/) { + unless (system "$MANW -k Vt=$1 > /dev/null 2>&1") { + print "Vt $line\n" if $verbose; + next; + } + if ($verbose) { + print "XX $line\n"; + } else { + warn "not found: typedef $1"; + } + next; + } + if (/^\w+(?:\(\w+\))?(?:\s+\w+)?(?:\s+|\s*\(?\*\s*)(\w+)\s*\(/) { + my $id = $1; + /\);$/ or $in_function = 1; + unless (system "$MANW $id > /dev/null 2>&1") { + print "Fn $line\n" if $verbose; + next; + } + if ($id =~ /NETSCAPE/) { + print "F- $line\n" if $verbose; + next; + } + unless (system qw/grep -qR/, '^\.\\\\" .*' . $id . '\>', + "$srcdir/") { + print "F- $line\n" if $verbose; + next; + } + if (grep { $_ eq $id } @obsolete) { + print "F- $line\n" if $verbose; + next; + } + if ($verbose) { + print "XX $line\n"; + } else { + warn "not found: function $id()"; + } + next; + } + if (/ \*$/) { + $_ .= <$in_fh>; + goto try_again; + } + die "parse error: $_"; +} + +close $in_fh; +exit 0; -- 2.20.1