| 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 May 25, 2012 |
|---|
| 6 | .Dt SCAN-BUILD 1 |
|---|
| 7 | .Os "clang" "3.5" |
|---|
| 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 contraint 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 jklowden@schemamania.org . |
|---|
| 351 | |
|---|