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