SCAN-BUILD(1)

📦 version 16.0.6, in debian bookworm, ubuntu noble

✨ SCAN-BUILD — the Clang static analyzer ✨

okay bestie, so this is scan-build, from the General Commands Manual, and it is literally the glow-up your C/C++/Objective-C code has been begging for. it's a Perl script that calls up the Clang static analyzer and lets it go feral on your build. 💅

🌸 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 🦋

scan-build is a Perl script that invokes the Clang static analyzer. no cap. 🧚

the way it works is: all the options meant for scan-build or for the analyzer come first, and then after them you put your build_command plus whatever build_options you'd normally use to build the target system. so it just wraps your build, like a cute little cardigan over a fit that already ate. 🎀

the static analyzer runs a long list of checking algorithms — scroll down for “CHECKERS”. and the output? it can be written in standard .plist and/or HTML format. your choice, your vibe. ✨

the following options are supported:

  • -analyze-headers — also analyze the functions living inside #included files. yes, we're going in there. 🙈
  • -enable-checker checker_name, -disable-checker checker_name — turn checker_name on / off. go look at “CHECKERS” for the whole menu. 🔥
  • -h, --help — display this message. classic.
  • --help-checkers — list the default checkers, see “CHECKERS”. 💜
  • --html-title[=title] — specify the title used on generated HTML pages. if you don't give a title, a default one gets generated for you. so generous. ✨
  • -k, --keep-going — adds a “keep on going” option to build_command. currently supports make and xcodebuild. it's a convenience option, fr — you can just set this behavior yourself directly using build options. 🫶
  • -o — target directory for the HTML report files. subdirectories will be 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. she finds a home either way. 🏠
  • -plist — output the results as a set of .plist files. (by default the output of scan-build is a set of HTML files, iykyk.) 📄
  • -plist-html — output the results as a set of HTML and .plist files. why not both, honestly. 💅
  • --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. go off, -vvv. 💬
  • -V, --view — view analysis results in a web browser when the build completes. main character energy, honestly. 🌐
  • -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 used by checker-0.160 and earlier. vintage, but like, in a weaker way. 🍓
  • -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. bestie, it will be slower, that's the trade. 🐢
  • -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. numbers!! 📊
  • -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. periodt.

👑 CHECKERS 👑

the checkers listed below may be enabled/disabled using the -enable-checker and -disable-checker options. a default group of checkers runs unless you explicitly disable them. exactly which checkers make up the default group is a function of the operating system in use; they are listed with --help-checkers. 🌈

  • 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. pls don't. 💀
  • 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. rip to those values. 🪦
  • 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(). and honestly, good.
  • 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. 😭 so parallel? slay. distributed? absolutely not. 🚫

💖 AUTHORS 💖

scan-build was written by Ted Kremenek. documentation contributed by James K. Lowden <jklowden@schemamania.org>. absolute icons, both of them. 👑

and that's the whole page bestie!! this one's from clang 16, dated Aug 1, 2022 — go forth and let the static analyzer read your code to filth. 🦋✨💅

📦 where this page comes from