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.

1 files changed, 266 insertions, 0 deletions

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 <schwarze@openbsd.org>
+#
+# 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;