|
NAME | SYNOPSIS | DESCRIPTION | WARNING OPTIONS | MISC OPTIONS | DEBUG OPTIONS | OTHER OPTIONS | SEE ALSO | HOMEPAGE | MAILING LIST | MAINTAINER | COLOPHON |
sparse(1) General Commands Manual sparse(1)
sparse - Semantic Parser for C
sparse [WARNING OPTIONS]... file.c
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.
-Wsparse-all
Turn on all sparse warnings, except for those explicitly
disabled via -Wno-something.
-Wsparse-error
Turn all sparse warnings into errors.
-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)).
__bitwise ends up being a "stronger integer separation". That
one doesn't allow you to mix with non-bitwise integers, so now
it's much harder to lose the type by mistake.
__bitwise is for *unique types* that cannot be mixed with
other types, and that you'd never want to just use as a random
integer (the integer 0 is special, though, and gets silently
accepted iirc - it's kind of like "NULL" for pointers). So
"gfp_t" or the "safe endianness" types would be __bitwise: you
can only operate on them by doing specific operations that
know about *that* particular type.
Generally, you want bitwise if you are looking for type
safety. 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
the value in_context (a constant nonnegative integer) when
called, and return with the value out_context (a constant
nonnegative integer). For APIs defined via macros, use the
statement form __context__(expression,in_value,out_value) in
the body of the macro.
With -Wcontext Sparse will warn when it sees a function change
the context without indicating this with a 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.
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.
-Wdesignated-init
Warn about positional initialization of structs marked as
requiring designated initializers.
Sparse allows an attribute __attribute__((designated_init))
which marks a struct as requiring designated initializers.
Sparse will warn about positional initialization of a struct
variable or struct literal of a type that has this attribute.
Requiring designated initializers for a particular struct type
will insulate code using that struct type from changes to the
layout of the type, avoiding the need to change initializers
for that type unless they initialize a removed or incompatibly
changed field.
Common examples of this type of struct include collections of
function pointers for the implementations of a class of
related operations, for which the default NULL for an
unmentioned field in a designated initializer will correctly
indicate the absence of that operation.
Sparse issues these warnings by default. To turn them off,
use -Wno-designated-init.
-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.
-Winit-cstring
Warn about initialization of a char array with a too long
constant C string.
If the size of the char array and the length of the string is
the same, there is no space for the last nul char of the
string in the array:
char s[3] = "abc";
If the array is used as a byte array, not as C string, this
warning is just noise. However, if the array is passed to
functions dealing with C string like printf(%s) and strcmp, it
may cause a trouble.
Sparse does not issue these warnings by default.
-Wmemcpy-max-count
Warn about call of memcpy(), memset(), copy_from_user(), or
copy_to_user() with a large compile-time byte count.
Sparse issues these warnings by default. To turn them off, use
-Wno-memcpy-max-count.
The limit can be changed with -fmemcpy-max-count=COUNT, the
default being 100000.
-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.
-Wsizeof-bool
Warn when checking the sizeof a _Bool.
C99 does not specify the sizeof a _Bool. gcc uses 1.
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.
-gcc-base-dir dir
Look for compiler-provided system headers in dir/include/ and
dir/include-fixed/.
-multiarch-dir dir
Look for system headers in the multiarch subdirectory dir.
The dir name would normally take the form of the target's
normalized GNU triplet. (e.g. i386-linux-gnu).
-fdump-linearize[=only]
Dump the IR code of a function directly after its
linearization, before any simplifications is made. If the
argument =only is also given no further processing is done on
the function. -fmem-report Report some statistics about
memory allocation used by the tool.
-fmemcpy-max-count=COUNT
Set the limit for the warnings given by -Wmemcpy-max-count. A
COUNT of 0, useless in itself, will effectively disable the
warning. The default limit is 100000.
-ftabstop=WIDTH
Set the distance between tab stops. This helps sparse report
correct column numbers in warnings or errors. If the value is
less than 1 or greater than 100, the option is ignored. The
default is 8.
cgcc(1)
http://www.kernel.org/pub/software/devel/sparse/
linux-sparse@vger.kernel.org
Christopher Li <sparse@chrisli.org>
This page is part of the sparse (a Semantic Parser for C) project.
Information about the project can be found at
⟨https://sparse.wiki.kernel.org/⟩. If you have a bug report for this
manual page, send it to linux-sparse@vger.kernel.org. This page was
obtained from the project's upstream Git repository
⟨https://git.kernel.org/pub/scm/devel/sparse/sparse.git⟩ on
2017-07-05. If you discover any rendering problems in this HTML ver‐
sion of the page, or you believe there is a better or more up-to-date
source for the page, or you have corrections or improvements to the
information in this COLOPHON (which is not part of the original man‐
ual page), send a mail to man-pages@man7.org
sparse(1)
Pages that refer to this page: cgcc(1)