Print this page
new smatch


   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 


 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


 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


 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>















   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 \-fmax-warnings=COUNT
  24 Set the maximum number of displayed warnings to COUNT, which should be
  25 a numerical value or 'unlimited'.
  26 The default limit is 100.
  27 .
  28 .TP
  29 .B \-Wsparse\-all
  30 Turn on all sparse warnings, except for those explicitly disabled via
  31 \fB\-Wno\-something\fR.
  32 .TP
  33 .B \-Wsparse\-error
  34 Turn all sparse warnings into errors.
  35 .TP
  36 .B \-Waddress\-space
  37 Warn about code which mixes pointers to different address spaces.
  38 
  39 Sparse allows an extended attribute
  40 .BI __attribute__((address_space( id )))
  41 on pointers, which designates a pointer target in address space \fIid\fR (an
  42 identifier or a constant integer).
  43 With \fB\-Waddress\-space\fR, Sparse treats pointers with
  44 identical target types but different address spaces as distinct types and
  45 will warn accordingly.
  46 
  47 Sparse will also warn on casts which remove the address space (casts to an
  48 integer type or to a plain pointer type). An exception to this is when the
  49 destination type is \fBuintptr_t\fR (or \fBunsigned long\fR) since such casts
  50 are often used to "get a pointer value representation in an integer type" and
  51 such values are independent of the address space.
  52 
  53 To override these warnings, use a type that includes \fB__attribute__((force))\fR.
  54 
  55 Sparse issues these warnings by default.  To turn them off, use
  56 \fB\-Wno\-address\-space\fR.
  57 .
  58 .TP
  59 .B \-Wbitwise
  60 Warn about unsupported operations or type mismatches with restricted integer
  61 types.
  62 
  63 Sparse supports an extended attribute, \fB__attribute__((bitwise))\fR, which
  64 creates a new restricted integer type from a base integer type, distinct from
  65 the base integer type and from any other restricted integer type not declared
  66 in the same declaration or \fBtypedef\fR.  For example, this allows programs
  67 to create \fBtypedef\fRs for integer types with specific endianness.  With
  68 \fB-Wbitwise\fR, Sparse will warn on any use of a restricted type in
  69 arithmetic operations other than bitwise operations, and on any conversion of
  70 one restricted type into another, except via a cast that includes
  71 \fB__attribute__((force))\fR.
  72 
  73 __bitwise ends up being a "stronger integer separation", one that
  74 doesn't allow you to mix with non-bitwise integers, so now it's much
  75 harder to lose the type by mistake.
  76 
  77 __bitwise is for *unique types* that cannot be mixed with other
  78 types, and that you'd never want to just use as a random integer (the
  79 integer 0 is special, though, and gets silently accepted iirc - it's
  80 kind of like "NULL" for pointers). So "gfp_t" or the "safe endianness"
  81 types would be __bitwise: you can only operate on them by doing
  82 specific operations that know about *that* particular type.
  83 
  84 Sparse issues these warnings by default.  To turn them off, use
  85 \fB\-Wno\-bitwise\fR.
  86 .
  87 .TP
  88 .B \-Wbitwise\-pointer
  89 Same as \fB\-Wbitwise\fR but for casts to or from pointers to bitwise types.
  90 
  91 Sparse does not issue these warnings by default.
  92 .
  93 .TP
  94 .B \-Wcast\-from\-as
  95 Warn about casts which remove an address space from a pointer type.
  96 
  97 This is similar to \fB\-Waddress\-space\fR but will also warn
  98 on casts to \fBunsigned long\fR.
  99 
 100 Sparse does not issues these warnings by default.
 101 .
 102 .TP
 103 .B \-Wcast\-to\-as
 104 Warn about casts which add an address space to a pointer type.
 105 
 106 A cast that includes \fB__attribute__((force))\fR will suppress this warning.
 107 No warning is generated if the original type is \fBuintptr_t\fR
 108 (or \fBunsigned long\fR).
 109 
 110 Sparse does not issue these warnings by default.
 111 .
 112 .TP
 113 .B \-Wcast\-truncate
 114 Warn about casts that truncate constant values.
 115 
 116 Sparse issues these warnings by default.  To turn them off, use
 117 \fB\-Wno\-cast\-truncate\fR.
 118 .
 119 .TP
 120 .B \-Wconstant\-suffix
 121 Warn if an integer constant is larger than the maximum representable value
 122 of the type indicated by its type suffix (if any). For example, on a
 123 system where ints are 32-bit and longs 64-bit, the constant \fB0x100000000U\fR
 124 is larger than can be represented by an \fBunsigned int\fR but fits in an
 125 \fBunsigned long\fR. So its type is \fBunsigned long\fR but this is not
 126 indicated by its suffix. In this case, the warning could be suppressed by
 127 using the suffix \fBUL\fR: \fB0x100000000UL\fR.
 128 


 227 
 228 Sparse issues these warnings by default.  To turn them off, use
 229 \fB\-Wno\-designated\-init\fR.
 230 .
 231 .TP
 232 .B \-Wdo\-while
 233 Warn about do-while loops that do not delimit the loop body with braces.
 234 
 235 Sparse does not issue these warnings by default.
 236 .
 237 .TP
 238 .B \-Wenum\-mismatch
 239 Warn about the use of an expression of an incorrect \fBenum\fR type when
 240 initializing another \fBenum\fR type, assigning to another \fBenum\fR type, or
 241 passing an argument to a function which expects another \fBenum\fR type.
 242 
 243 Sparse issues these warnings by default.  To turn them off, use
 244 \fB\-Wno\-enum\-mismatch\fR.
 245 .
 246 .TP







 247 .B \-Wexternal\-function\-has\-definition
 248 Warn about function definitions that are declared with external linkage.
 249 
 250 Sparse issues these warnings by default.  To turn them off, use
 251 \fB\-Wno\-external\-function\-has\-definition\fR.
 252 .
 253 .TP
 254 .B \-Winit\-cstring
 255 Warn about initialization of a char array with a too long constant C string.
 256 
 257 If the size of the char array and the length of the string are the same,
 258 there is no space for the last nul char of the string in the array:
 259 
 260 .nf
 261 char s[3] = "abc";
 262 .fi
 263 
 264 If the array is used as a byte array, not as C string, this
 265 warning is just noise. However, if the array is passed to functions
 266 dealing with C string like printf(%s) and strcmp, it may cause a
 267 trouble.
 268 
 269 Sparse does not issue these warnings by default.
 270 .
 271 .TP
 272 .B \-Wmemcpy\-max\-count
 273 Warn about call of \fBmemcpy()\fR, \fBmemset()\fR, \fBcopy_from_user()\fR, or
 274 \fBcopy_to_user()\fR with a large compile-time byte count.
 275 
 276 Sparse issues these warnings by default. To turn them off, use
 277 \fB\-Wno\-memcpy\-max\-count\fR.
 278 
 279 The limit can be changed with \fB\-fmemcpy\-max\-count=COUNT\fR,
 280 the default being \fB100000\fR.
 281 .
 282 .TP







 283 .B \-Wnon\-pointer\-null
 284 Warn about the use of 0 as a NULL pointer.
 285 
 286 0 has integer type.  NULL has pointer type.
 287 
 288 Sparse issues these warnings by default.  To turn them off, use
 289 \fB\-Wno\-non\-pointer\-null\fR.
 290 .
 291 .TP
 292 .B \-Wold\-initializer
 293 Warn about the use of the pre-C99 GCC syntax for designated initializers.
 294 
 295 C99 provides a standard syntax for designated fields in \fBstruct\fR or
 296 \fBunion\fR initializers:
 297 
 298 .nf
 299 struct structname var = { .field = value };
 300 .fi
 301 
 302 GCC also has an old, non-standard syntax for designated initializers which


 366 .B \-Wreturn\-void
 367 Warn if a function with return type void returns a void expression.
 368 
 369 C99 permits this, and in some cases this allows for more generic code in
 370 macros that use typeof or take a type as a macro argument.  However, some
 371 programs consider this poor style, and those programs can use
 372 \fB\-Wreturn\-void\fR to get warnings about it.
 373 
 374 Sparse does not issue these warnings by default.
 375 .
 376 .TP
 377 .B \-Wshadow
 378 Warn when declaring a symbol which shadows a declaration with the same name in
 379 an outer scope.
 380 
 381 Such declarations can lead to error-prone code.
 382 
 383 Sparse does not issue these warnings by default.
 384 .
 385 .TP
 386 .B \-Wshift-count-negative
 387 Warn if a shift count is negative.
 388 
 389 Sparse issues these warnings by default.
 390 .
 391 .TP
 392 .B \-Wshift-count-overflow
 393 Warn if a shift count is bigger than the operand's width.
 394 
 395 Sparse issues these warnings by default.
 396 .
 397 .TP
 398 .B \-Wsizeof-bool
 399 Warn when checking the sizeof a _Bool.
 400 
 401 C99 does not specify the size of a _Bool. GCC, by default, uses \fI1\fR.
 402 
 403 Sparse does not issue these warnings by default.
 404 .
 405 .TP
 406 .B \-Wtransparent\-union
 407 Warn about any declaration using the GCC extension
 408 \fB__attribute__((transparent_union))\fR.
 409 
 410 Sparse issues these warnings by default.  To turn them off, use
 411 \fB\-Wno\-transparent\-union\fR.
 412 .
 413 .TP
 414 .B \-Wtypesign
 415 Warn when converting a pointer to an integer type into a pointer to an integer
 416 type with different signedness.
 417 
 418 Sparse does not issue these warnings by default.
 419 .
 420 .TP
 421 .B \-Wundef


 424 
 425 Standard C (C99 6.10.1) permits using the value of an undefined preprocessor
 426 symbol in preprocessor conditionals, and specifies it has a value of 0.
 427 However, this behavior can lead to subtle errors.
 428 
 429 Sparse does not issue these warnings by default.
 430 .
 431 .SH MISC OPTIONS
 432 .TP
 433 .B \-gcc-base-dir \fIdir\fR
 434 Look for compiler-provided system headers in \fIdir\fR/include/ and \fIdir\fR/include-fixed/.
 435 .
 436 .TP
 437 .B \-multiarch-dir \fIdir\fR
 438 Look for system headers in the multiarch subdirectory \fIdir\fR.
 439 The \fIdir\fR name would normally take the form of the target's
 440 normalized GNU triplet. (e.g. i386-linux-gnu).
 441 .
 442 .SH DEBUG OPTIONS
 443 .TP





 444 .B \-fmem-report
 445 Report some statistics about memory allocation used by the tool.
 446 .
 447 .SH OTHER OPTIONS
 448 .TP
 449 .B \-fdiagnostic-prefix[=PREFIX]
 450 Prefix all diagnostics by the given PREFIX, followed by ": ".
 451 If no one is given "sparse" is used.
 452 The default is to not use a prefix at all.
 453 .
 454 .TP
 455 .B \-fmemcpy-max-count=COUNT
 456 Set the limit for the warnings given by \fB-Wmemcpy-max-count\fR.
 457 A COUNT of 'unlimited' or '0' will effectively disable the warning.
 458 The default limit is 100000.
 459 .
 460 .TP
 461 .B \-ftabstop=WIDTH
 462 Set the distance between tab stops.  This helps sparse report correct
 463 column numbers in warnings or errors.  If the value is less than 1 or
 464 greater than 100, the option is ignored.  The default is 8.
 465 .
 466 .TP
 467 .B \-f[no-]unsigned-char, \-f[no-]signed-char
 468 Let plain 'char' be unsigned or signed.
 469 By default chars are signed.
 470 .
 471 .SH SEE ALSO
 472 .BR cgcc (1)
 473 .
 474 .SH HOMEPAGE
 475 http://www.kernel.org/pub/software/devel/sparse/
 476 .
 477 .SH MAILING LIST
 478 linux-sparse@vger.kernel.org
 479 .
 480 .SH CONTRIBUTINGS AND REPORTING BUGS
 481 Submission of patches and reporting of bugs, as well as discussions
 482 related to Sparse, should be done via the mailing list (linux-sparse@vger.kernel.org)
 483 where the development and maintenance is primarily done.
 484 You do not have to be subscribed to the list to send a message there.
 485 
 486 Bugs can also be reported and tracked via the Linux kernel's bugzilla:
 487 http://bugzilla.kernel.org/enter_bug.cgi?component=Sparse&product=Tools .
 488 .
 489 .SH AUTHORS
 490 Sparse was started by Linus Torvalds.
 491 The complete list of contributors can be find at
 492 https://www.openhub.net/p/sparse/contributors .
 493 
 494 Luc Van Oostenryck is Sparse's current maintainer.