toolbox/perlcrc32.pl

   1 #!/usr/bin/env perl
   2
   3 # perlcrc32.pl - display CRC-32 checksum value
   4
   5 # Copyright (C) 2020 Kyle J. McKay.
   6 # All rights reserved.
   7 #
   8 # Permission to use, copy, modify, and distribute this software for any
   9 # purpose with or without fee is hereby granted, provided that the above
  10 # copyright notice and this permission notice appear in all copies.
  11 #
  12 # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  13 # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  14 # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  15 # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  16 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  17 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  18 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  19
  20 # Version 1.0.0
  21
  22 use strict;
  23 use warnings;
  24 use bytes;
  25
  26 use File::Basename qw(basename);
  27 use Compress::Zlib qw(crc32);
  28 use Getopt::Long;
  29 use Pod::Usage;
  30 BEGIN {
  31         eval 'require Pod::Text::Termcap; 1;' and
  32         @Pod::Usage::ISA = (qw( Pod::Text::Termcap ));
  33 }
  34 my $me = basename($0);
  35 close(DATA) if fileno(DATA);
  36
  37 exit(&main(@ARGV)||0);
  38
  39 my ($opt_c, $opt_d, $opt_v, $opt_x);
  40
  41 my $totalbytesread; BEGIN { $totalbytesread = 0 }
  42
  43 sub main {
  44         local *ARGV = \@_;
  45         select((select(STDERR),$|=1)[0]); # just in case
  46         Getopt::Long::Configure('bundling');
  47         GetOptions(
  48                 'h' => sub {pod2usage(-verbose => 0, -exitval => 0)},
  49                 'help' => sub {pod2usage(-verbose => 2, -exitval => 0)},
  50                 'c' => \$opt_c,
  51                 'd' => \$opt_d,
  52                 'v' => \$opt_v,
  53                 'x' => sub {$opt_x = 'x'},
  54                 'X' => sub {$opt_x = 'X'},
  55         ) && !@ARGV or pod2usage(-verbose => 0, -exitval => 2);
  56         $opt_x = 'x' if !defined($opt_x) && !defined($opt_d) && !defined($opt_c);
  57         $opt_x = '' if !defined($opt_x) && (defined($opt_d) || defined($opt_c));
  58
  59         my $crc32 = crc32("", undef);
  60
  61         binmode(STDIN);
  62
  63         for (;;) {
  64                 my $buf = '';
  65                 my $bytes = sysread(STDIN, $buf, 32768);
  66                 defined($bytes) or die "$me: error: failed reading input: $!\n";
  67                 last if $bytes == 0;
  68                 $crc32 = crc32($buf, $crc32);
  69         }
  70
  71         my $ec = 0;
  72         my $tapline = "";
  73         if ($opt_c) {
  74                 if ($crc32 == 0xFFFFFFFF) {
  75                         $tapline = "ok - checksum good\n";
  76                 } else {
  77                         $ec = 1;
  78                         $tapline = "not ok - checksum bad\n";
  79                 }
  80                 $opt_v or $tapline = "";
  81         }
  82         my $fmt = '%s';
  83         $fmt .= "%08$opt_x" if $opt_x;
  84         $fmt .= ($opt_x ? ' ' : '') . '%u' if $opt_d;
  85         $fmt .= "\n" if $opt_x || $opt_d;
  86         printf $fmt, $tapline, $crc32, $crc32;
  87
  88         exit($ec);
  89 }
  90
  91 __DATA__
  92
  93 =head1 NAME
  94
  95 perlcrc32.pl - display CRC-32 checksum value
  96
  97 =head1 SYNOPSIS
  98
  99 B<perlcrc32.pl> [options]
 100
 101  Options:
 102    -h                           show short usage help
 103    --help                       show long detailed help
 104    -c                           check the checksum is 0xffffffff
 105    -d                           show CRC-32 in decimal
 106    -v                           include TAP line with -c
 107    -x                           show CRC-32 in lowercase hexadecimal
 108    -X                           show CRC-32 in UPPERCASE hexadecimal
 109
 110 =head1 DESCRIPTION
 111
 112 B<perlcrc32.pl> computes the ISO CRC-32 value of standard input
 113 and displays it as an 8-digit lowercase hexadecimal number (by
 114 default) to standard output.
 115
 116 =head1 OPTIONS
 117
 118 =over
 119
 120 =item B<-c>
 121
 122 Verify that the computed checksum is 0xFFFFFFFF ("checksum good")
 123 and set the exit status to 0 if it is or 1 if it's not ("checksum
 124 bad").  Giving option B<-c> by itself suppresses other output by
 125 default.
 126
 127 =item B<-d>
 128
 129 Show the computed CRC-32 value in decimal.  If this option is given,
 130 then the decimal version of the computed CRC-32 value is always
 131 output (preceded by the hexadecimal value and a space if the
 132 hexadecimal value is also being output).
 133
 134 The checksum always appears on a separate, following line,
 135 I<after> any "ok/not ok" line (as produced by B<-cv>).
 136
 137 The decimal value of the computed CRC-32 value is never output by
 138 default.
 139
 140 =item B<-v>
 141
 142 Be verbose.  Currently the B<-v> option only affects the B<-c>
 143 option.
 144
 145 If both B<-c> and B<-v> have been specified then, in addition to
 146 setting the exit status, an S<"ok - checksum good"> or
 147 S<"not ok - checksum bad"> line will be output to standard output
 148 as the very first line (before the checksum itself).
 149
 150 =item B<-x>
 151
 152 Output the computed checksum using lowercase hexadecimal as exactly
 153 8 hexadecimal digits at the very beginning of the line.
 154
 155 This is the default output unless B<-c>, B<-d> or B<-X> have been
 156 given.  Giving an explicit option B<-x> will force output even with
 157 B<-c> and supersedes any B<-X> option.
 158
 159 The checksum always appears on a separate, following line,
 160 I<after> any "ok/not ok" line (as produced by B<-cv>).
 161
 162 =item B<-X>
 163
 164 Output the computed checksum using UPPERCASE hexadecimal as exactly
 165 8 hexadecimal digits at the very beginning of the line.
 166
 167 The B<-X> option supersedes any B<-x> option.
 168
 169 The checksum always appears on a separate, following line,
 170 I<after> any "ok/not ok" line (as produced by B<-cv>).
 171
 172 =back
 173
 174 =head1 DETAILS
 175
 176 The CRC-32 value being computed can be fully described as follows:
 177
 178      CRC 32 polynomial: 0x04C11DB7
 179   initialization value: 0xFFFFFFFF
 180     bitwise endianness: little
 181    bit reversed result: yes
 182   xor final value with: 0xFFFFFFFF
 183   checksum "123456789": 0xCBF43926
 184
 185 This is the standard Ethernet/zlib CRC-32 computation and, in fact,
 186 is performed by the zlib library's C<crc32> function courtesy of
 187 the Compress::Zlib perl module.
 188
 189 Any output produced by perlcpio -c will result in a "good checksum"
 190 result when using perlcrc32 -c.
 191
 192 =head1 LIMITATIONS
 193
 194 Requires the Compress::Zlib module to compute the CRC-32 value.
 195
 196 =head1 SEE ALSO
 197
 198 =over
 199
 200 =item Test Anything Protocol (TAP) specification (version 12)
 201
 202 =item L<https://testanything.org/tap-specification.html>
 203
 204 =back
 205
 206 =head1 COPYRIGHT AND LICENSE
 207
 208 =over
 209
 210 =item Copyright (C) 2020 Kyle J. McKay
 211
 212 =item All rights reserved.
 213
 214 =back
 215
 216 Permission to use, copy, modify, and distribute this software for any
 217 purpose with or without fee is hereby granted, provided that the above
 218 copyright notice and this permission notice appear in all copies.
 219
 220 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 221 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 222 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 223 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 224 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 225 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 226 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 227
 228 =cut