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