home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / gnu / brik-2.0-src.lha / brik-2.0 / brik.doc < prev    next >
Text File  |  1993-08-30  |  29KB  |  705 lines
  1.  
  2.  
  3.      BRIK(1)                    USER MANUAL                    BRIK(1)
  4.  
  5.  
  6.      NAME
  7.           brik - calculate 32-bit CRC
  8.  
  9.      SYNOPSIS
  10.           brik -h
  11.           brik -gcGCbafvsqWHT file ...
  12.  
  13.      DESCRIPTION
  14.           Brik generates and verifies 32-bit CRC values (checksums).
  15.           It is designed to generate CRCs for text files that are the
  16.           same on all computer systems that use the ASCII character
  17.           set, provided each text file is in the usual text file
  18.           format for each system. Brik will also optionally use binary
  19.           CRCs calculated using every byte in a file.  Such binary
  20.           CRCs are portable across systems for binary files that are
  21.           moved from system to system without any newline conversion.
  22.           Brik can be asked to decide by examining each file whether
  23.           to calculate a text mode or binary mode CRC for it.
  24.  
  25.           Changes from version 1.0 are summarized at the end of this
  26.           document.
  27.  
  28.           The general usage format is:
  29.  
  30.                brik -gcGCbafvsqWHT [ file ] ...
  31.  
  32.           The brackets mean that file, which is the name of a file, is
  33.           optional.  The three dots indicate that more than one
  34.           filename may be typed (separated by blanks).  Exactly one of
  35.           the options -c, -C, -g, -G, or -h, is required.  The -h
  36.           option gives a help screen.
  37.  
  38.           In addition to -h, the Brik options available (as they
  39.           appear on the help screen) are:
  40.  
  41.           -g   look for Checksum: header, generate CRC for rest of
  42.                file
  43.  
  44.           -c   get CRC from header, verify CRC of rest of file
  45.  
  46.           -G   generate CRC for entire file (add -b for binary files)
  47.  
  48.           -C   verify all file CRCs from output of -G (-f is not
  49.                needed)
  50.  
  51.           -b   use binary mode -- read file byte by byte, not line by
  52.                line
  53.  
  54.           -a   automatically decide whether each file is text or
  55.                binary
  56.  
  57.           -f   read filenames (wildcards ok) from specified files
  58.  
  59.           -v   be verbose, report all results (else only errors are
  60.                reported)
  61.  
  62.           -s   be silent, say nothing, just return status code
  63.  
  64.           -q   be quiet, don't print header for -G
  65.  
  66.           -W   after generating CRC with -g, write it to original
  67.                header
  68.  
  69.           -H   after generating CRC with -g, print header to stdout
  70.  
  71.           -T   include trailing empty lines, normally ignored (text
  72.                mode only)
  73.  
  74.           VERIFYING CRC HEADERS
  75.  
  76.           The primary intended use of Brik is to verify Checksum:
  77.           headers in Usenet postings and in C and Pascal source files.
  78.           A Checksum: header looks like this:
  79.  
  80.                Checksum: 9485762645b   (verify with "brik")
  81.  
  82.           The word Checksum: must occur at the beginning of a line.
  83.           It is followed by a colon, an optional blank, a ten-digit
  84.           decimal 32-bit CRC, and any arbitrary optional string such
  85.           as the comment shown above.  The CRC value may be followed
  86.           by a one-character suffix identifying the type of the CRC.
  87.           These suffixes are described later.
  88.  
  89.           When Brik is invoked with the syntax
  90.  
  91.                brik -c file ...
  92.  
  93.           it will search for the Checksum: header in each specified
  94.           file, read the CRC value from that header, calculate the
  95.           CRC-32 for all lines in the file (except trailing empty
  96.           lines) that occur *after* the header line, and report an
  97.           error if the two values do not match.
  98.  
  99.           CALCULATING CRC HEADERS
  100.  
  101.           The command
  102.  
  103.                brik -g file ...
  104.  
  105.           tells Brik to look for the Checksum: header in each
  106.           specified file, calculate the CRC of the lines in the file
  107.           following the header, and print the CRC and filename without
  108.           changing the file in any way.  You can also ask Brik to
  109.           update the Checksum: header with the following command:
  110.  
  111.                brik -gW file ...
  112.  
  113.           This causes Brik to update the Checksum: header in the file
  114.           with the newly-calculated CRC.  If there is not enough space
  115.           for the CRC in the existing header, Brik reports an error
  116.           and does not change the existing header.  To initially add a
  117.           Checksum: header to a file, insert a line of the following
  118.           form into the file with a text editor:
  119.  
  120.                Checksum: XXXXXXXXXX  -- this is an optional comment
  121.  
  122.           The word Checksum must be at the beginning of a line.  The
  123.           ten `X' characters shown can be any ten characters.  They
  124.           will be later replaced by the calculated CRC value.  They do
  125.           not need to be `X'.  The comment following them is optional
  126.           and can be any arbitrary string of characters after the CRC
  127.           field, separated from it by blanks.  As an example, in a C
  128.           source file called main.c, you might have:
  129.  
  130.                /*
  131.                Checksum: XXXXXXXXXX  (verify or update with brik)
  132.                */
  133.  
  134.           Once a header like this exists in the file, invoke Brik as
  135.           follows:
  136.  
  137.                brik -gW main.c
  138.  
  139.           This will cause the ten `X' characters to be replaced with
  140.           the calculated checksum, giving something like this:
  141.  
  142.                /*
  143.                Checksum: 1922837484  (verify or update with brik)
  144.                */
  145.  
  146.           Later you can use the command
  147.  
  148.                brik -c main.c
  149.  
  150.           to verify that the contents of the file following the header
  151.           have the same CRC as the stored value.
  152.  
  153.           If Brik is invoked with the -c or -g options and it cannot
  154.           find a Checksum: header in a file, it prints a row of
  155.           question marks.  If it is invoked with the -gW option and it
  156.           does not find enough character positions after the Checksum:
  157.           string to hold the CRC, it does not fill in the CRC and
  158.           prints an error message.
  159.  
  160.           Brik can be asked to generate a complete Checksum: header
  161.           but print it to standard output instead of writing it to the
  162.           file.  Do this by adding the -H option.  If both -W and -H
  163.           are given, the Checksum: header will be written both to the
  164.           file and to standard output.
  165.  
  166.           WHOLE-FILE CRCS
  167.  
  168.           A "whole-file" CRC calculation is done for the entire
  169.           contents of a file, without looking for a Checksum: header.
  170.           The command
  171.  
  172.                brik -G file ...
  173.  
  174.           asks Brik to do this calculation for all specified files.
  175.           The output from this command is a list of files and their
  176.           whole-file CRCs.  It is sent to the standard output stream,
  177.           which in most cases is your screen.  The output should be
  178.           saved in a file by redirecting it.  For example, the command
  179.  
  180.                brik -G *.h *.c > crc.lst
  181.  
  182.           on an MS-DOS system might yield the following in the output
  183.           file crc.lst:
  184.  
  185.                # CRC-32        filename
  186.                # ------        --------
  187.  
  188.                2566277976      getopt.c
  189.                 100594287      brik.c
  190.                1151475469      vms.c
  191.                3929503738      turboc.c
  192.                2424271922      addbfcrc.c
  193.                1943472856      assert.h
  194.                2601923477      brik.h
  195.  
  196.           The output of the -G option is in free format.  The output
  197.           file may be edited by hand.  Empty lines and lines beginning
  198.           with '#' will be ignored by Brik when it is later asked to
  199.           read this file.
  200.  
  201.           This list of filenames and whole-file CRCs may be verified
  202.           by a command like this:
  203.  
  204.                brik -C crc.lst
  205.  
  206.           This makes Brik read the file crc.lst, get the CRCs and
  207.           filenames from it, do the CRC calculation again for each
  208.           file, and report an error if it does not match the CRC
  209.           recorded inside crc.lst.
  210.  
  211.           **IX and MS-DOS users (and others who can pipe the output of
  212.           one command into another) could use a command like the
  213.           following to see if Brik's -G and -C options are working: