sparse.1

   1 .\" Sparse manpage by Josh Triplett
   2 .TH sparse "1"
   3 .
   4 .SH NAME
   5 sparse \- Semantic Parser for C
   6 .
   7 .SH SYNOPSIS
   8 .B sparse
   9 [\fIWARNING OPTIONS\fR]... \fIfile.c\fR
  10 .
  11 .SH DESCRIPTION
  12 Sparse parses C source and looks for errors, producing warnings on standard
  13 error.
  14 .P
  15 Sparse accepts options controlling the set of warnings to generate.  To turn
  16 on warnings Sparse does not issue by default, use the corresponding warning
  17 option \fB\-Wsomething\fR.  Sparse issues some warnings by default; to turn
  18 off those warnings, pass the negation of the associated warning option,
  19 \fB\-Wno\-something\fR.
  20 .
  21 .SH WARNING OPTIONS
  22 .TP
  23 .B \-Waddress\-space
  24 Warn about code which mixes pointers to different address spaces.
  25
  26 Sparse allows an extended attribute
  27 .BI __attribute__((address_space( num )))
  28 on pointers, which designates a pointer target in address space \fInum\fR (a
  29 constant integer).  With \fB\-Waddress\-space\fR, Sparse treats pointers with
  30 identical target types but different address spaces as distinct types.  To
  31 override this warning, such as for functions which convert pointers between
  32 address spaces, use a type that includes \fB__attribute__((force))\fR.
  33
  34 Sparse issues these warnings by default.  To turn them off, use
  35 \fB\-Wno\-address\-space\fR.
  36 .
  37 .TP
  38 .B \-Wbitwise
  39 Warn about unsupported operations or type mismatches with restricted integer
  40 types.
  41
  42 Sparse supports an extended attribute, \fB__attribute__((bitwise))\fR, which
  43 creates a new restricted integer type from a base integer type, distinct from
  44 the base integer type and from any other restricted integer type not declared
  45 in the same declaration or \fBtypedef\fR.  For example, this allows programs
  46 to create \fBtypedef\fRs for integer types with specific endianness.  With
  47 \fB-Wbitwise\fR, Sparse will warn on any use of a restricted type in
  48 arithmetic operations other than bitwise operations, and on any conversion of
  49 one restricted type into another, except via a cast that includes
  50 \fB__attribute__((force))\fR.
  51
  52 Sparse does not issue these warnings by default.
  53 .
  54 .TP
  55 .B \-Wcast\-to\-as
  56 Warn about casts which add an address space to a pointer type.
  57
  58 A cast that includes \fB__attribute__((force))\fR will suppress this warning.
  59
  60 Sparse does not issue these warnings by default.
  61 .
  62 .TP
  63 .B \-Wcast\-truncate
  64 Warn about casts that truncate constant values.
  65
  66 Sparse issues these warnings by default.  To turn them off, use
  67 \fB\-Wno\-cast\-truncate\fR.
  68 .
  69 .TP
  70 .B \-Wcontext
  71 Warn about potential errors in synchronization or other delimited contexts.
  72
  73 Sparse supports several means of designating functions or statements that
  74 delimit contexts, such as synchronization.  Functions with the extended
  75 attribute
  76 .BI __attribute__((context( expression , in_context , out_context ))
  77 require the context \fIexpression\fR (for instance, a lock) to have the value
  78 \fIin_context\fR (a constant nonnegative integer) when called, and return with
  79 the value \fIout_context\fR (a constant nonnegative integer).  For APIs
  80 defined via macros, use the statement form
  81 .BI __context__( expression , in_value , out_value )
  82 in the body of the macro.
  83
  84 With \fB-Wcontext\fR Sparse will warn when it sees a function change the
  85 context without indicating this with a \fBcontext\fR attribute, either by
  86 decreasing a context below zero (such as by releasing a lock without acquiring
  87 it), or returning with a changed context (such as by acquiring a lock without
  88 releasing it).  Sparse will also warn about blocks of code which may
  89 potentially execute with different contexts.
  90
  91 Sparse issues these warnings by default.  To turn them off, use
  92 \fB\-Wno\-context\fR.
  93 .
  94 .TP
  95 .B \-Wdecl
  96 Warn about any non-\fBstatic\fR variable or function definition that has no
  97 previous declaration.
  98
  99 Private symbols (functions and variables) internal to a given source file
 100 should use \fBstatic\fR, to allow additional compiler optimizations, allow
 101 detection of unused symbols, and prevent other code from relying on these
 102 internal symbols.  Public symbols used by other source files will need
 103 declarations visible to those other source files, such as in a header file.
 104 All declarations should fall into one of these two categories.  Thus, with
 105 \fB-Wdecl\fR, Sparse warns about any symbol definition with neither
 106 \fBstatic\fR nor a declaration.  To fix this warning, declare private symbols
 107 \fBstatic\fR, and ensure that the files defining public symbols have the
 108 symbol declarations available first (such as by including the appropriate
 109 header file).
 110
 111 Sparse issues these warnings by default.  To turn them off, use
 112 \fB\-Wno\-decl\fR.
 113 .
 114 .TP
 115 .B \-Wdeclaration-after-statement
 116 Warn about declarations that are not at the start of a block.
 117
 118 These declarations are permitted in C99 but not in C89.
 119
 120 Sparse issues these warnings by default only when the C dialect is
 121 C89 (i.e. -ansi or -std=c89).  To turn them off, use
 122 \fB\-Wno\-declaration\-after\-statement\fR.
 123 .
 124 .TP
 125 .B \-Wdefault\-bitfield\-sign
 126 Warn about any bitfield with no explicit signedness.
 127
 128 Bitfields have no standard-specified default signedness. (C99 6.7.2) A
 129 bitfield without an explicit \fBsigned\fR or \fBunsigned\fR creates a
 130 portability problem for software that relies on the available range of values.
 131 To fix this, specify the bitfield type as \fBsigned\fR or \fBunsigned\fR
 132 explicitly.
 133
 134 Sparse does not issue these warnings by default.
 135 .
 136 .TP
 137 .B \-Wdo\-while
 138 Warn about do-while loops that do not delimit the loop body with braces.
 139
 140 Sparse does not issue these warnings by default.
 141 .
 142 .TP
 143 .B \-Wenum\-mismatch
 144 Warn about the use of an expression of an incorrect \fBenum\fR type when
 145 initializing another \fBenum\fR type, assigning to another \fBenum\fR type, or
 146 passing an argument to a function which expects another \fBenum\fR type.
 147
 148 Sparse issues these warnings by default.  To turn them off, use
 149 \fB\-Wno\-enum\-mismatch\fR.
 150 .
 151 .TP
 152 .B \-Wnon\-pointer\-null
 153 Warn about the use of 0 as a NULL pointer.
 154
 155 0 has integer type.  NULL has pointer type.
 156
 157 Sparse issues these warnings by default.  To turn them off, use
 158 \fB\-Wno\-non\-pointer\-null\fR.
 159 .
 160 .TP
 161 .B \-Wold\-initializer
 162 Warn about the use of the pre-C99 GCC syntax for designated initializers.
 163
 164 C99 provides a standard syntax for designated fields in \fBstruct\fR or
 165 \fBunion\fR initializers:
 166
 167 .nf
 168 struct structname var = { .field = value };
 169 .fi
 170
 171 GCC also has an old, non-standard syntax for designated initializers which
 172 predates C99:
 173
 174 .nf
 175 struct structname var = { field: value };
 176 .fi
 177
 178 Sparse will warn about the use of GCC's non-standard syntax for designated
 179 initializers.  To fix this warning, convert designated initializers to use the
 180 standard C99 syntax.
 181
 182 Sparse issues these warnings by default.  To turn them off, use
 183 \fB\-Wno\-old\-initializer\fR.
 184 .
 185 .TP
 186 .B \-Wone\-bit\-signed\-bitfield
 187 Warn about any one-bit \fBsigned\fR bitfields.
 188
 189 A one-bit \fBsigned\fR bitfield can only have the values 0 and -1, or with
 190 some compilers only 0; this results in unexpected behavior for programs which
 191 expected the ability to store 0 and 1.
 192
 193 Sparse issues these warnings by default.  To turn them off, use
 194 \fB\-Wno\-one\-bit\-signed\-bitfield\fR.
 195 .
 196 .TP
 197 .B \-Wparen\-string
 198 Warn about the use of a parenthesized string to initialize an array.
 199
 200 Standard C syntax does not permit a parenthesized string as an array
 201 initializer.  GCC allows this syntax as an extension.  With
 202 \fB\-Wparen\-string\fR, Sparse will warn about this syntax.
 203
 204 Sparse does not issue these warnings by default.
 205 .
 206 .TP
 207 .B \-Wptr\-subtraction\-blows
 208 Warn when subtracting two pointers to a type with a non-power-of-two size.
 209
 210 Subtracting two pointers to a given type gives a difference in terms of the
 211 number of items of that type.  To generate this value, compilers will usually
 212 need to divide the difference by the size of the type, an potentially
 213 expensive operation for sizes other than powers of two.
 214
 215 Code written using pointer subtraction can often use another approach instead,
 216 such as array indexing with an explicit array index variable, which may allow
 217 compilers to generate more efficient code.
 218
 219 Sparse does not issue these warnings by default.
 220 .
 221 .TP
 222 .B \-Wreturn\-void
 223 Warn if a function with return type void returns a void expression.
 224
 225 C99 permits this, and in some cases this allows for more generic code in
 226 macros that use typeof or take a type as a macro argument.  However, some
 227 programs consider this poor style, and those programs can use
 228 \fB\-Wreturn\-void\fR to get warnings about it.
 229
 230 Sparse does not issue these warnings by default.
 231 .
 232 .TP
 233 .B \-Wshadow
 234 Warn when declaring a symbol which shadows a declaration with the same name in
 235 an outer scope.
 236
 237 Such declarations can lead to error-prone code.
 238
 239 Sparse does not issue these warnings by default.
 240 .
 241 .TP
 242 .B \-Wtransparent\-union
 243 Warn about any declaration using the GCC extension
 244 \fB__attribute__((transparent_union))\fR.
 245
 246 Sparse issues these warnings by default.  To turn them off, use
 247 \fB\-Wno\-transparent\-union\fR.
 248 .
 249 .TP
 250 .B \-Wtypesign
 251 Warn when converting a pointer to an integer type into a pointer to an integer
 252 type with different signedness.
 253
 254 Sparse does not issue these warnings by default.
 255 .
 256 .TP
 257 .B \-Wundef
 258 Warn about preprocessor conditionals that use the value of an undefined
 259 preprocessor symbol.
 260
 261 Standard C (C99 6.10.1) permits using the value of an undefined preprocessor
 262 symbol in preprocessor conditionals, and specifies it has have a value of 0.
 263 However, this behavior can lead to subtle errors.
 264
 265 Sparse does not issue these warnings by default.
 266 .
 267 .SH MISC OPTIONS
 268 .TP
 269 .B \-gcc-base-dir \fIdir\fR
 270 Look for compiler-provided system headers in \fIdir\fR/include/ and \fIdir\fR/include-fixed/.
 271 .
 272 .SH SEE ALSO
 273 .BR cgcc (1)
 274 .
 275 .SH HOMEPAGE
 276 http://www.kernel.org/pub/software/devel/sparse/
 277 .
 278 .SH MAILING LIST
 279 linux-sparse@vger.kernel.org
 280 .
 281 .SH MAINTAINER
 282 Josh Triplett <josh@kernel.org>