1.\" SPDX-License-Identifier: CDDL-1.0 2.\" Copyright 2009 Sun Microsystems, Inc. All rights reserved. 3.\" Use is subject to license terms. 4.\" 5.\" CDDL HEADER START 6.\" 7.\" The contents of this file are subject to the terms of the 8.\" Common Development and Distribution License (the "License"). 9.\" You may not use this file except in compliance with the License. 10.\" 11.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 12.\" or https://opensource.org/licenses/CDDL-1.0. 13.\" See the License for the specific language governing permissions 14.\" and limitations under the License. 15.\" 16.\" When distributing Covered Code, include this CDDL HEADER in each 17.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 18.\" If applicable, add the following below this CDDL HEADER, with the 19.\" fields enclosed by brackets "[]" replaced with your own identifying 20.\" information: Portions Copyright [yyyy] [name of copyright owner] 21.\" 22.\" CDDL HEADER END 23.\" 24.Dd May 26, 2021 25.Dt CSTYLE 1 26.Os 27. 28.Sh NAME 29.Nm cstyle 30.Nd check for some common stylistic errors in C source files 31.Sh SYNOPSIS 32.Nm 33.Op Fl chpvCP 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 48.Bl -tag -width "-c" 49.It Fl c 50Check continuation line indentation inside of functions. 51Sun's C style 52states that all statements must be indented to an appropriate tab stop, 53and any continuation lines after them must be indented 54.Em exactly 55four spaces from the start line. 56This option enables a series of checks designed to find 57continuation line problems within functions only. 58The checks have some limitations; see 59.Sy CONTINUATION CHECKING , 60below. 61.It Fl p 62Performs some of the more picky checks. 63Includes ANSI 64.Sy #else 65and 66.Sy #endif 67rules, and tries to detect spaces after casts. 68Used as part of the putback checks. 69.It Fl v 70Verbose output; includes the text of the line of error, and, for 71.Fl c , 72the first statement in the current continuation block. 73.It Fl P 74Check for use of non-POSIX types. 75Historically, types like 76.Sy u_int 77and 78.Sy u_long 79were used, but they are now deprecated in favor of the POSIX 80types 81.Sy uint_t , 82.Sy ulong_t , 83etc. 84This detects any use of the deprecated types. 85Used as part of the putback checks. 86.It Fl g 87Also print GitHub-Actions-style 88.Li ::error 89output. 90.El 91. 92.Sh ENVIRONMENT 93.Bl -tag -compact -width ".Ev CI" 94.It Ev CI 95If set and nonempty, equivalent to 96.Fl g . 97.El 98. 99.Sh CONTINUATION CHECKING 100The continuation checker is a reasonably simple state machine that knows 101something about how C is laid out, and can match parenthesis, etc. over 102multiple lines. 103It does have some limitations: 104.Bl -enum 105.It 106Preprocessor macros which cause unmatched parenthesis will confuse the 107checker for that line. 108To fix this, you'll need to make sure that each branch of the 109.Sy #if 110statement has balanced parenthesis. 111.It 112Some 113.Xr cpp 1 114macros do not require 115.Sy ;\& Ns s after them. 116Any such macros 117.Em must 118be ALL_CAPS; any lower case letters will cause bad output. 119.Pp 120The bad output will generally be corrected after the next 121.Sy ;\& , { , No or Sy } . 122.El 123Some continuation error messages deserve some additional explanation: 124.Bl -tag -width Ds 125.It Sy multiple statements continued over multiple lines 126A multi-line statement which is not broken at statement boundaries. 127For example: 128.Bd -literal -compact -offset Ds 129if (this_is_a_long_variable == another_variable) a = 130 b + c; 131.Ed 132.Pp 133Will trigger this error. 134Instead, do: 135.Bd -literal -compact -offset Ds 136if (this_is_a_long_variable == another_variable) 137 a = b + c; 138.Ed 139.It Sy empty if/for/while body not on its own line 140For visibility, empty bodies for if, for, and while statements should be 141on their own line. 142For example: 143.Bd -literal -compact -offset Ds 144while (do_something(&x) == 0); 145.Ed 146.Pp 147Will trigger this error. 148Instead, do: 149.Bd -literal -compact -offset Ds 150while (do_something(&x) == 0) 151 ; 152.Ed 153.El 154