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