1 sparse(1) User Commands 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. 129 130 -Wconstexpr-not-const 131 Warn if a non-constant expression is encountered when really 132 expecting a constant expression instead. Currently, this warns 133 when initializing an object of static storage duration with an 134 initializer which is not a constant expression. 135 136 Sparse does not issue these warnings by default. 137 138 -Wcontext 139 Warn about potential errors in synchronization or other 140 delimited contexts. 141 142 Sparse supports several means of designating functions or 143 statements that delimit contexts, such as synchronization. 144 Functions with the extended attribute 145 __attribute__((context(expression,in_context,out_context)) 146 require the context expression (for instance, a lock) to have 147 the value in_context (a constant nonnegative integer) when 148 called, and return with the value out_context (a constant 149 nonnegative integer). For APIs defined via macros, use the 150 statement form __context__(expression,in_value,out_value) in the 151 body of the macro. 152 153 With -Wcontext Sparse will warn when it sees a function change 154 the context without indicating this with a context attribute, 155 either by decreasing a context below zero (such as by releasing 156 a lock without acquiring it), or returning with a changed 157 context (such as by acquiring a lock without releasing it). 158 Sparse will also warn about blocks of code which may potentially 159 execute with different contexts. 160 161 Sparse issues these warnings by default. To turn them off, use 162 -Wno-context. 163 164 -Wdecl Warn about any non-static variable or function definition that 165 has no previous declaration. 166 167 Private symbols (functions and variables) internal to a given 168 source file should use static, to allow additional compiler 169 optimizations, allow detection of unused symbols, and prevent 170 other code from relying on these internal symbols. Public 171 symbols used by other source files will need declarations 172 visible to those other source files, such as in a header file. 173 All declarations should fall into one of these two categories. 174 Thus, with -Wdecl, Sparse warns about any symbol definition with 175 neither static nor a declaration. To fix this warning, declare 176 private symbols static, and ensure that the files defining 177 public symbols have the symbol declarations available first 178 (such as by including the appropriate header file). 179 180 Sparse issues these warnings by default. To turn them off, use 181 -Wno-decl. 182 183 -Wdeclaration-after-statement 184 Warn about declarations that are not at the start of a block. 185 186 These declarations are permitted in C99 but not in C89. 187 188 Sparse issues these warnings by default only when the C dialect 189 is C89 (i.e. -ansi or -std=c89). To turn them off, use 190 -Wno-declaration-after-statement. 191 192 -Wdefault-bitfield-sign 193 Warn about any bitfield with no explicit signedness. 194 195 Bitfields have no standard-specified default signedness. (C99 196 6.7.2) A bitfield without an explicit signed or unsigned creates 197 a portability problem for software that relies on the available 198 range of values. To fix this, specify the bitfield type as 199 signed or unsigned explicitly. 200 201 Sparse does not issue these warnings by default. 202 203 -Wdesignated-init 204 Warn about positional initialization of structs marked as 205 requiring designated initializers. 206 207 Sparse allows an attribute __attribute__((designated_init)) 208 which marks a struct as requiring designated initializers. 209 Sparse will warn about positional initialization of a struct 210 variable or struct literal of a type that has this attribute. 211 212 Requiring designated initializers for a particular struct type 213 will insulate code using that struct type from changes to the 214 layout of the type, avoiding the need to change initializers for 215 that type unless they initialize a removed or incompatibly 216 changed field. 217 218 Common examples of this type of struct include collections of 219 function pointers for the implementations of a class of related 220 operations, for which the default NULL for an unmentioned field 221 in a designated initializer will correctly indicate the absence 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 296 struct structname var = { field: value }; 297 298 Sparse will warn about the use of GCC's non-standard syntax for 299 designated initializers. To fix this warning, convert 300 designated initializers to use the standard C99 syntax. 301 302 Sparse issues these warnings by default. To turn them off, use 303 -Wno-old-initializer. 304 305 -Wone-bit-signed-bitfield 306 Warn about any one-bit signed bitfields. 307 308 A one-bit signed bitfield can only have the values 0 and -1, or 309 with some compilers only 0; this results in unexpected behavior 310 for programs which expected the ability to store 0 and 1. 311 312 Sparse issues these warnings by default. To turn them off, use 313 -Wno-one-bit-signed-bitfield. 314 315 -Wparen-string 316 Warn about the use of a parenthesized string to initialize an 317 array. 318 319 Standard C syntax does not permit a parenthesized string as an 320 array initializer. GCC allows this syntax as an extension. 321 With -Wparen-string, Sparse will warn about this syntax. 322 323 Sparse does not issue these warnings by default. 324 325 -Wpointer-arith 326 Warn about anything that depends on the sizeof a void or 327 function type. 328 329 C99 does not allow the sizeof operator to be applied to function 330 types or to incomplete types such as void. GCC allows sizeof to 331 be applied to these types as an extension and assigns these 332 types a size of 1. With -pointer-arith, Sparse will warn about 333 pointer arithmetic on void or function pointers, as well as 334 expressions which directly apply the sizeof operator to void or 335 function types. 336 337 Sparse does not issue these warnings by default. 338 339 -Wptr-subtraction-blows 340 Warn when subtracting two pointers to a type with a non-power- 341 of-two size. 342 343 Subtracting two pointers to a given type gives a difference in 344 terms of the number of items of that type. To generate this 345 value, compilers will usually need to divide the difference by 346 the size of the type, an potentially expensive operation for 347 sizes other than powers of two. 348 349 Code written using pointer subtraction can often use another 350 approach instead, such as array indexing with an explicit array 351 index variable, which may allow compilers to generate more 352 efficient code. 353 354 Sparse does not issue these warnings by default. 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)