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