1//===- CheckerDocumentation.cpp - Documentation checker ---------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This checker lists all the checker callbacks and provides documentation for
10// checker writers.
11//
12//===----------------------------------------------------------------------===//
13
14#include "clang/StaticAnalyzer/Checkers/BuiltinCheckerRegistration.h"
15#include "clang/StaticAnalyzer/Core/BugReporter/BugType.h"
16#include "clang/StaticAnalyzer/Core/Checker.h"
17#include "clang/StaticAnalyzer/Core/CheckerManager.h"
18#include "clang/StaticAnalyzer/Core/PathSensitive/CheckerContext.h"
19
20using namespace clang;
21using namespace ento;
22
23// All checkers should be placed into anonymous namespace.
24// We place the CheckerDocumentation inside ento namespace to make the
25// it visible in doxygen.
26namespace clang {
27namespace ento {
28
29/// This checker documents the callback functions checkers can use to implement
30/// the custom handling of the specific events during path exploration as well
31/// as reporting bugs. Most of the callbacks are targeted at path-sensitive
32/// checking.
33///
34/// \sa CheckerContext
35class CheckerDocumentation
36 : public Checker<
37 // clang-format off
38 check::ASTCodeBody,
39 check::ASTDecl<FunctionDecl>,
40 check::BeginFunction,
41 check::Bind,
42 check::BlockEntrance,
43 check::BranchCondition,
44 check::ConstPointerEscape,
45 check::DeadSymbols,
46 check::EndAnalysis,
47 check::EndFunction,
48 check::EndOfTranslationUnit,
49 check::Event<ImplicitNullDerefEvent>,
50 check::LiveSymbols,
51 check::Location,
52 check::NewAllocator,
53 check::ObjCMessageNil,
54 check::PointerEscape,
55 check::PostCall,
56 check::PostObjCMessage,
57 check::PostStmt<DeclStmt>,
58 check::PreCall,
59 check::PreObjCMessage,
60 check::PreStmt<ReturnStmt>,
61 check::RegionChanges,
62 eval::Assume,
63 eval::Call
64 // clang-format on
65 > {
66public:
67 /// Pre-visit the Statement.
68 ///
69 /// The method will be called before the analyzer core processes the
70 /// statement. The notification is performed for every explored CFGElement,
71 /// which does not include the control flow statements such as IfStmt. The
72 /// callback can be specialized to be called with any subclass of Stmt.
73 ///
74 /// See checkBranchCondition() callback for performing custom processing of
75 /// the branching statements.
76 ///
77 /// check::PreStmt<ReturnStmt>
78 void checkPreStmt(const ReturnStmt *DS, CheckerContext &C) const {}
79
80 /// Post-visit the Statement.
81 ///
82 /// The method will be called after the analyzer core processes the
83 /// statement. The notification is performed for every explored CFGElement,
84 /// which does not include the control flow statements such as IfStmt. The
85 /// callback can be specialized to be called with any subclass of Stmt.
86 ///
87 /// check::PostStmt<DeclStmt>
88 void checkPostStmt(const DeclStmt *DS, CheckerContext &C) const;
89
90 /// Pre-visit the Objective C message.
91 ///
92 /// This will be called before the analyzer core processes the method call.
93 /// This is called for any action which produces an Objective-C message send,
94 /// including explicit message syntax and property access.
95 ///
96 /// check::PreObjCMessage
97 void checkPreObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {}
98
99 /// Post-visit the Objective C message.
100 /// \sa checkPreObjCMessage()
101 ///
102 /// check::PostObjCMessage
103 void checkPostObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {}
104
105 /// Visit an Objective-C message whose receiver is nil.
106 ///
107 /// This will be called when the analyzer core processes a method call whose
108 /// receiver is definitely nil. In this case, check{Pre/Post}ObjCMessage and
109 /// check{Pre/Post}Call will not be called.
110 ///
111 /// check::ObjCMessageNil
112 void checkObjCMessageNil(const ObjCMethodCall &M, CheckerContext &C) const {}
113
114 /// Pre-visit an abstract "call" event.
115 ///
116 /// This is used for checkers that want to check arguments or attributed
117 /// behavior for functions and methods no matter how they are being invoked.
118 ///
119 /// Note that this includes ALL cross-body invocations, so if you want to
120 /// limit your checks to, say, function calls, you should test for that at the
121 /// beginning of your callback function.
122 ///
123 /// check::PreCall
124 void checkPreCall(const CallEvent &Call, CheckerContext &C) const {}
125
126 /// Post-visit an abstract "call" event.
127 /// \sa checkPreObjCMessage()
128 ///
129 /// check::PostCall
130 void checkPostCall(const CallEvent &Call, CheckerContext &C) const {}
131
132 /// Pre-visit of the condition statement of a branch.
133 /// For example:
134 /// - logical operators (&&, ||)
135 /// - if, do, while, for, ranged-for statements
136 /// - ternary operators (?:), gnu conditionals, gnu choose expressions
137 /// Interestingly, switch statements don't seem to trigger BranchCondition.
138 ///
139 /// check::BlockEntrance is a similar callback, which is strictly more
140 /// generic. Prefer check::BranchCondition to check::BlockEntrance if
141 /// pre-visiting conditional statements is enough for the checker.
142 /// Note that check::BlockEntrance is also invoked for leaving basic blocks
143 /// while entering the next.
144 ///
145 /// check::BranchCondition
146 void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {}
147
148 /// Post-visit the C++ operator new's allocation call.
149 ///
150 /// Execution of C++ operator new consists of the following phases: (1) call
151 /// default or overridden operator new() to allocate memory (2) cast the
152 /// return value of operator new() from void pointer type to class pointer
153 /// type, (3) assuming that the value is non-null, call the object's
154 /// constructor over this pointer, (4) declare that the value of the
155 /// new-expression is this pointer. This callback is called between steps
156 /// (2) and (3). Post-call for the allocator is called after step (1).
157 /// Pre-statement for the new-expression is called on step (4) when the value
158 /// of the expression is evaluated.
159 void checkNewAllocator(const CXXAllocatorCall &, CheckerContext &) const {}
160
161 /// Called on a load from and a store to a location.
162 ///
163 /// The method will be called each time a location (pointer) value is
164 /// accessed.
165 /// \param Loc The value of the location (pointer).
166 /// \param IsLoad The flag specifying if the location is a store or a load.
167 /// \param S The load is performed while processing the statement.
168 ///
169 /// check::Location
170 void checkLocation(SVal Loc, bool IsLoad, const Stmt *S,
171 CheckerContext &) const {}
172
173 /// Called on binding of a value to a location.
174 ///
175 /// \param Loc The value of the location (pointer).
176 /// \param Val The value which will be stored at the location Loc.
177 /// \param S The bind is performed while processing the statement S.
178 ///
179 /// check::Bind
180 void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {}
181
182 /// Called after a CFG edge is taken within a function.
183 ///
184 /// This callback can be used to obtain information about potential branching
185 /// points or any other constructs that involve traversing a CFG edge.
186 ///
187 /// check::BranchCondition is a similar callback, which is only invoked for
188 /// pre-visiting the condition statement of a branch. Prefer that callback if
189 /// possible.
190 ///
191 /// \remark There is no CFG edge from the caller to a callee, consequently
192 /// this callback is not invoked for "inlining" a function call.
193 /// \remark Once a function call is inlined, we will start from the imaginary
194 /// "entry" basic block of that CFG. This callback will be invoked for
195 /// entering the real first basic block of the "inlined" function body from
196 /// that "entry" basic block.
197 /// \remark This callback is also invoked for entering the imaginary "exit"
198 /// basic block of the CFG when returning from a function.
199 ///
200 /// \param E The ProgramPoint that describes the transition.
201 ///
202 /// check::BlockEntrance
203 void checkBlockEntrance(const BlockEntrance &E, CheckerContext &) const {}
204
205 /// Called whenever a symbol becomes dead.
206 ///
207 /// This callback should be used by the checkers to aggressively clean
208 /// up/reduce the checker state, which is important for reducing the overall
209 /// memory usage. Specifically, if a checker keeps symbol specific information
210 /// in the state, it can and should be dropped after the symbol becomes dead.
211 /// In addition, reporting a bug as soon as the checker becomes dead leads to
212 /// more precise diagnostics. (For example, one should report that a malloced
213 /// variable is not freed right after it goes out of scope.)
214 ///
215 /// \param SR The SymbolReaper object can be queried to determine which
216 /// symbols are dead.
217 ///
218 /// check::DeadSymbols
219 void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {}
220
221
222 /// Called when the analyzer core starts analyzing a function,
223 /// regardless of whether it is analyzed at the top level or is inlined.
224 ///
225 /// check::BeginFunction
226 void checkBeginFunction(CheckerContext &Ctx) const {}
227
228 /// Called when the analyzer core reaches the end of a
229 /// function being analyzed regardless of whether it is analyzed at the top
230 /// level or is inlined.
231 ///
232 /// check::EndFunction
233 void checkEndFunction(const ReturnStmt *RS, CheckerContext &Ctx) const {}
234
235 /// Called after all the paths in the ExplodedGraph reach end of path
236 /// - the symbolic execution graph is fully explored.
237 ///
238 /// This callback should be used in cases when a checker needs to have a
239 /// global view of the information generated on all paths. For example, to
240 /// compare execution summary/result several paths.
241 /// See IdempotentOperationChecker for a usage example.
242 ///
243 /// check::EndAnalysis
244 void checkEndAnalysis(ExplodedGraph &G,
245 BugReporter &BR,
246 ExprEngine &Eng) const {}
247
248 /// Called after analysis of a TranslationUnit is complete.
249 ///
250 /// check::EndOfTranslationUnit
251 void checkEndOfTranslationUnit(const TranslationUnitDecl *TU,
252 AnalysisManager &Mgr,
253 BugReporter &BR) const {}
254
255 /// Evaluates function call.
256 ///
257 /// The analysis core treats all function calls in the same way. However, some
258 /// functions have special meaning, which should be reflected in the program
259 /// state. This callback allows a checker to provide domain specific knowledge
260 /// about the particular functions it knows about.
261 ///
262 /// \returns true if the call has been successfully evaluated
263 /// and false otherwise. Note, that only one checker can evaluate a call. If
264 /// more than one checker claims that they can evaluate the same call the
265 /// first one wins.
266 ///
267 /// eval::Call
268 bool evalCall(const CallEvent &Call, CheckerContext &C) const { return true; }
269
270 /// Handles assumptions on symbolic values.
271 ///
272 /// This method is called when a symbolic expression is assumed to be true or
273 /// false. For example, the assumptions are performed when evaluating a
274 /// condition at a branch. The callback allows checkers track the assumptions
275 /// performed on the symbols of interest and change the state accordingly.
276 ///
277 /// eval::Assume
278 ProgramStateRef evalAssume(ProgramStateRef State,
279 SVal Cond,
280 bool Assumption) const { return State; }
281
282 /// Allows modifying SymbolReaper object. For example, checkers can explicitly
283 /// register symbols of interest as live. These symbols will not be marked
284 /// dead and removed.
285 ///
286 /// check::LiveSymbols
287 void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const {}
288
289 /// Called when the contents of one or more regions change.
290 ///
291 /// This can occur in many different ways: an explicit bind, a blanket
292 /// invalidation of the region contents, or by passing a region to a function
293 /// call whose behavior the analyzer cannot model perfectly.
294 ///
295 /// \param State The current program state.
296 /// \param Invalidated A set of all symbols potentially touched by the change.
297 /// \param ExplicitRegions The regions explicitly requested for invalidation.
298 /// For a function call, this would be the arguments. For a bind, this
299 /// would be the region being bound to.
300 /// \param Regions The transitive closure of regions accessible from,
301 /// \p ExplicitRegions, i.e. all regions that may have been touched
302 /// by this change. For a simple bind, this list will be the same as
303 /// \p ExplicitRegions, since a bind does not affect the contents of
304 /// anything accessible through the base region.
305 /// \param LCtx LocationContext that is useful for getting various contextual
306 /// info, like callstack, CFG etc.
307 /// \param Call The opaque call triggering this invalidation. Will be 0 if the
308 /// change was not triggered by a call.
309 ///
310 /// check::RegionChanges
311 ProgramStateRef
312 checkRegionChanges(ProgramStateRef State,
313 const InvalidatedSymbols *Invalidated,
314 ArrayRef<const MemRegion *> ExplicitRegions,
315 ArrayRef<const MemRegion *> Regions,
316 const LocationContext *LCtx,
317 const CallEvent *Call) const {
318 return State;
319 }
320
321 /// Called when pointers escape.
322 ///
323 /// This notifies the checkers about pointer escape, which occurs whenever
324 /// the analyzer cannot track the symbol any more. For example, as a
325 /// result of assigning a pointer into a global or when it's passed to a
326 /// function call the analyzer cannot model.
327 ///
328 /// \param State The state at the point of escape.
329 /// \param Escaped The list of escaped symbols.
330 /// \param Call The corresponding CallEvent, if the symbols escape as
331 /// parameters to the given call.
332 /// \param Kind How the symbols have escaped.
333 /// \returns Checkers can modify the state by returning a new state.
334 ProgramStateRef checkPointerEscape(ProgramStateRef State,
335 const InvalidatedSymbols &Escaped,
336 const CallEvent *Call,
337 PointerEscapeKind Kind) const {
338 return State;
339 }
340
341 /// Called when const pointers escape.
342 ///
343 /// Note: in most cases checkPointerEscape callback is sufficient.
344 /// \sa checkPointerEscape
345 ProgramStateRef checkConstPointerEscape(ProgramStateRef State,
346 const InvalidatedSymbols &Escaped,
347 const CallEvent *Call,
348 PointerEscapeKind Kind) const {
349 return State;
350 }
351
352 /// check::Event<ImplicitNullDerefEvent>
353 void checkEvent(ImplicitNullDerefEvent Event) const {}
354
355 /// Check every declaration in the AST.
356 ///
357 /// An AST traversal callback, which should only be used when the checker is
358 /// not path sensitive. It will be called for every Declaration in the AST and
359 /// can be specialized to only be called on subclasses of Decl, for example,
360 /// FunctionDecl.
361 ///
362 /// check::ASTDecl<FunctionDecl>
363 void checkASTDecl(const FunctionDecl *D,
364 AnalysisManager &Mgr,
365 BugReporter &BR) const {}
366
367 /// Check every declaration that has a statement body in the AST.
368 ///
369 /// As AST traversal callback, which should only be used when the checker is
370 /// not path sensitive. It will be called for every Declaration in the AST.
371 void checkASTCodeBody(const Decl *D, AnalysisManager &Mgr,
372 BugReporter &BR) const {}
373};
374
375void CheckerDocumentation::checkPostStmt(const DeclStmt *DS,
376 CheckerContext &C) const {
377}
378
379void registerCheckerDocumentationChecker(CheckerManager &Mgr) {
380 Mgr.registerChecker<CheckerDocumentation>();
381}
382
383bool shouldRegisterCheckerDocumentationChecker(const CheckerManager &) {
384 return false;
385}
386
387} // end namespace ento
388} // end namespace clang
389