Print this page
11972 resync smatch


   2 
   3 
   4 
   5 NAME
   6        sparse - Semantic Parser for C
   7 
   8 SYNOPSIS
   9        sparse [WARNING OPTIONS]... file.c
  10 
  11 DESCRIPTION
  12        Sparse parses C source and looks for errors, producing warnings on
  13        standard error.
  14 
  15        Sparse accepts options controlling the set of warnings to generate.  To
  16        turn on warnings Sparse does not issue by default, use the
  17        corresponding warning option -Wsomething.  Sparse issues some warnings
  18        by default; to turn off those warnings, pass the negation of the
  19        associated warning option, -Wno-something.
  20 
  21 WARNING OPTIONS





  22        -Wsparse-all
  23               Turn on all sparse warnings, except for those explicitly
  24               disabled via -Wno-something.
  25 
  26        -Wsparse-error
  27               Turn all sparse warnings into errors.
  28 
  29        -Waddress-space
  30               Warn about code which mixes pointers to different address
  31               spaces.
  32 
  33               Sparse allows an extended attribute
  34               __attribute__((address_space(num))) on pointers, which
  35               designates a pointer target in address space num (a constant
  36               integer).  With -Waddress-space, Sparse treats pointers with
  37               identical target types but different address spaces as distinct
  38               types.  To override this warning, such as for functions which
  39               convert pointers between address spaces, use a type that
  40               includes __attribute__((force)).
  41 










  42               Sparse issues these warnings by default.  To turn them off, use
  43               -Wno-address-space.
  44 
  45        -Wbitwise
  46               Warn about unsupported operations or type mismatches with
  47               restricted integer types.
  48 
  49               Sparse supports an extended attribute, __attribute__((bitwise)),
  50               which creates a new restricted integer type from a base integer
  51               type, distinct from the base integer type and from any other
  52               restricted integer type not declared in the same declaration or
  53               typedef.  For example, this allows programs to create typedefs
  54               for integer types with specific endianness.  With -Wbitwise,
  55               Sparse will warn on any use of a restricted type in arithmetic
  56               operations other than bitwise operations, and on any conversion
  57               of one restricted type into another, except via a cast that
  58               includes __attribute__((force)).
  59 
  60               __bitwise ends up being a "stronger integer separation", one
  61               that doesn't allow you to mix with non-bitwise integers, so now
  62               it's much harder to lose the type by mistake.
  63 
  64               __bitwise is for *unique types* that cannot be mixed with other
  65               types, and that you'd never want to just use as a random integer
  66               (the integer 0 is special, though, and gets silently accepted
  67               iirc - it's kind of like "NULL" for pointers). So "gfp_t" or the
  68               "safe endianness" types would be __bitwise: you can only operate
  69               on them by doing specific operations that know about *that*
  70               particular type.
  71 
  72               Sparse issues these warnings by default.  To turn them off, use
  73               -Wno-bitwise.
  74 















  75        -Wcast-to-as
  76               Warn about casts which add an address space to a pointer type.
  77 
  78               A cast that includes __attribute__((force)) will suppress this
  79               warning.

  80 
  81               Sparse does not issue these warnings by default.
  82 
  83        -Wcast-truncate
  84               Warn about casts that truncate constant values.
  85 
  86               Sparse issues these warnings by default.  To turn them off, use
  87               -Wno-cast-truncate.
  88 
  89        -Wconstant-suffix
  90               Warn if an integer constant is larger than the maximum
  91               representable value of the type indicated by its type suffix (if
  92               any). For example, on a system where ints are 32-bit and longs
  93               64-bit, the constant 0x100000000U is larger than can be
  94               represented by an unsigned int but fits in an unsigned long. So
  95               its type is unsigned long but this is not indicated by its
  96               suffix. In this case, the warning could be suppressed by using
  97               the suffix UL: 0x100000000UL.
  98 
  99               Sparse does not issue these warnings by default.


 193               of that operation.
 194 
 195               Sparse issues these warnings by default.  To turn them off, use
 196               -Wno-designated-init.
 197 
 198        -Wdo-while
 199               Warn about do-while loops that do not delimit the loop body with
 200               braces.
 201 
 202               Sparse does not issue these warnings by default.
 203 
 204        -Wenum-mismatch
 205               Warn about the use of an expression of an incorrect enum type
 206               when initializing another enum type, assigning to another enum
 207               type, or passing an argument to a function which expects another
 208               enum type.
 209 
 210               Sparse issues these warnings by default.  To turn them off, use
 211               -Wno-enum-mismatch.
 212 
 213        -Wempty-character-constant
 214               Warn about a constant such as ''.
 215 
 216               Sparse issues these warnings by default.  To turn them off, use
 217               -Wno-empty-character-constant.
 218 
 219        -Wexternal-function-has-definition
 220               Warn about function definitions that are declared with external
 221               linkage.
 222 
 223               Sparse issues these warnings by default.  To turn them off, use
 224               -Wno-external-function-has-definition.
 225 
 226        -Winit-cstring
 227               Warn about initialization of a char array with a too long
 228               constant C string.
 229 
 230               If the size of the char array and the length of the string are
 231               the same, there is no space for the last nul char of the string
 232               in the array:
 233 
 234               char s[3] = "abc";
 235 
 236               If the array is used as a byte array, not as C string, this
 237               warning is just noise. However, if the array is passed to
 238               functions dealing with C string like printf(%s) and strcmp, it
 239               may cause a trouble.
 240 
 241               Sparse does not issue these warnings by default.
 242 
 243        -Wmemcpy-max-count
 244               Warn about call of memcpy(), memset(), copy_from_user(), or
 245               copy_to_user() with a large compile-time byte count.
 246 
 247               Sparse issues these warnings by default. To turn them off, use
 248               -Wno-memcpy-max-count.
 249 
 250               The limit can be changed with -fmemcpy-max-count=COUNT, the
 251               default being 100000.
 252 
 253        -Wnon-ansi-function-declaration
 254               Warn about non-ANSI function declarations.
 255 
 256               Sparse issues these warnings by default.  To turn them off, use
 257               -Wno-non-ansi-function-declaration.
 258 
 259        -Wnon-pointer-null
 260               Warn about the use of 0 as a NULL pointer.
 261 
 262               0 has integer type.  NULL has pointer type.
 263 
 264               Sparse issues these warnings by default.  To turn them off, use
 265               -Wno-non-pointer-null.
 266 
 267        -Wold-initializer
 268               Warn about the use of the pre-C99 GCC syntax for designated
 269               initializers.
 270 
 271               C99 provides a standard syntax for designated fields in struct
 272               or union initializers:
 273 
 274               struct structname var = { .field = value };
 275 
 276               GCC also has an old, non-standard syntax for designated
 277               initializers which predates C99:
 278 


 338 
 339        -Wreturn-void
 340               Warn if a function with return type void returns a void
 341               expression.
 342 
 343               C99 permits this, and in some cases this allows for more generic
 344               code in macros that use typeof or take a type as a macro
 345               argument.  However, some programs consider this poor style, and
 346               those programs can use -Wreturn-void to get warnings about it.
 347 
 348               Sparse does not issue these warnings by default.
 349 
 350        -Wshadow
 351               Warn when declaring a symbol which shadows a declaration with
 352               the same name in an outer scope.
 353 
 354               Such declarations can lead to error-prone code.
 355 
 356               Sparse does not issue these warnings by default.
 357 










 358        -Wsizeof-bool
 359               Warn when checking the sizeof a _Bool.
 360 
 361               C99 does not specify the sizeof a _Bool.  gcc uses 1.

 362 
 363               Sparse does not issue these warnings by default.
 364 
 365        -Wtransparent-union
 366               Warn about any declaration using the GCC extension
 367               __attribute__((transparent_union)).
 368 
 369               Sparse issues these warnings by default.  To turn them off, use
 370               -Wno-transparent-union.
 371 
 372        -Wtypesign
 373               Warn when converting a pointer to an integer type into a pointer
 374               to an integer type with different signedness.
 375 
 376               Sparse does not issue these warnings by default.
 377 
 378        -Wundef
 379               Warn about preprocessor conditionals that use the value of an
 380               undefined preprocessor symbol.
 381 
 382               Standard C (C99 6.10.1) permits using the value of an undefined
 383               preprocessor symbol in preprocessor conditionals, and specifies
 384               it has a value of 0.  However, this behavior can lead to subtle
 385               errors.
 386 
 387               Sparse does not issue these warnings by default.
 388 
 389 MISC OPTIONS
 390        -gcc-base-dir dir
 391               Look for compiler-provided system headers in dir/include/ and
 392               dir/include-fixed/.
 393 
 394        -multiarch-dir dir
 395               Look for system headers in the multiarch subdirectory dir.  The
 396               dir name would normally take the form of the target's normalized
 397               GNU triplet. (e.g. i386-linux-gnu).
 398 
 399 DEBUG OPTIONS
 400        -fdump-linearize[=only]
 401               Dump the IR code of a function directly after its linearization,
 402               before any simplifications are made. If the argument =only is
 403               also given no further processing is done on the function.
 404               -fmem-report Report some statistics about memory allocation used
 405               by the tool.
 406 
 407 OTHER OPTIONS





 408        -fmemcpy-max-count=COUNT
 409               Set the limit for the warnings given by -Wmemcpy-max-count.  A
 410               COUNT of 0, useless in itself, will effectively disable the
 411               warning.  The default limit is 100000.
 412 
 413        -ftabstop=WIDTH
 414               Set the distance between tab stops.  This helps sparse report
 415               correct column numbers in warnings or errors.  If the value is
 416               less than 1 or greater than 100, the option is ignored.  The
 417               default is 8.
 418 




 419 SEE ALSO
 420        cgcc(1)
 421 
 422 HOMEPAGE
 423        http://www.kernel.org/pub/software/devel/sparse/
 424 
 425 MAILING LIST
 426        linux-sparse@vger.kernel.org
 427 
 428 MAINTAINER
 429        Christopher Li <sparse@chrisli.org>




 430 



 431 








 432 
 433                                                                      sparse(1)


   2 
   3 
   4 
   5 NAME
   6        sparse - Semantic Parser for C
   7 
   8 SYNOPSIS
   9        sparse [WARNING OPTIONS]... file.c
  10 
  11 DESCRIPTION
  12        Sparse parses C source and looks for errors, producing warnings on
  13        standard error.
  14 
  15        Sparse accepts options controlling the set of warnings to generate.  To
  16        turn on warnings Sparse does not issue by default, use the
  17        corresponding warning option -Wsomething.  Sparse issues some warnings
  18        by default; to turn off those warnings, pass the negation of the
  19        associated warning option, -Wno-something.
  20 
  21 WARNING OPTIONS
  22        -fmax-warnings=COUNT
  23               Set the maximum number of displayed warnings to COUNT, which
  24               should be a numerical value or 'unlimited'.  The default limit
  25               is 100.
  26 
  27        -Wsparse-all
  28               Turn on all sparse warnings, except for those explicitly
  29               disabled via -Wno-something.
  30 
  31        -Wsparse-error
  32               Turn all sparse warnings into errors.
  33 
  34        -Waddress-space
  35               Warn about code which mixes pointers to different address
  36               spaces.
  37 
  38               Sparse allows an extended attribute
  39               __attribute__((address_space(id))) on pointers, which designates
  40               a pointer target in address space id (an identifier or a
  41               constant integer).  With -Waddress-space, Sparse treats pointers
  42               with identical target types but different address spaces as
  43               distinct types and will warn accordingly.


  44 
  45               Sparse will also warn on casts which remove the address space
  46               (casts to an integer type or to a plain pointer type). An
  47               exception to this is when the destination type is uintptr_t (or
  48               unsigned long) since such casts are often used to "get a pointer
  49               value representation in an integer type" and such values are
  50               independent of the address space.
  51 
  52               To override these warnings, use a type that includes
  53               __attribute__((force)).
  54 
  55               Sparse issues these warnings by default.  To turn them off, use
  56               -Wno-address-space.
  57 
  58        -Wbitwise
  59               Warn about unsupported operations or type mismatches with
  60               restricted integer types.
  61 
  62               Sparse supports an extended attribute, __attribute__((bitwise)),
  63               which creates a new restricted integer type from a base integer
  64               type, distinct from the base integer type and from any other
  65               restricted integer type not declared in the same declaration or
  66               typedef.  For example, this allows programs to create typedefs
  67               for integer types with specific endianness.  With -Wbitwise,
  68               Sparse will warn on any use of a restricted type in arithmetic
  69               operations other than bitwise operations, and on any conversion
  70               of one restricted type into another, except via a cast that
  71               includes __attribute__((force)).
  72 
  73               __bitwise ends up being a "stronger integer separation", one
  74               that doesn't allow you to mix with non-bitwise integers, so now
  75               it's much 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
  79               (the integer 0 is special, though, and gets silently accepted
  80               iirc - it's kind of like "NULL" for pointers). So "gfp_t" or the
  81               "safe endianness" types would be __bitwise: you can only operate
  82               on them by doing specific operations that know about *that*
  83               particular type.
  84 
  85               Sparse issues these warnings by default.  To turn them off, use
  86               -Wno-bitwise.
  87 
  88        -Wbitwise-pointer
  89               Same as -Wbitwise but for casts to or from pointers to bitwise
  90               types.
  91 
  92               Sparse does not issue these warnings by default.
  93 
  94        -Wcast-from-as
  95               Warn about casts which remove an address space from a pointer
  96               type.
  97 
  98               This is similar to -Waddress-space but will also warn on casts
  99               to unsigned long.
 100 
 101               Sparse does not issues these warnings by default.
 102 
 103        -Wcast-to-as
 104               Warn about casts which add an address space to a pointer type.
 105 
 106               A cast that includes __attribute__((force)) will suppress this
 107               warning.  No warning is generated if the original type is
 108               uintptr_t (or unsigned long).
 109 
 110               Sparse does not issue these warnings by default.
 111 
 112        -Wcast-truncate
 113               Warn about casts that truncate constant values.
 114 
 115               Sparse issues these warnings by default.  To turn them off, use
 116               -Wno-cast-truncate.
 117 
 118        -Wconstant-suffix
 119               Warn if an integer constant is larger than the maximum
 120               representable value of the type indicated by its type suffix (if
 121               any). For example, on a system where ints are 32-bit and longs
 122               64-bit, the constant 0x100000000U is larger than can be
 123               represented by an unsigned int but fits in an unsigned long. So
 124               its type is unsigned long but this is not indicated by its
 125               suffix. In this case, the warning could be suppressed by using
 126               the suffix UL: 0x100000000UL.
 127 
 128               Sparse does not issue these warnings by default.


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






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






 276        -Wnon-pointer-null
 277               Warn about the use of 0 as a NULL pointer.
 278 
 279               0 has integer type.  NULL has pointer type.
 280 
 281               Sparse issues these warnings by default.  To turn them off, use
 282               -Wno-non-pointer-null.
 283 
 284        -Wold-initializer
 285               Warn about the use of the pre-C99 GCC syntax for designated
 286               initializers.
 287 
 288               C99 provides a standard syntax for designated fields in struct
 289               or union initializers:
 290 
 291               struct structname var = { .field = value };
 292 
 293               GCC also has an old, non-standard syntax for designated
 294               initializers which predates C99:
 295 


 355 
 356        -Wreturn-void
 357               Warn if a function with return type void returns a void
 358               expression.
 359 
 360               C99 permits this, and in some cases this allows for more generic
 361               code in macros that use typeof or take a type as a macro
 362               argument.  However, some programs consider this poor style, and
 363               those programs can use -Wreturn-void to get warnings about it.
 364 
 365               Sparse does not issue these warnings by default.
 366 
 367        -Wshadow
 368               Warn when declaring a symbol which shadows a declaration with
 369               the same name in an outer scope.
 370 
 371               Such declarations can lead to error-prone code.
 372 
 373               Sparse does not issue these warnings by default.
 374 
 375        -Wshift-count-negative
 376               Warn if a shift count is negative.
 377 
 378               Sparse issues these warnings by default.
 379 
 380        -Wshift-count-overflow
 381               Warn if a shift count is bigger than the operand's width.
 382 
 383               Sparse issues these warnings by default.
 384 
 385        -Wsizeof-bool
 386               Warn when checking the sizeof a _Bool.
 387 
 388               C99 does not specify the size of a _Bool. GCC, by default, uses
 389               1.
 390 
 391               Sparse does not issue these warnings by default.
 392 
 393        -Wtransparent-union
 394               Warn about any declaration using the GCC extension
 395               __attribute__((transparent_union)).
 396 
 397               Sparse issues these warnings by default.  To turn them off, use
 398               -Wno-transparent-union.
 399 
 400        -Wtypesign
 401               Warn when converting a pointer to an integer type into a pointer
 402               to an integer type with different signedness.
 403 
 404               Sparse does not issue these warnings by default.
 405 
 406        -Wundef
 407               Warn about preprocessor conditionals that use the value of an
 408               undefined preprocessor symbol.
 409 
 410               Standard C (C99 6.10.1) permits using the value of an undefined
 411               preprocessor symbol in preprocessor conditionals, and specifies
 412               it has a value of 0.  However, this behavior can lead to subtle
 413               errors.
 414 
 415               Sparse does not issue these warnings by default.
 416 
 417 MISC OPTIONS
 418        -gcc-base-dir dir
 419               Look for compiler-provided system headers in dir/include/ and
 420               dir/include-fixed/.
 421 
 422        -multiarch-dir dir
 423               Look for system headers in the multiarch subdirectory dir.  The
 424               dir name would normally take the form of the target's normalized
 425               GNU triplet. (e.g. i386-linux-gnu).
 426 
 427 DEBUG OPTIONS
 428        -fmem-report
 429               Report some statistics about memory allocation used by the tool.




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