1 .\" Sparse manpage by Josh Triplett
2 .TH sparse "1"
3 .
4 .SH NAME
5 sparse \- Semantic Parser for C
6 .
7 .SH SYNOPSIS
8 .B sparse
9 [\fIWARNING OPTIONS\fR]... \fIfile.c\fR
10 .
11 .SH DESCRIPTION
12 Sparse parses C source and looks for errors, producing warnings on standard
13 error.
14 .P
15 Sparse accepts options controlling the set of warnings to generate. To turn
16 on warnings Sparse does not issue by default, use the corresponding warning
17 option \fB\-Wsomething\fR. Sparse issues some warnings by default; to turn
18 off those warnings, pass the negation of the associated warning option,
19 \fB\-Wno\-something\fR.
20 .
21 .SH WARNING OPTIONS
22 .TP
23 .B \-Wsparse\-all
24 Turn on all sparse warnings, except for those explicitly disabled via
25 \fB\-Wno\-something\fR.
26 .TP
27 .B \-Wsparse\-error
28 Turn all sparse warnings into errors.
29 .TP
30 .B \-Waddress\-space
31 Warn about code which mixes pointers to different address spaces.
32
33 Sparse allows an extended attribute
34 .BI __attribute__((address_space( num )))
35 on pointers, which designates a pointer target in address space \fInum\fR (a
36 constant integer). With \fB\-Waddress\-space\fR, Sparse treats pointers with
37 identical target types but different address spaces as distinct types. To
38 override this warning, such as for functions which convert pointers between
39 address spaces, use a type that includes \fB__attribute__((force))\fR.
40
41 Sparse issues these warnings by default. To turn them off, use
42 \fB\-Wno\-address\-space\fR.
43 .
44 .TP
45 .B \-Wbitwise
46 Warn about unsupported operations or type mismatches with restricted integer
47 types.
48
49 Sparse supports an extended attribute, \fB__attribute__((bitwise))\fR, which
50 creates a new restricted integer type from a base integer type, distinct from
51 the base integer type and from any other restricted integer type not declared
52 in the same declaration or \fBtypedef\fR. For example, this allows programs
53 to create \fBtypedef\fRs for integer types with specific endianness. With
54 \fB-Wbitwise\fR, Sparse will warn on any use of a restricted type in
55 arithmetic operations other than bitwise operations, and on any conversion of
56 one restricted type into another, except via a cast that includes
57 \fB__attribute__((force))\fR.
58
59 __bitwise ends up being a "stronger integer separation", one that
60 doesn't allow you to mix with non-bitwise integers, so now it's much
61 harder to lose the type by mistake.
62
63 __bitwise is for *unique types* that cannot be mixed with other
64 types, and that you'd never want to just use as a random integer (the
65 integer 0 is special, though, and gets silently accepted iirc - it's
66 kind of like "NULL" for pointers). So "gfp_t" or the "safe endianness"
67 types would be __bitwise: you can only operate on them by doing
68 specific operations that know about *that* particular type.
69
70 Sparse issues these warnings by default. To turn them off, use
71 \fB\-Wno\-bitwise\fR.
72 .
73 .TP
74 .B \-Wcast\-to\-as
75 Warn about casts which add an address space to a pointer type.
76
77 A cast that includes \fB__attribute__((force))\fR will suppress this warning.
78
79 Sparse does not issue these warnings by default.
80 .
81 .TP
82 .B \-Wcast\-truncate
83 Warn about casts that truncate constant values.
84
85 Sparse issues these warnings by default. To turn them off, use
86 \fB\-Wno\-cast\-truncate\fR.
87 .
88 .TP
89 .B \-Wconstant\-suffix
90 Warn if an integer constant is larger than the maximum representable value
91 of the type indicated by its type suffix (if any). For example, on a
92 system where ints are 32-bit and longs 64-bit, the constant \fB0x100000000U\fR
93 is larger than can be represented by an \fBunsigned int\fR but fits in an
94 \fBunsigned long\fR. So its type is \fBunsigned long\fR but this is not
95 indicated by its suffix. In this case, the warning could be suppressed by
96 using the suffix \fBUL\fR: \fB0x100000000UL\fR.
97
98 Sparse does not issue these warnings by default.
99 .
100 .TP
101 .B \-Wconstexpr-not-const
102 Warn if a non-constant expression is encountered when really expecting a
103 constant expression instead.
104 Currently, this warns when initializing an object of static storage duration
105 with an initializer which is not a constant expression.
106
107 Sparse does not issue these warnings by default.
108 .
109 .TP
110 .B \-Wcontext
111 Warn about potential errors in synchronization or other delimited contexts.
112
113 Sparse supports several means of designating functions or statements that
114 delimit contexts, such as synchronization. Functions with the extended
115 attribute
116 .BI __attribute__((context( expression , in_context , out_context ))
117 require the context \fIexpression\fR (for instance, a lock) to have the value
118 \fIin_context\fR (a constant nonnegative integer) when called, and return with
119 the value \fIout_context\fR (a constant nonnegative integer). For APIs
120 defined via macros, use the statement form
121 .BI __context__( expression , in_value , out_value )
122 in the body of the macro.
123
124 With \fB-Wcontext\fR Sparse will warn when it sees a function change the
125 context without indicating this with a \fBcontext\fR attribute, either by
126 decreasing a context below zero (such as by releasing a lock without acquiring
127 it), or returning with a changed context (such as by acquiring a lock without
128 releasing it). Sparse will also warn about blocks of code which may
129 potentially execute with different contexts.
130
131 Sparse issues these warnings by default. To turn them off, use
132 \fB\-Wno\-context\fR.
133 .
134 .TP
135 .B \-Wdecl
136 Warn about any non-\fBstatic\fR variable or function definition that has no
137 previous declaration.
138
139 Private symbols (functions and variables) internal to a given source file
140 should use \fBstatic\fR, to allow additional compiler optimizations, allow
141 detection of unused symbols, and prevent other code from relying on these
142 internal symbols. Public symbols used by other source files will need
143 declarations visible to those other source files, such as in a header file.
144 All declarations should fall into one of these two categories. Thus, with
145 \fB-Wdecl\fR, Sparse warns about any symbol definition with neither
146 \fBstatic\fR nor a declaration. To fix this warning, declare private symbols
147 \fBstatic\fR, and ensure that the files defining public symbols have the
148 symbol declarations available first (such as by including the appropriate
149 header file).
150
151 Sparse issues these warnings by default. To turn them off, use
152 \fB\-Wno\-decl\fR.
153 .
154 .TP
155 .B \-Wdeclaration-after-statement
156 Warn about declarations that are not at the start of a block.
157
158 These declarations are permitted in C99 but not in C89.
159
160 Sparse issues these warnings by default only when the C dialect is
161 C89 (i.e. -ansi or -std=c89). To turn them off, use
162 \fB\-Wno\-declaration\-after\-statement\fR.
163 .
164 .TP
165 .B \-Wdefault\-bitfield\-sign
166 Warn about any bitfield with no explicit signedness.
167
168 Bitfields have no standard-specified default signedness. (C99 6.7.2) A
169 bitfield without an explicit \fBsigned\fR or \fBunsigned\fR creates a
170 portability problem for software that relies on the available range of values.
171 To fix this, specify the bitfield type as \fBsigned\fR or \fBunsigned\fR
172 explicitly.
173
174 Sparse does not issue these warnings by default.
175 .
176 .TP
177 .B \-Wdesignated\-init
178 Warn about positional initialization of structs marked as requiring designated
179 initializers.
180
181 Sparse allows an attribute
182 .BI __attribute__((designated_init))
183 which marks a struct as requiring designated initializers. Sparse will warn
184 about positional initialization of a struct variable or struct literal of a
185 type that has this attribute.
186
187 Requiring designated initializers for a particular struct type will insulate
188 code using that struct type from changes to the layout of the type, avoiding
189 the need to change initializers for that type unless they initialize a removed
190 or incompatibly changed field.
191
192 Common examples of this type of struct include collections of function pointers
193 for the implementations of a class of related operations, for which the default
194 NULL for an unmentioned field in a designated initializer will correctly
195 indicate the absence of that operation.
196
197 Sparse issues these warnings by default. To turn them off, use
198 \fB\-Wno\-designated\-init\fR.
199 .
200 .TP
201 .B \-Wdo\-while
202 Warn about do-while loops that do not delimit the loop body with braces.
203
204 Sparse does not issue these warnings by default.
205 .
206 .TP
207 .B \-Wenum\-mismatch
208 Warn about the use of an expression of an incorrect \fBenum\fR type when
209 initializing another \fBenum\fR type, assigning to another \fBenum\fR type, or
210 passing an argument to a function which expects another \fBenum\fR type.
211
212 Sparse issues these warnings by default. To turn them off, use
213 \fB\-Wno\-enum\-mismatch\fR.
214 .
215 .TP
216 .B \-Wempty\-character\-constant
217 Warn about a constant such as ''.
218
219 Sparse issues these warnings by default. To turn them off, use
220 \fB\-Wno\-empty\-character\-constant\fR.
221 .
222 .TP
223 .B \-Wexternal\-function\-has\-definition
224 Warn about function definitions that are declared with external linkage.
225
226 Sparse issues these warnings by default. To turn them off, use
227 \fB\-Wno\-external\-function\-has\-definition\fR.
228 .
229 .TP
230 .B \-Winit\-cstring
231 Warn about initialization of a char array with a too long constant C string.
232
233 If the size of the char array and the length of the string are the same,
234 there is no space for the last nul char of the string in the array:
235
236 .nf
237 char s[3] = "abc";
238 .fi
239
240 If the array is used as a byte array, not as C string, this
241 warning is just noise. However, if the array is passed to functions
242 dealing with C string like printf(%s) and strcmp, it may cause a
243 trouble.
244
245 Sparse does not issue these warnings by default.
246 .
247 .TP
248 .B \-Wmemcpy\-max\-count
249 Warn about call of \fBmemcpy()\fR, \fBmemset()\fR, \fBcopy_from_user()\fR, or
250 \fBcopy_to_user()\fR with a large compile-time byte count.
251
252 Sparse issues these warnings by default. To turn them off, use
253 \fB\-Wno\-memcpy\-max\-count\fR.
254
255 The limit can be changed with \fB\-fmemcpy\-max\-count=COUNT\fR,
256 the default being \fB100000\fR.
257 .
258 .TP
259 .B \-Wnon\-ansi\-function\-declaration
260 Warn about non-ANSI function declarations.
261
262 Sparse issues these warnings by default. To turn them off, use
263 \fB\-Wno\-non\-ansi\-function\-declaration\fR.
264 .
265 .TP
266 .B \-Wnon\-pointer\-null
267 Warn about the use of 0 as a NULL pointer.
268
269 0 has integer type. NULL has pointer type.
270
271 Sparse issues these warnings by default. To turn them off, use
272 \fB\-Wno\-non\-pointer\-null\fR.
273 .
274 .TP
275 .B \-Wold\-initializer
276 Warn about the use of the pre-C99 GCC syntax for designated initializers.
277
278 C99 provides a standard syntax for designated fields in \fBstruct\fR or
279 \fBunion\fR initializers:
280
281 .nf
282 struct structname var = { .field = value };
283 .fi
284
285 GCC also has an old, non-standard syntax for designated initializers which
286 predates C99:
287
288 .nf
289 struct structname var = { field: value };
290 .fi
291
292 Sparse will warn about the use of GCC's non-standard syntax for designated
293 initializers. To fix this warning, convert designated initializers to use the
294 standard C99 syntax.
295
296 Sparse issues these warnings by default. To turn them off, use
297 \fB\-Wno\-old\-initializer\fR.
298 .
299 .TP
300 .B \-Wone\-bit\-signed\-bitfield
301 Warn about any one-bit \fBsigned\fR bitfields.
302
303 A one-bit \fBsigned\fR bitfield can only have the values 0 and -1, or with
304 some compilers only 0; this results in unexpected behavior for programs which
305 expected the ability to store 0 and 1.
306
307 Sparse issues these warnings by default. To turn them off, use
308 \fB\-Wno\-one\-bit\-signed\-bitfield\fR.
309 .
310 .TP
311 .B \-Wparen\-string
312 Warn about the use of a parenthesized string to initialize an array.
313
314 Standard C syntax does not permit a parenthesized string as an array
315 initializer. GCC allows this syntax as an extension. With
316 \fB\-Wparen\-string\fR, Sparse will warn about this syntax.
317
318 Sparse does not issue these warnings by default.
319 .
320 .TP
321 .B \-Wpointer\-arith
322 Warn about anything that depends on the \fBsizeof\fR a void or function type.
323
324 C99 does not allow the \fBsizeof\fR operator to be applied to function types
325 or to incomplete types such as void. GCC allows \fBsizeof\fR to be applied to
326 these types as an extension and assigns these types a size of \fI1\fR. With
327 \fB\-pointer\-arith\fR, Sparse will warn about pointer arithmetic on void
328 or function pointers, as well as expressions which directly apply the
329 \fBsizeof\fR operator to void or function types.
330
331 Sparse does not issue these warnings by default.
332 .
333 .TP
334 .B \-Wptr\-subtraction\-blows
335 Warn when subtracting two pointers to a type with a non-power-of-two size.
336
337 Subtracting two pointers to a given type gives a difference in terms of the
338 number of items of that type. To generate this value, compilers will usually
339 need to divide the difference by the size of the type, an potentially
340 expensive operation for sizes other than powers of two.
341
342 Code written using pointer subtraction can often use another approach instead,
343 such as array indexing with an explicit array index variable, which may allow
344 compilers to generate more efficient code.
345
346 Sparse does not issue these warnings by default.
347 .
348 .TP
349 .B \-Wreturn\-void
350 Warn if a function with return type void returns a void expression.
351
352 C99 permits this, and in some cases this allows for more generic code in
353 macros that use typeof or take a type as a macro argument. However, some
354 programs consider this poor style, and those programs can use
355 \fB\-Wreturn\-void\fR to get warnings about it.
356
357 Sparse does not issue these warnings by default.
358 .
359 .TP
360 .B \-Wshadow
361 Warn when declaring a symbol which shadows a declaration with the same name in
362 an outer scope.
363
364 Such declarations can lead to error-prone code.
365
366 Sparse does not issue these warnings by default.
367 .
368 .TP
369 .B \-Wsizeof-bool
370 Warn when checking the sizeof a _Bool.
371
372 C99 does not specify the sizeof a _Bool. gcc uses 1.
373
374 Sparse does not issue these warnings by default.
375 .
376 .TP
377 .B \-Wtransparent\-union
378 Warn about any declaration using the GCC extension
379 \fB__attribute__((transparent_union))\fR.
380
381 Sparse issues these warnings by default. To turn them off, use
382 \fB\-Wno\-transparent\-union\fR.
383 .
384 .TP
385 .B \-Wtypesign
386 Warn when converting a pointer to an integer type into a pointer to an integer
387 type with different signedness.
388
389 Sparse does not issue these warnings by default.
390 .
391 .TP
392 .B \-Wundef
393 Warn about preprocessor conditionals that use the value of an undefined
394 preprocessor symbol.
395
396 Standard C (C99 6.10.1) permits using the value of an undefined preprocessor
397 symbol in preprocessor conditionals, and specifies it has a value of 0.
398 However, this behavior can lead to subtle errors.
399
400 Sparse does not issue these warnings by default.
401 .
402 .SH MISC OPTIONS
403 .TP
404 .B \-gcc-base-dir \fIdir\fR
405 Look for compiler-provided system headers in \fIdir\fR/include/ and \fIdir\fR/include-fixed/.
406 .
407 .TP
408 .B \-multiarch-dir \fIdir\fR
409 Look for system headers in the multiarch subdirectory \fIdir\fR.
410 The \fIdir\fR name would normally take the form of the target's
411 normalized GNU triplet. (e.g. i386-linux-gnu).
412 .
413 .SH DEBUG OPTIONS
414 .TP
415 .B \-fdump-linearize[=only]
416 Dump the IR code of a function directly after its linearization,
417 before any simplifications are made. If the argument \fB=only\fR is
418 also given no further processing is done on the function.
419 .
420 .B \-fmem-report
421 Report some statistics about memory allocation used by the tool.
422 .
423 .SH OTHER OPTIONS
424 .TP
425 .B \-fmemcpy-max-count=COUNT
426 Set the limit for the warnings given by \fB-Wmemcpy-max-count\fR.
427 A COUNT of 0, useless in itself, will effectively disable the warning.
428 The default limit is 100000.
429 .
430 .TP
431 .B \-ftabstop=WIDTH
432 Set the distance between tab stops. This helps sparse report correct
433 column numbers in warnings or errors. If the value is less than 1 or
434 greater than 100, the option is ignored. The default is 8.
435 .
436 .SH SEE ALSO
437 .BR cgcc (1)
438 .
439 .SH HOMEPAGE
440 http://www.kernel.org/pub/software/devel/sparse/
441 .
442 .SH MAILING LIST
443 linux-sparse@vger.kernel.org
444 .
445 .SH MAINTAINER
446 Christopher Li <sparse@chrisli.org>