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