SCAN-BUILD(1)

🌸 NAME 🌸

scan-build — the Clang static analyzer. That's her. That's the whole name, periodt 💅 (and yeah, she lives in the General Commands Manual, section 1, iykyk)

✨ SYNOPSIS ✨

scan-build [-ohkvV] [-analyze-headers] [-enable-checker [checker_name]]
           [-disable-checker [checker_name]] [--help] [--help-checkers]
           [--html-title [=title]] [--keep-going] [-plist] [-plist-html]
           [--status-bugs] [--use-c++ [=compiler_path]]
           [--use-cc [=compiler_path]] [--view] [-constraints [model]]
           [-maxloop N] [-no-failure-reports] [-stats] [-store [model]]
           build_command [build_options]

🦋 DESCRIPTION 🦋

okay so scan-build is a Perl script that invokes the Clang static analyzer. That's the whole vibe. The options meant for scan-build itself (or for the analyzer) come first, and then after all of those you put your build_command plus any build_options you'd normally use to build the target system. Simple as that 🫶

The static analyzer runs a long list of checking algorithms — go peek at CHECKERS for the whole roster. Output can be written in standard .plist format and/or HTML format, your choice bestie ✨

🎀 the options (yes, all of them) 🎀

The following options are supported:

• -analyze-headers — also analyze functions inside #included files. yes, go deeper 🔍
• -enable-checker checker_name, -disable-checker checker_name — turn checker_name on or off. See CHECKERS for the menu 💖
• -h, --help — display this message.
• --help-checkers — list the default checkers. See CHECKERS.
• --html-title[=title] — specify the title used on generated HTML pages. If you don't pass title, a default title gets generated for you, no stress ✨
• -k, --keep-going — adds a “keep on going” option to build_command. Currently supports make and xcodebuild. It's a convenience option — you can absolutely just specify this behavior directly using build options if that's your thing.
• -o — target directory for HTML report files. Subdirectories get created as needed to represent separate invocations of the analyzer. If you don't specify this option, a directory is created in /tmp (TMPDIR on Mac OS X) to store the reports.
• -plist — output the results as a set of .plist files. (By default the output of scan-build is a set of HTML files, jsyk.)
• -plist-html — output the results as a set of HTML and .plist files. both. greedy. iconic 👑
• --status-bugs — set exit status to 1 if it found potential bugs and 0 otherwise. By default the exit status of scan-build is whatever build_command returned.
• --use-c++[=compiler_path] — guess the default compiler for your C++ and Objective-C++ code. Use this option to specify an alternate compiler.
• --use-cc[=compiler_path] — guess the default compiler for your C and Objective-C code. Use this option to specify an alternate compiler.
• -v — verbose output from scan-build and the analyzer. A second and third v increases verbosity. v, vv, vvv — the escalation we deserve 🗣️
• -V, --view — view analysis results in a web browser when the build completes.
• -constraints [model] — specify the constraint engine used by the analyzer. By default the range model is used. Specifying basic uses a simpler, less powerful constraint model — the one used by checker-0.160 and earlier.
• -maxloop N — specify the number of times a block can be visited before giving up. Default is 4. Increase it for more comprehensive coverage, at a cost of speed. (trade-offs, always trade-offs 😭)
• -no-failure-reports — do not create a failures subdirectory that includes analyzer crash reports and preprocessed source files.
• -stats — generates visitation statistics for the project being analyzed.
• -store [model] — specify the store model used by the analyzer. By default, the region store model is used. region specifies a field-sensitive store model. Users can also specify basic, which is far less precise but can more quickly analyze code. basic was the default store model for checker-0.221 and earlier.

💀 EXIT STATUS 💀

scan-build returns the value returned by build_command — unless --status-bugs or --keep-going is used. Then all bets are off and the rules change, so read the option list again, bestie 🙈

👑 CHECKERS 👑

The checkers listed below may be enabled/disabled using the -enable-checker and -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 --help-checkers. So if you're wondering "wait, which ones are actually on right now" — that's the command, go ask her 💅

• 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).
• core.AttributeNonNull — check for null pointers passed as arguments to a function whose arguments are marked with the nonnull attribute.
• core.CallAndMessage — check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers).
• core.DivideZero — check for division by zero.
• core.NullDereference — check for dereferences of null pointers.
• core.StackAddressEscape — check that addresses to stack memory do not escape the function.
• core.UndefinedBinaryOperatorResult — check for undefined results of binary operators.
• core.VLASize — check for declarations of VLA of undefined or zero size.
• core.builtin.BuiltinFunctions — evaluate compiler builtin functions, e.g. alloca().
• core.builtin.NoReturnFunctions — evaluate panic functions that are known to not return to the caller.
• core.uninitialized.ArraySubscript — check for uninitialized values used as array subscripts.
• core.uninitialized.Assign — check for assigning uninitialized values.
• core.uninitialized.Branch — check for uninitialized values used as branch conditions.
• core.uninitialized.CapturedBlockVariable — check for blocks that capture uninitialized values.
• core.uninitialized.UndefReturn — check for uninitialized values being returned to the caller.
• deadcode.DeadStores — check for values stored to variables that are never read afterwards.
• debug.DumpCFG — display Control-Flow Graphs.
• debug.DumpCallGraph — display Call Graph.
• debug.DumpDominators — print the dominance tree for a given Control-Flow Graph.
• debug.DumpLiveVars — print results of live variable analysis.
• debug.Stats — emit warnings with analyzer statistics.
• debug.TaintTest — mark tainted symbols as such.
• debug.ViewCFG — view Control-Flow Graphs using GraphViz.
• debug.ViewCallGraph — view Call Graph using GraphViz.
• llvm.Conventions — check code for LLVM codebase conventions.
• osx.API — check for proper uses of various Mac OS X APIs.
• osx.AtomicCAS — evaluate calls to OSAtomic functions.
• osx.SecKeychainAPI — check for proper uses of Secure Keychain APIs.
• osx.cocoa.AtSync — check for null pointers used as mutexes for @synchronized.
• osx.cocoa.ClassRelease — check for sending retain, release, or autorelease directly to a Class.
• osx.cocoa.IncompatibleMethodTypes — warn about Objective-C method signatures with type incompatibilities.
• osx.cocoa.NSAutoreleasePool — warn for suboptimal uses of NSAutoreleasePool in Objective-C GC mode.
• osx.cocoa.NSError — check usage of NSError** parameters.
• osx.cocoa.NilArg — check for prohibited nil arguments to Objective-C method calls.
• osx.cocoa.RetainCount — check for leaks and improper reference count management.
• osx.cocoa.SelfInit — check that self is properly initialized inside an initializer method.
• osx.cocoa.UnusedIvars — warn about private ivars that are never used.
• osx.cocoa.VariadicMethodTypes — check for passing non-Objective-C types to variadic methods that expect only Objective-C types.
• osx.coreFoundation.CFError — check usage of CFErrorRef* parameters.
• osx.coreFoundation.CFNumber — check for proper uses of CFNumberCreate().
• osx.coreFoundation.CFRetainRelease — check for null arguments to CFRetain(), CFRelease(), and CFMakeCollectable().
• osx.coreFoundation.containers.OutOfBounds — checks for index out-of-bounds when using the CFArray API.
• osx.coreFoundation.containers.PointerSizedValues — warns if CFArray, CFDictionary, or CFSet are created with non-pointer-size values.
• security.FloatLoopCounter — warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP).
• security.insecureAPI.UncheckedReturn — warn on uses of functions whose return values must be always checked.
• security.insecureAPI.getpw — warn on uses of getpw().
• security.insecureAPI.gets — warn on uses of gets().
• security.insecureAPI.mkstemp — warn when mkstemp() is passed fewer than 6 X's in the format string.
• security.insecureAPI.mktemp — warn on uses of mktemp().
• security.insecureAPI.rand — warn on uses of rand(), random(), and related functions.
• security.insecureAPI.strcpy — warn on uses of strcpy() and strcat().
• security.insecureAPI.vfork — warn on uses of vfork().
• unix.API — check calls to various UNIX/Posix functions.
• unix.Malloc — check for memory leaks, double free, and use-after-free.
• unix.cstring.BadSizeArg — check the size argument passed into C string functions for common erroneous patterns.
• unix.cstring.NullArg — check for null pointers being passed as arguments to C string functions.

🌈 EXAMPLE 🌈

scan-build -o /tmp/myhtmldir make -j4

The above example causes analysis reports to be deposited into a subdirectory of /tmp/myhtmldir and to run make with the -j4 option. A different subdirectory is created each time scan-build analyzes a project. The analyzer should support most parallel builds, but not distributed builds.

ok real talk: parallel builds? mostly yes bestie 🫶. distributed builds? absolutely not, don't even try it 💀

💜 AUTHORS 💜

scan-build was written by Ted Kremenek. Documentation contributed by James K. Lowden <jklowden@schemamania.org>.

and that's the whole page, bestie 🎀 this was clang 20, dated Aug 18, 2024, and it's the SCAN-BUILD(1) page — go analyze something and make it slay ✨🦋💖