% $Id: crc.tex 1.4 1998/01/11 21:07:41 brian Exp $

\chapter{crc and crcchk}

The \textbf{crc} command is used to record the length and 16-bit CRC value (or,
optionally, the 32-bit CRC value) for one or more files.

The \textbf{crcchk} command is used to record the length and CRC value
(either 16-bit or 32-bit) for a list of files and optionally check
their lengths and CRC values against a previously-obtained set of
values for those files.

The code used to calculate the 16-bit CRC value for an individual file
was developed at IBM Austin, Texas, by Jim Czenkusch. The code to
calculate the 32-bit CRC has enhancements to pre-condition and
post-condition each value so that it is compatible with the 32-bit CRC
value generated by PKWARE's PKZIP and InfoZIP's \textbf{zip} commands.

\section{Usage}

\begin{verbatim}
crc [ -s ] [ -l ] fspec ...
crcchk [ -l ] infile [ outfile ]
\end{verbatim}
%\medskip

The \textbf{crc} program gets the length and calculates the CRC value
for each file that matches the given command-line file
specification(s). If \texttt{-s} is specified, then \textbf{crc}
recursively descends into subdirectories looking for files that match
the file specification(s).

The \textbf{crcchk} program reads the input text file to get a list of
files. It then calcuates the length and CRC of each file listed. If
the input file also contains a length and CRC value for a file, those
values are compared against the calculated values for that file. This
input file can be created directly from the output of either the
\textbf{crc} or \textbf{crcchk} command.

If an output file name is specified to \textbf{crcchk}, then each file
listed in the input text file, along with its actual length and CRC,
is written to the output file. Later, this output file can be read by
the \textbf{crcchk} program to check to see if any of the listed files
has changed.

File lengths are displayed in decimal format. CRCs are displayed in
hexadecimal format with a leading \texttt{0x}. Filenames are enclosed
within double quotes in case they contain embedded spaces or other
puncutation.

If the \texttt{-l} (letter el) flat is specified, \textbf{crc} and
\textbf{crcchk} generate 32-bit (long) CRCs that are compatible with
those generated by PKZIP and \textbf{zip}. The default is to generate
16-bit CRCs.

The \textbf{crcchk} program only honors the \texttt{-l} flag if an
output file is specified. It ignores the \texttt{-l} flag if no output
file was specified.

For each matching file, \textbf{crc} writes one line to standard
output as follows:

\begin{verbatim}
        length  CRC  "filename"
\end{verbatim}

\section{Flags}

\begin{itemize}

    \item[\texttt{-l}] (letter el) \textbf{crcchk} (if an output file
        was specified) and \textbf{crc} calculate and show long
        (32-bit) CRC values. The default is to calculate and show
        16-bit CRC values.

    \item[\texttt{-s}] Descend subdirectories searching for matching
        files (\textbf{crc} only).

\end{itemize}

\section{Input File for crcchk}

        Blank lines are ignored. Lines that begin with \verb+#+ are
        assumed to contain comments and are ignored. Each non-blank,
        non-comment line must be formatted as follows:

        \begin{itemize}
        \item[{}] \verb+[ length  CRC ]  "filename"+
        \end{itemize}

        The \textit{length} and \textit{CRC} values in the line are
        optional. Either both must be present or both must be missing.
        If present, the length must be specified in decimal, while the
        CRC must be specified in hexadecimal as \texttt{0x} followed
        by one or more hexadecimal digits.

        If the CRC is \texttt{0xNNNN} or shorter (4 or less hex
        digits), then it is assumed to be a 16-bit CRC\@. If it contains
        5 or more hex digits, then it is assumed to be a 32-bit CRC\@.

        If the length and CRC value are present, then \textbf{crcchk}
        compares the values to those it calculated and logs any
        discrepancies to stderr.

        The \textit{filename} must be enclosed in double quotes if it
        contains spaces, semicolons, commas, or other punctuation.
        Double quotes around the filename are optional otherwise.

\section{Output File from crcchk}

        If an output file is specified, then \textbf{crcchk} writes to
        this output file the name, length, and CRC value for each file
        that is listed in the input file, one file per line, as
        follows:

        \begin{itemize}
        \item[{}] \verb+length  CRC  "filename"+
        \end{itemize}

        If the CRC in the input text file is a 32-bit CRC, then the CRC
        in the output file will also be a 32-bit CRC\@. If the CRC in the
        input text file is a 16-bit CRC, then the CRC in the output text
        file will be a 16-bit CRC\@.

        \textbf{Note:} If an output file is specified but a file
        listed in the input file has no CRC, then \textbf{crcchk}
        checks the \texttt{-l} (letter el) flag. If \texttt{-l} is
        specified in this case, \textbf{crcchk} generates a 32-bit
        (long) CRC for the file. Otherwise, it defaults to generating
        a 16-bit CRC for the file.

\section{Examples}

\begin{enumerate}

\item I entered the following command on my system (a very long time
        ago, I might add):

\begin{verbatim}
        crc *.h \*.sys
\end{verbatim}

        It produced the following output:

\begin{verbatim}
         3159  0xD65B  BMTBL.H
        10780  0x5495  UTIL.H
        15473  0x064B  REGEXP.H
          178  0x4E87  \CONFIG.SYS
\end{verbatim}

\item I entered the following command on my system (also a long time ago):

\begin{verbatim}
        crc -l crc.doc
\end{verbatim}

   It produced the following output:

\begin{verbatim}
        2409  0x070E5D3F  CRC.DOC
\end{verbatim}


\item The \verb'ls \u\brian\bin\*.exe >files.txt' command was run to
        produce a list of files that I wanted to check with
        \textbf{crcchk}. You should normally specify the full pathname
        of the files for \textbf{ls} so that you can later run
        \textbf{crcchk} from any directory---\textbf{crcchk} will
        attempt to open each file using the name as listed. I then
        added the comment and blank line to the beginning of the file,
        as follows:

\begin{verbatim}
        # files.txt created on 05/20/91

        \u\brian\bin\ati.exe
        \u\brian\bin\b.exe
        \u\brian\bin\cdcl.exe
        \u\brian\bin\config.exe
        \u\brian\bin\ccmt.exe
        \u\brian\bin\cdir.exe
        \u\brian\bin\chmod.exe
\end{verbatim}

The \verb'crcchk files.txt files.crc' command produced the following file
named \textbf{files.crc}:

\begin{verbatim}
         7070  0xF359  "\u\brian\bin\ati.exe"
        10000  0x8CFB  "\u\brian\bin\b.exe"
        27630  0x13AC  "\u\brian\bin\cdcl.exe"
        57954  0x5D88  "\u\brian\bin\config.exe"
        14401  0x7352  "\u\brian\bin\ccmt.exe"
        17827  0xDE07  "\u\brian\bin\cdir.exe"
        24053  0xFE94  "\u\brian\bin\chmod.exe"
\end{verbatim}

Now, we can run the \verb'crcchk files.crc' command any time we want
to see if any of those executable files has been changed. We might
also want to backup the \textbf{files.crc} file or make it read-only
so we don't lose the information it contains.

Note that since the length and CRC values are missing from the input
text file, \textbf{crcchk} calculates 16-bit CRCs for the output file
by default.

\end{enumerate}
