1sparse(1) General Commands Manual sparse(1)
2
6 sparse - Semantic Parser for C
7
9 sparse [WARNING OPTIONS]... file.c
10
12 Sparse parses C source and looks for errors, producing warnings on
13 standard error.
14 Sparse accepts options controlling the set of warnings to generate. To
16 turn on warnings Sparse does not issue by default, use the correspond‐
17 ing warning option -Wsomething. Sparse issues some warnings by de‐
18 fault; to turn off those warnings, pass the negation of the associated
19 warning option, -Wno-something.
20
22 -fmax-errors=COUNT
23 Set the maximum number of displayed errors to COUNT, which
24 should be a numerical value or 'unlimited'. The default limit
25 is 100.
26 -fmax-warnings=COUNT
28 Set the maximum number of displayed warnings to COUNT, which
29 should be a numerical value or 'unlimited'. The default limit
30 is 100.
31 -Wsparse-all
33 Turn on all sparse warnings, except for those explicitly dis‐
34 abled via -Wno-something.
35 -Wsparse-error
37 Turn all sparse warnings into errors.
38 -Waddress-space
40 Warn about code which mixes pointers to different address spa‐
41 ces.
42 Sparse allows an extended attribute __attribute__((ad‐
44 dress_space(id))) on pointers, which designates a pointer target
45 in address space id (an identifier or a constant integer). With
46 -Waddress-space, Sparse treats pointers with identical target
47 types but different address spaces as distinct types and will
48 warn accordingly.
49 Sparse will also warn on casts which remove the address space
51 (casts to an integer type or to a plain pointer type). An excep‐
52 tion to this is when the destination type is uintptr_t (or un‐
53 signed long) since such casts are often used to "get a pointer
54 value representation in an integer type" and such values are in‐
55 dependent of the address space.
56 To override these warnings, use a type that includes __attri‐
58 bute__((force)).
59 Sparse issues these warnings by default. To turn them off, use
61 -Wno-address-space.
62 -Wbitwise
64 Warn about unsupported operations or type mismatches with re‐
65 stricted integer types.
66 Sparse supports an extended attribute, __attribute__((bitwise)),
68 which creates a new restricted integer type from a base integer
69 type, distinct from the base integer type and from any other re‐
70 stricted integer type not declared in the same declaration or
71 typedef. For example, this allows programs to create typedefs
72 for integer types with specific endianness. With -Wbitwise,
73 Sparse will warn on any use of a restricted type in arithmetic
74 operations other than bitwise operations, and on any conversion
75 of one restricted type into another, except via a cast that in‐
76 cludes __attribute__((force)).
77 __bitwise ends up being a "stronger integer separation", one
79 that doesn't allow you to mix with non-bitwise integers, so now
80 it's much harder to lose the type by mistake.
81 __bitwise is for *unique types* that cannot be mixed with other
83 types, and that you'd never want to just use as a random integer
84 (the integer 0 is special, though, and gets silently accepted
85 iirc - it's kind of like "NULL" for pointers). So "gfp_t" or the
86 "safe endianness" types would be __bitwise: you can only operate
87 on them by doing specific operations that know about *that* par‐
88 ticular type.
89 Sparse issues these warnings by default. To turn them off, use
91 -Wno-bitwise.
92 -Wbitwise-pointer
94 Same as -Wbitwise but for casts to or from pointers to bitwise
95 types.
96 Sparse does not issue these warnings by default.
98 -Wcast-from-as
100 Warn about casts which remove an address space from a pointer
101 type.
102 This is similar to -Waddress-space but will also warn on casts
104 to unsigned long.
105 Sparse does not issues these warnings by default.
107 -Wcast-to-as
109 Warn about casts which add an address space to a pointer type.
110 A cast that includes __attribute__((force)) will suppress this
112 warning. No warning is generated if the original type is
113 uintptr_t (or unsigned long).
114 Sparse does not issue these warnings by default.
116 -Wcast-truncate
118 Warn about casts that truncate constant values.
119 Sparse issues these warnings by default. To turn them off, use
121 -Wno-cast-truncate.
122 -Wconstant-suffix
124 Warn if an integer constant is larger than the maximum repre‐
125 sentable value of the type indicated by its type suffix (if
126 any). For example, on a system where ints are 32-bit and longs
127 64-bit, the constant 0x100000000U is larger than can be repre‐
128 sented by an unsigned int but fits in an unsigned long. So its
129 type is unsigned long but this is not indicated by its suffix.
130 In this case, the warning could be suppressed by using the suf‐
131 fix UL: 0x100000000UL.
132 Sparse does not issue these warnings by default.
134 -Wconstexpr-not-const
136 Warn if a non-constant expression is encountered when really ex‐
137 pecting a constant expression instead. Currently, this warns
138 when initializing an object of static storage duration with an
139 initializer which is not a constant expression.
140 Sparse does not issue these warnings by default.
142 -Wcontext
144 Warn about potential errors in synchronization or other delim‐
145 ited contexts.
146 Sparse supports several means of designating functions or state‐
148 ments that delimit contexts, such as synchronization. Functions
149 with the extended attribute __attribute__((context(expres‐
150 sion,in_context,out_context)) require the context expression
151 (for instance, a lock) to have the value in_context (a constant
152 nonnegative integer) when called, and return with the value
153 out_context (a constant nonnegative integer). For APIs defined
154 via macros, use the statement form __context__(expres‐
155 sion,in_value,out_value) in the body of the macro.
156 With -Wcontext Sparse will warn when it sees a function change
158 the context without indicating this with a context attribute,
159 either by decreasing a context below zero (such as by releasing
160 a lock without acquiring it), or returning with a changed con‐
161 text (such as by acquiring a lock without releasing it). Sparse
162 will also warn about blocks of code which may potentially exe‐
163 cute with different contexts.
164 Sparse issues these warnings by default. To turn them off, use
166 -Wno-context.
167 -Wdecl Warn about any non-static variable or function definition that
169 has no previous declaration.
170 Private symbols (functions and variables) internal to a given
172 source file should use static, to allow additional compiler op‐
173 timizations, allow detection of unused symbols, and prevent
174 other code from relying on these internal symbols. Public sym‐
175 bols used by other source files will need declarations visible
176 to those other source files, such as in a header file. All dec‐
177 larations should fall into one of these two categories. Thus,
178 with -Wdecl, Sparse warns about any symbol definition with nei‐
179 ther static nor a declaration. To fix this warning, declare
180 private symbols static, and ensure that the files defining pub‐
181 lic symbols have the symbol declarations available first (such
182 as by including the appropriate header file).
183 Sparse issues these warnings by default. To turn them off, use
185 -Wno-decl.
186 -Wdeclaration-after-statement
188 Warn about declarations that are not at the start of a block.
189 These declarations are permitted in C99 but not in C89.
191 Sparse issues these warnings by default only when the C dialect
193 is C89 (i.e. -ansi or -std=c89). To turn them off, use
194 -Wno-declaration-after-statement.
195 -Wdefault-bitfield-sign
197 Warn about any bitfield with no explicit signedness.
198 Bitfields have no standard-specified default signedness. (C99
200 6.7.2) A bitfield without an explicit signed or unsigned creates
201 a portability problem for software that relies on the available
202 range of values. To fix this, specify the bitfield type as
203 signed or unsigned explicitly.
204 Sparse does not issue these warnings by default.
206 -Wdesignated-init
208 Warn about positional initialization of structs marked as re‐
209 quiring designated initializers.
210 Sparse allows an attribute __attribute__((designated_init))
212 which marks a struct as requiring designated initializers.
213 Sparse will warn about positional initialization of a struct
214 variable or struct literal of a type that has this attribute.
215 Requiring designated initializers for a particular struct type
217 will insulate code using that struct type from changes to the
218 layout of the type, avoiding the need to change initializers for
219 that type unless they initialize a removed or incompatibly
220 changed field.
221 Common examples of this type of struct include collections of
223 function pointers for the implementations of a class of related
224 operations, for which the default NULL for an unmentioned field
225 in a designated initializer will correctly indicate the absence
226 of that operation.
227 Sparse issues these warnings by default. To turn them off, use
229 -Wno-designated-init.
230 -Wdo-while
232 Warn about do-while loops that do not delimit the loop body with
233 braces.
234 Sparse does not issue these warnings by default.
236 -Wenum-mismatch
238 Warn about the use of an expression of an incorrect enum type
239 when initializing another enum type, assigning to another enum
240 type, or passing an argument to a function which expects another
241 enum type.
242 Sparse issues these warnings by default. To turn them off, use
244 -Wno-enum-mismatch.
245 -Wexternal-function-has-definition
247 Warn about function definitions that are declared with external
248 linkage.
249 Sparse issues these warnings by default. To turn them off, use
251 -Wno-external-function-has-definition.
252 -Wflexible-array-array
254 Warn about arrays of structures containing a flexible array.
255 Sparse issues these warnings by default. To turn them off, use
257 -Wno-flexible-array-array.
258 -Wflexible-array-nested
260 Warn about structures containing a flexible array being con‐
261 tained into another structure, union or array.
262 Sparse does not issue these warnings by default.
264 -Wflexible-array-sizeof
266 Warn about using the sizeof operator on a structure containing a
267 flexible array, possibly recursively.
268 Sparse does not issue these warnings by default.
270 -Wflexible-array-union
272 Enable the warnings regarding flexible arrays and unions. To
273 have any effect, at least one of -Wflexible-array-array, -Wflex‐
274 ible-array-nested or -Wflexible-array-sizeof must also be en‐
275 abled.
276 Sparse does issue these warnings by default.
278 -Winit-cstring
280 Warn about initialization of a char array with a too long con‐
281 stant C string.
282 If the size of the char array and the length of the string are
284 the same, there is no space for the last nul char of the string
285 in the array:
286 char s[3] = "abc";
288 If the array is used as a byte array, not as C string, this
290 warning is just noise. However, if the array is passed to func‐
291 tions dealing with C string like printf(%s) and strcmp, it may
292 cause a trouble.
293 Sparse does not issue these warnings by default.
295 -Wmemcpy-max-count
297 Warn about call of memcpy(), memset(), copy_from_user(), or
298 copy_to_user() with a large compile-time byte count.
299 Sparse issues these warnings by default. To turn them off, use
301 -Wno-memcpy-max-count.
302 The limit can be changed with -fmemcpy-max-count=COUNT, the de‐
304 fault being 100000.
305 -Wnewline-eof
307 Warn if the input file doesn't end with a newline.
308 Sparse issues these warnings by default. To turn them off, use
310 -Wno-newline-eof.
311 -Wnon-pointer-null
313 Warn about the use of 0 as a NULL pointer.
314 0 has integer type. NULL has pointer type.
316 Sparse issues these warnings by default. To turn them off, use
318 -Wno-non-pointer-null.
319 -Wold-initializer
321 Warn about the use of the pre-C99 GCC syntax for designated ini‐
322 tializers.
323 C99 provides a standard syntax for designated fields in struct
325 or union initializers:
326 struct structname var = { .field = value };
328 GCC also has an old, non-standard syntax for designated initial‐
330 izers which predates C99:
331 struct structname var = { field: value };
333 Sparse will warn about the use of GCC's non-standard syntax for
335 designated initializers. To fix this warning, convert desig‐
336 nated initializers to use the standard C99 syntax.
337 Sparse issues these warnings by default. To turn them off, use
339 -Wno-old-initializer.
340 -Wone-bit-signed-bitfield
342 Warn about any one-bit signed bitfields.
343 A one-bit signed bitfield can only have the values 0 and -1, or
345 with some compilers only 0; this results in unexpected behavior
346 for programs which expected the ability to store 0 and 1.
347 Sparse issues these warnings by default. To turn them off, use
349 -Wno-one-bit-signed-bitfield.
350 -Wparen-string
352 Warn about the use of a parenthesized string to initialize an
353 array.
354 Standard C syntax does not permit a parenthesized string as an
356 array initializer. GCC allows this syntax as an extension.
357 With -Wparen-string, Sparse will warn about this syntax.
358 Sparse does not issue these warnings by default.
360 -Wpast-deep-designator
362 Warn when, in a initializer-list, a initializer with a deep
363 (nested) designator is followed by a non-designated one.
364 Sparse does not issue these warnings by default.
366 -Wpointer-arith
368 Warn about anything that depends on the sizeof a void or func‐
369 tion type.
370 C99 does not allow the sizeof operator to be applied to function
372 types or to incomplete types such as void. GCC allows sizeof to
373 be applied to these types as an extension and assigns these
374 types a size of 1. With -pointer-arith, Sparse will warn about
375 pointer arithmetic on void or function pointers, as well as ex‐
376 pressions which directly apply the sizeof operator to void or
377 function types.
378 Sparse does not issue these warnings by default.
380 -Wptr-subtraction-blows
382 Warn when subtracting two pointers to a type with a non-power-
383 of-two size.
384 Subtracting two pointers to a given type gives a difference in
386 terms of the number of items of that type. To generate this
387 value, compilers will usually need to divide the difference by
388 the size of the type, an potentially expensive operation for
389 sizes other than powers of two.
390 Code written using pointer subtraction can often use another ap‐
392 proach instead, such as array indexing with an explicit array
393 index variable, which may allow compilers to generate more effi‐
394 cient code.
395 Sparse does not issue these warnings by default.
397 -Wreturn-void
399 Warn if a function with return type void returns a void expres‐
400 sion.
401 C99 permits this, and in some cases this allows for more generic
403 code in macros that use typeof or take a type as a macro argu‐
404 ment. However, some programs consider this poor style, and
405 those programs can use -Wreturn-void to get warnings about it.
406 Sparse does not issue these warnings by default.
408 -Wshadow
410 Warn when declaring a symbol which shadows a declaration with
411 the same name in an outer scope.
412 Such declarations can lead to error-prone code.
414 Sparse does not issue these warnings by default.
416 -Wshift-count-negative
418 Warn if a shift count is negative.
419 Sparse issues these warnings by default.
421 -Wshift-count-overflow
423 Warn if a shift count is bigger than the operand's width.
424 Sparse issues these warnings by default.
426 -Wsizeof-bool
428 Warn when checking the sizeof a _Bool.
429 C99 does not specify the size of a _Bool. GCC, by default, uses
431 1.
432 Sparse does not issue these warnings by default.
434 -Wtransparent-union
436 Warn about any declaration using the GCC extension __attri‐
437 bute__((transparent_union)).
438 Sparse issues these warnings by default. To turn them off, use
440 -Wno-transparent-union.
441 -Wtypesign
443 Warn when converting a pointer to an integer type into a pointer
444 to an integer type with different signedness.
445 Sparse does not issue these warnings by default.
447 -Wundef
449 Warn about preprocessor conditionals that use the value of an
450 undefined preprocessor symbol.
451 Standard C (C99 6.10.1) permits using the value of an undefined
453 preprocessor symbol in preprocessor conditionals, and specifies
454 it has a value of 0. However, this behavior can lead to subtle
455 errors.
456 Sparse does not issue these warnings by default.
458 -Wuniversal-initializer
460 Do not suppress warnings caused by using '{ 0 }' instead of
461 '{ }' on aggregate types, ignoring its special status as univer‐
462 sal initializer. The concerned warnings are, for example, those
463 triggered by -Wdesignated-init or -Wnon-pointer-null.
464 Sparse does not issue these warnings by default, processing
466 '{ 0 }' the same as '{ }'.
467 -Wunion-cast
469 Warn on casts to union types.
470 Sparse does not issues these warnings by default.
472
474 --arch=ARCH
475 Specify the target architecture. For architectures having both
476 a 32-bit and a 64-bit variant (mips, powerpc, riscv and sparc)
477 the architecture name can be suffixed with 32 or 64.
478 The default architecture and size is the one of the machine used
480 to build Sparse.
481 -gcc-base-dir dir
483 Look for compiler-provided system headers in dir/include/ and
484 dir/include-fixed/.
485 -multiarch-dir dir
487 Look for system headers in the multiarch subdirectory dir. The
488 dir name would normally take the form of the target's normalized
489 GNU triplet. (e.g. i386-linux-gnu).
490 --os=OS
492 Specify the target Operating System. This only makes a few dif‐
493 ferences with the predefined types. The accepted values are:
494 linux, unix, freebsd, netbsd, opensd, sunos, darwin and cygwin.
495 The default OS is the one of the machine used to build Sparse if
497 it can be detected, otherwise some generic settings are used.
498
500 -fmem-report
501 Report some statistics about memory allocation used by the tool.
502
504 -fdiagnostic-prefix[=PREFIX]
505 Prefix all diagnostics by the given PREFIX, followed by ": ".
506 If no one is given "sparse" is used. The default is to not use
507 a prefix at all.
508 -fmemcpy-max-count=COUNT
510 Set the limit for the warnings given by -Wmemcpy-max-count. A
511 COUNT of 'unlimited' or '0' will effectively disable the warn‐
512 ing. The default limit is 100000.
513 -ftabstop=WIDTH
515 Set the distance between tab stops. This helps sparse report
516 correct column numbers in warnings or errors. If the value is
517 less than 1 or greater than 100, the option is ignored. The de‐
518 fault is 8.
519 -f[no-]unsigned-bitfields, -f[no-]signed-bitfields
521 Determine the signedness of bitfields declared without an ex‐
522 plicit sign ('signed' or 'unsigned'). By default such bitfields
523 are signed, like others plain integers.
524 -f[no-]unsigned-char, -f[no-]signed-char
526 Let plain 'char' be unsigned or signed. By default chars are
527 signed.
528
530 cgcc(1)
531
533 https://sparse.docs.kernel.org
534
536 linux-sparse@vger.kernel.org
537
539 Submission of patches and reporting of bugs, as well as discussions re‐
540 lated to Sparse, should be done via the mailing list (linux-
541 sparse@vger.kernel.org) where the development and maintenance is pri‐
542 marily done. You do not have to be subscribed to the list to send a
543 message there.
544 Bugs can also be reported and tracked via the Linux kernel's bugzilla:
546 http://bugzilla.kernel.org/enter_bug.cgi?component=Sparse&product=Tools
547 .
548
550 More documentation about Sparse can be found at
551 https://sparse.docs.kernel.org
552
554 Sparse was started by Linus Torvalds. The complete list of contribu‐
555 tors can be find at https://www.openhub.net/p/sparse/contributors .
556 Luc Van Oostenryck is Sparse's current maintainer.
558 sparse(1)