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
          +++ new/usr/src/tools/scripts/cstyle.1onbld

   1    1  .\" Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
   2    2  .\" Use is subject to license terms.
   3    3  .\"
   4    4  .\" CDDL HEADER START
   5    5  .\"
   6    6  .\" The contents of this file are subject to the terms of the
   7    7  .\" Common Development and Distribution License (the "License").
   8    8  .\" You may not use this file except in compliance with the License.
   9    9  .\"
  10   10  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  11   11  .\" or http://www.opensolaris.org/os/licensing.
  12   12  .\" See the License for the specific language governing permissions

  13   13  .\" and limitations under the License.
  14   14  .\"
  15   15  .\" When distributing Covered Code, include this CDDL HEADER in each
  16   16  .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  17   17  .\" If applicable, add the following below this CDDL HEADER, with the
  18   18  .\" fields enclosed by brackets "[]" replaced with your own identifying
  19   19  .\" information: Portions Copyright [yyyy] [name of copyright owner]
  20   20  .\"
  21   21  .\" CDDL HEADER END
  22   22  .\"
  23      -.TH cstyle 1ONBLD "28 March 2005"
       23 +.TH CSTYLE 1ONBLD "Mar 28, 2005"
  24   24  .SH NAME
  25   25  .I cstyle
  26   26  \- check for some common stylistic errors in C source files
  27   27  .SH SYNOPSIS
  28   28  \fBcstyle [-chpvCP] [-o constructs] [file...]\fP
  29      -.LP
  30   29  .SH DESCRIPTION
  31      -.IX "OS-Net build tools" "cstyle" "" "\fBcstyle\fP"
  32   30  .LP
  33   31  .I cstyle
  34   32  inspects C source files (*.c and *.h) for common sylistic errors.  It
  35      -attempts to check for the cstyle documented in 
       33 +attempts to check for the cstyle documented in
  36   34  \fI/shared/ON/general_docs/cstyle.ms.pdf\fP.  Note that there is much
  37   35  in that document that
  38   36  .I cannot
  39   37  be checked for; just because your code is \fBcstyle(1ONBLD)\fP clean does not
  40   38  mean that you've followed Sun's C style.  \fICaveat emptor\fP.
  41      -.LP
  42   39  .SH OPTIONS
  43   40  .LP
  44   41  The following options are supported:
  45   42  .TP 4
  46   43  .B \-c
  47   44  Check continuation line indentation inside of functions.  Sun's C style
  48   45  states that all statements must be indented to an appropriate tab stop,
  49   46  and any continuation lines after them must be indented \fIexactly\fP four
  50   47  spaces from the start line.  This option enables a series of checks
  51   48  designed to find contination line problems within functions only.  The
  52   49  checks have some limitations;  see CONTINUATION CHECKING, below.
  53      -.LP
  54   50  .TP 4
  55   51  .B \-h
  56   52  Performs heuristic checks that are sometimes wrong.  Not generally used.
  57      -.LP
  58   53  .TP 4
  59   54  .B \-p
  60   55  Performs some of the more picky checks.  Includes ANSI #else and #endif
  61   56  rules, and tries to detect spaces after casts.  Used as part of the
  62   57  putback checks.
  63      -.LP
  64   58  .TP 4
  65   59  .B \-v
  66   60  Verbose output;  includes the text of the line of error, and, for
  67   61  \fB-c\fP, the first statement in the current continuation block.
  68      -.LP
  69   62  .TP 4
  70   63  .B \-C
  71   64  Ignore errors in header comments (i.e. block comments starting in the
  72   65  first column).  Not generally used.
  73      -.LP
  74   66  .TP 4
  75   67  .B \-P
  76   68  Check for use of non-POSIX types.  Historically, types like "u_int" and
  77   69  "u_long" were used, but they are now deprecated in favor of the POSIX
  78   70  types uint_t, ulong_t, etc.  This detects any use of the deprecated
  79   71  types.  Used as part of the putback checks.
  80      -.LP
  81   72  .TP 4
  82   73  .B \-o \fIconstructs\fP
  83   74  Allow a comma-seperated list of additional constructs.  Available
  84   75  constructs include:
  85      -.LP
  86   76  .TP 10
  87   77  .B doxygen
  88   78  Allow doxygen-style block comments (\fB/**\fP and \fB/*!\fP)
  89      -.LP
  90   79  .TP 10
  91   80  .B splint
  92   81  Allow splint-style lint comments (\fB/*@...@*/\fP)
  93      -.LP
  94   82  .SH NOTES
  95   83  .LP
  96   84  The cstyle rule for the OS/Net consolidation is that all new files must
  97   85  be \fB-pP\fP clean.  For existing files, the following invocations are
  98   86  run against both the old and new files:
  99      -.LP
 100   87  .TP 4
 101   88  \fBcstyle file\fB
 102      -.LP
 103   89  .TP 4
 104   90  \fBcstyle -p file\fB
 105      -.LP
 106   91  .TP 4
 107   92  \fBcstyle -pP file\fB
 108   93  .LP
 109   94  If the old file gave no errors for one of the invocations, the new file
 110   95  must also give no errors.  This way, files can only become more clean.
 111      -.LP
 112   96  .SH CONTINUATION CHECKING
 113   97  .LP
 114   98  The continuation checker is a resonably simple state machine that knows
 115   99  something about how C is layed out, and can match parenthesis, etc. over
 116  100  multiple lines.  It does have some limitations:
 117      -.LP
 118  101  .TP 4
 119  102  .B 1.
 120  103  Preprocessor macros which cause unmatched parenthesis will confuse the
 121  104  checker for that line.  To fix this, you'll need to make sure that each
 122  105  branch of the #if statement has balanced parenthesis.
 123      -.LP
 124  106  .TP 4
 125  107  .B 2.
 126  108  Some \fBcpp\fP macros do not require ;s after them.  Any such macros
 127  109  *must* be ALL_CAPS; any lower case letters will cause bad output.
 128  110  .LP
 129  111  The bad output will generally be corrected after the next \fB;\fP,
 130  112  \fB{\fP, or \fB}\fP.
 131  113  .LP
 132  114  Some continuation error messages deserve some additional explanation
 133      -.LP
 134  115  .TP 4
 135  116  .B
 136  117  multiple statements continued over multiple lines
 137  118  A multi-line statement which is not broken at statement
 138  119  boundries.  For example:
 139  120  .RS 4
 140  121  .HP 4
 141  122  if (this_is_a_long_variable == another_variable) a =
 142  123  .br
 143  124  b + c;
 144  125  .LP
 145  126  Will trigger this error.  Instead, do:
 146  127  .HP 8
 147  128  if (this_is_a_long_variable == another_variable)
 148  129  .br
 149  130  a = b + c;
 150  131  .RE
 151      -.LP
 152  132  .TP 4
 153  133  .B
 154  134  empty if/for/while body not on its own line
 155  135  For visibility, empty bodies for if, for, and while statements should be
 156  136  on their own line.  For example:
 157  137  .RS 4
 158  138  .HP 4
 159  139  while (do_something(&x) == 0);
 160  140  .LP
 161  141  Will trigger this error.  Instead, do:
 162  142  .HP 8
 163  143  while (do_something(&x) == 0)
 164  144  .br
 165  145  ;
 166  146  .RE
 167  147  
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX