1 sparse(1) User Commands 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.
129
130 -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
136 Sparse does not issue these warnings by default.
137
138 -Wcontext
139 Warn about potential errors in synchronization or other
140 delimited contexts.
141
142 Sparse supports several means of designating functions or
143 statements that delimit contexts, such as synchronization.
144 Functions with the extended attribute
145 __attribute__((context(expression,in_context,out_context))
146 require the context expression (for instance, a lock) to have
147 the value in_context (a constant nonnegative integer) when
148 called, and return with the value out_context (a constant
149 nonnegative integer). For APIs defined via macros, use the
150 statement form __context__(expression,in_value,out_value) in the
151 body of the macro.
152
153 With -Wcontext Sparse will warn when it sees a function change
154 the context without indicating this with a context attribute,
155 either by decreasing a context below zero (such as by releasing
156 a lock without acquiring it), or returning with a changed
157 context (such as by acquiring a lock without releasing it).
158 Sparse will also warn about blocks of code which may potentially
159 execute with different contexts.
160
161 Sparse issues these warnings by default. To turn them off, use
162 -Wno-context.
163
164 -Wdecl Warn about any non-static variable or function definition that
165 has no previous declaration.
166
167 Private symbols (functions and variables) internal to a given
168 source file should use static, to allow additional compiler
169 optimizations, allow detection of unused symbols, and prevent
170 other code from relying on these internal symbols. Public
171 symbols used by other source files will need declarations
172 visible to those other source files, such as in a header file.
173 All declarations should fall into one of these two categories.
174 Thus, with -Wdecl, Sparse warns about any symbol definition with
175 neither static nor a declaration. To fix this warning, declare
176 private symbols static, and ensure that the files defining
177 public symbols have the symbol declarations available first
178 (such as by including the appropriate header file).
179
180 Sparse issues these warnings by default. To turn them off, use
181 -Wno-decl.
182
183 -Wdeclaration-after-statement
184 Warn about declarations that are not at the start of a block.
185
186 These declarations are permitted in C99 but not in C89.
187
188 Sparse issues these warnings by default only when the C dialect
189 is C89 (i.e. -ansi or -std=c89). To turn them off, use
190 -Wno-declaration-after-statement.
191
192 -Wdefault-bitfield-sign
193 Warn about any bitfield with no explicit signedness.
194
195 Bitfields have no standard-specified default signedness. (C99
196 6.7.2) A bitfield without an explicit signed or unsigned creates
197 a portability problem for software that relies on the available
198 range of values. To fix this, specify the bitfield type as
199 signed or unsigned explicitly.
200
201 Sparse does not issue these warnings by default.
202
203 -Wdesignated-init
204 Warn about positional initialization of structs marked as
205 requiring designated initializers.
206
207 Sparse allows an attribute __attribute__((designated_init))
208 which marks a struct as requiring designated initializers.
209 Sparse will warn about positional initialization of a struct
210 variable or struct literal of a type that has this attribute.
211
212 Requiring designated initializers for a particular struct type
213 will insulate code using that struct type from changes to the
214 layout of the type, avoiding the need to change initializers for
215 that type unless they initialize a removed or incompatibly
216 changed field.
217
218 Common examples of this type of struct include collections of
219 function pointers for the implementations of a class of related
220 operations, for which the default NULL for an unmentioned field
221 in a designated initializer will correctly indicate the absence
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
296 struct structname var = { field: value };
297
298 Sparse will warn about the use of GCC's non-standard syntax for
299 designated initializers. To fix this warning, convert
300 designated initializers to use the standard C99 syntax.
301
302 Sparse issues these warnings by default. To turn them off, use
303 -Wno-old-initializer.
304
305 -Wone-bit-signed-bitfield
306 Warn about any one-bit signed bitfields.
307
308 A one-bit signed bitfield can only have the values 0 and -1, or
309 with some compilers only 0; this results in unexpected behavior
310 for programs which expected the ability to store 0 and 1.
311
312 Sparse issues these warnings by default. To turn them off, use
313 -Wno-one-bit-signed-bitfield.
314
315 -Wparen-string
316 Warn about the use of a parenthesized string to initialize an
317 array.
318
319 Standard C syntax does not permit a parenthesized string as an
320 array initializer. GCC allows this syntax as an extension.
321 With -Wparen-string, Sparse will warn about this syntax.
322
323 Sparse does not issue these warnings by default.
324
325 -Wpointer-arith
326 Warn about anything that depends on the sizeof a void or
327 function type.
328
329 C99 does not allow the sizeof operator to be applied to function
330 types or to incomplete types such as void. GCC allows sizeof to
331 be applied to these types as an extension and assigns these
332 types a size of 1. With -pointer-arith, Sparse will warn about
333 pointer arithmetic on void or function pointers, as well as
334 expressions which directly apply the sizeof operator to void or
335 function types.
336
337 Sparse does not issue these warnings by default.
338
339 -Wptr-subtraction-blows
340 Warn when subtracting two pointers to a type with a non-power-
341 of-two size.
342
343 Subtracting two pointers to a given type gives a difference in
344 terms of the number of items of that type. To generate this
345 value, compilers will usually need to divide the difference by
346 the size of the type, an potentially expensive operation for
347 sizes other than powers of two.
348
349 Code written using pointer subtraction can often use another
350 approach instead, such as array indexing with an explicit array
351 index variable, which may allow compilers to generate more
352 efficient code.
353
354 Sparse does not issue these warnings by default.
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)