tools/scan-build/man/scan-build.1

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