1 cstyle(1ONBLD)                illumos Build Tools               cstyle(1ONBLD)
   2 
   3 
   4 
   5 NAME
   6        cstyle - check for some common stylistic errors in C source files
   7 
   8 SYNOPSIS
   9        cstyle [-chpvCP] [-o constructs] [file...]
  10 
  11 DESCRIPTION
  12        cstyle inspects C source files (*.c and *.h) for common sylistic
  13        errors.  It attempts to check for the cstyle documented in
  14        /shared/ON/general_docs/cstyle.ms.pdf.  Note that there is much in that
  15        document that cannot be checked for; just because your code is
  16        cstyle(1ONBLD) clean does not mean that you've followed Sun's C style.
  17        Caveat emptor.
  18 
  19 OPTIONS
  20        The following options are supported:
  21 
  22        -c  Check continuation line indentation inside of functions.  Sun's C
  23            style states that all statements must be indented to an appropriate
  24            tab stop, and any continuation lines after them must be indented
  25            exactly four spaces from the start line.  This option enables a
  26            series of checks designed to find contination line problems within
  27            functions only.  The checks have some limitations;  see
  28            CONTINUATION CHECKING, below.
  29 
  30        -h  Performs heuristic checks that are sometimes wrong.  Not generally
  31            used.
  32 
  33        -p  Performs some of the more picky checks.  Includes ANSI #else and
  34            #endif rules, and tries to detect spaces after casts.  Used as part
  35            of the putback checks.
  36 
  37        -v  Verbose output;  includes the text of the line of error, and, for
  38            -c, the first statement in the current continuation block.
  39 
  40        -C  Ignore errors in header comments (i.e. block comments starting in
  41            the first column).  Not generally used.
  42 
  43        -P  Check for use of non-POSIX types.  Historically, types like "u_int"
  44            and "u_long" were used, but they are now deprecated in favor of the
  45            POSIX types uint_t, ulong_t, etc.  This detects any use of the
  46            deprecated types.  Used as part of the putback checks.
  47 
  48        -o constructs
  49            Allow a comma-seperated list of additional constructs.  Available
  50            constructs include:
  51 
  52        doxygen   Allow doxygen-style block comments (/** and /*!)
  53 
  54        splint    Allow splint-style lint comments (/*@...@*/)
  55 
  56 NOTES
  57        The cstyle rule for the OS/Net consolidation is that all new files must
  58        be -pP clean.  For existing files, the following invocations are run
  59        against both the old and new files:
  60 
  61        cstyle file
  62 
  63        cstyle -p file
  64 
  65        cstyle -pP file
  66 
  67        If the old file gave no errors for one of the invocations, the new file
  68        must also give no errors.  This way, files can only become more clean.
  69 
  70 CONTINUATION CHECKING
  71        The continuation checker is a resonably simple state machine that knows
  72        something about how C is layed out, and can match parenthesis, etc.
  73        over multiple lines.  It does have some limitations:
  74 
  75        1.  Preprocessor macros which cause unmatched parenthesis will confuse
  76            the checker for that line.  To fix this, you'll need to make sure
  77            that each branch of the #if statement has balanced parenthesis.
  78 
  79        2.  Some cpp macros do not require ;s after them.  Any such macros
  80            *must* be ALL_CAPS; any lower case letters will cause bad output.
  81 
  82        The bad output will generally be corrected after the next ;, {, or }.
  83 
  84        Some continuation error messages deserve some additional explanation
  85 
  86        multiple statements continued over multiple lines
  87            A multi-line statement which is not broken at statement boundries.
  88            For example:
  89 
  90            if (this_is_a_long_variable == another_variable) a =
  91            b + c;
  92 
  93            Will trigger this error.  Instead, do:
  94 
  95            if (this_is_a_long_variable == another_variable)
  96            a = b + c;
  97 
  98        empty if/for/while body not on its own line
  99            For visibility, empty bodies for if, for, and while statements
 100            should be on their own line.  For example:
 101 
 102            while (do_something(&x) == 0);
 103 
 104            Will trigger this error.  Instead, do:
 105 
 106            while (do_something(&x) == 0)
 107            ;
 108 
 109 
 110 
 111 
 112                                  28 March 2005                  cstyle(1ONBLD)