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
18 default; to turn off those warnings, pass the negation of the associ‐
19 ated warning option, -Wno-something.
20
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 -Wsparse-all
28 Turn on all sparse warnings, except for those explicitly dis‐
29 abled via -Wno-something.
30 -Wsparse-error
32 Turn all sparse warnings into errors.
33 -Waddress-space
35 Warn about code which mixes pointers to different address spa‐
36 ces.
37 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 con‐
41 stant integer). With -Waddress-space, Sparse treats pointers
42 with identical target types but different address spaces as dis‐
43 tinct types and will warn accordingly.
44 Sparse will also warn on casts which remove the address space
46 (casts to an integer type or to a plain pointer type). An excep‐
47 tion 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 To override these warnings, use a type that includes
53 __attribute__((force)).
54 Sparse issues these warnings by default. To turn them off, use
56 -Wno-address-space.
57 -Wbitwise
59 Warn about unsupported operations or type mismatches with
60 restricted integer types.
61 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 __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 __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* par‐
83 ticular type.
84 Sparse issues these warnings by default. To turn them off, use
86 -Wno-bitwise.
87 -Wbitwise-pointer
89 Same as -Wbitwise but for casts to or from pointers to bitwise
90 types.
91 Sparse does not issue these warnings by default.
93 -Wcast-from-as
95 Warn about casts which remove an address space from a pointer
96 type.
97 This is similar to -Waddress-space but will also warn on casts
99 to unsigned long.
100 Sparse does not issues these warnings by default.
102 -Wcast-to-as
104 Warn about casts which add an address space to a pointer type.
105 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 Sparse does not issue these warnings by default.
111 -Wcast-truncate
113 Warn about casts that truncate constant values.
114 Sparse issues these warnings by default. To turn them off, use
116 -Wno-cast-truncate.
117 -Wconstant-suffix
119 Warn if an integer constant is larger than the maximum repre‐
120 sentable 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 repre‐
123 sented by an unsigned int but fits in an unsigned long. So its
124 type is unsigned long but this is not indicated by its suffix.
125 In this case, the warning could be suppressed by using the suf‐
126 fix UL: 0x100000000UL.
127 Sparse does not issue these warnings by default.
129 -Wconstexpr-not-const
131 Warn if a non-constant expression is encountered when really
132 expecting a constant expression instead. Currently, this warns
133 when initializing an object of static storage duration with an
134 initializer which is not a constant expression.
135 Sparse does not issue these warnings by default.
137 -Wcontext
139 Warn about potential errors in synchronization or other delim‐
140 ited contexts.
141 Sparse supports several means of designating functions or state‐
143 ments that delimit contexts, such as synchronization. Functions
144 with the extended attribute __attribute__((context(expres‐
145 sion,in_context,out_context)) require the context expression
146 (for instance, a lock) to have the value in_context (a constant
147 nonnegative integer) when called, and return with the value
148 out_context (a constant nonnegative integer). For APIs defined
149 via macros, use the statement form __context__(expres‐
150 sion,in_value,out_value) in the body of the macro.
151 With -Wcontext Sparse will warn when it sees a function change
153 the context without indicating this with a context attribute,
154 either by decreasing a context below zero (such as by releasing
155 a lock without acquiring it), or returning with a changed con‐
156 text (such as by acquiring a lock without releasing it). Sparse
157 will also warn about blocks of code which may potentially exe‐
158 cute with different contexts.
159 Sparse issues these warnings by default. To turn them off, use
161 -Wno-context.
162 -Wdecl Warn about any non-static variable or function definition that
164 has no previous declaration.
165 Private symbols (functions and variables) internal to a given
167 source file should use static, to allow additional compiler
168 optimizations, allow detection of unused symbols, and prevent
169 other code from relying on these internal symbols. Public sym‐
170 bols used by other source files will need declarations visible
171 to those other source files, such as in a header file. All dec‐
172 larations should fall into one of these two categories. Thus,
173 with -Wdecl, Sparse warns about any symbol definition with nei‐
174 ther static nor a declaration. To fix this warning, declare
175 private symbols static, and ensure that the files defining pub‐
176 lic symbols have the symbol declarations available first (such
177 as by including the appropriate header file).
178 Sparse issues these warnings by default. To turn them off, use
180 -Wno-decl.
181 -Wdeclaration-after-statement
183 Warn about declarations that are not at the start of a block.
184 These declarations are permitted in C99 but not in C89.
186 Sparse issues these warnings by default only when the C dialect
188 is C89 (i.e. -ansi or -std=c89). To turn them off, use
189 -Wno-declaration-after-statement.
190 -Wdefault-bitfield-sign
192 Warn about any bitfield with no explicit signedness.
193 Bitfields have no standard-specified default signedness. (C99
195 6.7.2) A bitfield without an explicit signed or unsigned creates
196 a portability problem for software that relies on the available
197 range of values. To fix this, specify the bitfield type as
198 signed or unsigned explicitly.
199 Sparse does not issue these warnings by default.
201 -Wdesignated-init
203 Warn about positional initialization of structs marked as
204 requiring designated initializers.
205 Sparse allows an attribute __attribute__((designated_init))
207 which marks a struct as requiring designated initializers.
208 Sparse will warn about positional initialization of a struct
209 variable or struct literal of a type that has this attribute.
210 Requiring designated initializers for a particular struct type
212 will insulate code using that struct type from changes to the
213 layout of the type, avoiding the need to change initializers for
214 that type unless they initialize a removed or incompatibly
215 changed field.
216 Common examples of this type of struct include collections of
218 function pointers for the implementations of a class of related
219 operations, for which the default NULL for an unmentioned field
220 in a designated initializer will correctly indicate the absence
221 of that operation.
222 Sparse issues these warnings by default. To turn them off, use
224 -Wno-designated-init.
225 -Wdo-while
227 Warn about do-while loops that do not delimit the loop body with
228 braces.
229 Sparse does not issue these warnings by default.
231 -Wenum-mismatch
233 Warn about the use of an expression of an incorrect enum type
234 when initializing another enum type, assigning to another enum
235 type, or passing an argument to a function which expects another
236 enum type.
237 Sparse issues these warnings by default. To turn them off, use
239 -Wno-enum-mismatch.
240 -Winit-cstring
242 Warn about initialization of a char array with a too long con‐
243 stant C string.
244 If the size of the char array and the length of the string are
246 the same, there is no space for the last nul char of the string
247 in the array:
248 char s[3] = "abc";
250 If the array is used as a byte array, not as C string, this
252 warning is just noise. However, if the array is passed to func‐
253 tions dealing with C string like printf(%s) and strcmp, it may
254 cause a trouble.
255 Sparse does not issue these warnings by default.
257 -Wmemcpy-max-count
259 Warn about call of memcpy(), memset(), copy_from_user(), or
260 copy_to_user() with a large compile-time byte count.
261 Sparse issues these warnings by default. To turn them off, use
263 -Wno-memcpy-max-count.
264 The limit can be changed with -fmemcpy-max-count=COUNT, the
266 default being 100000.
267 -Wnon-pointer-null
269 Warn about the use of 0 as a NULL pointer.
270 0 has integer type. NULL has pointer type.
272 Sparse issues these warnings by default. To turn them off, use
274 -Wno-non-pointer-null.
275 -Wold-initializer
277 Warn about the use of the pre-C99 GCC syntax for designated ini‐
278 tializers.
279 C99 provides a standard syntax for designated fields in struct
281 or union initializers:
282 struct structname var = { .field = value };
284 GCC also has an old, non-standard syntax for designated initial‐
286 izers which predates C99:
287 struct structname var = { field: value };
289 Sparse will warn about the use of GCC's non-standard syntax for
291 designated initializers. To fix this warning, convert desig‐
292 nated initializers to use the standard C99 syntax.
293 Sparse issues these warnings by default. To turn them off, use
295 -Wno-old-initializer.
296 -Wone-bit-signed-bitfield
298 Warn about any one-bit signed bitfields.
299 A one-bit signed bitfield can only have the values 0 and -1, or
301 with some compilers only 0; this results in unexpected behavior
302 for programs which expected the ability to store 0 and 1.
303 Sparse issues these warnings by default. To turn them off, use
305 -Wno-one-bit-signed-bitfield.
306 -Wparen-string
308 Warn about the use of a parenthesized string to initialize an
309 array.
310 Standard C syntax does not permit a parenthesized string as an
312 array initializer. GCC allows this syntax as an extension.
313 With -Wparen-string, Sparse will warn about this syntax.
314 Sparse does not issue these warnings by default.
316 -Wpointer-arith
318 Warn about anything that depends on the sizeof a void or func‐
319 tion type.
320 C99 does not allow the sizeof operator to be applied to function
322 types or to incomplete types such as void. GCC allows sizeof to
323 be applied to these types as an extension and assigns these
324 types a size of 1. With -pointer-arith, Sparse will warn about
325 pointer arithmetic on void or function pointers, as well as
326 expressions which directly apply the sizeof operator to void or
327 function types.
328 Sparse does not issue these warnings by default.
330 -Wptr-subtraction-blows
332 Warn when subtracting two pointers to a type with a non-power-
333 of-two size.
334 Subtracting two pointers to a given type gives a difference in
336 terms of the number of items of that type. To generate this
337 value, compilers will usually need to divide the difference by
338 the size of the type, an potentially expensive operation for
339 sizes other than powers of two.
340 Code written using pointer subtraction can often use another
342 approach instead, such as array indexing with an explicit array
343 index variable, which may allow compilers to generate more effi‐
344 cient code.
345 Sparse does not issue these warnings by default.
347 -Wreturn-void
349 Warn if a function with return type void returns a void expres‐
350 sion.
351 C99 permits this, and in some cases this allows for more generic
353 code in macros that use typeof or take a type as a macro argu‐
354 ment. However, some programs consider this poor style, and
355 those programs can use -Wreturn-void to get warnings about it.
356 Sparse does not issue these warnings by default.
358 -Wshadow
360 Warn when declaring a symbol which shadows a declaration with
361 the same name in an outer scope.
362 Such declarations can lead to error-prone code.
364 Sparse does not issue these warnings by default.
366 -Wshift-count-negative
368 Warn if a shift count is negative.
369 Sparse issues these warnings by default.
371 -Wshift-count-overflow
373 Warn if a shift count is bigger than the operand's width.
374 Sparse issues these warnings by default.
376 -Wsizeof-bool
378 Warn when checking the sizeof a _Bool.
379 C99 does not specify the size of a _Bool. GCC, by default, uses
381 1.
382 Sparse does not issue these warnings by default.
384 -Wtransparent-union
386 Warn about any declaration using the GCC extension
387 __attribute__((transparent_union)).
388 Sparse issues these warnings by default. To turn them off, use
390 -Wno-transparent-union.
391 -Wtypesign
393 Warn when converting a pointer to an integer type into a pointer
394 to an integer type with different signedness.
395 Sparse does not issue these warnings by default.
397 -Wundef
399 Warn about preprocessor conditionals that use the value of an
400 undefined preprocessor symbol.
401 Standard C (C99 6.10.1) permits using the value of an undefined
403 preprocessor symbol in preprocessor conditionals, and specifies
404 it has a value of 0. However, this behavior can lead to subtle
405 errors.
406 Sparse does not issue these warnings by default.
408
410 -gcc-base-dir dir
411 Look for compiler-provided system headers in dir/include/ and
412 dir/include-fixed/.
413 -multiarch-dir dir
415 Look for system headers in the multiarch subdirectory dir. The
416 dir name would normally take the form of the target's normalized
417 GNU triplet. (e.g. i386-linux-gnu).
418
420 -fmem-report
421 Report some statistics about memory allocation used by the tool.
422
424 -fdiagnostic-prefix[=PREFIX]
425 Prefix all diagnostics by the given PREFIX, followed by ": ".
426 If no one is given "sparse" is used. The default is to not use
427 a prefix at all.
428 -fmemcpy-max-count=COUNT
430 Set the limit for the warnings given by -Wmemcpy-max-count. A
431 COUNT of 'unlimited' or '0' will effectively disable the warn‐
432 ing. The default limit is 100000.
433 -ftabstop=WIDTH
435 Set the distance between tab stops. This helps sparse report
436 correct column numbers in warnings or errors. If the value is
437 less than 1 or greater than 100, the option is ignored. The
438 default is 8.
439 -f[no-]unsigned-char, -f[no-]signed-char
441 Let plain 'char' be unsigned or signed. By default chars are
442 signed.
443
445 cgcc(1)
446
448 http://www.kernel.org/pub/software/devel/sparse/
449
451 linux-sparse@vger.kernel.org
452
454 Submission of patches and reporting of bugs, as well as discussions
455 related to Sparse, should be done via the mailing list (linux-
456 sparse@vger.kernel.org) where the development and maintenance is pri‐
457 marily done. You do not have to be subscribed to the list to send a
458 message there.
459 Bugs can also be reported and tracked via the Linux kernel's bugzilla:
461 http://bugzilla.kernel.org/enter_bug.cgi?component=Sparse&product=Tools
462 .
463
465 Sparse was started by Linus Torvalds. The complete list of contribu‐
466 tors can be find at https://www.openhub.net/p/sparse/contributors .
467 Luc Van Oostenryck is Sparse's current maintainer.
469 sparse(1)