diff options
Diffstat (limited to 'tools/scan-build/scan-build.1')
| -rw-r--r-- | tools/scan-build/scan-build.1 | 349 |
1 files changed, 349 insertions, 0 deletions
diff --git a/tools/scan-build/scan-build.1 b/tools/scan-build/scan-build.1 new file mode 100644 index 0000000..0c7ef1d --- /dev/null +++ b/tools/scan-build/scan-build.1 @@ -0,0 +1,349 @@ +.\" This file is distributed under the University of Illinois Open Source +.\" License. See LICENSE.TXT for details. +.\" $Id: scan-build.1 167537 2012-11-07 17:12:37Z jrose $ +.Dd May 25, 2012 +.Dt SCAN-BUILD 1 +.Os "clang" "3.1" +.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. +.Pp +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. +.Pp +The following options are supported: +.Bl -tag -width indent +.It Fl analyze-headers +Also analyze functions in #included files. +.It Fl enable-checker Ar checker_name , Fl disable-checker Ar checker_name +Enable/disable +.Ar checker_name . +See +.Sx CHECKERS . +.It Fl h , Fl Fl help +Display this message. +.It Fl Fl help-checkers +List default checkers, see +.Sx CHECKERS . +.It 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. +.It 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. +.It 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. +.It Fl plist +Output the results as a set of +.Li .plist +files. (By default the output of +.Nm +is a set of HTML files.) +.It Fl plist-html +Output the results as a set of HTML and .plist files +.It 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 . +.It 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. +.It 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. +.It Fl v +Verbose output from +.Nm +and the analyzer. A second and +third +.Ar v +increases verbosity. +.It Fl V , Fl Fl view +View analysis results in a web browser when the build completes. +.It 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. +.It 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. +.It Fl no-failure-reports +Do not create a +.Ql failures +subdirectory that includes analyzer crash reports and preprocessed +source files. +.It Fl stats +Generates visitation statistics for the project being analyzed. +.It 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 . +.Bl -tag -width indent. +.It 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). +.It core.AttributeNonNull +Check for null pointers passed as arguments to a function whose arguments are marked with the +.Ql nonnull +attribute. +.It core.CallAndMessage +Check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers). +.It core.DivideZero +Check for division by zero. +.It core.NullDereference +Check for dereferences of null pointers. +.It core.StackAddressEscape +Check that addresses to stack memory do not escape the function. +.It core.UndefinedBinaryOperatorResult +Check for undefined results of binary operators. +.It core.VLASize +Check for declarations of VLA of undefined or zero size. +.It core.builtin.BuiltinFunctions +Evaluate compiler builtin functions, e.g. +.Fn alloca . +.It core.builtin.NoReturnFunctions +Evaluate +.Ql panic +functions that are known to not return to the caller. +.It core.uninitialized.ArraySubscript +Check for uninitialized values used as array subscripts. +.It core.uninitialized.Assign +Check for assigning uninitialized values. +.It core.uninitialized.Branch +Check for uninitialized values used as branch conditions. +.It core.uninitialized.CapturedBlockVariable +Check for blocks that capture uninitialized values. +.It core.uninitialized.UndefReturn +Check for uninitialized values being returned to the caller. +.It deadcode.DeadStores +Check for values stored to variables that are never read afterwards. +.It debug.DumpCFG +Display Control-Flow Graphs. +.It debug.DumpCallGraph +Display Call Graph. +.It debug.DumpDominators +Print the dominance tree for a given Control-Flow Graph. +.It debug.DumpLiveVars +Print results of live variable analysis. +.It debug.Stats +Emit warnings with analyzer statistics. +.It debug.TaintTest +Mark tainted symbols as such. +.It debug.ViewCFG +View Control-Flow Graphs using +.Ic GraphViz . +.It debug.ViewCallGraph +View Call Graph using +.Ic GraphViz . +.It llvm.Conventions +Check code for LLVM codebase conventions. +.It osx.API +Check for proper uses of various Mac OS X APIs. +.It osx.AtomicCAS +Evaluate calls to +.Vt OSAtomic +functions. +.It osx.SecKeychainAPI +Check for proper uses of Secure Keychain APIs. +.It osx.cocoa.AtSync +Check for null pointers used as mutexes for @synchronized. +.It osx.cocoa.ClassRelease +Check for sending +.Ql retain , +.Ql release, +or +.Ql autorelease +directly to a Class. +.It osx.cocoa.IncompatibleMethodTypes +Warn about Objective-C method signatures with type incompatibilities. +.It osx.cocoa.NSAutoreleasePool +Warn for suboptimal uses of +.Vt NSAutoreleasePool +in Objective-C GC mode. +.It osx.cocoa.NSError +Check usage of NSError** parameters. +.It osx.cocoa.NilArg +Check for prohibited nil arguments to Objective-C method calls. +.It osx.cocoa.RetainCount +Check for leaks and improper reference count management. +.It osx.cocoa.SelfInit +Check that +.Ql self +is properly initialized inside an initializer method. +.It osx.cocoa.UnusedIvars +Warn about private ivars that are never used. +.It osx.cocoa.VariadicMethodTypes +Check for passing non-Objective-C types to variadic methods that expect only Objective-C types. +.It osx.coreFoundation.CFError +Check usage of CFErrorRef* parameters. +.It osx.coreFoundation.CFNumber +Check for proper uses of +.Fn CFNumberCreate . +.It osx.coreFoundation.CFRetainRelease +Check for null arguments to +.Fn CFRetain , +.Fn CFRelease , +and +.Fn CFMakeCollectable . +.It osx.coreFoundation.containers.OutOfBounds +Checks for index out-of-bounds when using the +.Vt CFArray +API. +.It osx.coreFoundation.containers.PointerSizedValues +Warns if +.Vt CFArray , +.Vt CFDictionary , +or +.Vt CFSet +are created with non-pointer-size values. +.It security.FloatLoopCounter +Warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP). +.It security.insecureAPI.UncheckedReturn +Warn on uses of functions whose return values must be always checked. +.It security.insecureAPI.getpw +Warn on uses of +.Fn getpw . +.It security.insecureAPI.gets +Warn on uses of +.Fn gets . +.It security.insecureAPI.mkstemp +Warn when +.Fn mkstemp +is passed fewer than 6 X's in the format string. +.It security.insecureAPI.mktemp +Warn on uses of +.Fn mktemp . +.It security.insecureAPI.rand +Warn on uses of +.Fn rand , +.Fn random , +and related functions. +.It security.insecureAPI.strcpy +Warn on uses of +.Fn strcpy +and +.Fn strcat . +.It security.insecureAPI.vfork +Warn on uses of +.Fn vfork . +.It unix.API +Check calls to various UNIX/Posix functions. +.It unix.Malloc +Check for memory leaks, double free, and use-after-free. +.It unix.cstring.BadSizeArg +Check the size argument passed into C string functions for common +erroneous patterns. +.It unix.cstring.NullArg +Check for null pointers being passed as arguments to C string functions. +.El +.\" +.Sh EXAMPLE +.Ic scan-build -o /tmp/myhtmldir make -j4 +.Pp +The above example causes analysis reports to be deposited into +a subdirectory of +.Pa /tmp/myhtmldir +and to run +.Ic 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@schemamania.org . |