usr/src/tools/scripts/cstyle.1onbld

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