diff options
author | Josh Triplett <josh@freedesktop.org> | 2007-08-31 12:30:42 -0700 |
---|---|---|
committer | Josh Triplett <josh@freedesktop.org> | 2007-08-31 14:06:47 -0700 |
commit | 969858e1c7a6f227d8e897d81e0fbda9b44b9661 (patch) | |
tree | e35317477ab6ec9c562bdac9dd375db9174eb22a /sparse.1 | |
parent | Rename Wcast_to_address_space to Wcast_to_as to match the command-line argument (diff) | |
download | sparse-969858e1c7a6f227d8e897d81e0fbda9b44b9661.tar.gz sparse-969858e1c7a6f227d8e897d81e0fbda9b44b9661.tar.bz2 sparse-969858e1c7a6f227d8e897d81e0fbda9b44b9661.zip |
Add a manpage for sparse
This manpage documents every Sparse warning option and the corresponding
attributes, except that it does not document -Wuninitialized, which only seems
to work with -v, and which references internal Sparse register numbers.
Signed-off-by: Josh Triplett <josh@freedesktop.org>
Diffstat (limited to 'sparse.1')
-rw-r--r-- | sparse.1 | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/sparse.1 b/sparse.1 new file mode 100644 index 0000000..7e0a031 --- /dev/null +++ b/sparse.1 @@ -0,0 +1,264 @@ +.\" Sparse manpage by Josh Triplett +.TH sparse "1" +. +.SH NAME +sparse \- Semantic Parser for C +. +.SH SYNOPSIS +.B sparse +[\fIWARNING OPTIONS\fR]... \fIfile.c\fR +. +.SH DESCRIPTION +Sparse parses C source and looks for errors, producing warnings on standard +error. +.P +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 \fB\-Wsomething\fR. Sparse issues some warnings by default; to turn +off those warnings, pass the negation of the associated warning option, +\fB\-Wno\-something\fR. +. +.SH WARNING OPTIONS +.TP +.B \-Waddress\-space +Warn about code which mixes pointers to different address spaces. + +Sparse allows an extended attribute +.BI __attribute__((address_space( num ))) +on pointers, which designates a pointer target in address space \fInum\fR (a +constant integer). With \fB\-Waddress\-space\fR, 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 \fB__attribute__((force))\fR. + +Sparse issues these warnings by default. To turn them off, use +\fB\-Wno\-address\-space\fR. +. +.TP +.B \-Wbitwise +Warn about unsupported operations or type mismatches with restricted integer +types. + +Sparse supports an extended attribute, \fB__attribute__((bitwise))\fR, 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 \fBtypedef\fR. For example, this allows programs +to create \fBtypedef\fRs for integer types with specific endianness. With +\fB-Wbitwise\fR, 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 +\fB__attribute__((force))\fR. + +Sparse does not issue these warnings by default. +. +.TP +.B \-Wcast\-to\-as +Warn about casts which add an address space to a pointer type. + +A cast that includes \fB__attribute__((force))\fR will suppress this warning. + +Sparse does not issue these warnings by default. +. +.TP +.B \-Wcast\-truncate +Warn about casts that truncate constant values. + +Sparse issues these warnings by default. To turn them off, use +\fB\-Wno\-cast\-truncate\fR. +. +.TP +.B \-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 +.BI __attribute__((context( expression , in_context , out_context )) +require the context \fIexpression\fR (for instance, a lock) to have the value +\fIin_context\fR (a constant nonnegative integer) when called, and return with +the value \fIout_context\fR (a constant nonnegative integer). For APIs +defined via macros, use the statement form +.BI __context__( expression , in_value , out_value ) +in the body of the macro. + +With \fB-Wcontext\fR Sparse will warn when it sees a function change the +context without indicating this with a \fBcontext\fR 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 +\fB\-Wno\-context\fR. +. +.TP +.B \-Wdecl +Warn about any non-\fBstatic\fR variable or function definition that has no +previous declaration. + +Private symbols (functions and variables) internal to a given source file +should use \fBstatic\fR, 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 +\fB-Wdecl\fR, Sparse warns about any symbol definition with neither +\fBstatic\fR nor a declaration. To fix this warning, declare private symbols +\fBstatic\fR, 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 +\fB\-Wno\-decl\fR. +. +.TP +.B \-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 \fBsigned\fR or \fBunsigned\fR creates a +portability problem for software that relies on the available range of values. +To fix this, specify the bitfield type as \fBsigned\fR or \fBunsigned\fR +explicitly. + +Sparse does not issue these warnings by default. +. +.TP +.B \-Wdo\-while +Warn about do-while loops that do not delimit the loop body with braces. + +Sparse does not issue these warnings by default. +. +.TP +.B \-Wenum\-mismatch +Warn about the use of an expression of an incorrect \fBenum\fR type when +initializing another \fBenum\fR type, assigning to another \fBenum\fR type, or +passing an argument to a function which expects another \fBenum\fR type. + +Sparse issues these warnings by default. To turn them off, use +\fB\-Wno\-enum\-mismatch\fR. +. +.TP +.B \-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 +\fB\-Wno\-non\-pointer\-null\fR. +. +.TP +.B \-Wold\-initializer +Warn about the use of the pre-C99 GCC syntax for designated initializers. + +C99 provides a standard syntax for designated fields in \fBstruct\fR or +\fBunion\fR initializers: + +.nf +struct structname var = { .field = value }; +.fi + +GCC also has an old, non-standard syntax for designated initializers which +predates C99: + +.nf +struct structname var = { field: value }; +.fi + +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 +\fB\-Wno\-old\-initializer\fR. +. +.TP +.B \-Wone\-bit\-signed\-bitfield +Warn about any one-bit \fBsigned\fR bitfields. + +A one-bit \fBsigned\fR 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 +\fB\-Wno\-one\-bit\-signed\-bitfield\fR. +. +.TP +.B \-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 +\fB\-Wparen\-string\fR, Sparse will warn about this syntax. + +Sparse does not issue these warnings by default. +. +.TP +.B \-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. +. +.TP +.B \-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 +\fB\-Wreturn\-void\fR to get warnings about it. + +Sparse does not issue these warnings by default. +. +.TP +.B \-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. +. +.TP +.B \-Wtransparent\-union +Warn about any declaration using the GCC extension +\fB__attribute__((transparent_union))\fR. + +Sparse issues these warnings by default. To turn them off, use +\fB\-Wno\-transparent\-union\fR. +. +.TP +.B \-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. +. +.TP +.B \-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. +. +.SH HOMEPAGE +http://www.kernel.org/pub/software/devel/sparse/ +. +.SH MAILING LIST +linux-sparse@vger.kernel.org +. +.SH MAINTAINER +Josh Triplett <josh@kernel.org> |