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