#! /usr/bin/perl -w
########################################################################
#
#  Copyright (c) 2000, 2001 by Donald Sharp <sharpd@cisco.com>
#  All Rights Reserved
#
#  Some portions Copyright (c) 2002, 2003 by
#                Derek R. Price <mailto:derek@ximbiot.com>
#                & Ximbiot <http://ximbiot.com>.
#  All rights reserved.
#
#  Permission is granted to copy and/or distribute this file, with or
#  without modifications, provided this notice is preserved.
#
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2, or (at your option)
#  any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
########################################################################

=head1 validate_repo.pl

Script to check the integrity of the Repository.

=head1 SYNOPSIS

    perldoc validate_repo.pl
    validate_repo.pl --help [--verbose!]
    validate_repo.pl [--verbose!] [--cvsroot=CVSROOT] [--exec=SCRIPT]...
                     [--all-revisions!] [module]...

=head1 DESCRIPTION

This script will search through a repository and determine if any of the
files in it are corrupted.

This is normally accomplished by checking out all I<important> revisions, where
I<important> revisions are defined as the smallest set which, when checked out,
will cause each and every revision's integrity to be verified.  This resolves
to the most recent revision on each branch and the first and last revisions on
the trunk.

Please do not run this script inside of the repository itself.  This will cause
it too fail.

=head1 OPTIONS

=over

=item C<--help>

Print this very help text (or, with C<--verbose>, act like
C<perldoc validate_repo.pl>).

=item C<-a> or C<--all-revisions>

Check out each and every revision rather than just the I<important> ones.
This flag is useful with C<--exec> to execute the C<SCRIPT> (from C<--exec>
below) on a checked out copy of each and every revision.

=item C<-d> or C<--cvsroot=CVSROOT>

Use repository specified by C<CVSROOT>.  Defaults to the contents of the
F<./CVS/Root> file when it exists and is readable, then to the contents of the
C<$CVSROOT> environment variable when it is set and non-empty.

=item C<-e> or C<--exec=SCRIPT>

Execute (as from command prompt) C<SCRIPT> if it exists as a file, is readable,
and is executable, or evaluate (as a perl script) C<SCRIPT> for a checked out
copy of each I<important> revision of each RCS archive in CVSROOT.  Executed
scripts are passed C<CVSROOT FILE REVISION FNO>, where C<CVSROOT> is what
you'd think, C<FILE> is the path to the file relative to C<CVSROOT> and
suitable for use as an argument to C<cvs co>, C<cvs rlog>, and so on,
C<REVISION> is the revision of the checked out file, and C<FNO> is the file
number of the open, read-only file descriptor containing the checked out
contents of revision C<REVISION> of C<FILE>.  An evaluated C<SCRIPT> will find
the same four arguments in the same order in C<@_>, except that C<FNO> will be
an open file handle.

With C<--all-revisions>, execute or evaluate C<SCRIPT> for a checked out
version of each revsion in the RCS archive.

=item C<-v> or C<--verbose>

Print verbose debugging information (or, when specified with C<--help>, act
like C<perldoc validate_repo.pl>).

=head1 ARGUMENTS

=over

=item C<modules>

The module in the repository to examine.  Defaults to the contents of the
F<./CVS/Repository> file when it exists and is readable, then to F<.>
(all modules).

=head1 EXAMPLES

    setenv CVSROOT /release/111/cvs
    validate_repo.pl


    validate_repo.pl -d /another/cvsroot --verbose --exec '
    system "grep \"This string means Im a bad, bad file!\" <&"
           . fileno( $_[3] )
           . ">/dev/null"
        or die "Revision $_[2] of $_[0]/$_[1],v is bad, bad, bad!"'

=head1 SEE ALSO

None.

=cut

######################################################################
#                    MODULES                                         #
######################################################################
use strict;

use Fcntl qw( F_GETFD F_SETFD );
use File::Find;
use File::Basename;
use File::Path;
use File::Spec;
use Getopt::Long;
use IO::File;
use Pod::Usage;

######################################################################
#                    GLOBALS                                         #
######################################################################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbose
           );



######################################################################
#                    SUBROUTINES                                     #
######################################################################

######################################################################
#
#    NAME :
#      main
#
#    PURPOSE :
#      To search the repository for broken files
#
#    PARAMETERS :
#      NONE
#
#    GLOBALS :
#      $cvsroot              - The CVS repository to search through.
#      $ENV{ CVSROOT }       - The default CVS repository to search through.
#      @list_of_broken_files - The list of files that ne##############################

use vars qw(
             $all_revisions
             $cvsroot
             @extra_files
             @ignore_files
             $ignored_files
             @invalid_revs
             @list_of_broken_files
             @scripts
             $total_files
             $total_interesting_revisions
             $total_revisions
             $verbos