| blob | 29edbca1fc63881a525fd1f268d5edfce33934e7 |
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 Sep 21, 2023
6 .Dt SCAN-BUILD 1
7 .Os "clang" "18"
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 jklowden@schemamania.org .