351 lines · plain
1.\" Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.2.\" See https://llvm.org/LICENSE.txt for license information.3.\" SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception4.\" $Id$5.Dd Aug 18, 20246.Dt SCAN-BUILD 17.Os "clang" "20"8.Sh NAME9.Nm scan-build10.Nd Clang static analyzer11.Sh SYNOPSIS12.Nm13.Op Fl ohkvV14.Op Fl analyze-headers15.Op Fl enable-checker Op Ar checker_name16.Op Fl disable-checker Op Ar checker_name17.Op Fl Fl help18.Op Fl Fl help-checkers19.Op Fl Fl html-title Op Ar =title20.Op Fl Fl keep-going21.Op Fl plist22.Op Fl plist-html23.Op Fl Fl status-bugs24.Op Fl Fl use-c++ Op Ar =compiler_path25.Op Fl Fl use-cc Op Ar =compiler_path26.Op Fl Fl view27.Op Fl constraints Op Ar model28.Op Fl maxloop Ar N29.Op Fl no-failure-reports30.Op Fl stats31.Op Fl store Op Ar model32.Ar build_command33.Op build_options34.\"35.\" Sh DESCRIPTION36.Sh DESCRIPTION37.Nm38is a Perl script that invokes the Clang static analyzer. Options used by39.Nm40or by the analyzer appear first, followed by the41.Ar build_command42and any43.Ar build_options44normally used to build the target system.45.Pp46The static analyzer employs a long list of checking algorithms, see47.Sx CHECKERS .48Output can be written in standard49.Li .plist50and/or HTML format.51.Pp52The following options are supported:53.Bl -tag -width indent54.It Fl analyze-headers55Also analyze functions in #included files.56.It Fl enable-checker Ar checker_name , Fl disable-checker Ar checker_name57Enable/disable58.Ar checker_name .59See60.Sx CHECKERS .61.It Fl h , Fl Fl help62Display this message.63.It Fl Fl help-checkers64List default checkers, see65.Sx CHECKERS .66.It Fl Fl html-title Ns Op = Ns Ar title67Specify the title used on generated HTML pages.68A default title is generated if69.Ar title70is not specified.71.It Fl k , Fl Fl keep-going72Add a73.Dq keep on going74option to75.Ar build_command .76Currently supports make and xcodebuild. This is a convenience option;77one can specify this behavior directly using build options.78.It Fl o79Target directory for HTML report files. Subdirectories will be80created as needed to represent separate invocations81of the analyzer. If this option is not specified, a directory is82created in /tmp (TMPDIR on Mac OS X) to store the reports.83.It Fl plist84Output the results as a set of85.Li .plist86files. (By default the output of87.Nm88is a set of HTML files.)89.It Fl plist-html90Output the results as a set of HTML and .plist files91.It Fl Fl status-bugs92Set exit status to 1 if it found potential bugs and 0 otherwise. By93default the exit status of94.Nm95is that returned by96.Ar build_command .97.It Fl Fl use-c++ Ns Op = Ns Ar compiler_path98Guess the default compiler for your C++ and Objective-C++ code. Use this99option to specify an alternate compiler.100.It Fl Fl use-cc Ns Op = Ns Ar compiler_path101Guess the default compiler for your C and Objective-C code. Use this102option to specify an alternate compiler.103.It Fl v104Verbose output from105.Nm106and the analyzer. A second and107third108.Ar v109increases verbosity.110.It Fl V , Fl Fl view111View analysis results in a web browser when the build completes.112.It Fl constraints Op Ar model113Specify the constraint engine used by the analyzer. By default the114.Ql range115model is used. Specifying116.Ql basic117uses a simpler, less powerful constraint model used by checker-0.160118and earlier.119.It Fl maxloop Ar N120Specify the number of times a block can be visited before giving121up. Default is 4. Increase for more comprehensive coverage at a122cost of speed.123.It Fl no-failure-reports124Do not create a125.Ql failures126subdirectory that includes analyzer crash reports and preprocessed127source files.128.It Fl stats129Generates visitation statistics for the project being analyzed.130.It Fl store Op Ar model131Specify the store model used by the analyzer. By default, the132.Ql region133store model is used.134.Ql region135specifies a field-136sensitive store model. Users can also specify137.Ql basic138which is far less precise but can more quickly analyze code.139.Ql basic140was the default store model for checker-0.221 and earlier.141.\"142.El143.Sh EXIT STATUS144.Nm145returns the value returned by146.Ar build_command147unless148.Fl Fl status-bugs149or150.Fl Fl keep-going151is used.152.\"153.\" Other sections not yet used ...154.\" .Sh ENVIRONMENT155.\" .Sh FILES156.\" .Sh DIAGNOSTICS157.\" .Sh COMPATIBILITY158.\" .Sh HISTORY159.\" .Sh BUGS160.\"161.Sh CHECKERS162The checkers listed below may be enabled/disabled using the163.Fl enable-checker164and165.Fl disable-checker166options.167A default group of checkers is run unless explicitly disabled.168Exactly which checkers constitute the default group is a function169of the operating system in use; they are listed with170.Fl Fl help-checkers .171.Bl -tag -width indent.172.It core.AdjustedReturnValue173Check to see if the return value of a function call is different than174the caller expects (e.g., from calls through function pointers).175.It core.AttributeNonNull176Check for null pointers passed as arguments to a function whose arguments are marked with the177.Ql nonnull178attribute.179.It core.CallAndMessage180Check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers).181.It core.DivideZero182Check for division by zero.183.It core.NullDereference184Check for dereferences of null pointers.185.It core.StackAddressEscape186Check that addresses to stack memory do not escape the function.187.It core.UndefinedBinaryOperatorResult188Check for undefined results of binary operators.189.It core.VLASize190Check for declarations of VLA of undefined or zero size.191.It core.builtin.BuiltinFunctions192Evaluate compiler builtin functions, e.g.193.Fn alloca .194.It core.builtin.NoReturnFunctions195Evaluate196.Ql panic197functions that are known to not return to the caller.198.It core.uninitialized.ArraySubscript199Check for uninitialized values used as array subscripts.200.It core.uninitialized.Assign201Check for assigning uninitialized values.202.It core.uninitialized.Branch203Check for uninitialized values used as branch conditions.204.It core.uninitialized.CapturedBlockVariable205Check for blocks that capture uninitialized values.206.It core.uninitialized.UndefReturn207Check for uninitialized values being returned to the caller.208.It deadcode.DeadStores209Check for values stored to variables that are never read afterwards.210.It debug.DumpCFG211Display Control-Flow Graphs.212.It debug.DumpCallGraph213Display Call Graph.214.It debug.DumpDominators215Print the dominance tree for a given Control-Flow Graph.216.It debug.DumpLiveVars217Print results of live variable analysis.218.It debug.Stats219Emit warnings with analyzer statistics.220.It debug.TaintTest221Mark tainted symbols as such.222.It debug.ViewCFG223View Control-Flow Graphs using224.Ic GraphViz .225.It debug.ViewCallGraph226View Call Graph using227.Ic GraphViz .228.It llvm.Conventions229Check code for LLVM codebase conventions.230.It osx.API231Check for proper uses of various Mac OS X APIs.232.It osx.AtomicCAS233Evaluate calls to234.Vt OSAtomic235functions.236.It osx.SecKeychainAPI237Check for proper uses of Secure Keychain APIs.238.It osx.cocoa.AtSync239Check for null pointers used as mutexes for @synchronized.240.It osx.cocoa.ClassRelease241Check for sending242.Ql retain ,243.Ql release,244or245.Ql autorelease246directly to a Class.247.It osx.cocoa.IncompatibleMethodTypes248Warn about Objective-C method signatures with type incompatibilities.249.It osx.cocoa.NSAutoreleasePool250Warn for suboptimal uses of251.Vt NSAutoreleasePool252in Objective-C GC mode.253.It osx.cocoa.NSError254Check usage of NSError** parameters.255.It osx.cocoa.NilArg256Check for prohibited nil arguments to Objective-C method calls.257.It osx.cocoa.RetainCount258Check for leaks and improper reference count management.259.It osx.cocoa.SelfInit260Check that261.Ql self262is properly initialized inside an initializer method.263.It osx.cocoa.UnusedIvars264Warn about private ivars that are never used.265.It osx.cocoa.VariadicMethodTypes266Check for passing non-Objective-C types to variadic methods that expect only Objective-C types.267.It osx.coreFoundation.CFError268Check usage of CFErrorRef* parameters.269.It osx.coreFoundation.CFNumber270Check for proper uses of271.Fn CFNumberCreate .272.It osx.coreFoundation.CFRetainRelease273Check for null arguments to274.Fn CFRetain ,275.Fn CFRelease ,276and277.Fn CFMakeCollectable .278.It osx.coreFoundation.containers.OutOfBounds279Checks for index out-of-bounds when using the280.Vt CFArray281API.282.It osx.coreFoundation.containers.PointerSizedValues283Warns if284.Vt CFArray ,285.Vt CFDictionary ,286or287.Vt CFSet288are created with non-pointer-size values.289.It security.FloatLoopCounter290Warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP).291.It security.insecureAPI.UncheckedReturn292Warn on uses of functions whose return values must be always checked.293.It security.insecureAPI.getpw294Warn on uses of295.Fn getpw .296.It security.insecureAPI.gets297Warn on uses of298.Fn gets .299.It security.insecureAPI.mkstemp300Warn when301.Fn mkstemp302is passed fewer than 6 X's in the format string.303.It security.insecureAPI.mktemp304Warn on uses of305.Fn mktemp .306.It security.insecureAPI.rand307Warn on uses of308.Fn rand ,309.Fn random ,310and related functions.311.It security.insecureAPI.strcpy312Warn on uses of313.Fn strcpy314and315.Fn strcat .316.It security.insecureAPI.vfork317Warn on uses of318.Fn vfork .319.It unix.API320Check calls to various UNIX/Posix functions.321.It unix.Malloc322Check for memory leaks, double free, and use-after-free.323.It unix.cstring.BadSizeArg324Check the size argument passed into C string functions for common325erroneous patterns.326.It unix.cstring.NullArg327Check for null pointers being passed as arguments to C string functions.328.El329.\"330.Sh EXAMPLE331.Ic scan-build -o /tmp/myhtmldir make -j4332.Pp333The above example causes analysis reports to be deposited into334a subdirectory of335.Pa /tmp/myhtmldir336and to run337.Ic make338with the339.Fl j4340option.341A different subdirectory is created each time342.Nm343analyzes a project.344The analyzer should support most parallel builds, but not distributed builds.345.Sh AUTHORS346.Nm347was written by348.An "Ted Kremenek" .349Documentation contributed by350.An "James K. Lowden" Aq jklowden@schemamania.org .351