NAME
sparse - Semantic Parser for C
SYNOPSIS
sparse [WARNING OPTIONS]... file.c
DESCRIPTION
Sparse parses C source and looks for errors, producing warnings on
standard error.
Sparse accepts options controlling the set of warnings to generate. To
turn on warnings Sparse does not issue by default, use the
corresponding warning option -Wsomething. Sparse issues some warnings
by default; to turn off those warnings, pass the negation of the
associated warning option, -Wno-something.
WARNING OPTIONS
-Waddress-space
Warn about code which mixes pointers to different address
spaces.
Sparse allows an extended attribute
__attribute__((address_space(num))) on pointers, which
designates a pointer target in address space num (a constant
integer). With -Waddress-space, Sparse treats pointers with
identical target types but different address spaces as distinct
types. To override this warning, such as for functions which
convert pointers between address spaces, use a type that
includes __attribute__((force)).
Sparse issues these warnings by default. To turn them off, use
-Wno-address-space.
-Wbitwise
Warn about unsupported operations or type mismatches with
restricted integer types.
Sparse supports an extended attribute, __attribute__((bitwise)),
which creates a new restricted integer type from a base integer
type, distinct from the base integer type and from any other
restricted integer type not declared in the same declaration or
typedef. For example, this allows programs to create typedefs
for integer types with specific endianness. With -Wbitwise,
Sparse will warn on any use of a restricted type in arithmetic
operations other than bitwise operations, and on any conversion
of one restricted type into another, except via a cast that
includes __attribute__((force)).
Sparse does not issue these warnings by default.
-Wcast-to-as
Warn about casts which add an address space to a pointer type.
A cast that includes __attribute__((force)) will suppress this
warning.
Sparse does not issue these warnings by default.
-Wcast-truncate
Warn about casts that truncate constant values.
Sparse issues these warnings by default. To turn them off, use
-Wno-cast-truncate.
-Wcontext
Warn about potential errors in synchronization or other
delimited contexts.
Sparse supports several means of designating functions or
statements that delimit contexts, such as synchronization.
Functions with the extended attribute
__attribute__((context([expression,]in_context,out_context))
require the context expression (for instance, a lock) to have at
least the value in_context (a constant nonnegative integer) when
called, and return with the value adjusted by out_context -
in_context (where out_context is a constant nonnegative
integer). To change the value of a context (for example in
macros), use the statement
__context__([expression,]adjust_value[,required]) where
adjust_value is a constant integer and required is a constant
nonnegative integer. Not giving required is equivalent to giving
zero and means that the statement does not need the context as a
precondition, when given it means that the context must at least
have the value of required.
To indicate that a function requires exactly a certain lock
context (not "at least" as above), use the form
__attribute__((exact_context([expression,]in_context,out_context))
There currently is no corresponding
__exact_context__([expression,]adjust_value[,required])
statement.
To indicate that a certain function acquires a context depending
on its return value, use
__attribute__((conditional_context([expression,]in_context,out_success,out_failure))
where out_success and out_failure indicate the context change
done depending on success (non-zero) or failure (zero) return of
the function. Note that currently, using this attribute on a
function means that the function itself won’t be checked for
context handling at all. See the testsuite for examples.
Sparse will warn when it sees a function change a context
without indicating this with a context or exact_context
attribute, either by decreasing a context below zero (such as by
releasing a lock without acquiring it), or returning with a
changed context (such as by acquiring a lock without releasing
it). Sparse will also warn about blocks of code which may
potentially execute with different contexts and about functions
that are executed without a lock they require.
Sparse issues these warnings by default. To turn them off, use
-Wno-context.
-Wdecl Warn about any non-static variable or function definition that
has no previous declaration.
Private symbols (functions and variables) internal to a given
source file should use static, to allow additional compiler
optimizations, allow detection of unused symbols, and prevent
other code from relying on these internal symbols. Public
symbols used by other source files will need declarations
visible to those other source files, such as in a header file.
All declarations should fall into one of these two categories.
Thus, with -Wdecl, Sparse warns about any symbol definition with
neither static nor a declaration. To fix this warning, declare
private symbols static, and ensure that the files defining
public symbols have the symbol declarations available first
(such as by including the appropriate header file).
Sparse issues these warnings by default. To turn them off, use
-Wno-decl.
-Wdeclaration-after-statement
Warn about declarations that are not at the start of a block.
These declarations are permitted in C99 but not in C89.
Sparse issues these warnings by default only when the C dialect
is C89 (i.e. -ansi or -std=c89). To turn them off, use
-Wno-declaration-after-statement.
-Wdefault-bitfield-sign
Warn about any bitfield with no explicit signedness.
Bitfields have no standard-specified default signedness. (C99
6.7.2) A bitfield without an explicit signed or unsigned creates
a portability problem for software that relies on the available
range of values. To fix this, specify the bitfield type as
signed or unsigned explicitly.
Sparse does not issue these warnings by default.
-Wdo-while
Warn about do-while loops that do not delimit the loop body with
braces.
Sparse does not issue these warnings by default.
-Wenum-mismatch
Warn about the use of an expression of an incorrect enum type
when initializing another enum type, assigning to another enum
type, or passing an argument to a function which expects another
enum type.
Sparse issues these warnings by default. To turn them off, use
-Wno-enum-mismatch.
-Wnon-pointer-null
Warn about the use of 0 as a NULL pointer.
0 has integer type. NULL has pointer type.
Sparse issues these warnings by default. To turn them off, use
-Wno-non-pointer-null.
-Wold-initializer
Warn about the use of the pre-C99 GCC syntax for designated
initializers.
C99 provides a standard syntax for designated fields in struct
or union initializers:
struct structname var = { .field = value };
GCC also has an old, non-standard syntax for designated
initializers which predates C99:
struct structname var = { field: value };
Sparse will warn about the use of GCC’s non-standard syntax for
designated initializers. To fix this warning, convert
designated initializers to use the standard C99 syntax.
Sparse issues these warnings by default. To turn them off, use
-Wno-old-initializer.
-Wone-bit-signed-bitfield
Warn about any one-bit signed bitfields.
A one-bit signed bitfield can only have the values 0 and -1, or
with some compilers only 0; this results in unexpected behavior
for programs which expected the ability to store 0 and 1.
Sparse issues these warnings by default. To turn them off, use
-Wno-one-bit-signed-bitfield.
-Wparen-string
Warn about the use of a parenthesized string to initialize an
array.
Standard C syntax does not permit a parenthesized string as an
array initializer. GCC allows this syntax as an extension.
With -Wparen-string, Sparse will warn about this syntax.
Sparse does not issue these warnings by default.
-Wptr-subtraction-blows
Warn when subtracting two pointers to a type with a non-power-
of-two size.
Subtracting two pointers to a given type gives a difference in
terms of the number of items of that type. To generate this
value, compilers will usually need to divide the difference by
the size of the type, an potentially expensive operation for
sizes other than powers of two.
Code written using pointer subtraction can often use another
approach instead, such as array indexing with an explicit array
index variable, which may allow compilers to generate more
efficient code.
Sparse does not issue these warnings by default.
-Wreturn-void
Warn if a function with return type void returns a void
expression.
C99 permits this, and in some cases this allows for more generic
code in macros that use typeof or take a type as a macro
argument. However, some programs consider this poor style, and
those programs can use -Wreturn-void to get warnings about it.
Sparse does not issue these warnings by default.
-Wshadow
Warn when declaring a symbol which shadows a declaration with
the same name in an outer scope.
Such declarations can lead to error-prone code.
Sparse does not issue these warnings by default.
-Wtransparent-union
Warn about any declaration using the GCC extension
__attribute__((transparent_union)).
Sparse issues these warnings by default. To turn them off, use
-Wno-transparent-union.
-Wtypesign
Warn when converting a pointer to an integer type into a pointer
to an integer type with different signedness.
Sparse does not issue these warnings by default.
-Wundef
Warn about preprocessor conditionals that use the value of an
undefined preprocessor symbol.
Standard C (C99 6.10.1) permits using the value of an undefined
preprocessor symbol in preprocessor conditionals, and specifies
it has have a value of 0. However, this behavior can lead to
subtle errors.
Sparse does not issue these warnings by default.
MISC OPTIONS
-gcc-base-dir dir
Look for compiler-provided system headers in dir/include/ and
dir/include-fixed/.
SEE ALSO
cgcc(1)
HOMEPAGE
http://www.kernel.org/pub/software/devel/sparse/
MAILING LIST
linux-sparse@vger.kernel.org
MAINTAINER
Josh Triplett <josh@kernel.org>
sparse(1)