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>

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>