License. See LICENSE.TXT for details.
$Id$
.Dd May 25, 2012 .Dt SCAN-BUILD 1 .Os "clang" "3.5" .Sh NAME .Nm scan-build .Nd Clang static analyzer .Sh SYNOPSIS .Nm .Op Fl ohkvV .Op Fl analyze-headers .Op Fl enable-checker Op Ar checker_name .Op Fl disable-checker Op Ar checker_name .Op Fl Fl help .Op Fl Fl help-checkers .Op Fl Fl html-title Op Ar =title .Op Fl Fl keep-going .Op Fl plist .Op Fl plist-html .Op Fl Fl status-bugs .Op Fl Fl use-c++ Op Ar =compiler_path .Op Fl Fl use-cc Op Ar =compiler_path .Op Fl Fl view .Op Fl constraints Op Ar model .Op Fl maxloop Ar N .Op Fl no-failure-reports .Op Fl stats .Op Fl store Op Ar model .Ar build_command .Op build_options
Sh DESCRIPTION
.Sh DESCRIPTION .Nm is a Perl script that invokes the Clang static analyzer. Options used by .Nm or by the analyzer appear first, followed by the .Ar build_command and any .Ar build_options normally used to build the target system.
p The static analyzer employs a long list of checking algorithms, see .Sx CHECKERS . Output can be written in standard .Li .plist and/or HTML format.
p
The following options are supported:
l -tag -width indent t Fl analyze-headers Also analyze functions in #included files.
t Fl enable-checker Ar checker_name , Fl disable-checker Ar checker_name Enable/disable
.Ar checker_name .
See
.Sx CHECKERS .
t Fl h , Fl Fl help Display this message.
t Fl Fl help-checkers List default checkers, see
.Sx CHECKERS .
t Fl Fl html-title Ns Op = Ns Ar title Specify the title used on generated HTML pages.
A default title is generated if
.Ar title
is not specified.
t Fl k , Fl Fl keep-going Add a
.Dq keep on going
option to
.Ar build_command .
Currently supports make and xcodebuild. This is a convenience option;
one can specify this behavior directly using build options.
t Fl o Target directory for HTML report files. Subdirectories will be
created as needed to represent separate invocations
of the analyzer. If this option is not specified, a directory is
created in /tmp (TMPDIR on Mac OS X) to store the reports.
t Fl plist Output the results as a set of
.Li .plist
files. (By default the output of
.Nm
is a set of HTML files.)
t Fl plist-html Output the results as a set of HTML and .plist files
t Fl Fl status-bugs Set exit status to 1 if it found potential bugs and 0 otherwise. By
default the exit status of
.Nm
is that returned by
.Ar build_command .
t Fl Fl use-c++ Ns Op = Ns Ar compiler_path Guess the default compiler for your C++ and Objective-C++ code. Use this
option to specify an alternate compiler.
t Fl Fl use-cc Ns Op = Ns Ar compiler_path Guess the default compiler for your C and Objective-C code. Use this
option to specify an alternate compiler.
t Fl v Verbose output from
.Nm
and the analyzer. A second and
third
.Ar v
increases verbosity.
t Fl V , Fl Fl view View analysis results in a web browser when the build completes.
t Fl constraints Op Ar model Specify the contraint engine used by the analyzer. By default the
.Ql range
model is used. Specifying
.Ql basic
uses a simpler, less powerful constraint model used by checker-0.160
and earlier.
t Fl maxloop Ar N Specifiy the number of times a block can be visited before giving
up. Default is 4. Increase for more comprehensive coverage at a
cost of speed.
t Fl no-failure-reports Do not create a
.Ql failures
subdirectory that includes analyzer crash reports and preprocessed
source files.
t Fl stats Generates visitation statistics for the project being analyzed.
t Fl store Op Ar model Specify the store model used by the analyzer. By default, the
.Ql region
store model is used.
.Ql region
specifies a field-
sensitive store model. Users can also specify
.Ql basic
which is far less precise but can more quickly analyze code.
.Ql basic
was the default store model for checker-0.221 and earlier.
.El
.Sh EXIT STATUS
.Nm
returns the value returned by
.Ar build_command
unless
.Fl Fl status-bugs
or
.Fl Fl keep-going
is used.
Other sections not yet used ...
.Sh ENVIRONMENT
.Sh FILES
.Sh DIAGNOSTICS
.Sh COMPATIBILITY
.Sh HISTORY
.Sh BUGS
.Sh CHECKERS
The checkers listed below may be enabled/disabled using the
.Fl enable-checker
and
.Fl disable-checker
options.
A default group of checkers is run unless explicitly disabled.
Exactly which checkers constitute the default group is a function
of the operating system in use; they are listed with
.Fl Fl help-checkers .
l -tag -width indent. t core.AdjustedReturnValue Check to see if the return value of a function call is different than
the caller expects (e.g., from calls through function pointers).
t core.AttributeNonNull Check for null pointers passed as arguments to a function whose arguments are marked with the
.Ql nonnull
attribute.
t core.CallAndMessage Check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers).
t core.DivideZero Check for division by zero.
t core.NullDereference Check for dereferences of null pointers.
t core.StackAddressEscape Check that addresses to stack memory do not escape the function.
t core.UndefinedBinaryOperatorResult Check for undefined results of binary operators.
t core.VLASize Check for declarations of VLA of undefined or zero size.
t core.builtin.BuiltinFunctions Evaluate compiler builtin functions, e.g.
.Fn alloca .
t core.builtin.NoReturnFunctions Evaluate
.Ql panic
functions that are known to not return to the caller.
t core.uninitialized.ArraySubscript Check for uninitialized values used as array subscripts.
t core.uninitialized.Assign Check for assigning uninitialized values.
t core.uninitialized.Branch Check for uninitialized values used as branch conditions.
t core.uninitialized.CapturedBlockVariable Check for blocks that capture uninitialized values.
t core.uninitialized.UndefReturn Check for uninitialized values being returned to the caller.
t deadcode.DeadStores Check for values stored to variables that are never read afterwards.
t debug.DumpCFG Display Control-Flow Graphs.
t debug.DumpCallGraph Display Call Graph.
t debug.DumpDominators Print the dominance tree for a given Control-Flow Graph.
t debug.DumpLiveVars Print results of live variable analysis.
t debug.Stats Emit warnings with analyzer statistics.
t debug.TaintTest Mark tainted symbols as such.
t debug.ViewCFG View Control-Flow Graphs using
c GraphViz . t debug.ViewCallGraph View Call Graph using
c GraphViz . t llvm.Conventions Check code for LLVM codebase conventions.
t osx.API Check for proper uses of various Mac OS X APIs.
t osx.AtomicCAS Evaluate calls to
.Vt OSAtomic
functions.
t osx.SecKeychainAPI Check for proper uses of Secure Keychain APIs.
t osx.cocoa.AtSync Check for null pointers used as mutexes for @synchronized.
t osx.cocoa.ClassRelease Check for sending
.Ql retain ,
.Ql release,
or
.Ql autorelease
directly to a Class.
t osx.cocoa.IncompatibleMethodTypes Warn about Objective-C method signatures with type incompatibilities.
t osx.cocoa.NSAutoreleasePool Warn for suboptimal uses of
.Vt NSAutoreleasePool
in Objective-C GC mode.
t osx.cocoa.NSError Check usage of NSError** parameters.
t osx.cocoa.NilArg Check for prohibited nil arguments to Objective-C method calls.
t osx.cocoa.RetainCount Check for leaks and improper reference count management.
t osx.cocoa.SelfInit Check that
.Ql self
is properly initialized inside an initializer method.
t osx.cocoa.UnusedIvars Warn about private ivars that are never used.
t osx.cocoa.VariadicMethodTypes Check for passing non-Objective-C types to variadic methods that expect only Objective-C types.
t osx.coreFoundation.CFError Check usage of CFErrorRef* parameters.
t osx.coreFoundation.CFNumber Check for proper uses of
.Fn CFNumberCreate .
t osx.coreFoundation.CFRetainRelease Check for null arguments to
.Fn CFRetain ,
.Fn CFRelease ,
and
.Fn CFMakeCollectable .
t osx.coreFoundation.containers.OutOfBounds Checks for index out-of-bounds when using the
.Vt CFArray
API.
t osx.coreFoundation.containers.PointerSizedValues Warns if
.Vt CFArray ,
.Vt CFDictionary ,
or
.Vt CFSet
are created with non-pointer-size values.
t security.FloatLoopCounter Warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP).
t security.insecureAPI.UncheckedReturn Warn on uses of functions whose return values must be always checked.
t security.insecureAPI.getpw Warn on uses of
.Fn getpw .
t security.insecureAPI.gets Warn on uses of
.Fn gets .
t security.insecureAPI.mkstemp Warn when
.Fn mkstemp
is passed fewer than 6 X's in the format string.
t security.insecureAPI.mktemp Warn on uses of
.Fn mktemp .
t security.insecureAPI.rand Warn on uses of
.Fn rand ,
.Fn random ,
and related functions.
t security.insecureAPI.strcpy Warn on uses of
.Fn strcpy
and
.Fn strcat .
t security.insecureAPI.vfork Warn on uses of
.Fn vfork .
t unix.API Check calls to various UNIX/Posix functions.
t unix.Malloc Check for memory leaks, double free, and use-after-free.
t unix.cstring.BadSizeArg Check the size argument passed into C string functions for common
erroneous patterns.
t unix.cstring.NullArg Check for null pointers being passed as arguments to C string functions.
.El
.Sh EXAMPLE
c scan-build -o /tmp/myhtmldir make -j4
p The above example causes analysis reports to be deposited into a subdirectory of
a /tmp/myhtmldir and to run c make with the .Fl j4 option. A different subdirectory is created each time .Nm analyzes a project. The analyzer should support most parallel builds, but not distributed builds. .Sh AUTHORS .Nm was written by .An "Ted Kremenek" . Documentation contributed by .An "James K. Lowden" Aq jklowden (at] schemamania.org .
