[hcoop/debian/openafs.git] / doc / man-pages / checkman

#!/usr/bin/perl
#
# Copyright (c) 2013 Sine Nomine Associates
# All rights reserved.
#
# 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.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT HOLDERS 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.

# checkman - run everything in the given directory of binaries, and try to
# find mismatches between the -help output, and the man page for that command

use strict;
use warnings;

use Getopt::Long;
use File::Find;

my $bindir;
my $mandir;

sub usage {
	print STDERR "WARNING: Running checkman can be dangerous, as it tries to \n";
	print STDERR "blindly run almost everything in the given binaries dir.\n\n";
	print STDERR "Usage: $0 --bindir <binaries_dir> --mandir <manpages_dir>";
}

GetOptions(
	"b|bindir=s" => \$bindir,
	"M|mandir=s" => \$mandir,
) or die("Error while parsing options\n");

if (not defined($bindir)) {
	usage();
}
if (not defined($mandir)) {
	usage();
}

if (not -d $bindir) {
	die("--bindir $bindir is not a directory\n");
}
if (not -d $mandir) {
	die("--mandir $mandir is not a directory\n");
}
if (not -d "$mandir/man1") {
	die("--mandir must point to a dir containing man1, man8, etc\n");
}

my %cmd_blacklist = (
	rmtsysd => '',
	pagsh => '',
	'pagsh.krb' => '',
	kpwvalid => '',
	'afs.rc' => '',
);

my %cmd_map;
my $mismatch = 0;

# find a list of all possible commands we can run, and map them to their full
# path
find(sub {
	if (-f and -x and -s) {
		$cmd_map{$_} = $File::Find::name;
	}
}, $bindir);

my %opt_map;
my @error_cmds;

sub parsehelp($$;$);

sub
check_opts($$)
{
	my ($manstr, $helpout) = @_;

	my %help_opts;

	my %syn_opts;
	my %man_opts;
	my %man_just_opts;

	$helpout =~ tr/\n/ /;

	# match everything that looks like an option
	# basically, find stuff that begins with a hyphen, and is surrounded by
	# brackets or spaces, or precedes a '='
	for ($helpout =~ m/(?:\[| )-([a-zA-Z0-9_-]+)(?=\s|[][]|=)/g) {
		#print "   help str $manstr opt -$_\n" if ($manstr =~ /ptserver/);
		if ($_ eq 'c') {
			# Almost everything lists '-c' as an alias for '-cell'.
			# We don't put that in the first synopsis for each man
			# page, so just pretend it's not there.
			next;
		}
		$help_opts{$_} = 1;
	}

	my $manout = `man -s 8,1 -M '$mandir' $manstr 2>/dev/null`;

	my $insyn = 0;
	my $inopts = 0;

	my $syn_sections = 0;
	my $lastline;
	my $curline;

	for (split /^/, $manout) {
		$lastline = $curline if (defined($curline));
		$curline = $_;

		if (m/^SYNOPSIS$/) {
			$insyn = 1;
			$inopts = 0;
			next;
		}
		if (m/^OPTIONS$/) {
			$insyn = 0;
			$inopts = 1;
			next;
		}
		if (m/^[A-Z]+$/) {
			if ($inopts) {
				# don't need anything after OPTIONS
				$inopts = 0;
				last;
			}
			$insyn = 0;
			next;
		}
		if (m/^\s+[a-z]/ and $insyn) {
			$syn_sections++;
			if ($syn_sections > 1) {
				# don't need anything in the synopsis after the first area
				$insyn = 0;
				next;
			}
		}

		if ($insyn) {
			# check for options in the synopsis...
			for (m/(?:\[|\s)-([a-zA-Z0-9_-]+)(?=\s|\]|\[)/g) {
				#print "   man page $manstr syn opt -$_\n" if ($manstr =~ /ptserver/);
				$syn_opts{$_} = 1;
			}
		}
		if ($inopts) {
			# check for options in the OPTIONS section
			#print "last: $lastline, cur: $_\n";
			if ($lastline =~ m/^(\s*|OPTIONS)$/ && m/^\s+-[a-zA-Z0-9_-]+/) {
				# Options only appear after a blank line (or right after the
				# OPTIONS line), so only go here if the last
				# line was blank, and we see what looks like an
				# option as the first thing on the current
				# line.

				# Find all options on the current line. Option
				# aliases can appear on the same =items line,
				# so get all of the aliases.
				for (m/\s-([a-zA-Z0-9_-]+)/g) {
					$man_just_opts{$_} = 1;
					if (exists $syn_opts{$_}) {
						# only count them if they also appeared in the synopsis earlier
						$man_opts{$_} = 1;
					}
				}
			}
		}
	}

	if (not %man_opts and not %syn_opts) {
		# we found no options in the man page output; so probably, we didn't
		# actually get a man page back. just print a single message, so we don't
		# print out something for every single option
		print "man page $manstr missing\n";
		return;
	}

	for (keys %help_opts) {
		if (not exists $man_opts{$_}) {
			my $extra = '';
			if (exists $syn_opts{$_}) {
				$extra = " from OPTIONS";
			} elsif (exists $man_just_opts{$_}) {
				$extra = " from synopsis";
			}

			print "man page $manstr missing option -$_$extra\n";
			$mismatch = 1;
		}
	}
	my %tmphash = (%syn_opts, %man_just_opts);
	for (keys %tmphash) {
		if (not exists $help_opts{$_}) {
			my $extra = '';
			if (not exists $syn_opts{$_}) {
				$extra = " in OPTIONS";
			} elsif (not exists $man_just_opts{$_}) {
				$extra = " in synopsis";
			}

			print "man page $manstr extra option -$_$extra\n";
			$mismatch = 1;
		}
	}
}

sub
parsehelp($$;$) {
	my ($cmd, $path, $subcmd) = @_;

	my $runstr;
	my $manstr;

	$runstr = $path;
	$manstr = $cmd;

	if (defined($subcmd)) {
		$runstr = "$path $subcmd";
		if ($subcmd ne "initcmd") {
			$manstr = "$cmd"."_"."$subcmd";
		}
	}

	if (defined($cmd_blacklist{$cmd})) {
		return;
	}

	my $out = `$runstr -help 2>&1`;
	if (defined($out)) {
		if ($out =~ m/^Usage: /) {
			# actual help output, listing options etc
			check_opts($manstr, $out);
			return;
		}

		if ($out =~ m/Commands are:$/m) {
			# multi-command program
			if (defined($subcmd)) {
				die("Subcommand $cmd $subcmd gave more subcommands?");
			}

			if ($out =~ m/^initcmd.*initialize the program$/m) {
				# not actually multi-command; we just need to give the initcmd
				# pseudo-subcommand
				parsehelp($cmd, $path, "initcmd");
				return;
			}

			# find all of the subcommands, and call parsehelp() on them
			for (split /^/, $out) {
				chomp;
				next if m/Commands are:$/;
				next if m/^apropos\s/ or m/^help\s/;
				if (m/^(\S+)\s+[\S ]+$/) {
					parsehelp($cmd, $path, $1);
				} else {
					print "for cmd $cmd got unmatched line $_\n";
				}
			}

			return;
		}
	}

	if (not defined($subcmd)) {
		$subcmd = "";
	}

	print "Skipped command $path $subcmd\n";

	# not sure what to do about this one
	push @error_cmds, "$path $subcmd";
}

for my $cmd (keys %cmd_map) {
	my $path = $cmd_map{$cmd};

	parsehelp($cmd, $path);
}

exit($mismatch);
Commit	Line	Data
805e021f CE	1	#!/usr/bin/perl
	2	#
	3	# Copyright (c) 2013 Sine Nomine Associates
	4	# All rights reserved.
	5	#
	6	# Redistribution and use in source and binary forms, with or without
	7	# modification, are permitted provided that the following conditions
	8	# are met:
	9	#
	10	# 1. Redistributions of source code must retain the above copyright
	11	# notice, this list of conditions and the following disclaimer.
	12	#
	13	# 2. Redistributions in binary form must reproduce the above copyright
	14	# notice, this list of conditions and the following disclaimer in the
	15	# documentation and/or other materials provided with the distribution.
	16	#
	17	# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
	18	# IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
	19	# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	20	# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
	21	# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
	22	# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
	23	# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
	24	# OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
	25	# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
	26	# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
	27	# ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	28
	29	# checkman - run everything in the given directory of binaries, and try to
	30	# find mismatches between the -help output, and the man page for that command
	31
	32	use strict;
	33	use warnings;
	34
	35	use Getopt::Long;
	36	use File::Find;
	37
	38	my $bindir;
	39	my $mandir;
	40
	41	sub usage {
	42	print STDERR "WARNING: Running checkman can be dangerous, as it tries to \n";
	43	print STDERR "blindly run almost everything in the given binaries dir.\n\n";
	44	print STDERR "Usage: $0 --bindir <binaries_dir> --mandir <manpages_dir>";
	45	}
	46
	47	GetOptions(
	48	"b\|bindir=s" => \$bindir,
	49	"M\|mandir=s" => \$mandir,
	50	) or die("Error while parsing options\n");
	51
	52	if (not defined($bindir)) {
	53	usage();
	54	}
	55	if (not defined($mandir)) {
	56	usage();
	57	}
	58
	59	if (not -d $bindir) {
	60	die("--bindir $bindir is not a directory\n");
	61	}
	62	if (not -d $mandir) {
	63	die("--mandir $mandir is not a directory\n");
	64	}
65	if (not -d "$mandir/man1") {
66	die("--mandir must point to a dir containing man1, man8, etc\n");
67	}
68
69	my %cmd_blacklist = (
70	rmtsysd => '',
71	pagsh => '',
72	'pagsh.krb' => '',
73	kpwvalid => '',
74	'afs.rc' => '',
75	);
76
77	my %cmd_map;
78	my $mismatch = 0;
79
80	# find a list of all possible commands we can run, and map them to their full
81	# path
82	find(sub {
83	if (-f and -x and -s) {
84	$cmd_map{$_} = $File::Find::name;
85	}
86	}, $bindir);
87
88	my %opt_map;
89	my @error_cmds;
90
91	sub parsehelp($$;$);
92
93	sub
94	check_opts($$)
95	{
96	my ($manstr, $helpout) = @_;
97
98	my %help_opts;
99
100	my %syn_opts;
101	my %man_opts;
102	my %man_just_opts;
103
104	$helpout =~ tr/\n/ /;
105
106	# match everything that looks like an option
107	# basically, find stuff that begins with a hyphen, and is surrounded by
108	# brackets or spaces, or precedes a '='
109	for ($helpout =~ m/(?:\[\| )-([a-zA-Z0-9_-]+)(?=\s\|[][]\|=)/g) {
110	#print " help str $manstr opt -$_\n" if ($manstr =~ /ptserver/);
111	if ($_ eq 'c') {
112	# Almost everything lists '-c' as an alias for '-cell'.
113	# We don't put that in the first synopsis for each man
114	# page, so just pretend it's not there.
115	next;
116	}
117	$help_opts{$_} = 1;
118	}
119
120	my $manout = `man -s 8,1 -M '$mandir' $manstr 2>/dev/null`;
121
122	my $insyn = 0;
123	my $inopts = 0;
124
125	my $syn_sections = 0;
126	my $lastline;
127	my $curline;
128
129	for (split /^/, $manout) {
130	$lastline = $curline if (defined($curline));
131	$curline = $_;
132
133	if (m/^SYNOPSIS$/) {
134	$insyn = 1;
135	$inopts = 0;
136	next;
137	}
138	if (m/^OPTIONS$/) {
139	$insyn = 0;
140	$inopts = 1;
141	next;
142	}
143	if (m/^[A-Z]+$/) {
144	if ($inopts) {
145	# don't need anything after OPTIONS
146	$inopts = 0;
147	last;
148	}
149	$insyn = 0;
150	next;
151	}
152	if (m/^\s+[a-z]/ and $insyn) {
153	$syn_sections++;
154	if ($syn_sections > 1) {
155	# don't need anything in the synopsis after the first area
156	$insyn = 0;
157	next;
158	}
159	}
160
161	if ($insyn) {
162	# check for options in the synopsis...
163	for (m/(?:\[\|\s)-([a-zA-Z0-9_-]+)(?=\s\|\]\|\[)/g) {
164	#print " man page $manstr syn opt -$_\n" if ($manstr =~ /ptserver/);
165	$syn_opts{$_} = 1;
166	}
167	}
168	if ($inopts) {
169	# check for options in the OPTIONS section
170	#print "last: $lastline, cur: $_\n";
171	if ($lastline =~ m/^(\s*\|OPTIONS)$/ && m/^\s+-[a-zA-Z0-9_-]+/) {
172	# Options only appear after a blank line (or right after the
173	# OPTIONS line), so only go here if the last
174	# line was blank, and we see what looks like an
175	# option as the first thing on the current
176	# line.
177
178	# Find all options on the current line. Option
179	# aliases can appear on the same =items line,
180	# so get all of the aliases.
181	for (m/\s-([a-zA-Z0-9_-]+)/g) {
182	$man_just_opts{$_} = 1;
183	if (exists $syn_opts{$_}) {
184	# only count them if they also appeared in the synopsis earlier
185	$man_opts{$_} = 1;
186	}
187	}
188	}
189	}
190	}
191
192	if (not %man_opts and not %syn_opts) {
193	# we found no options in the man page output; so probably, we didn't
194	# actually get a man page back. just print a single message, so we don't
195	# print out something for every single option
196	print "man page $manstr missing\n";
197	return;
198	}
199
200	for (keys %help_opts) {
201	if (not exists $man_opts{$_}) {
202	my $extra = '';
203	if (exists $syn_opts{$_}) {
204	$extra = " from OPTIONS";
205	} elsif (exists $man_just_opts{$_}) {
206	$extra = " from synopsis";
207	}
208
209	print "man page $manstr missing option -$_$extra\n";
210	$mismatch = 1;
211	}
212	}
213	my %tmphash = (%syn_opts, %man_just_opts);
214	for (keys %tmphash) {
215	if (not exists $help_opts{$_}) {
216	my $extra = '';
217	if (not exists $syn_opts{$_}) {
218	$extra = " in OPTIONS";
219	} elsif (not exists $man_just_opts{$_}) {
220	$extra = " in synopsis";
221	}
222
223	print "man page $manstr extra option -$_$extra\n";
224	$mismatch = 1;
225	}
226	}
227	}
228
229	sub
230	parsehelp($$;$) {
231	my ($cmd, $path, $subcmd) = @_;
232
233	my $runstr;
234	my $manstr;
235
236	$runstr = $path;
237	$manstr = $cmd;
238
239	if (defined($subcmd)) {
240	$runstr = "$path $subcmd";
241	if ($subcmd ne "initcmd") {
242	$manstr = "$cmd"."_"."$subcmd";
243	}
244	}
245
246	if (defined($cmd_blacklist{$cmd})) {
247	return;
248	}
249
250	my $out = `$runstr -help 2>&1`;
251	if (defined($out)) {
252	if ($out =~ m/^Usage: /) {
253	# actual help output, listing options etc
254	check_opts($manstr, $out);
255	return;
256	}
257
258	if ($out =~ m/Commands are:$/m) {
259	# multi-command program
260	if (defined($subcmd)) {
261	die("Subcommand $cmd $subcmd gave more subcommands?");
262	}
263
264	if ($out =~ m/^initcmd.*initialize the program$/m) {
265	# not actually multi-command; we just need to give the initcmd
266	# pseudo-subcommand
267	parsehelp($cmd, $path, "initcmd");
268	return;
269	}
270
271	# find all of the subcommands, and call parsehelp() on them
272	for (split /^/, $out) {
273	chomp;
274	next if m/Commands are:$/;
275	next if m/^apropos\s/ or m/^help\s/;
276	if (m/^(\S+)\s+[\S ]+$/) {
277	parsehelp($cmd, $path, $1);
278	} else {
279	print "for cmd $cmd got unmatched line $_\n";
280	}
281	}
282
283	return;
284	}
285	}
286
287	if (not defined($subcmd)) {
288	$subcmd = "";
289	}
290
291	print "Skipped command $path $subcmd\n";
292
293	# not sure what to do about this one
294	push @error_cmds, "$path $subcmd";
295	}
296
297	for my $cmd (keys %cmd_map) {
298	my $path = $cmd_map{$cmd};
299
300	parsehelp($cmd, $path);
301	}
302
303	exit($mismatch);