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. To override this warning, such as for functions
44 which convert pointers between address spaces, use a type that
45 includes __attribute__((force)).
46 Sparse issues these warnings by default. To turn them off, use
48 -Wno-address-space.
49 -Wbitwise
51 Warn about unsupported operations or type mismatches with
52 restricted integer types.
53 Sparse supports an extended attribute, __attribute__((bitwise)),
55 which creates a new restricted integer type from a base integer
56 type, distinct from the base integer type and from any other
57 restricted integer type not declared in the same declaration or
58 typedef. For example, this allows programs to create typedefs
59 for integer types with specific endianness. With -Wbitwise,
60 Sparse will warn on any use of a restricted type in arithmetic
61 operations other than bitwise operations, and on any conversion
62 of one restricted type into another, except via a cast that
63 includes __attribute__((force)).
64 __bitwise ends up being a "stronger integer separation", one
66 that doesn't allow you to mix with non-bitwise integers, so now
67 it's much harder to lose the type by mistake.
68 __bitwise is for *unique types* that cannot be mixed with other
70 types, and that you'd never want to just use as a random integer
71 (the integer 0 is special, though, and gets silently accepted
72 iirc - it's kind of like "NULL" for pointers). So "gfp_t" or the
73 "safe endianness" types would be __bitwise: you can only operate
74 on them by doing specific operations that know about *that* par‐
75 ticular type.
76 Sparse issues these warnings by default. To turn them off, use
78 -Wno-bitwise.
79 -Wbitwise-pointer
81 Same as -Wbitwise but for casts to or from pointers to bitwise
82 types.
83 Sparse does not issue these warnings by default.
85 -Wcast-from-as
87 Warn about which remove an address space to a pointer type.
88 This is similar to -Waddress-space but will also warn on casts
90 to unsigned long.
91 Sparse does not issues these warnings by default.
93 -Wcast-to-as
95 Warn about casts which add an address space to a pointer type.
96 A cast that includes __attribute__((force)) will suppress this
98 warning.
99 Sparse does not issue these warnings by default.
101 -Wcast-truncate
103 Warn about casts that truncate constant values.
104 Sparse issues these warnings by default. To turn them off, use
106 -Wno-cast-truncate.
107 -Wconstant-suffix
109 Warn if an integer constant is larger than the maximum repre‐
110 sentable value of the type indicated by its type suffix (if
111 any). For example, on a system where ints are 32-bit and longs
112 64-bit, the constant 0x100000000U is larger than can be repre‐
113 sented by an unsigned int but fits in an unsigned long. So its
114 type is unsigned long but this is not indicated by its suffix.
115 In this case, the warning could be suppressed by using the suf‐
116 fix UL: 0x100000000UL.
117 Sparse does not issue these warnings by default.
119 -Wconstexpr-not-const
121 Warn if a non-constant expression is encountered when really
122 expecting a constant expression instead. Currently, this warns
123 when initializing an object of static storage duration with an
124 initializer which is not a constant expression.
125 Sparse does not issue these warnings by default.
127 -Wcontext
129 Warn about potential errors in synchronization or other delim‐
130 ited contexts.
131 Sparse supports several means of designating functions or state‐
133 ments that delimit contexts, such as synchronization. Functions
134 with the extended attribute __attribute__((context(expres‐
135 sion,in_context,out_context)) require the context expression
136 (for instance, a lock) to have the value in_context (a constant
137 nonnegative integer) when called, and return with the value
138 out_context (a constant nonnegative integer). For APIs defined
139 via macros, use the statement form __context__(expres‐
140 sion,in_value,out_value) in the body of the macro.
141 With -Wcontext Sparse will warn when it sees a function change
143 the context without indicating this with a context attribute,
144 either by decreasing a context below zero (such as by releasing
145 a lock without acquiring it), or returning with a changed con‐
146 text (such as by acquiring a lock without releasing it). Sparse
147 will also warn about blocks of code which may potentially exe‐
148 cute with different contexts.
149 Sparse issues these warnings by default. To turn them off, use
151 -Wno-context.
152 -Wdecl Warn about any non-static variable or function definition that
154 has no previous declaration.
155 Private symbols (functions and variables) internal to a given
157 source file should use static, to allow additional compiler
158 optimizations, allow detection of unused symbols, and prevent
159 other code from relying on these internal symbols. Public sym‐
160 bols used by other source files will need declarations visible
161 to those other source files, such as in a header file. All dec‐
162 larations should fall into one of these two categories. Thus,
163 with -Wdecl, Sparse warns about any symbol definition with nei‐
164 ther static nor a declaration. To fix this warning, declare
165 private symbols static, and ensure that the files defining pub‐
166 lic symbols have the symbol declarations available first (such
167 as by including the appropriate header file).
168 Sparse issues these warnings by default. To turn them off, use
170 -Wno-decl.
171 -Wdeclaration-after-statement
173 Warn about declarations that are not at the start of a block.
174 These declarations are permitted in C99 but not in C89.
176 Sparse issues these warnings by default only when the C dialect
178 is C89 (i.e. -ansi or -std=c89). To turn them off, use
179 -Wno-declaration-after-statement.
180 -Wdefault-bitfield-sign
182 Warn about any bitfield with no explicit signedness.
183 Bitfields have no standard-specified default signedness. (C99
185 6.7.2) A bitfield without an explicit signed or unsigned creates
186 a portability problem for software that relies on the available
187 range of values. To fix this, specify the bitfield type as
188 signed or unsigned explicitly.
189 Sparse does not issue these warnings by default.
191 -Wdesignated-init
193 Warn about positional initialization of structs marked as
194 requiring designated initializers.
195 Sparse allows an attribute __attribute__((designated_init))
197 which marks a struct as requiring designated initializers.
198 Sparse will warn about positional initialization of a struct
199 variable or struct literal of a type that has this attribute.
200 Requiring designated initializers for a particular struct type
202 will insulate code using that struct type from changes to the
203 layout of the type, avoiding the need to change initializers for
204 that type unless they initialize a removed or incompatibly
205 changed field.
206 Common examples of this type of struct include collections of
208 function pointers for the implementations of a class of related
209 operations, for which the default NULL for an unmentioned field
210 in a designated initializer will correctly indicate the absence
211 of that operation.
212 Sparse issues these warnings by default. To turn them off, use
214 -Wno-designated-init.
215 -Wdo-while
217 Warn about do-while loops that do not delimit the loop body with
218 braces.
219 Sparse does not issue these warnings by default.
221 -Wenum-mismatch
223 Warn about the use of an expression of an incorrect enum type
224 when initializing another enum type, assigning to another enum
225 type, or passing an argument to a function which expects another
226 enum type.
227 Sparse issues these warnings by default. To turn them off, use
229 -Wno-enum-mismatch.
230 -Winit-cstring
232 Warn about initialization of a char array with a too long con‐
233 stant C string.
234 If the size of the char array and the length of the string are
236 the same, there is no space for the last nul char of the string
237 in the array:
238 char s[3] = "abc";
240 If the array is used as a byte array, not as C string, this
242 warning is just noise. However, if the array is passed to func‐
243 tions dealing with C string like printf(%s) and strcmp, it may
244 cause a trouble.
245 Sparse does not issue these warnings by default.
247 -Wmemcpy-max-count
249 Warn about call of memcpy(), memset(), copy_from_user(), or
250 copy_to_user() with a large compile-time byte count.
251 Sparse issues these warnings by default. To turn them off, use
253 -Wno-memcpy-max-count.
254 The limit can be changed with -fmemcpy-max-count=COUNT, the
256 default being 100000.
257 -Wnon-pointer-null
259 Warn about the use of 0 as a NULL pointer.
260 0 has integer type. NULL has pointer type.
262 Sparse issues these warnings by default. To turn them off, use
264 -Wno-non-pointer-null.
265 -Wold-initializer
267 Warn about the use of the pre-C99 GCC syntax for designated ini‐
268 tializers.
269 C99 provides a standard syntax for designated fields in struct
271 or union initializers:
272 struct structname var = { .field = value };
274 GCC also has an old, non-standard syntax for designated initial‐
276 izers which predates C99:
277 struct structname var = { field: value };
279 Sparse will warn about the use of GCC's non-standard syntax for
281 designated initializers. To fix this warning, convert desig‐
282 nated initializers to use the standard C99 syntax.
283 Sparse issues these warnings by default. To turn them off, use
285 -Wno-old-initializer.
286 -Wone-bit-signed-bitfield
288 Warn about any one-bit signed bitfields.
289 A one-bit signed bitfield can only have the values 0 and -1, or
291 with some compilers only 0; this results in unexpected behavior
292 for programs which expected the ability to store 0 and 1.
293 Sparse issues these warnings by default. To turn them off, use
295 -Wno-one-bit-signed-bitfield.
296 -Wparen-string
298 Warn about the use of a parenthesized string to initialize an
299 array.
300 Standard C syntax does not permit a parenthesized string as an
302 array initializer. GCC allows this syntax as an extension.
303 With -Wparen-string, Sparse will warn about this syntax.
304 Sparse does not issue these warnings by default.
306 -Wpointer-arith
308 Warn about anything that depends on the sizeof a void or func‐
309 tion type.
310 C99 does not allow the sizeof operator to be applied to function
312 types or to incomplete types such as void. GCC allows sizeof to
313 be applied to these types as an extension and assigns these
314 types a size of 1. With -pointer-arith, Sparse will warn about
315 pointer arithmetic on void or function pointers, as well as
316 expressions which directly apply the sizeof operator to void or
317 function types.
318 Sparse does not issue these warnings by default.
320 -Wptr-subtraction-blows
322 Warn when subtracting two pointers to a type with a non-power-
323 of-two size.
324 Subtracting two pointers to a given type gives a difference in
326 terms of the number of items of that type. To generate this
327 value, compilers will usually need to divide the difference by
328 the size of the type, an potentially expensive operation for
329 sizes other than powers of two.
330 Code written using pointer subtraction can often use another
332 approach instead, such as array indexing with an explicit array
333 index variable, which may allow compilers to generate more effi‐
334 cient code.
335 Sparse does not issue these warnings by default.
337 -Wreturn-void
339 Warn if a function with return type void returns a void expres‐
340 sion.
341 C99 permits this, and in some cases this allows for more generic
343 code in macros that use typeof or take a type as a macro argu‐
344 ment. However, some programs consider this poor style, and
345 those programs can use -Wreturn-void to get warnings about it.
346 Sparse does not issue these warnings by default.
348 -Wshadow
350 Warn when declaring a symbol which shadows a declaration with
351 the same name in an outer scope.
352 Such declarations can lead to error-prone code.
354 Sparse does not issue these warnings by default.
356 -Wshift-count-negative
358 Warn if a shift count is negative.
359 Sparse issues these warnings by default.
361 -Wshift-count-overflow
363 Warn if a shift count is bigger than the operand's width.
364 Sparse issues these warnings by default.
366 -Wsizeof-bool
368 Warn when checking the sizeof a _Bool.
369 C99 does not specify the size of a _Bool. GCC, by default, uses
371 1.
372 Sparse does not issue these warnings by default.
374 -Wtransparent-union
376 Warn about any declaration using the GCC extension
377 __attribute__((transparent_union)).
378 Sparse issues these warnings by default. To turn them off, use
380 -Wno-transparent-union.
381 -Wtypesign
383 Warn when converting a pointer to an integer type into a pointer
384 to an integer type with different signedness.
385 Sparse does not issue these warnings by default.
387 -Wundef
389 Warn about preprocessor conditionals that use the value of an
390 undefined preprocessor symbol.
391 Standard C (C99 6.10.1) permits using the value of an undefined
393 preprocessor symbol in preprocessor conditionals, and specifies
394 it has a value of 0. However, this behavior can lead to subtle
395 errors.
396 Sparse does not issue these warnings by default.
398
400 -gcc-base-dir dir
401 Look for compiler-provided system headers in dir/include/ and
402 dir/include-fixed/.
403 -multiarch-dir dir
405 Look for system headers in the multiarch subdirectory dir. The
406 dir name would normally take the form of the target's normalized
407 GNU triplet. (e.g. i386-linux-gnu).
408
410 -fmem-report
411 Report some statistics about memory allocation used by the tool.
412
414 -fdiagnostic-prefix[=PREFIX]
415 Prefix all diagnostics by the given PREFIX, followed by ": ".
416 If no one is given "sparse" is used. The default is to not use
417 a prefix at all.
418 -fmemcpy-max-count=COUNT
420 Set the limit for the warnings given by -Wmemcpy-max-count. A
421 COUNT of 'unlimited' or '0' will effectively disable the warn‐
422 ing. The default limit is 100000.
423 -ftabstop=WIDTH
425 Set the distance between tab stops. This helps sparse report
426 correct column numbers in warnings or errors. If the value is
427 less than 1 or greater than 100, the option is ignored. The
428 default is 8.
429 -f[no-]unsigned-char, -f[no-]signed-char
431 Let plain 'char' be unsigned or signed. By default chars are
432 signed.
433
435 cgcc(1)
436
438 http://www.kernel.org/pub/software/devel/sparse/
439
441 linux-sparse@vger.kernel.org
442
444 Submission of patches and reporting of bugs, as well as discussions
445 related to Sparse, should be done via the mailing list (linux-
446 sparse@vger.kernel.org) where the development and maintenance is pri‐
447 marily done. You do not have to be subscribed to the list to send a
448 message there.
449 Bugs can also be reported and tracked via the Linux kernel's bugzilla:
451 http://bugzilla.kernel.org/enter_bug.cgi?component=Sparse&product=Tools
452 .
453
455 Sparse was started by Linus Torvalds. The complete list of contribu‐
456 tors can be find at https://www.openhub.net/p/sparse/contributors .
457 Luc Van Oostenryck is Sparse's current maintainer.
459 sparse(1)