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 -Waddress-space
23 Warn about code which mixes pointers to different address spa‐
24 ces.
25 Sparse allows an extended attribute
27 __attribute__((address_space(num))) on pointers, which desig‐
28 nates a pointer target in address space num (a constant inte‐
29 ger). With -Waddress-space, Sparse treats pointers with identi‐
30 cal target types but different address spaces as distinct types.
31 To override this warning, such as for functions which convert
32 pointers between address spaces, use a type that includes
33 __attribute__((force)).
34 Sparse issues these warnings by default. To turn them off, use
36 -Wno-address-space.
37 -Wbitwise
39 Warn about unsupported operations or type mismatches with
40 restricted integer types.
41 Sparse supports an extended attribute, __attribute__((bitwise)),
43 which creates a new restricted integer type from a base integer
44 type, distinct from the base integer type and from any other
45 restricted integer type not declared in the same declaration or
46 typedef. For example, this allows programs to create typedefs
47 for integer types with specific endianness. With -Wbitwise,
48 Sparse will warn on any use of a restricted type in arithmetic
49 operations other than bitwise operations, and on any conversion
50 of one restricted type into another, except via a cast that
51 includes __attribute__((force)).
52 Sparse does not issue these warnings by default.
54 -Wcast-to-as
56 Warn about casts which add an address space to a pointer type.
57 A cast that includes __attribute__((force)) will suppress this
59 warning.
60 Sparse does not issue these warnings by default.
62 -Wcast-truncate
64 Warn about casts that truncate constant values.
65 Sparse issues these warnings by default. To turn them off, use
67 -Wno-cast-truncate.
68 -Wcontext
70 Warn about potential errors in synchronization or other delim‐
71 ited contexts.
72 Sparse supports several means of designating functions or state‐
74 ments that delimit contexts, such as synchronization. Functions
75 with the extended attribute __attribute__((context(expres‐
76 sion,in_context,out_context)) require the context expression
77 (for instance, a lock) to have the value in_context (a constant
78 nonnegative integer) when called, and return with the value
79 out_context (a constant nonnegative integer). For APIs defined
80 via macros, use the statement form __context__(expres‐
81 sion,in_value,out_value) in the body of the macro.
82 With -Wcontext Sparse will warn when it sees a function change
84 the context without indicating this with a context attribute,
85 either by decreasing a context below zero (such as by releasing
86 a lock without acquiring it), or returning with a changed con‐
87 text (such as by acquiring a lock without releasing it). Sparse
88 will also warn about blocks of code which may potentially exe‐
89 cute with different contexts.
90 Sparse issues these warnings by default. To turn them off, use
92 -Wno-context.
93 -Wdecl Warn about any non-static variable or function definition that
95 has no previous declaration.
96 Private symbols (functions and variables) internal to a given
98 source file should use static, to allow additional compiler
99 optimizations, allow detection of unused symbols, and prevent
100 other code from relying on these internal symbols. Public sym‐
101 bols used by other source files will need declarations visible
102 to those other source files, such as in a header file. All dec‐
103 larations should fall into one of these two categories. Thus,
104 with -Wdecl, Sparse warns about any symbol definition with nei‐
105 ther static nor a declaration. To fix this warning, declare
106 private symbols static, and ensure that the files defining pub‐
107 lic symbols have the symbol declarations available first (such
108 as by including the appropriate header file).
109 Sparse issues these warnings by default. To turn them off, use
111 -Wno-decl.
112 -Wdeclaration-after-statement
114 Warn about declarations that are not at the start of a block.
115 These declarations are permitted in C99 but not in C89.
117 Sparse issues these warnings by default only when the C dialect
119 is C89 (i.e. -ansi or -std=c89). To turn them off, use
120 -Wno-declaration-after-statement.
121 -Wdefault-bitfield-sign
123 Warn about any bitfield with no explicit signedness.
124 Bitfields have no standard-specified default signedness. (C99
126 6.7.2) A bitfield without an explicit signed or unsigned creates
127 a portability problem for software that relies on the available
128 range of values. To fix this, specify the bitfield type as
129 signed or unsigned explicitly.
130 Sparse does not issue these warnings by default.
132 -Wdo-while
134 Warn about do-while loops that do not delimit the loop body with
135 braces.
136 Sparse does not issue these warnings by default.
138 -Wenum-mismatch
140 Warn about the use of an expression of an incorrect enum type
141 when initializing another enum type, assigning to another enum
142 type, or passing an argument to a function which expects another
143 enum type.
144 Sparse issues these warnings by default. To turn them off, use
146 -Wno-enum-mismatch.
147 -Wnon-pointer-null
149 Warn about the use of 0 as a NULL pointer.
150 0 has integer type. NULL has pointer type.
152 Sparse issues these warnings by default. To turn them off, use
154 -Wno-non-pointer-null.
155 -Wold-initializer
157 Warn about the use of the pre-C99 GCC syntax for designated ini‐
158 tializers.
159 C99 provides a standard syntax for designated fields in struct
161 or union initializers:
162 struct structname var = { .field = value };
164 GCC also has an old, non-standard syntax for designated initial‐
166 izers which predates C99:
167 struct structname var = { field: value };
169 Sparse will warn about the use of GCC's non-standard syntax for
171 designated initializers. To fix this warning, convert desig‐
172 nated initializers to use the standard C99 syntax.
173 Sparse issues these warnings by default. To turn them off, use
175 -Wno-old-initializer.
176 -Wone-bit-signed-bitfield
178 Warn about any one-bit signed bitfields.
179 A one-bit signed bitfield can only have the values 0 and -1, or
181 with some compilers only 0; this results in unexpected behavior
182 for programs which expected the ability to store 0 and 1.
183 Sparse issues these warnings by default. To turn them off, use
185 -Wno-one-bit-signed-bitfield.
186 -Wparen-string
188 Warn about the use of a parenthesized string to initialize an
189 array.
190 Standard C syntax does not permit a parenthesized string as an
192 array initializer. GCC allows this syntax as an extension.
193 With -Wparen-string, Sparse will warn about this syntax.
194 Sparse does not issue these warnings by default.
196 -Wptr-subtraction-blows
198 Warn when subtracting two pointers to a type with a non-power-
199 of-two size.
200 Subtracting two pointers to a given type gives a difference in
202 terms of the number of items of that type. To generate this
203 value, compilers will usually need to divide the difference by
204 the size of the type, an potentially expensive operation for
205 sizes other than powers of two.
206 Code written using pointer subtraction can often use another
208 approach instead, such as array indexing with an explicit array
209 index variable, which may allow compilers to generate more effi‐
210 cient code.
211 Sparse does not issue these warnings by default.
213 -Wreturn-void
215 Warn if a function with return type void returns a void expres‐
216 sion.
217 C99 permits this, and in some cases this allows for more generic
219 code in macros that use typeof or take a type as a macro argu‐
220 ment. However, some programs consider this poor style, and
221 those programs can use -Wreturn-void to get warnings about it.
222 Sparse does not issue these warnings by default.
224 -Wshadow
226 Warn when declaring a symbol which shadows a declaration with
227 the same name in an outer scope.
228 Such declarations can lead to error-prone code.
230 Sparse does not issue these warnings by default.
232 -Wtransparent-union
234 Warn about any declaration using the GCC extension
235 __attribute__((transparent_union)).
236 Sparse issues these warnings by default. To turn them off, use
238 -Wno-transparent-union.
239 -Wtypesign
241 Warn when converting a pointer to an integer type into a pointer
242 to an integer type with different signedness.
243 Sparse does not issue these warnings by default.
245 -Wundef
247 Warn about preprocessor conditionals that use the value of an
248 undefined preprocessor symbol.
249 Standard C (C99 6.10.1) permits using the value of an undefined
251 preprocessor symbol in preprocessor conditionals, and specifies
252 it has have a value of 0. However, this behavior can lead to
253 subtle errors.
254 Sparse does not issue these warnings by default.
256
258 -gcc-base-dir dir
259 Look for compiler-provided system headers in dir/include/ and
260 dir/include-fixed/.
261
263 -ftabstop=WIDTH
264 Set the distance between tab stops. This helps sparse report
265 correct column numbers in warnings or errors. If the value is
266 less than 1 or greater than 100, the option is ignored. The
267 default is 8.
268
270 cgcc(1)
271
273 http://www.kernel.org/pub/software/devel/sparse/
274
276 linux-sparse@vger.kernel.org
277
279 Josh Triplett <josh@kernel.org>
280 sparse(1)