6282 ONBLD man pages not pbchk clean
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Reviewed by: Josef Sipek <jeffpc@josefsipek.net>

          --- old/usr/src/tools/scripts/cstyle.1onbld.man.txt
          +++ new/usr/src/tools/scripts/cstyle.1onbld.man.txt
   1      -cstyle(1ONBLD)                illumos Build Tools               cstyle(1ONBLD)
        1 +CSTYLE(1ONBLD)                illumos Build Tools               CSTYLE(1ONBLD)
   2    2  
   3    3  
   4    4  
   5    5  NAME
   6    6         cstyle - check for some common stylistic errors in C source files
   7    7  
   8    8  SYNOPSIS
   9    9         cstyle [-chpvCP] [-o constructs] [file...]
  10   10  
  11   11  DESCRIPTION

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

 102  102             while (do_something(&x) == 0);
 103  103  
 104  104             Will trigger this error.  Instead, do:
 105  105  
 106  106             while (do_something(&x) == 0)
 107  107             ;
 108  108  
 109  109  
 110  110  
 111  111  
 112      -                                 28 March 2005                  cstyle(1ONBLD)
      112 +                                March 28, 2005                  CSTYLE(1ONBLD)
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX