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.1
  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         {
  87                 no warnings;
  88                 printf $fmt, $tapline, $crc32, $crc32;
  89         }
  90
  91         exit($ec);
  92 }
  93
  94 __DATA__
  95
  96 =head1 NAME
  97
  98 perlcrc32.pl - display CRC-32 checksum value
  99
 100 =head1 SYNOPSIS
 101
 102 B<perlcrc32.pl> [options]
 103
 104  Options:
 105    -h                           show short usage help
 106    --help                       show long detailed help
 107    -c                           check the checksum is 0xffffffff
 108    -d                           show CRC-32 in decimal
 109    -v                           include TAP line with -c
 110    -x                           show CRC-32 in lowercase hexadecimal
 111    -X                           show CRC-32 in UPPERCASE hexadecimal
 112
 113 =head1 DESCRIPTION
 114
 115 B<perlcrc32.pl> computes the ISO CRC-32 value of standard input
 116 and displays it as an 8-digit lowercase hexadecimal number (by
 117 default) to standard output.
 118
 119 =head1 OPTIONS
 120
 121 =over
 122
 123 =item B<-c>
 124
 125 Verify that the computed checksum is 0xFFFFFFFF ("checksum good")
 126 and set the exit status to 0 if it is or 1 if it's not ("checksum
 127 bad").  Giving option B<-c> by itself suppresses other output by
 128 default.
 129
 130 =item B<-d>
 131
 132 Show the computed CRC-32 value in decimal.  If this option is given,
 133 then the decimal version of the computed CRC-32 value is always
 134 output (preceded by the hexadecimal value and a space if the
 135 hexadecimal value is also being output).
 136
 137 The checksum always appears on a separate, following line,
 138 I<after> any "ok/not ok" line (as produced by B<-cv>).
 139
 140 The decimal value of the computed CRC-32 value is never output by
 141 default.
 142
 143 =item B<-v>
 144
 145 Be verbose.  Currently the B<-v> option only affects the B<-c>
 146 option.
 147
 148 If both B<-c> and B<-v> have been specified then, in addition to
 149 setting the exit status, an S<"ok - checksum good"> or
 150 S<"not ok - checksum bad"> line will be output to standard output
 151 as the very first line (before the checksum itself).
 152
 153 =item B<-x>
 154
 155 Output the computed checksum using lowercase hexadecimal as exactly
 156 8 hexadecimal digits at the very beginning of the line.
 157
 158 This is the default output unless B<-c>, B<-d> or B<-X> have been
 159 given.  Giving an explicit option B<-x> will force output even with
 160 B<-c> and supersedes any B<-X> option.
 161
 162 The checksum always appears on a separate, following line,
 163 I<after> any "ok/not ok" line (as produced by B<-cv>).
 164
 165 =item B<-X>
 166
 167 Output the computed checksum using UPPERCASE hexadecimal as exactly
 168 8 hexadecimal digits at the very beginning of the line.
 169
 170 The B<-X> option supersedes any B<-x> option.
 171
 172 The checksum always appears on a separate, following line,
 173 I<after> any "ok/not ok" line (as produced by B<-cv>).
 174
 175 =back
 176
 177 =head1 DETAILS
 178
 179 The CRC-32 value being computed can be fully described as follows:
 180
 181      CRC 32 polynomial: 0x04C11DB7
 182   initialization value: 0xFFFFFFFF
 183     bitwise endianness: little
 184    bit reversed result: yes
 185   xor final value with: 0xFFFFFFFF
 186   checksum "123456789": 0xCBF43926
 187
 188 This is the standard Ethernet/zlib CRC-32 computation and, in fact,
 189 is performed by the zlib library's C<crc32> function courtesy of
 190 the Compress::Zlib perl module.
 191
 192 Any output produced by perlcpio -c will result in a "good checksum"
 193 result when using perlcrc32 -c.
 194
 195 =head1 LIMITATIONS
 196
 197 Requires the Compress::Zlib module to compute the CRC-32 value.
 198
 199 =head1 SEE ALSO
 200
 201 =over
 202
 203 =item Test Anything Protocol (TAP) specification (version 12)
 204
 205 =item L<https://testanything.org/tap-specification.html>
 206
 207 =back
 208
 209 =head1 COPYRIGHT AND LICENSE
 210
 211 =over
 212
 213 =item Copyright (C) 2020 Kyle J. McKay
 214
 215 =item All rights reserved.
 216
 217 =back
 218
 219 Permission to use, copy, modify, and distribute this software for any
 220 purpose with or without fee is hereby granted, provided that the above
 221 copyright notice and this permission notice appear in all copies.
 222
 223 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 224 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 225 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 226 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 227 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 228 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 229 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 230
 231 =cut