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