| .\" Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
| .\" See https://llvm.org/LICENSE.txt for license information. |
| .\" SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
| .\" $Id$ |
| .Dd Sep 29, 2021 |
| .Dt SCAN-BUILD 1 |
| .Os "clang" "14" |
| .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 constraint 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 |
| Specify 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 . |