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 \-Wsparse\-all
  24 Turn on all sparse warnings, except for those explicitly disabled via
  25 \fB\-Wno\-something\fR.
  26 .TP
  27 .B \-Wsparse\-error
  28 Turn all sparse warnings into errors.
  29 .TP
  30 .B \-Waddress\-space
  31 Warn about code which mixes pointers to different address spaces.
  32 
  33 Sparse allows an extended attribute
  34 .BI __attribute__((address_space( num )))
  35 on pointers, which designates a pointer target in address space \fInum\fR (a
  36 constant integer).  With \fB\-Waddress\-space\fR, Sparse treats pointers with
  37 identical target types but different address spaces as distinct types.  To
  38 override this warning, such as for functions which convert pointers between
  39 address spaces, use a type that includes \fB__attribute__((force))\fR.
  40 
  41 Sparse issues these warnings by default.  To turn them off, use
  42 \fB\-Wno\-address\-space\fR.
  43 .
  44 .TP
  45 .B \-Wbitwise
  46 Warn about unsupported operations or type mismatches with restricted integer
  47 types.
  48 
  49 Sparse supports an extended attribute, \fB__attribute__((bitwise))\fR, which
  50 creates a new restricted integer type from a base integer type, distinct from
  51 the base integer type and from any other restricted integer type not declared
  52 in the same declaration or \fBtypedef\fR.  For example, this allows programs
  53 to create \fBtypedef\fRs for integer types with specific endianness.  With
  54 \fB-Wbitwise\fR, Sparse will warn on any use of a restricted type in
  55 arithmetic operations other than bitwise operations, and on any conversion of
  56 one restricted type into another, except via a cast that includes
  57 \fB__attribute__((force))\fR.
  58 
  59 __bitwise ends up being a "stronger integer separation", one that
  60 doesn't allow you to mix with non-bitwise integers, so now it's much
  61 harder to lose the type by mistake.
  62 
  63 __bitwise is for *unique types* that cannot be mixed with other
  64 types, and that you'd never want to just use as a random integer (the
  65 integer 0 is special, though, and gets silently accepted iirc - it's
  66 kind of like "NULL" for pointers). So "gfp_t" or the "safe endianness"
  67 types would be __bitwise: you can only operate on them by doing
  68 specific operations that know about *that* particular type.
  69 
  70 Sparse issues these warnings by default.  To turn them off, use
  71 \fB\-Wno\-bitwise\fR.
  72 .
  73 .TP
  74 .B \-Wcast\-to\-as
  75 Warn about casts which add an address space to a pointer type.
  76 
  77 A cast that includes \fB__attribute__((force))\fR will suppress this warning.
  78 
  79 Sparse does not issue these warnings by default.
  80 .
  81 .TP
  82 .B \-Wcast\-truncate
  83 Warn about casts that truncate constant values.
  84 
  85 Sparse issues these warnings by default.  To turn them off, use
  86 \fB\-Wno\-cast\-truncate\fR.
  87 .
  88 .TP
  89 .B \-Wconstant\-suffix
  90 Warn if an integer constant is larger than the maximum representable value
  91 of the type indicated by its type suffix (if any). For example, on a
  92 system where ints are 32-bit and longs 64-bit, the constant \fB0x100000000U\fR
  93 is larger than can be represented by an \fBunsigned int\fR but fits in an
  94 \fBunsigned long\fR. So its type is \fBunsigned long\fR but this is not
  95 indicated by its suffix. In this case, the warning could be suppressed by
  96 using the suffix \fBUL\fR: \fB0x100000000UL\fR.
  97 
  98 Sparse does not issue these warnings by default.
  99 .
 100 .TP
 101 .B \-Wconstexpr-not-const
 102 Warn if a non-constant expression is encountered when really expecting a
 103 constant expression instead.
 104 Currently, this warns when initializing an object of static storage duration
 105 with an initializer which is not a constant expression.
 106 
 107 Sparse does not issue these warnings by default.
 108 .
 109 .TP
 110 .B \-Wcontext
 111 Warn about potential errors in synchronization or other delimited contexts.
 112 
 113 Sparse supports several means of designating functions or statements that
 114 delimit contexts, such as synchronization.  Functions with the extended
 115 attribute
 116 .BI __attribute__((context( expression , in_context , out_context ))
 117 require the context \fIexpression\fR (for instance, a lock) to have the value
 118 \fIin_context\fR (a constant nonnegative integer) when called, and return with
 119 the value \fIout_context\fR (a constant nonnegative integer).  For APIs
 120 defined via macros, use the statement form
 121 .BI __context__( expression , in_value , out_value )
 122 in the body of the macro.
 123 
 124 With \fB-Wcontext\fR Sparse will warn when it sees a function change the
 125 context without indicating this with a \fBcontext\fR attribute, either by
 126 decreasing a context below zero (such as by releasing a lock without acquiring
 127 it), or returning with a changed context (such as by acquiring a lock without
 128 releasing it).  Sparse will also warn about blocks of code which may
 129 potentially execute with different contexts.
 130 
 131 Sparse issues these warnings by default.  To turn them off, use
 132 \fB\-Wno\-context\fR.
 133 .
 134 .TP
 135 .B \-Wdecl
 136 Warn about any non-\fBstatic\fR variable or function definition that has no
 137 previous declaration.
 138 
 139 Private symbols (functions and variables) internal to a given source file
 140 should use \fBstatic\fR, to allow additional compiler optimizations, allow
 141 detection of unused symbols, and prevent other code from relying on these
 142 internal symbols.  Public symbols used by other source files will need
 143 declarations visible to those other source files, such as in a header file.
 144 All declarations should fall into one of these two categories.  Thus, with
 145 \fB-Wdecl\fR, Sparse warns about any symbol definition with neither
 146 \fBstatic\fR nor a declaration.  To fix this warning, declare private symbols
 147 \fBstatic\fR, and ensure that the files defining public symbols have the
 148 symbol declarations available first (such as by including the appropriate
 149 header file).
 150 
 151 Sparse issues these warnings by default.  To turn them off, use
 152 \fB\-Wno\-decl\fR.
 153 .
 154 .TP
 155 .B \-Wdeclaration-after-statement
 156 Warn about declarations that are not at the start of a block.
 157 
 158 These declarations are permitted in C99 but not in C89.
 159 
 160 Sparse issues these warnings by default only when the C dialect is
 161 C89 (i.e. -ansi or -std=c89).  To turn them off, use
 162 \fB\-Wno\-declaration\-after\-statement\fR.
 163 .
 164 .TP
 165 .B \-Wdefault\-bitfield\-sign
 166 Warn about any bitfield with no explicit signedness.
 167 
 168 Bitfields have no standard-specified default signedness. (C99 6.7.2) A
 169 bitfield without an explicit \fBsigned\fR or \fBunsigned\fR creates a
 170 portability problem for software that relies on the available range of values.
 171 To fix this, specify the bitfield type as \fBsigned\fR or \fBunsigned\fR
 172 explicitly.
 173 
 174 Sparse does not issue these warnings by default.
 175 .
 176 .TP
 177 .B \-Wdesignated\-init
 178 Warn about positional initialization of structs marked as requiring designated
 179 initializers.
 180 
 181 Sparse allows an attribute
 182 .BI __attribute__((designated_init))
 183 which marks a struct as requiring designated initializers.  Sparse will warn
 184 about positional initialization of a struct variable or struct literal of a
 185 type that has this attribute.
 186 
 187 Requiring designated initializers for a particular struct type will insulate
 188 code using that struct type from changes to the layout of the type, avoiding
 189 the need to change initializers for that type unless they initialize a removed
 190 or incompatibly changed field.
 191 
 192 Common examples of this type of struct include collections of function pointers
 193 for the implementations of a class of related operations, for which the default
 194 NULL for an unmentioned field in a designated initializer will correctly
 195 indicate the absence of that operation.
 196 
 197 Sparse issues these warnings by default.  To turn them off, use
 198 \fB\-Wno\-designated\-init\fR.
 199 .
 200 .TP
 201 .B \-Wdo\-while
 202 Warn about do-while loops that do not delimit the loop body with braces.
 203 
 204 Sparse does not issue these warnings by default.
 205 .
 206 .TP
 207 .B \-Wenum\-mismatch
 208 Warn about the use of an expression of an incorrect \fBenum\fR type when
 209 initializing another \fBenum\fR type, assigning to another \fBenum\fR type, or
 210 passing an argument to a function which expects another \fBenum\fR type.
 211 
 212 Sparse issues these warnings by default.  To turn them off, use
 213 \fB\-Wno\-enum\-mismatch\fR.
 214 .
 215 .TP
 216 .B \-Wempty\-character\-constant
 217 Warn about a constant such as ''.
 218 
 219 Sparse issues these warnings by default.  To turn them off, use
 220 \fB\-Wno\-empty\-character\-constant\fR.
 221 .
 222 .TP
 223 .B \-Wexternal\-function\-has\-definition
 224 Warn about function definitions that are declared with external linkage.
 225 
 226 Sparse issues these warnings by default.  To turn them off, use
 227 \fB\-Wno\-external\-function\-has\-definition\fR.
 228 .
 229 .TP
 230 .B \-Winit\-cstring
 231 Warn about initialization of a char array with a too long constant C string.
 232 
 233 If the size of the char array and the length of the string are the same,
 234 there is no space for the last nul char of the string in the array:
 235 
 236 .nf
 237 char s[3] = "abc";
 238 .fi
 239 
 240 If the array is used as a byte array, not as C string, this
 241 warning is just noise. However, if the array is passed to functions
 242 dealing with C string like printf(%s) and strcmp, it may cause a
 243 trouble.
 244 
 245 Sparse does not issue these warnings by default.
 246 .
 247 .TP
 248 .B \-Wmemcpy\-max\-count
 249 Warn about call of \fBmemcpy()\fR, \fBmemset()\fR, \fBcopy_from_user()\fR, or
 250 \fBcopy_to_user()\fR with a large compile-time byte count.
 251 
 252 Sparse issues these warnings by default. To turn them off, use
 253 \fB\-Wno\-memcpy\-max\-count\fR.
 254 
 255 The limit can be changed with \fB\-fmemcpy\-max\-count=COUNT\fR,
 256 the default being \fB100000\fR.
 257 .
 258 .TP
 259 .B \-Wnon\-ansi\-function\-declaration
 260 Warn about non-ANSI function declarations.
 261 
 262 Sparse issues these warnings by default.  To turn them off, use
 263 \fB\-Wno\-non\-ansi\-function\-declaration\fR.
 264 .
 265 .TP
 266 .B \-Wnon\-pointer\-null
 267 Warn about the use of 0 as a NULL pointer.
 268 
 269 0 has integer type.  NULL has pointer type.
 270 
 271 Sparse issues these warnings by default.  To turn them off, use
 272 \fB\-Wno\-non\-pointer\-null\fR.
 273 .
 274 .TP
 275 .B \-Wold\-initializer
 276 Warn about the use of the pre-C99 GCC syntax for designated initializers.
 277 
 278 C99 provides a standard syntax for designated fields in \fBstruct\fR or
 279 \fBunion\fR initializers:
 280 
 281 .nf
 282 struct structname var = { .field = value };
 283 .fi
 284 
 285 GCC also has an old, non-standard syntax for designated initializers which
 286 predates C99:
 287 
 288 .nf
 289 struct structname var = { field: value };
 290 .fi
 291 
 292 Sparse will warn about the use of GCC's non-standard syntax for designated
 293 initializers.  To fix this warning, convert designated initializers to use the
 294 standard C99 syntax.
 295 
 296 Sparse issues these warnings by default.  To turn them off, use
 297 \fB\-Wno\-old\-initializer\fR.
 298 .
 299 .TP
 300 .B \-Wone\-bit\-signed\-bitfield
 301 Warn about any one-bit \fBsigned\fR bitfields.
 302 
 303 A one-bit \fBsigned\fR bitfield can only have the values 0 and -1, or with
 304 some compilers only 0; this results in unexpected behavior for programs which
 305 expected the ability to store 0 and 1.
 306 
 307 Sparse issues these warnings by default.  To turn them off, use
 308 \fB\-Wno\-one\-bit\-signed\-bitfield\fR.
 309 .
 310 .TP
 311 .B \-Wparen\-string
 312 Warn about the use of a parenthesized string to initialize an array.
 313 
 314 Standard C syntax does not permit a parenthesized string as an array
 315 initializer.  GCC allows this syntax as an extension.  With
 316 \fB\-Wparen\-string\fR, Sparse will warn about this syntax.
 317 
 318 Sparse does not issue these warnings by default.
 319 .
 320 .TP
 321 .B \-Wpointer\-arith
 322 Warn about anything that depends on the \fBsizeof\fR a void or function type.
 323 
 324 C99 does not allow the \fBsizeof\fR operator to be applied to function types
 325 or to incomplete types such as void. GCC allows \fBsizeof\fR to be applied to
 326 these types as an extension and assigns these types a size of \fI1\fR. With
 327 \fB\-pointer\-arith\fR, Sparse will warn about pointer arithmetic on void
 328 or function pointers, as well as expressions which directly apply the
 329 \fBsizeof\fR operator to void or function types.
 330 
 331 Sparse does not issue these warnings by default.
 332 .
 333 .TP
 334 .B \-Wptr\-subtraction\-blows
 335 Warn when subtracting two pointers to a type with a non-power-of-two size.
 336 
 337 Subtracting two pointers to a given type gives a difference in terms of the
 338 number of items of that type.  To generate this value, compilers will usually
 339 need to divide the difference by the size of the type, an potentially
 340 expensive operation for sizes other than powers of two.
 341 
 342 Code written using pointer subtraction can often use another approach instead,
 343 such as array indexing with an explicit array index variable, which may allow
 344 compilers to generate more efficient code.
 345 
 346 Sparse does not issue these warnings by default.
 347 .
 348 .TP
 349 .B \-Wreturn\-void
 350 Warn if a function with return type void returns a void expression.
 351 
 352 C99 permits this, and in some cases this allows for more generic code in
 353 macros that use typeof or take a type as a macro argument.  However, some
 354 programs consider this poor style, and those programs can use
 355 \fB\-Wreturn\-void\fR to get warnings about it.
 356 
 357 Sparse does not issue these warnings by default.
 358 .
 359 .TP
 360 .B \-Wshadow
 361 Warn when declaring a symbol which shadows a declaration with the same name in
 362 an outer scope.
 363 
 364 Such declarations can lead to error-prone code.
 365 
 366 Sparse does not issue these warnings by default.
 367 .
 368 .TP
 369 .B \-Wsizeof-bool
 370 Warn when checking the sizeof a _Bool.
 371 
 372 C99 does not specify the sizeof a _Bool.  gcc uses 1.
 373 
 374 Sparse does not issue these warnings by default.
 375 .
 376 .TP
 377 .B \-Wtransparent\-union
 378 Warn about any declaration using the GCC extension
 379 \fB__attribute__((transparent_union))\fR.
 380 
 381 Sparse issues these warnings by default.  To turn them off, use
 382 \fB\-Wno\-transparent\-union\fR.
 383 .
 384 .TP
 385 .B \-Wtypesign
 386 Warn when converting a pointer to an integer type into a pointer to an integer
 387 type with different signedness.
 388 
 389 Sparse does not issue these warnings by default.
 390 .
 391 .TP
 392 .B \-Wundef
 393 Warn about preprocessor conditionals that use the value of an undefined
 394 preprocessor symbol.
 395 
 396 Standard C (C99 6.10.1) permits using the value of an undefined preprocessor
 397 symbol in preprocessor conditionals, and specifies it has a value of 0.
 398 However, this behavior can lead to subtle errors.
 399 
 400 Sparse does not issue these warnings by default.
 401 .
 402 .SH MISC OPTIONS
 403 .TP
 404 .B \-gcc-base-dir \fIdir\fR
 405 Look for compiler-provided system headers in \fIdir\fR/include/ and \fIdir\fR/include-fixed/.
 406 .
 407 .TP
 408 .B \-multiarch-dir \fIdir\fR
 409 Look for system headers in the multiarch subdirectory \fIdir\fR.
 410 The \fIdir\fR name would normally take the form of the target's
 411 normalized GNU triplet. (e.g. i386-linux-gnu).
 412 .
 413 .SH DEBUG OPTIONS
 414 .TP
 415 .B \-fdump-linearize[=only]
 416 Dump the IR code of a function directly after its linearization,
 417 before any simplifications are made. If the argument \fB=only\fR is
 418 also given no further processing is done on the function.
 419 .
 420 .B \-fmem-report
 421 Report some statistics about memory allocation used by the tool.
 422 .
 423 .SH OTHER OPTIONS
 424 .TP
 425 .B \-fmemcpy-max-count=COUNT
 426 Set the limit for the warnings given by \fB-Wmemcpy-max-count\fR.
 427 A COUNT of 0, useless in itself, will effectively disable the warning.
 428 The default limit is 100000.
 429 .
 430 .TP
 431 .B \-ftabstop=WIDTH
 432 Set the distance between tab stops.  This helps sparse report correct
 433 column numbers in warnings or errors.  If the value is less than 1 or
 434 greater than 100, the option is ignored.  The default is 8.
 435 .
 436 .SH SEE ALSO
 437 .BR cgcc (1)
 438 .
 439 .SH HOMEPAGE
 440 http://www.kernel.org/pub/software/devel/sparse/
 441 .
 442 .SH MAILING LIST
 443 linux-sparse@vger.kernel.org
 444 .
 445 .SH MAINTAINER
 446 Christopher Li <sparse@chrisli.org>