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
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
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
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>
|
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
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
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
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.
|