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 -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.
100
101 -Wconstexpr-not-const
102 Warn if a non-constant expression is encountered when really
103 expecting a constant expression instead. Currently, this warns
104 when initializing an object of static storage duration with an
105 initializer which is not a constant expression.
106
107 Sparse does not issue these warnings by default.
108
109 -Wcontext
110 Warn about potential errors in synchronization or other
111 delimited contexts.
112
113 Sparse supports several means of designating functions or
114 statements that delimit contexts, such as synchronization.
115 Functions with the extended attribute
116 __attribute__((context(expression,in_context,out_context))
117 require the context expression (for instance, a lock) to have
118 the value in_context (a constant nonnegative integer) when
119 called, and return with the value out_context (a constant
120 nonnegative integer). For APIs defined via macros, use the
121 statement form __context__(expression,in_value,out_value) in the
122 body of the macro.
123
124 With -Wcontext Sparse will warn when it sees a function change
125 the context without indicating this with a context attribute,
126 either by decreasing a context below zero (such as by releasing
127 a lock without acquiring it), or returning with a changed
128 context (such as by acquiring a lock without releasing it).
129 Sparse will also warn about blocks of code which may potentially
130 execute with different contexts.
131
132 Sparse issues these warnings by default. To turn them off, use
133 -Wno-context.
134
135 -Wdecl Warn about any non-static variable or function definition that
136 has no previous declaration.
137
138 Private symbols (functions and variables) internal to a given
139 source file should use static, to allow additional compiler
140 optimizations, allow detection of unused symbols, and prevent
141 other code from relying on these internal symbols. Public
142 symbols used by other source files will need declarations
143 visible to those other source files, such as in a header file.
144 All declarations should fall into one of these two categories.
145 Thus, with -Wdecl, Sparse warns about any symbol definition with
146 neither static nor a declaration. To fix this warning, declare
147 private symbols static, and ensure that the files defining
148 public symbols have the symbol declarations available first
149 (such as by including the appropriate header file).
150
151 Sparse issues these warnings by default. To turn them off, use
152 -Wno-decl.
153
154 -Wdeclaration-after-statement
155 Warn about declarations that are not at the start of a block.
156
157 These declarations are permitted in C99 but not in C89.
158
159 Sparse issues these warnings by default only when the C dialect
160 is C89 (i.e. -ansi or -std=c89). To turn them off, use
161 -Wno-declaration-after-statement.
162
163 -Wdefault-bitfield-sign
164 Warn about any bitfield with no explicit signedness.
165
166 Bitfields have no standard-specified default signedness. (C99
167 6.7.2) A bitfield without an explicit signed or unsigned creates
168 a portability problem for software that relies on the available
169 range of values. To fix this, specify the bitfield type as
170 signed or unsigned explicitly.
171
172 Sparse does not issue these warnings by default.
173
174 -Wdesignated-init
175 Warn about positional initialization of structs marked as
176 requiring designated initializers.
177
178 Sparse allows an attribute __attribute__((designated_init))
179 which marks a struct as requiring designated initializers.
180 Sparse will warn about positional initialization of a struct
181 variable or struct literal of a type that has this attribute.
182
183 Requiring designated initializers for a particular struct type
184 will insulate code using that struct type from changes to the
185 layout of the type, avoiding the need to change initializers for
186 that type unless they initialize a removed or incompatibly
187 changed field.
188
189 Common examples of this type of struct include collections of
190 function pointers for the implementations of a class of related
191 operations, for which the default NULL for an unmentioned field
192 in a designated initializer will correctly indicate the absence
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
279 struct structname var = { field: value };
280
281 Sparse will warn about the use of GCC's non-standard syntax for
282 designated initializers. To fix this warning, convert
283 designated initializers to use the standard C99 syntax.
284
285 Sparse issues these warnings by default. To turn them off, use
286 -Wno-old-initializer.
287
288 -Wone-bit-signed-bitfield
289 Warn about any one-bit signed bitfields.
290
291 A one-bit signed bitfield can only have the values 0 and -1, or
292 with some compilers only 0; this results in unexpected behavior
293 for programs which expected the ability to store 0 and 1.
294
295 Sparse issues these warnings by default. To turn them off, use
296 -Wno-one-bit-signed-bitfield.
297
298 -Wparen-string
299 Warn about the use of a parenthesized string to initialize an
300 array.
301
302 Standard C syntax does not permit a parenthesized string as an
303 array initializer. GCC allows this syntax as an extension.
304 With -Wparen-string, Sparse will warn about this syntax.
305
306 Sparse does not issue these warnings by default.
307
308 -Wpointer-arith
309 Warn about anything that depends on the sizeof a void or
310 function type.
311
312 C99 does not allow the sizeof operator to be applied to function
313 types or to incomplete types such as void. GCC allows sizeof to
314 be applied to these types as an extension and assigns these
315 types a size of 1. With -pointer-arith, Sparse will warn about
316 pointer arithmetic on void or function pointers, as well as
317 expressions which directly apply the sizeof operator to void or
318 function types.
319
320 Sparse does not issue these warnings by default.
321
322 -Wptr-subtraction-blows
323 Warn when subtracting two pointers to a type with a non-power-
324 of-two size.
325
326 Subtracting two pointers to a given type gives a difference in
327 terms of the number of items of that type. To generate this
328 value, compilers will usually need to divide the difference by
329 the size of the type, an potentially expensive operation for
330 sizes other than powers of two.
331
332 Code written using pointer subtraction can often use another
333 approach instead, such as array indexing with an explicit array
334 index variable, which may allow compilers to generate more
335 efficient code.
336
337 Sparse does not issue these warnings by default.
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)