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