man/man1/cstyle.1

   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
  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 .
  39 Note that there is much in that document that
  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
  47 .Bl -tag -width "-c"
  48 .It Fl c
  49 Check continuation line indentation inside of functions.
  50 Sun's C style
  51 states that all statements must be indented to an appropriate tab stop,
  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.
  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.
  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.
  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 .
  96 .El
  97 .
  98 .Sh CONTINUATION CHECKING
  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
 101 multiple lines.
 102 It does have some limitations:
 103 .Bl -enum
 104 .It
 105 Preprocessor macros which cause unmatched parenthesis will confuse the
 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
 113 macros do not require
 114 .Sy ;\& Ns s after them.
 115 Any such macros
 116 .Em must
 117 be ALL_CAPS; any lower case letters will cause bad output.
 118 .Pp
 119 The bad output will generally be corrected after the next
 120 .Sy ;\& , { , No or Sy } .
 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:
 127 .Bd -literal -compact -offset Ds
 128 if (this_is_a_long_variable == another_variable) a =
 129     b + c;
 130 .Ed
 131 .Pp
 132 Will trigger this error.
 133 Instead, do:
 134 .Bd -literal -compact -offset Ds
 135 if (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
 139 For visibility, empty bodies for if, for, and while statements should be
 140 on their own line.
 141 For example:
 142 .Bd -literal -compact -offset Ds
 143 while (do_something(&x) == 0);
 144 .Ed
 145 .Pp
 146 Will trigger this error.
 147 Instead, do:
 148 .Bd -literal -compact -offset Ds
 149 while (do_something(&x) == 0)
 150     ;
 151 .Ed
 152 .El