]>
Commit | Line | Data |
---|---|---|
a35beedf BB |
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 | |
1d3ba0bf | 11 | .\" or https://opensource.org/licenses/CDDL-1.0. |
a35beedf BB |
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 | .\" | |
3bcbb6af AZ |
23 | .Dd May 26, 2021 |
24 | .Dt CSTYLE 1 | |
25 | .Os | |
26 | . | |
27 | .Sh NAME | |
28 | .Nm cstyle | |
29 | .Nd check for some common stylistic errors in C source files | |
30 | .Sh SYNOPSIS | |
31 | .Nm | |
32 | .Op Fl chpvCP | |
1b37cc1a | 33 | .Oo Ar file Oc Ns … |
3bcbb6af AZ |
34 | .Sh DESCRIPTION |
35 | .Nm | |
36 | inspects C source files (*.c and *.h) for common stylistic errors. | |
37 | It attempts to check for the cstyle documented in | |
38 | .Lk http://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf . | |
a35beedf | 39 | Note that there is much in that document that |
3bcbb6af AZ |
40 | .Em cannot |
41 | be checked for; just because your code is | |
42 | .Nm Ns -clean | |
43 | does not mean that you've followed Sun's C style. | |
44 | .Em Caveat emptor . | |
45 | . | |
46 | .Sh OPTIONS | |
3bcbb6af AZ |
47 | .Bl -tag -width "-c" |
48 | .It Fl c | |
49 | Check continuation line indentation inside of functions. | |
50 | Sun's C style | |
a35beedf | 51 | states that all statements must be indented to an appropriate tab stop, |
3bcbb6af AZ |
52 | and any continuation lines after them must be indented |
53 | .Em exactly | |
54 | four spaces from the start line. | |
55 | This option enables a series of checks designed to find | |
56 | continuation line problems within functions only. | |
57 | The checks have some limitations; see | |
58 | .Sy CONTINUATION CHECKING , | |
59 | below. | |
3bcbb6af AZ |
60 | .It Fl p |
61 | Performs some of the more picky checks. | |
62 | Includes ANSI | |
63 | .Sy #else | |
64 | and | |
65 | .Sy #endif | |
66 | rules, and tries to detect spaces after casts. | |
67 | Used as part of the putback checks. | |
68 | .It Fl v | |
69 | Verbose output; includes the text of the line of error, and, for | |
70 | .Fl c , | |
71 | the first statement in the current continuation block. | |
3bcbb6af AZ |
72 | .It Fl P |
73 | Check for use of non-POSIX types. | |
74 | Historically, types like | |
75 | .Sy u_int | |
76 | and | |
77 | .Sy u_long | |
78 | were used, but they are now deprecated in favor of the POSIX | |
79 | types | |
80 | .Sy uint_t , | |
81 | .Sy ulong_t , | |
82 | etc. | |
83 | This detects any use of the deprecated types. | |
84 | Used as part of the putback checks. | |
14ed1f24 AZ |
85 | .It Fl g |
86 | Also print GitHub-Actions-style | |
87 | .Li ::error | |
88 | output. | |
89 | .El | |
90 | . | |
91 | .Sh ENVIRONMENT | |
92 | .Bl -tag -compact -width ".Ev CI" | |
93 | .It Ev CI | |
94 | If set and nonempty, equivalent to | |
95 | .Fl g . | |
3bcbb6af AZ |
96 | .El |
97 | . | |
98 | .Sh CONTINUATION CHECKING | |
6b4e21c6 NB |
99 | The continuation checker is a reasonably simple state machine that knows |
100 | something about how C is laid out, and can match parenthesis, etc. over | |
3bcbb6af AZ |
101 | multiple lines. |
102 | It does have some limitations: | |
103 | .Bl -enum | |
104 | .It | |
a35beedf | 105 | Preprocessor macros which cause unmatched parenthesis will confuse the |
3bcbb6af AZ |
106 | checker for that line. |
107 | To fix this, you'll need to make sure that each branch of the | |
108 | .Sy #if | |
109 | statement has balanced parenthesis. | |
110 | .It | |
111 | Some | |
112 | .Xr cpp 1 | |
1b37cc1a AZ |
113 | macros do not require |
114 | .Sy ;\& Ns s after them. | |
3bcbb6af AZ |
115 | Any such macros |
116 | .Em must | |
117 | be ALL_CAPS; any lower case letters will cause bad output. | |
118 | .Pp | |
1b37cc1a AZ |
119 | The bad output will generally be corrected after the next |
120 | .Sy ;\& , { , No or Sy } . | |
3bcbb6af AZ |
121 | .El |
122 | Some continuation error messages deserve some additional explanation: | |
123 | .Bl -tag -width Ds | |
124 | .It Sy multiple statements continued over multiple lines | |
125 | A multi-line statement which is not broken at statement boundaries. | |
126 | For example: | |
1b37cc1a | 127 | .Bd -literal -compact -offset Ds |
a35beedf | 128 | if (this_is_a_long_variable == another_variable) a = |
3bcbb6af AZ |
129 | b + c; |
130 | .Ed | |
131 | .Pp | |
132 | Will trigger this error. | |
133 | Instead, do: | |
1b37cc1a | 134 | .Bd -literal -compact -offset Ds |
a35beedf | 135 | if (this_is_a_long_variable == another_variable) |
3bcbb6af AZ |
136 | a = b + c; |
137 | .Ed | |
138 | .It Sy empty if/for/while body not on its own line | |
a35beedf | 139 | For visibility, empty bodies for if, for, and while statements should be |
3bcbb6af AZ |
140 | on their own line. |
141 | For example: | |
1b37cc1a | 142 | .Bd -literal -compact -offset Ds |
a35beedf | 143 | while (do_something(&x) == 0); |
3bcbb6af AZ |
144 | .Ed |
145 | .Pp | |
146 | Will trigger this error. | |
147 | Instead, do: | |
1b37cc1a | 148 | .Bd -literal -compact -offset Ds |
a35beedf | 149 | while (do_something(&x) == 0) |
3bcbb6af AZ |
150 | ; |
151 | .Ed | |
152 | .El |