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