| 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-exception |
| 4 |
.\" $Id$ |
| 5 |
.Dd Aug 1, 2022 |
| 6 |
.Dt SCAN-BUILD 1 |
| 7 |
.Os "clang" "16" |
| 8 |
.Sh NAME |
| 9 |
.Nm scan-build |
| 10 |
.Nd Clang static analyzer |
| 11 |
.Sh SYNOPSIS |
| 12 |
.Nm |
| 13 |
.Op Fl ohkvV |
| 14 |
.Op Fl analyze-headers |
| 15 |
.Op Fl enable-checker Op Ar checker_name |
| 16 |
.Op Fl disable-checker Op Ar checker_name |
| 17 |
.Op Fl Fl help |
| 18 |
.Op Fl Fl help-checkers |
| 19 |
.Op Fl Fl html-title Op Ar =title |
| 20 |
.Op Fl Fl keep-going |
| 21 |
.Op Fl plist |
| 22 |
.Op Fl plist-html |
| 23 |
.Op Fl Fl status-bugs |
| 24 |
.Op Fl Fl use-c++ Op Ar =compiler_path |
| 25 |
.Op Fl Fl use-cc Op Ar =compiler_path |
| 26 |
.Op Fl Fl view |
| 27 |
.Op Fl constraints Op Ar model |
| 28 |
.Op Fl maxloop Ar N |
| 29 |
.Op Fl no-failure-reports |
| 30 |
.Op Fl stats |
| 31 |
.Op Fl store Op Ar model |
| 32 |
.Ar build_command |
| 33 |
.Op build_options |
| 34 |
.\" |
| 35 |
.\" Sh DESCRIPTION |
| 36 |
.Sh DESCRIPTION |
| 37 |
.Nm |
| 38 |
is a Perl script that invokes the Clang static analyzer. Options used by |
| 39 |
.Nm |
| 40 |
or by the analyzer appear first, followed by the |
| 41 |
.Ar build_command |
| 42 |
and any |
| 43 |
.Ar build_options |
| 44 |
normally used to build the target system. |
| 45 |
.Pp |
| 46 |
The static analyzer employs a long list of checking algorithms, see |
| 47 |
.Sx CHECKERS . |
| 48 |
Output can be written in standard |
| 49 |
.Li .plist |
| 50 |
and/or HTML format. |
| 51 |
.Pp |
| 52 |
The following options are supported: |
| 53 |
.Bl -tag -width indent |
| 54 |
.It Fl analyze-headers |
| 55 |
Also analyze functions in #included files. |
| 56 |
.It Fl enable-checker Ar checker_name , Fl disable-checker Ar checker_name |
| 57 |
Enable/disable |
| 58 |
.Ar checker_name . |
| 59 |
See |
| 60 |
.Sx CHECKERS . |
| 61 |
.It Fl h , Fl Fl help |
| 62 |
Display this message. |
| 63 |
.It Fl Fl help-checkers |
| 64 |
List default checkers, see |
| 65 |
.Sx CHECKERS . |
| 66 |
.It Fl Fl html-title Ns Op = Ns Ar title |
| 67 |
Specify the title used on generated HTML pages. |
| 68 |
A default title is generated if |
| 69 |
.Ar title |
| 70 |
is not specified. |
| 71 |
.It Fl k , Fl Fl keep-going |
| 72 |
Add a |
| 73 |
.Dq keep on going |
| 74 |
option to |
| 75 |
.Ar build_command . |
| 76 |
Currently supports make and xcodebuild. This is a convenience option; |
| 77 |
one can specify this behavior directly using build options. |
| 78 |
.It Fl o |
| 79 |
Target directory for HTML report files. Subdirectories will be |
| 80 |
created as needed to represent separate invocations |
| 81 |
of the analyzer. If this option is not specified, a directory is |
| 82 |
created in /tmp (TMPDIR on Mac OS X) to store the reports. |
| 83 |
.It Fl plist |
| 84 |
Output the results as a set of |
| 85 |
.Li .plist |
| 86 |
files. (By default the output of |
| 87 |
.Nm |
| 88 |
is a set of HTML files.) |
| 89 |
.It Fl plist-html |
| 90 |
Output the results as a set of HTML and .plist files |
| 91 |
.It Fl Fl status-bugs |
| 92 |
Set exit status to 1 if it found potential bugs and 0 otherwise. By |
| 93 |
default the exit status of |
| 94 |
.Nm |
| 95 |
is that returned by |
| 96 |
.Ar build_command . |
| 97 |
.It Fl Fl use-c++ Ns Op = Ns Ar compiler_path |
| 98 |
Guess the default compiler for your C++ and Objective-C++ code. Use this |
| 99 |
option to specify an alternate compiler. |
| 100 |
.It Fl Fl use-cc Ns Op = Ns Ar compiler_path |
| 101 |
Guess the default compiler for your C and Objective-C code. Use this |
| 102 |
option to specify an alternate compiler. |
| 103 |
.It Fl v |
| 104 |
Verbose output from |
| 105 |
.Nm |
| 106 |
and the analyzer. A second and |
| 107 |
third |
| 108 |
.Ar v |
| 109 |
increases verbosity. |
| 110 |
.It Fl V , Fl Fl view |
| 111 |
View analysis results in a web browser when the build completes. |
| 112 |
.It Fl constraints Op Ar model |
| 113 |
Specify the constraint engine used by the analyzer. By default the |
| 114 |
.Ql range |
| 115 |
model is used. Specifying |
| 116 |
.Ql basic |
| 117 |
uses a simpler, less powerful constraint model used by checker-0.160 |
| 118 |
and earlier. |
| 119 |
.It Fl maxloop Ar N |
| 120 |
Specify the number of times a block can be visited before giving |
| 121 |
up. Default is 4. Increase for more comprehensive coverage at a |
| 122 |
cost of speed. |
| 123 |
.It Fl no-failure-reports |
| 124 |
Do not create a |
| 125 |
.Ql failures |
| 126 |
subdirectory that includes analyzer crash reports and preprocessed |
| 127 |
source files. |
| 128 |
.It Fl stats |
| 129 |
Generates visitation statistics for the project being analyzed. |
| 130 |
.It Fl store Op Ar model |
| 131 |
Specify the store model used by the analyzer. By default, the |
| 132 |
.Ql region |
| 133 |
store model is used. |
| 134 |
.Ql region |
| 135 |
specifies a field- |
| 136 |
sensitive store model. Users can also specify |
| 137 |
.Ql basic |
| 138 |
which is far less precise but can more quickly analyze code. |
| 139 |
.Ql basic |
| 140 |
was the default store model for checker-0.221 and earlier. |
| 141 |
.\" |
| 142 |
.El |
| 143 |
.Sh EXIT STATUS |
| 144 |
.Nm |
| 145 |
returns the value returned by |
| 146 |
.Ar build_command |
| 147 |
unless |
| 148 |
.Fl Fl status-bugs |
| 149 |
or |
| 150 |
.Fl Fl keep-going |
| 151 |
is used. |
| 152 |
.\" |
| 153 |
.\" Other sections not yet used ... |
| 154 |
.\" .Sh ENVIRONMENT |
| 155 |
.\" .Sh FILES |
| 156 |
.\" .Sh DIAGNOSTICS |
| 157 |
.\" .Sh COMPATIBILITY |
| 158 |
.\" .Sh HISTORY |
| 159 |
.\" .Sh BUGS |
| 160 |
.\" |
| 161 |
.Sh CHECKERS |
| 162 |
The checkers listed below may be enabled/disabled using the |
| 163 |
.Fl enable-checker |
| 164 |
and |
| 165 |
.Fl disable-checker |
| 166 |
options. |
| 167 |
A default group of checkers is run unless explicitly disabled. |
| 168 |
Exactly which checkers constitute the default group is a function |
| 169 |
of the operating system in use; they are listed with |
| 170 |
.Fl Fl help-checkers . |
| 171 |
.Bl -tag -width indent. |
| 172 |
.It core.AdjustedReturnValue |
| 173 |
Check to see if the return value of a function call is different than |
| 174 |
the caller expects (e.g., from calls through function pointers). |
| 175 |
.It core.AttributeNonNull |
| 176 |
Check for null pointers passed as arguments to a function whose arguments are marked with the |
| 177 |
.Ql nonnull |
| 178 |
attribute. |
| 179 |
.It core.CallAndMessage |
| 180 |
Check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers). |
| 181 |
.It core.DivideZero |
| 182 |
Check for division by zero. |
| 183 |
.It core.NullDereference |
| 184 |
Check for dereferences of null pointers. |
| 185 |
.It core.StackAddressEscape |
| 186 |
Check that addresses to stack memory do not escape the function. |
| 187 |
.It core.UndefinedBinaryOperatorResult |
| 188 |
Check for undefined results of binary operators. |
| 189 |
.It core.VLASize |
| 190 |
Check for declarations of VLA of undefined or zero size. |
| 191 |
.It core.builtin.BuiltinFunctions |
| 192 |
Evaluate compiler builtin functions, e.g. |
| 193 |
.Fn alloca . |
| 194 |
.It core.builtin.NoReturnFunctions |
| 195 |
Evaluate |
| 196 |
.Ql panic |
| 197 |
functions that are known to not return to the caller. |
| 198 |
.It core.uninitialized.ArraySubscript |
| 199 |
Check for uninitialized values used as array subscripts. |
| 200 |
.It core.uninitialized.Assign |
| 201 |
Check for assigning uninitialized values. |
| 202 |
.It core.uninitialized.Branch |
| 203 |
Check for uninitialized values used as branch conditions. |
| 204 |
.It core.uninitialized.CapturedBlockVariable |
| 205 |
Check for blocks that capture uninitialized values. |
| 206 |
.It core.uninitialized.UndefReturn |
| 207 |
Check for uninitialized values being returned to the caller. |
| 208 |
.It deadcode.DeadStores |
| 209 |
Check for values stored to variables that are never read afterwards. |
| 210 |
.It debug.DumpCFG |
| 211 |
Display Control-Flow Graphs. |
| 212 |
.It debug.DumpCallGraph |
| 213 |
Display Call Graph. |
| 214 |
.It debug.DumpDominators |
| 215 |
Print the dominance tree for a given Control-Flow Graph. |
| 216 |
.It debug.DumpLiveVars |
| 217 |
Print results of live variable analysis. |
| 218 |
.It debug.Stats |
| 219 |
Emit warnings with analyzer statistics. |
| 220 |
.It debug.TaintTest |
| 221 |
Mark tainted symbols as such. |
| 222 |
.It debug.ViewCFG |
| 223 |
View Control-Flow Graphs using |
| 224 |
.Ic GraphViz . |
| 225 |
.It debug.ViewCallGraph |
| 226 |
View Call Graph using |
| 227 |
.Ic GraphViz . |
| 228 |
.It llvm.Conventions |
| 229 |
Check code for LLVM codebase conventions. |
| 230 |
.It osx.API |
| 231 |
Check for proper uses of various Mac OS X APIs. |
| 232 |
.It osx.AtomicCAS |
| 233 |
Evaluate calls to |
| 234 |
.Vt OSAtomic |
| 235 |
functions. |
| 236 |
.It osx.SecKeychainAPI |
| 237 |
Check for proper uses of Secure Keychain APIs. |
| 238 |
.It osx.cocoa.AtSync |
| 239 |
Check for null pointers used as mutexes for @synchronized. |
| 240 |
.It osx.cocoa.ClassRelease |
| 241 |
Check for sending |
| 242 |
.Ql retain , |
| 243 |
.Ql release, |
| 244 |
or |
| 245 |
.Ql autorelease |
| 246 |
directly to a Class. |
| 247 |
.It osx.cocoa.IncompatibleMethodTypes |
| 248 |
Warn about Objective-C method signatures with type incompatibilities. |
| 249 |
.It osx.cocoa.NSAutoreleasePool |
| 250 |
Warn for suboptimal uses of |
| 251 |
.Vt NSAutoreleasePool |
| 252 |
in Objective-C GC mode. |
| 253 |
.It osx.cocoa.NSError |
| 254 |
Check usage of NSError** parameters. |
| 255 |
.It osx.cocoa.NilArg |
| 256 |
Check for prohibited nil arguments to Objective-C method calls. |
| 257 |
.It osx.cocoa.RetainCount |
| 258 |
Check for leaks and improper reference count management. |
| 259 |
.It osx.cocoa.SelfInit |
| 260 |
Check that |
| 261 |
.Ql self |
| 262 |
is properly initialized inside an initializer method. |
| 263 |
.It osx.cocoa.UnusedIvars |
| 264 |
Warn about private ivars that are never used. |
| 265 |
.It osx.cocoa.VariadicMethodTypes |
| 266 |
Check for passing non-Objective-C types to variadic methods that expect only Objective-C types. |
| 267 |
.It osx.coreFoundation.CFError |
| 268 |
Check usage of CFErrorRef* parameters. |
| 269 |
.It osx.coreFoundation.CFNumber |
| 270 |
Check for proper uses of |
| 271 |
.Fn CFNumberCreate . |
| 272 |
.It osx.coreFoundation.CFRetainRelease |
| 273 |
Check for null arguments to |
| 274 |
.Fn CFRetain , |
| 275 |
.Fn CFRelease , |
| 276 |
and |
| 277 |
.Fn CFMakeCollectable . |
| 278 |
.It osx.coreFoundation.containers.OutOfBounds |
| 279 |
Checks for index out-of-bounds when using the |
| 280 |
.Vt CFArray |
| 281 |
API. |
| 282 |
.It osx.coreFoundation.containers.PointerSizedValues |
| 283 |
Warns if |
| 284 |
.Vt CFArray , |
| 285 |
.Vt CFDictionary , |
| 286 |
or |
| 287 |
.Vt CFSet |
| 288 |
are created with non-pointer-size values. |
| 289 |
.It security.FloatLoopCounter |
| 290 |
Warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP). |
| 291 |
.It security.insecureAPI.UncheckedReturn |
| 292 |
Warn on uses of functions whose return values must be always checked. |
| 293 |
.It security.insecureAPI.getpw |
| 294 |
Warn on uses of |
| 295 |
.Fn getpw . |
| 296 |
.It security.insecureAPI.gets |
| 297 |
Warn on uses of |
| 298 |
.Fn gets . |
| 299 |
.It security.insecureAPI.mkstemp |
| 300 |
Warn when |
| 301 |
.Fn mkstemp |
| 302 |
is passed fewer than 6 X's in the format string. |
| 303 |
.It security.insecureAPI.mktemp |
| 304 |
Warn on uses of |
| 305 |
.Fn mktemp . |
| 306 |
.It security.insecureAPI.rand |
| 307 |
Warn on uses of |
| 308 |
.Fn rand , |
| 309 |
.Fn random , |
| 310 |
and related functions. |
| 311 |
.It security.insecureAPI.strcpy |
| 312 |
Warn on uses of |
| 313 |
.Fn strcpy |
| 314 |
and |
| 315 |
.Fn strcat . |
| 316 |
.It security.insecureAPI.vfork |
| 317 |
Warn on uses of |
| 318 |
.Fn vfork . |
| 319 |
.It unix.API |
| 320 |
Check calls to various UNIX/Posix functions. |
| 321 |
.It unix.Malloc |
| 322 |
Check for memory leaks, double free, and use-after-free. |
| 323 |
.It unix.cstring.BadSizeArg |
| 324 |
Check the size argument passed into C string functions for common |
| 325 |
erroneous patterns. |
| 326 |
.It unix.cstring.NullArg |
| 327 |
Check for null pointers being passed as arguments to C string functions. |
| 328 |
.El |
| 329 |
.\" |
| 330 |
.Sh EXAMPLE |
| 331 |
.Ic scan-build -o /tmp/myhtmldir make -j4 |
| 332 |
.Pp |
| 333 |
The above example causes analysis reports to be deposited into |
| 334 |
a subdirectory of |
| 335 |
.Pa /tmp/myhtmldir |
| 336 |
and to run |
| 337 |
.Ic make |
| 338 |
with the |
| 339 |
.Fl j4 |
| 340 |
option. |
| 341 |
A different subdirectory is created each time |
| 342 |
.Nm |
| 343 |
analyzes a project. |
| 344 |
The analyzer should support most parallel builds, but not distributed builds. |
| 345 |
.Sh AUTHORS |
| 346 |
.Nm |
| 347 |
was written by |
| 348 |
.An "Ted Kremenek" . |
| 349 |
Documentation contributed by |
| 350 |
.An "James K. Lowden" Aq [email protected] . |