home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / MISC / ccheck.lzh / ccheck.man < prev    next >
Text File  |  1990-12-15  |  8KB  |  166 lines
  1.      NAME
  2.           ccheck - C program checker
  3.  
  4.      SYNOPSIS
  5.           ccheck [-q] [-v] [files ...]
  6.  
  7.      EXAMPLE
  8.          ccheck foo.c >foo.err
  9.  
  10.      DESCRIPTION
  11.       Ccheck checks    C programs for correctly matching brackets of
  12.       all kinds, including quotes and comment brackets, checks
  13.       that the indentation of matching brackets also matches, and
  14.       checks for symptoms of 3 kinds of errors that    the C compiler
  15.       allows without warning: "dangling else" errors where an else
  16.       is bound to the wrong    preceding if, nested comments, where
  17.       the first close-comment bracket prematurely ends the outer
  18.       comment, and the use of assignment ('=') where equality-test
  19.       ('==') was meant.  It    is meant to be run as a    pre-check on C
  20.       programs before calling the compiler.     Its virtues are that
  21.       it allows you    to weed    out some trivial syntactic errors
  22.       faster; for the errors it detects it produces    better error
  23.       messages than    the compiler; and it detects the errors
  24.       mentioned above that the compiler ignores.
  25.  
  26.       The indentation rules    it applies are that the    indentation of
  27.       the first non-white character    on the line holding an opener
  28.       should match that on the line    holding    the matching closer.
  29.       These    rules are fairly weak (e.g. they are compatible    with
  30.       but do not enforce the Ingres    format standard), though they
  31.       may still conflict with your own habits.  The    -q (quiet)
  32.       option suppresses messages classed as    warnings, which
  33.       includes those about mismatched indentations.     The -v
  34.       (verbose) option prints more information -- it shows what is
  35.       on its internal stack    at the time an error is    detected.  It
  36.       is probably only of real use for debugging ccheck itself.
  37.  
  38.       The distinction between warnings and errors is somewhat
  39.       arbitrary.  Because C    allows certain errors it would be
  40.       inappropriate    here to    make the distinction between
  41.       compilable and non-compilable    programs.  Basically only
  42.       indentation mismatches are warnings, and the symptoms    of
  43.       dangling elses or using assignment ('=') instead of equality
  44.       ('==') are treated as    errors.     The program will always print
  45.       some message if you have an error involving mismatched
  46.       brackets of some kind, and will pass any legal program if
  47.       its indentation is also correct, unless '=' is used in the
  48.       top level of a condition expression.    For cases in between
  49.       it tries hard    but may    make mistakes, though if you are
  50.       aiming for a properly    indented program you can be sure that
  51.       an error means that something    is wrong.
  52.  
  53.       When it detects signs    of a bracket mismatch it makes a
  54.       decision on the spot about the most likely underlying    cause.
  55.       It does not wait for more evidence to    disambiguate this, so
  56.       on the occasions it is wrong,    not only are the messages
  57.       inappropriate    to some    degree,    but several messages may be
  58.       produced concerning what is really a single (unrecognized)
  59.       error.  The most common example of this is if    you have the
  60.       wrong    indent on a closing brace such that it matches an
  61.       earlier opening brace, ccheck    assumes    first that there is a
  62.       missing closing brace, and then when it finds    the second
  63.       closing brace    that this has no matching opening brace    (this
  64.       having been already wrongly accounted    for).  The summary it
  65.       gives    at the end tells you whether there was really a    net
  66.       imbalance of brackets, which may help    sort out these cases.
  67.  
  68.       Ccheck was written as    a result of the    following
  69.       observations.
  70.  
  71.        1)  In Unix,    modularity suggests that it is appropriate to
  72.       have different programs with different special expertise
  73.       where    other systems would cram them all into one program.
  74.       Thus lint incorporates special knowledge about type-checking
  75.       and portability considerations that would be inappropriate
  76.       in a compiler.  Ccheck like lint takes advantage of the fact
  77.       that since it    is not the compiler it can be wrong some of
  78.       the time without preventing anyone from doing    anything.
  79.  
  80.        2)  C has, in my opinion, some bad choices in its syntax
  81.       that cause frequent errors by    users.    It turns out, though,
  82.       that these can largely be checked for    cheaply, which
  83.       alleviates the original poor design choice.  These are:
  84.  
  85.            a) Not supporting nested    comments (nor warning about
  86.       them in the compiler).
  87.  
  88.            b) Not having an    "endif"    (or "fi") closer to terminate
  89.       if statements, thus leaving users open to the    dangling else
  90.       problem.  (This is the problem that if you have nested if
  91.       statements the following else    will get bound to the nearest
  92.       preceding one, which is not always the intuitively
  93.       reasonable one.)  This is especially troublesome, as it
  94.       means    among other things that    if you modify a    program    by
  95.       adding an else clause    to an existing if statement, you may
  96.       have to modify (by adding braces) not    the if statement to
  97.       which    you are    attaching the else, but    a nested if statement
  98.       acting as its    "then" clause.
  99.  
  100.            c) The use of '=' for assignment, following Fortran's
  101.       bad usage.  It seems to be the case that both    '=' and    '=='
  102.       get seen and mentally    read as    "equals" so that it is hard to
  103.       spot if you write '='    for '==' in conditionals, an error
  104.       that may happen either because of the    language-promoted
  105.       confusion itself, or because of a typing slip    (which is then
  106.       hard to spot).
  107.  
  108.        3) The C compiler produces outstandingly unhelpful error
  109.       messages as a    rule, from the point of    view of    a user who
  110.       wants    to make    corrections as fast as possible.  Once past
  111.       the beginner stage however, a    user can usually do all    right
  112.       by ignoring the text of the error message, which almost
  113.       never    tells her/him what to correct, and attending to    the
  114.       line-number:    generally when your attention is directed to
  115.       only a line or two you can tell what is wrong.  This breaks
  116.       down when the    compiler fails to generate anything like the
  117.       helpful line number.    This is    usually    however    in cases of
  118.       failure to match brackets of some sort -- something which is
  119.       easy for another program to check.  Furthermore attending to
  120.       the user's indentation usually allows    accurate diagnoses and
  121.       helpful messages to be generated in just these cases.
  122.  
  123.       Ccheck, then,    attempts to address these points largely by
  124.       checking bracket matches and using indentation to guess what
  125.       the real problem was -- whether a missing opener, a missing
  126.       closer, wrong    indentation, or    some other mistake such    as a
  127.       spurious character.  Like the    compiler, it has only a    fair
  128.       chance of recovering after an    error and commenting
  129.       intelligently    on the remaining code.    However    its relatively
  130.       fast running time means that correcting only the first error
  131.       in each cycle    is not too time    consuming.
  132.  
  133.      BUGS
  134.       It inflicts its own idea of good indentation,    which neither
  135.       matches a recognized standard    exactly    nor your own
  136.       practices.  It can generate several error descriptions where
  137.       there    is only    one error -- one that it does not describe.
  138.  
  139.       It does not deal with    the preprocessor intelligently.     There
  140.       are two kinds    of case    to note:
  141.  
  142.        1) defines may themselves not be good C e.g.
  143.            #define ctrl(letter) ('letter' &    077)
  144.       will work ok in the program but will draw "bad character
  145.       constant" from ccheck. Similarly, though more    questionable,
  146.       you might define your    own opener and closer e.g.
  147.            #define then {
  148.            #define endif }
  149.  
  150.        2)  Some uses of #ifdef will    confuse    ccheck,    for instance
  151.       if alternative if-condition lines are    given, controlled by
  152.       #ifdef ... #else ccheck will see them    both.  Similarly using
  153.       "#ifdef comment" to comment out parts    of the text in order
  154.       to overcome the lack of nested comments in C will draw fire
  155.       if the commented out section is not legal C.
  156.  
  157.       Do-while loops within    an "if"    clause result in the "if"
  158.       being    forgotten.
  159.  
  160.      AUTHOR
  161.       Steve    Draper
  162.  
  163.      PROVIDER
  164.       Jeff Martin        (MS-DOS)
  165.       Martin Gregorie     (OS9/68K)
  166.