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#include "clang/StaticAnalyzer/Core/PathSensitive/ProgramStateTrait.h"
20
21using namespace clang;
22using namespace ento;
23
24// All checkers should be placed into anonymous namespace.
25// We place the CheckerDocumentation inside ento namespace to make the
26// it visible in doxygen.
27namespace clang {
28namespace ento {
29
30/// This checker documents the callback functions checkers can use to implement
31/// the custom handling of the specific events during path exploration as well
32/// as reporting bugs. Most of the callbacks are targeted at path-sensitive
33/// checking.
34///
35/// \sa CheckerContext
36class CheckerDocumentation
37 : public Checker<
38 // clang-format off
39 check::ASTCodeBody,
40 check::ASTDecl<FunctionDecl>,
41 check::BeginFunction,
42 check::Bind,
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 (such as IfStmt).
133 void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {}
134
135 /// Post-visit the C++ operator new's allocation call.
136 ///
137 /// Execution of C++ operator new consists of the following phases: (1) call
138 /// default or overridden operator new() to allocate memory (2) cast the
139 /// return value of operator new() from void pointer type to class pointer
140 /// type, (3) assuming that the value is non-null, call the object's
141 /// constructor over this pointer, (4) declare that the value of the
142 /// new-expression is this pointer. This callback is called between steps
143 /// (2) and (3). Post-call for the allocator is called after step (1).
144 /// Pre-statement for the new-expression is called on step (4) when the value
145 /// of the expression is evaluated.
146 void checkNewAllocator(const CXXAllocatorCall &, CheckerContext &) const {}
147
148 /// Called on a load from and a store to a location.
149 ///
150 /// The method will be called each time a location (pointer) value is
151 /// accessed.
152 /// \param Loc The value of the location (pointer).
153 /// \param IsLoad The flag specifying if the location is a store or a load.
154 /// \param S The load is performed while processing the statement.
155 ///
156 /// check::Location
157 void checkLocation(SVal Loc, bool IsLoad, const Stmt *S,
158 CheckerContext &) const {}
159
160 /// Called on binding of a value to a location.
161 ///
162 /// \param Loc The value of the location (pointer).
163 /// \param Val The value which will be stored at the location Loc.
164 /// \param S The bind is performed while processing the statement S.
165 ///
166 /// check::Bind
167 void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {}
168
169 /// Called whenever a symbol becomes dead.
170 ///
171 /// This callback should be used by the checkers to aggressively clean
172 /// up/reduce the checker state, which is important for reducing the overall
173 /// memory usage. Specifically, if a checker keeps symbol specific information
174 /// in the state, it can and should be dropped after the symbol becomes dead.
175 /// In addition, reporting a bug as soon as the checker becomes dead leads to
176 /// more precise diagnostics. (For example, one should report that a malloced
177 /// variable is not freed right after it goes out of scope.)
178 ///
179 /// \param SR The SymbolReaper object can be queried to determine which
180 /// symbols are dead.
181 ///
182 /// check::DeadSymbols
183 void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {}
184
185
186 /// Called when the analyzer core starts analyzing a function,
187 /// regardless of whether it is analyzed at the top level or is inlined.
188 ///
189 /// check::BeginFunction
190 void checkBeginFunction(CheckerContext &Ctx) const {}
191
192 /// Called when the analyzer core reaches the end of a
193 /// function being analyzed regardless of whether it is analyzed at the top
194 /// level or is inlined.
195 ///
196 /// check::EndFunction
197 void checkEndFunction(const ReturnStmt *RS, CheckerContext &Ctx) const {}
198
199 /// Called after all the paths in the ExplodedGraph reach end of path
200 /// - the symbolic execution graph is fully explored.
201 ///
202 /// This callback should be used in cases when a checker needs to have a
203 /// global view of the information generated on all paths. For example, to
204 /// compare execution summary/result several paths.
205 /// See IdempotentOperationChecker for a usage example.
206 ///
207 /// check::EndAnalysis
208 void checkEndAnalysis(ExplodedGraph &G,
209 BugReporter &BR,
210 ExprEngine &Eng) const {}
211
212 /// Called after analysis of a TranslationUnit is complete.
213 ///
214 /// check::EndOfTranslationUnit
215 void checkEndOfTranslationUnit(const TranslationUnitDecl *TU,
216 AnalysisManager &Mgr,
217 BugReporter &BR) const {}
218
219 /// Evaluates function call.
220 ///
221 /// The analysis core treats all function calls in the same way. However, some
222 /// functions have special meaning, which should be reflected in the program
223 /// state. This callback allows a checker to provide domain specific knowledge
224 /// about the particular functions it knows about.
225 ///
226 /// \returns true if the call has been successfully evaluated
227 /// and false otherwise. Note, that only one checker can evaluate a call. If
228 /// more than one checker claims that they can evaluate the same call the
229 /// first one wins.
230 ///
231 /// eval::Call
232 bool evalCall(const CallEvent &Call, CheckerContext &C) const { return true; }
233
234 /// Handles assumptions on symbolic values.
235 ///
236 /// This method is called when a symbolic expression is assumed to be true or
237 /// false. For example, the assumptions are performed when evaluating a
238 /// condition at a branch. The callback allows checkers track the assumptions
239 /// performed on the symbols of interest and change the state accordingly.
240 ///
241 /// eval::Assume
242 ProgramStateRef evalAssume(ProgramStateRef State,
243 SVal Cond,
244 bool Assumption) const { return State; }
245
246 /// Allows modifying SymbolReaper object. For example, checkers can explicitly
247 /// register symbols of interest as live. These symbols will not be marked
248 /// dead and removed.
249 ///
250 /// check::LiveSymbols
251 void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const {}
252
253 /// Called when the contents of one or more regions change.
254 ///
255 /// This can occur in many different ways: an explicit bind, a blanket
256 /// invalidation of the region contents, or by passing a region to a function
257 /// call whose behavior the analyzer cannot model perfectly.
258 ///
259 /// \param State The current program state.
260 /// \param Invalidated A set of all symbols potentially touched by the change.
261 /// \param ExplicitRegions The regions explicitly requested for invalidation.
262 /// For a function call, this would be the arguments. For a bind, this
263 /// would be the region being bound to.
264 /// \param Regions The transitive closure of regions accessible from,
265 /// \p ExplicitRegions, i.e. all regions that may have been touched
266 /// by this change. For a simple bind, this list will be the same as
267 /// \p ExplicitRegions, since a bind does not affect the contents of
268 /// anything accessible through the base region.
269 /// \param LCtx LocationContext that is useful for getting various contextual
270 /// info, like callstack, CFG etc.
271 /// \param Call The opaque call triggering this invalidation. Will be 0 if the
272 /// change was not triggered by a call.
273 ///
274 /// check::RegionChanges
275 ProgramStateRef
276 checkRegionChanges(ProgramStateRef State,
277 const InvalidatedSymbols *Invalidated,
278 ArrayRef<const MemRegion *> ExplicitRegions,
279 ArrayRef<const MemRegion *> Regions,
280 const LocationContext *LCtx,
281 const CallEvent *Call) const {
282 return State;
283 }
284
285 /// Called when pointers escape.
286 ///
287 /// This notifies the checkers about pointer escape, which occurs whenever
288 /// the analyzer cannot track the symbol any more. For example, as a
289 /// result of assigning a pointer into a global or when it's passed to a
290 /// function call the analyzer cannot model.
291 ///
292 /// \param State The state at the point of escape.
293 /// \param Escaped The list of escaped symbols.
294 /// \param Call The corresponding CallEvent, if the symbols escape as
295 /// parameters to the given call.
296 /// \param Kind How the symbols have escaped.
297 /// \returns Checkers can modify the state by returning a new state.
298 ProgramStateRef checkPointerEscape(ProgramStateRef State,
299 const InvalidatedSymbols &Escaped,
300 const CallEvent *Call,
301 PointerEscapeKind Kind) const {
302 return State;
303 }
304
305 /// Called when const pointers escape.
306 ///
307 /// Note: in most cases checkPointerEscape callback is sufficient.
308 /// \sa checkPointerEscape
309 ProgramStateRef checkConstPointerEscape(ProgramStateRef State,
310 const InvalidatedSymbols &Escaped,
311 const CallEvent *Call,
312 PointerEscapeKind Kind) const {
313 return State;
314 }
315
316 /// check::Event<ImplicitNullDerefEvent>
317 void checkEvent(ImplicitNullDerefEvent Event) const {}
318
319 /// Check every declaration in the AST.
320 ///
321 /// An AST traversal callback, which should only be used when the checker is
322 /// not path sensitive. It will be called for every Declaration in the AST and
323 /// can be specialized to only be called on subclasses of Decl, for example,
324 /// FunctionDecl.
325 ///
326 /// check::ASTDecl<FunctionDecl>
327 void checkASTDecl(const FunctionDecl *D,
328 AnalysisManager &Mgr,
329 BugReporter &BR) const {}
330
331 /// Check every declaration that has a statement body in the AST.
332 ///
333 /// As AST traversal callback, which should only be used when the checker is
334 /// not path sensitive. It will be called for every Declaration in the AST.
335 void checkASTCodeBody(const Decl *D, AnalysisManager &Mgr,
336 BugReporter &BR) const {}
337};
338
339void CheckerDocumentation::checkPostStmt(const DeclStmt *DS,
340 CheckerContext &C) const {
341}
342
343void registerCheckerDocumentationChecker(CheckerManager &Mgr) {
344 Mgr.registerChecker<CheckerDocumentation>();
345}
346
347bool shouldRegisterCheckerDocumentationChecker(const CheckerManager &) {
348 return false;
349}
350
351} // end namespace ento
352} // end namespace clang
353