SCAN-BUILD(1)

📦 version 18.1.8, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 SCAN-BUILD — the scan-build(1) page, but make it a vibe 💅

okay bestie, sit down, we're doing a General Commands Manual moment and honestly? it's iconic. this is the scan-build page, and no cap, it's literally the Clang static analyzer — the thing that reads your code and goes "girl…" 💀

✨ NAME ✨

scan-build — Clang static analyzer 🦋

🎀 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]

like… she has RANGE 💅

🌸 DESCRIPTION 🌸

scan-build is a Perl script that invokes the Clang static analyzer. the whole deal is: you give her your options, she gives you the analysis. so the options that scan-build or the analyzer use come first, and then you drop in the build_command plus any build_options you'd normally use to build the target system. periodt ✨

the static analyzer runs a whole long list of checking algorithms, so go peek at “CHECKERS” for that. and the output? she can write it in standard .plist and/or HTML format, your choice, your era 🫶

here's the tea on the options that are supported:

  • -analyze-headers — also analyze functions inside files that got #included. yep, she goes there 💖
  • -enable-checker checker_name, -disable-checker checker_name — turn checker_name on, or turn it off. check “CHECKERS” for the whole roster 👑
  • -h, --help — display this message. hi, that's the one you're reading 🎀
  • --help-checkers — list the default checkers, see “CHECKERS”. the default squad, if you will 💅
  • --html-title[=*title*] — specify the title used on the generated HTML pages. if you don't hand over a title, a default title gets generated for you, no stress ✨
  • -k, --keep-going — adds a “keep on going” option to build_command. currently this supports make and xcodebuild. it's a convenience option, bestie — you could just specify this behavior directly using build options if you wanted 🦋
  • -o — the 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 gets 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, so this is you switching up the fit 💅)
  • -plist-html — output the results as a set of HTML and .plist files. why choose one 💖
  • --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. so this one is her taking the wheel 🔥
  • --use-c++[=*compiler_path*] — guess the default compiler for your C++ and Objective-C++ code. use this option to specify an alternate compiler, iykyk 👑
  • --use-cc[=*compiler_path*] — guess the default compiler for your C and Objective-C code. use this option to specify an alternate compiler, same energy 💜
  • -v — verbose output from scan-build and the analyzer. a second and third v increases verbosity. stack 'em, girl 😭
  • -V, --view — view analysis results in a web browser when the build completes. main character reveal 🎀
  • -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. vintage, but like, in a limited 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. more thorough, less fast, the eternal tradeoff ✨
  • -no-failure-reports — do not create a ‘failures’ subdirectory that includes analyzer crash reports and preprocessed source files. sometimes you just don't want the receipts 🙈
  • -stats — generates visitation statistics for the project being analyzed. numbers, but make it gossip 💅
  • -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. so basically ‘region’ is the glow-up 🌸

💀 EXIT STATUS 💀

scan-build returns the value returned by build_command — unless --status-bugs or --keep-going is used, in which case she's got opinions of her own. periodt.

👑 CHECKERS 👑

okay so the checkers listed below may be enabled/disabled using the -enable-checker and -disable-checker options. a default group of checkers gets run unless you explicitly disable them. exactly which checkers make up that default group is a function of the operating system in use, and you can see them listed with --help-checkers. go off, OS-dependent queen 🦋

  • 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). the audacity 💀
  • core.AttributeNonNull — check for null pointers passed as arguments to a function whose arguments are marked with the ‘nonnull’ attribute. she said no nulls, and she meant it 💅
  • core.CallAndMessage — check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers). mess detected 😭
  • core.DivideZero — check for division by zero. math said absolutely not 🎀
  • core.NullDereference — check for dereferences of null pointers. the classic. the legend. the thing that ends careers 🙈
  • core.StackAddressEscape — check that addresses to stack memory do not escape the function. stay in your lane, address 💜
  • core.UndefinedBinaryOperatorResult — check for undefined results of binary operators. undefined behavior is not a personality ✨
  • core.VLASize — check for declarations of VLA of undefined or zero size. girl, what size 💀
  • core.builtin.BuiltinFunctions — evaluate compiler builtin functions, e.g. alloca(). builtin behavior, evaluated 🌸
  • core.builtin.NoReturnFunctions — evaluate ‘panic’ functions that are known to not return to the caller. they're not coming back, bestie 😭
  • core.uninitialized.ArraySubscript — check for uninitialized values used as array subscripts. indexing with vibes only, and that's the problem 🔥
  • core.uninitialized.Assign — check for assigning uninitialized values. she clocked it 👑
  • core.uninitialized.Branch — check for uninitialized values used as branch conditions. your if-statement is running on nothing 💅
  • core.uninitialized.CapturedBlockVariable — check for blocks that capture uninitialized values. the block said 👀
  • core.uninitialized.UndefReturn — check for uninitialized values being returned to the caller. returning mystery, iconic but bad 🎀
  • deadcode.DeadStores — check for values stored to variables that are never read afterwards. written and never read… not even the group chat 😭
  • debug.DumpCFG — display Control-Flow Graphs. the graph, dumped 🦋
  • debug.DumpCallGraph — display Call Graph. same energy, call edition 💜
  • debug.DumpDominators — print the dominance tree for a given Control-Flow Graph. she's printing the dominance tree, and honestly? dominating 🌈
  • debug.DumpLiveVars — print results of live variable analysis. live vars, live results ✨
  • debug.Stats — emit warnings with analyzer statistics. stats but with a warning attached 💅
  • debug.TaintTest — mark tainted symbols as such. label it, bestie 🏷️
  • debug.ViewCFG — view Control-Flow Graphs using GraphViz. now you can actually look at it 👑
  • debug.ViewCallGraph — view Call Graph using GraphViz. same, but calls 🎀
  • llvm.Conventions — check code for LLVM codebase conventions. dress code enforcement, but for code 🌸
  • osx.API — check for proper uses of various Mac OS X APIs. Apple said use me correctly 💅
  • osx.AtomicCAS — evaluate calls to OSAtomic functions. atomic, evaluated ⚛️
  • osx.SecKeychainAPI — check for proper uses of Secure Keychain APIs. keychain etiquette, no cap 🔐
  • osx.cocoa.AtSync — check for null pointers used as mutexes for @synchronized. synchronizing on nothing? ma'am 💀
  • osx.cocoa.ClassRelease — check for sending ‘retain’, ‘release,’ or ‘autorelease’ directly to a Class. class, not instance, bestie 😭
  • osx.cocoa.IncompatibleMethodTypes — warn about Objective-C method signatures with type incompatibilities. the types do not match and it shows 🙈
  • osx.cocoa.NSAutoreleasePool — warn for suboptimal uses of NSAutoreleasePool in Objective-C GC mode. suboptimal. she said it, not me 💅
  • osx.cocoa.NSError — check usage of NSError** parameters. two stars, one responsibility ✨
  • osx.cocoa.NilArg — check for prohibited nil arguments to Objective-C method calls. nil is not welcome here 🎀
  • osx.cocoa.RetainCount — check for leaks and improper reference count management. the reference counts are NOT counting correctly 😭
  • osx.cocoa.SelfInit — check that ‘self’ is properly initialized inside an initializer method. self-care, literally 🫶
  • osx.cocoa.UnusedIvars — warn about private ivars that are never used. a private ivar nobody reads… relatable 🙈
  • osx.cocoa.VariadicMethodTypes — check for passing non-Objective-C types to variadic methods that expect only Objective-C types. variadic said ObjC only 💜
  • osx.coreFoundation.CFError — check usage of CFErrorRef* parameters. errors, but handled with respect 🌸
  • osx.coreFoundation.CFNumber — check for proper uses of CFNumberCreate(). create her correctly or not at all 💅
  • osx.coreFoundation.CFRetainRelease — check for null arguments to CFRetain(), CFRelease(), and CFMakeCollectable(). null in, chaos out 🔥
  • osx.coreFoundation.containers.OutOfBounds — checks for index out-of-bounds when using the CFArray API. out of bounds means out of the group chat 💀
  • osx.coreFoundation.containers.PointerSizedValues — warns if CFArray, CFDictionary, or CFSet are created with non-pointer-size values. pointer-sized or nothing 👑
  • security.FloatLoopCounter — warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP). floats and loop counters? no ma'am, CERT said so too 😭
  • security.insecureAPI.UncheckedReturn — warn on uses of functions whose return values must be always checked. always checked. ALWAYS 🚨
  • security.insecureAPI.getpw — warn on uses of getpw(). insecure, flagged ✨
  • security.insecureAPI.gets — warn on uses of gets(). girl. gets(). you know better 💀
  • security.insecureAPI.mkstemp — warn when mkstemp() is passed fewer than 6 X's in the format string. count your X's, bestie, all six of them 💅
  • security.insecureAPI.mktemp — warn on uses of mktemp(). insecure, flagged 🎀
  • security.insecureAPI.rand — warn on uses of rand(), random(), and related functions. randomness said not like this 🌸
  • security.insecureAPI.strcpy — warn on uses of strcpy() and strcat(). the classics that ruin everything 😭
  • security.insecureAPI.vfork — warn on uses of vfork(). flagged, warned, noted 🦋
  • unix.API — check calls to various UNIX/Posix functions. unix said use me properly 💜
  • unix.Malloc — check for memory leaks, double free, and use-after-free. the holy trinity of pain 🙈
  • unix.cstring.BadSizeArg — check the size argument passed into C string functions for common erroneous patterns. size matters, and she's checking 🔥
  • unix.cstring.NullArg — check for null pointers being passed as arguments to C string functions. null args, denied ✨

🌈 EXAMPLE 🌈

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

so what's happening here: the above example causes analysis reports to be deposited into a subdirectory of /tmp/myhtmldir, and runs make with the -j4 option. a different subdirectory is created each time scan-build analyzes a project. and the analyzer should support most parallel builds — but not distributed builds. parallel yes, distributed no, know the difference bestie 💅

🫶 AUTHORS 🫶

scan-build was written by Ted Kremenek. documentation contributed by James K. Lowden <jklowden@schemamania.org>. legends, both of them, we thank them for their service 👑

and that's the whole page, bestie — every flag, every checker, every vibe, preserved exactly. go forth and analyze ✨

this was clang 18, dated Sep 21, 2023 — SCAN-BUILD(1), signing off 💖

📦 where this page comes from