1 .\" Sparse manpage by Josh Triplett
5 sparse \- Semantic Parser for C
9 [\fIWARNING OPTIONS\fR]... \fIfile.c\fR
12 Sparse parses C source and looks for errors, producing warnings on standard
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.
24 Warn about code which mixes pointers to different address spaces.
26 Sparse allows an extended attribute
27 .BI __attribute__((address_space( num )))
28 on pointers, which designates a pointer target in address space \fInum\fR (a
29 constant integer). With \fB\-Waddress\-space\fR, Sparse treats pointers with
30 identical target types but different address spaces as distinct types. To
31 override this warning, such as for functions which convert pointers between
32 address spaces, use a type that includes \fB__attribute__((force))\fR.
34 Sparse issues these warnings by default. To turn them off, use
35 \fB\-Wno\-address\-space\fR.
39 Warn about unsupported operations or type mismatches with restricted integer
42 Sparse supports an extended attribute, \fB__attribute__((bitwise))\fR, which
43 creates a new restricted integer type from a base integer type, distinct from
44 the base integer type and from any other restricted integer type not declared
45 in the same declaration or \fBtypedef\fR. For example, this allows programs
46 to create \fBtypedef\fRs for integer types with specific endianness. With
47 \fB-Wbitwise\fR, Sparse will warn on any use of a restricted type in
48 arithmetic operations other than bitwise operations, and on any conversion of
49 one restricted type into another, except via a cast that includes
50 \fB__attribute__((force))\fR.
52 Sparse does not issue these warnings by default.
56 Warn about casts which add an address space to a pointer type.
58 A cast that includes \fB__attribute__((force))\fR will suppress this warning.
60 Sparse does not issue these warnings by default.
64 Warn about casts that truncate constant values.
66 Sparse issues these warnings by default. To turn them off, use
67 \fB\-Wno\-cast\-truncate\fR.
71 Warn about potential errors in synchronization or other delimited contexts.
73 Sparse supports several means of designating functions or statements that
74 delimit contexts, such as synchronization. Functions with the extended
76 .BI __attribute__((context( expression , in_context , out_context ))
77 require the context \fIexpression\fR (for instance, a lock) to have the value
78 \fIin_context\fR (a constant nonnegative integer) when called, and return with
79 the value \fIout_context\fR (a constant nonnegative integer). For APIs
80 defined via macros, use the statement form
81 .BI __context__( expression , in_value , out_value )
82 in the body of the macro.
84 With \fB-Wcontext\fR Sparse will warn when it sees a function change the
85 context without indicating this with a \fBcontext\fR attribute, either by
86 decreasing a context below zero (such as by releasing a lock without acquiring
87 it), or returning with a changed context (such as by acquiring a lock without
88 releasing it). Sparse will also warn about blocks of code which may
89 potentially execute with different contexts.
91 Sparse issues these warnings by default. To turn them off, use
96 Warn about any non-\fBstatic\fR variable or function definition that has no
99 Private symbols (functions and variables) internal to a given source file
100 should use \fBstatic\fR, to allow additional compiler optimizations, allow
101 detection of unused symbols, and prevent other code from relying on these
102 internal symbols. Public symbols used by other source files will need
103 declarations visible to those other source files, such as in a header file.
104 All declarations should fall into one of these two categories. Thus, with
105 \fB-Wdecl\fR, Sparse warns about any symbol definition with neither
106 \fBstatic\fR nor a declaration. To fix this warning, declare private symbols
107 \fBstatic\fR, and ensure that the files defining public symbols have the
108 symbol declarations available first (such as by including the appropriate
111 Sparse issues these warnings by default. To turn them off, use
115 .B \-Wdefault\-bitfield\-sign
116 Warn about any bitfield with no explicit signedness.
118 Bitfields have no standard-specified default signedness. (C99 6.7.2) A
119 bitfield without an explicit \fBsigned\fR or \fBunsigned\fR creates a
120 portability problem for software that relies on the available range of values.
121 To fix this, specify the bitfield type as \fBsigned\fR or \fBunsigned\fR
124 Sparse does not issue these warnings by default.
128 Warn about do-while loops that do not delimit the loop body with braces.
130 Sparse does not issue these warnings by default.
134 Warn about the use of an expression of an incorrect \fBenum\fR type when
135 initializing another \fBenum\fR type, assigning to another \fBenum\fR type, or
136 passing an argument to a function which expects another \fBenum\fR type.
138 Sparse issues these warnings by default. To turn them off, use
139 \fB\-Wno\-enum\-mismatch\fR.
142 .B \-Wnon\-pointer\-null
143 Warn about the use of 0 as a NULL pointer.
145 0 has integer type. NULL has pointer type.
147 Sparse issues these warnings by default. To turn them off, use
148 \fB\-Wno\-non\-pointer\-null\fR.
151 .B \-Wold\-initializer
152 Warn about the use of the pre-C99 GCC syntax for designated initializers.
154 C99 provides a standard syntax for designated fields in \fBstruct\fR or
155 \fBunion\fR initializers:
158 struct structname var = { .field = value };
161 GCC also has an old, non-standard syntax for designated initializers which
165 struct structname var = { field: value };
168 Sparse will warn about the use of GCC's non-standard syntax for designated
169 initializers. To fix this warning, convert designated initializers to use the
172 Sparse issues these warnings by default. To turn them off, use
173 \fB\-Wno\-old\-initializer\fR.
176 .B \-Wone\-bit\-signed\-bitfield
177 Warn about any one-bit \fBsigned\fR bitfields.
179 A one-bit \fBsigned\fR bitfield can only have the values 0 and -1, or with
180 some compilers only 0; this results in unexpected behavior for programs which
181 expected the ability to store 0 and 1.
183 Sparse issues these warnings by default. To turn them off, use
184 \fB\-Wno\-one\-bit\-signed\-bitfield\fR.
188 Warn about the use of a parenthesized string to initialize an array.
190 Standard C syntax does not permit a parenthesized string as an array
191 initializer. GCC allows this syntax as an extension. With
192 \fB\-Wparen\-string\fR, Sparse will warn about this syntax.
194 Sparse does not issue these warnings by default.
197 .B \-Wptr\-subtraction\-blows
198 Warn when subtracting two pointers to a type with a non-power-of-two size.
200 Subtracting two pointers to a given type gives a difference in terms of the
201 number of items of that type. To generate this value, compilers will usually
202 need to divide the difference by the size of the type, an potentially
203 expensive operation for sizes other than powers of two.
205 Code written using pointer subtraction can often use another approach instead,
206 such as array indexing with an explicit array index variable, which may allow
207 compilers to generate more efficient code.
209 Sparse does not issue these warnings by default.
213 Warn if a function with return type void returns a void expression.
215 C99 permits this, and in some cases this allows for more generic code in
216 macros that use typeof or take a type as a macro argument. However, some
217 programs consider this poor style, and those programs can use
218 \fB\-Wreturn\-void\fR to get warnings about it.
220 Sparse does not issue these warnings by default.
224 Warn when declaring a symbol which shadows a declaration with the same name in
227 Such declarations can lead to error-prone code.
229 Sparse does not issue these warnings by default.
232 .B \-Wtransparent\-union
233 Warn about any declaration using the GCC extension
234 \fB__attribute__((transparent_union))\fR.
236 Sparse issues these warnings by default. To turn them off, use
237 \fB\-Wno\-transparent\-union\fR.
241 Warn when converting a pointer to an integer type into a pointer to an integer
242 type with different signedness.
244 Sparse does not issue these warnings by default.
248 Warn about preprocessor conditionals that use the value of an undefined
251 Standard C (C99 6.10.1) permits using the value of an undefined preprocessor
252 symbol in preprocessor conditionals, and specifies it has have a value of 0.
253 However, this behavior can lead to subtle errors.
255 Sparse does not issue these warnings by default.
258 http://www.kernel.org/pub/software/devel/sparse/
261 linux-sparse@vger.kernel.org
264 Josh Triplett <josh@kernel.org>