clang  3.7.0
CheckerDocumentation.cpp
Go to the documentation of this file.
1 //= CheckerDocumentation.cpp - Documentation checker ---------------*- C++ -*-//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This checker lists all the checker callbacks and provides documentation for
11 // checker writers.
12 //
13 //===----------------------------------------------------------------------===//
14 
15 #include "ClangSACheckers.h"
21 
22 using namespace clang;
23 using namespace ento;
24 
25 // All checkers should be placed into anonymous namespace.
26 // We place the CheckerDocumentation inside ento namespace to make the
27 // it visible in doxygen.
28 namespace clang {
29 namespace ento {
30 
31 /// This checker documents the callback functions checkers can use to implement
32 /// the custom handling of the specific events during path exploration as well
33 /// as reporting bugs. Most of the callbacks are targeted at path-sensitive
34 /// checking.
35 ///
36 /// \sa CheckerContext
37 class CheckerDocumentation : public Checker< check::PreStmt<ReturnStmt>,
38  check::PostStmt<DeclStmt>,
39  check::PreObjCMessage,
40  check::PostObjCMessage,
41  check::PreCall,
42  check::PostCall,
43  check::BranchCondition,
44  check::Location,
45  check::Bind,
46  check::DeadSymbols,
47  check::EndFunction,
48  check::EndAnalysis,
49  check::EndOfTranslationUnit,
50  eval::Call,
51  eval::Assume,
52  check::LiveSymbols,
53  check::RegionChanges,
54  check::PointerEscape,
55  check::ConstPointerEscape,
56  check::Event<ImplicitNullDerefEvent>,
57  check::ASTDecl<FunctionDecl> > {
58 public:
59 
60  /// \brief Pre-visit the Statement.
61  ///
62  /// The method will be called before the analyzer core processes the
63  /// statement. The notification is performed for every explored CFGElement,
64  /// which does not include the control flow statements such as IfStmt. The
65  /// callback can be specialized to be called with any subclass of Stmt.
66  ///
67  /// See checkBranchCondition() callback for performing custom processing of
68  /// the branching statements.
69  ///
70  /// check::PreStmt<ReturnStmt>
71  void checkPreStmt(const ReturnStmt *DS, CheckerContext &C) const {}
72 
73  /// \brief Post-visit the Statement.
74  ///
75  /// The method will be called after the analyzer core processes the
76  /// statement. The notification is performed for every explored CFGElement,
77  /// which does not include the control flow statements such as IfStmt. The
78  /// callback can be specialized to be called with any subclass of Stmt.
79  ///
80  /// check::PostStmt<DeclStmt>
81  void checkPostStmt(const DeclStmt *DS, CheckerContext &C) const;
82 
83  /// \brief Pre-visit the Objective C message.
84  ///
85  /// This will be called before the analyzer core processes the method call.
86  /// This is called for any action which produces an Objective-C message send,
87  /// including explicit message syntax and property access.
88  ///
89  /// check::PreObjCMessage
91 
92  /// \brief Post-visit the Objective C message.
93  /// \sa checkPreObjCMessage()
94  ///
95  /// check::PostObjCMessage
97 
98  /// \brief Pre-visit an abstract "call" event.
99  ///
100  /// This is used for checkers that want to check arguments or attributed
101  /// behavior for functions and methods no matter how they are being invoked.
102  ///
103  /// Note that this includes ALL cross-body invocations, so if you want to
104  /// limit your checks to, say, function calls, you should test for that at the
105  /// beginning of your callback function.
106  ///
107  /// check::PreCall
108  void checkPreCall(const CallEvent &Call, CheckerContext &C) const {}
109 
110  /// \brief Post-visit an abstract "call" event.
111  /// \sa checkPreObjCMessage()
112  ///
113  /// check::PostCall
114  void checkPostCall(const CallEvent &Call, CheckerContext &C) const {}
115 
116  /// \brief Pre-visit of the condition statement of a branch (such as IfStmt).
117  void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {}
118 
119  /// \brief Called on a load from and a store to a location.
120  ///
121  /// The method will be called each time a location (pointer) value is
122  /// accessed.
123  /// \param Loc The value of the location (pointer).
124  /// \param IsLoad The flag specifying if the location is a store or a load.
125  /// \param S The load is performed while processing the statement.
126  ///
127  /// check::Location
128  void checkLocation(SVal Loc, bool IsLoad, const Stmt *S,
129  CheckerContext &) const {}
130 
131  /// \brief Called on binding of a value to a location.
132  ///
133  /// \param Loc The value of the location (pointer).
134  /// \param Val The value which will be stored at the location Loc.
135  /// \param S The bind is performed while processing the statement S.
136  ///
137  /// check::Bind
138  void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {}
139 
140 
141  /// \brief Called whenever a symbol becomes dead.
142  ///
143  /// This callback should be used by the checkers to aggressively clean
144  /// up/reduce the checker state, which is important for reducing the overall
145  /// memory usage. Specifically, if a checker keeps symbol specific information
146  /// in the sate, it can and should be dropped after the symbol becomes dead.
147  /// In addition, reporting a bug as soon as the checker becomes dead leads to
148  /// more precise diagnostics. (For example, one should report that a malloced
149  /// variable is not freed right after it goes out of scope.)
150  ///
151  /// \param SR The SymbolReaper object can be queried to determine which
152  /// symbols are dead.
153  ///
154  /// check::DeadSymbols
156 
157  /// \brief Called when the analyzer core reaches the end of a
158  /// function being analyzed.
159  ///
160  /// check::EndFunction
161  void checkEndFunction(CheckerContext &Ctx) const {}
162 
163  /// \brief Called after all the paths in the ExplodedGraph reach end of path
164  /// - the symbolic execution graph is fully explored.
165  ///
166  /// This callback should be used in cases when a checker needs to have a
167  /// global view of the information generated on all paths. For example, to
168  /// compare execution summary/result several paths.
169  /// See IdempotentOperationChecker for a usage example.
170  ///
171  /// check::EndAnalysis
173  BugReporter &BR,
174  ExprEngine &Eng) const {}
175 
176  /// \brief Called after analysis of a TranslationUnit is complete.
177  ///
178  /// check::EndOfTranslationUnit
180  AnalysisManager &Mgr,
181  BugReporter &BR) const {}
182 
183 
184  /// \brief Evaluates function call.
185  ///
186  /// The analysis core threats all function calls in the same way. However, some
187  /// functions have special meaning, which should be reflected in the program
188  /// state. This callback allows a checker to provide domain specific knowledge
189  /// about the particular functions it knows about.
190  ///
191  /// \returns true if the call has been successfully evaluated
192  /// and false otherwise. Note, that only one checker can evaluate a call. If
193  /// more than one checker claims that they can evaluate the same call the
194  /// first one wins.
195  ///
196  /// eval::Call
197  bool evalCall(const CallExpr *CE, CheckerContext &C) const { return true; }
198 
199  /// \brief Handles assumptions on symbolic values.
200  ///
201  /// This method is called when a symbolic expression is assumed to be true or
202  /// false. For example, the assumptions are performed when evaluating a
203  /// condition at a branch. The callback allows checkers track the assumptions
204  /// performed on the symbols of interest and change the state accordingly.
205  ///
206  /// eval::Assume
208  SVal Cond,
209  bool Assumption) const { return State; }
210 
211  /// Allows modifying SymbolReaper object. For example, checkers can explicitly
212  /// register symbols of interest as live. These symbols will not be marked
213  /// dead and removed.
214  ///
215  /// check::LiveSymbols
217 
218  /// \brief Called to determine if the checker currently needs to know if when
219  /// contents of any regions change.
220  ///
221  /// Since it is not necessarily cheap to compute which regions are being
222  /// changed, this allows the analyzer core to skip the more expensive
223  /// #checkRegionChanges when no checkers are tracking any state.
224  bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; }
225 
226  /// \brief Called when the contents of one or more regions change.
227  ///
228  /// This can occur in many different ways: an explicit bind, a blanket
229  /// invalidation of the region contents, or by passing a region to a function
230  /// call whose behavior the analyzer cannot model perfectly.
231  ///
232  /// \param State The current program state.
233  /// \param Invalidated A set of all symbols potentially touched by the change.
234  /// \param ExplicitRegions The regions explicitly requested for invalidation.
235  /// For a function call, this would be the arguments. For a bind, this
236  /// would be the region being bound to.
237  /// \param Regions The transitive closure of regions accessible from,
238  /// \p ExplicitRegions, i.e. all regions that may have been touched
239  /// by this change. For a simple bind, this list will be the same as
240  /// \p ExplicitRegions, since a bind does not affect the contents of
241  /// anything accessible through the base region.
242  /// \param Call The opaque call triggering this invalidation. Will be 0 if the
243  /// change was not triggered by a call.
244  ///
245  /// Note that this callback will not be invoked unless
246  /// #wantsRegionChangeUpdate returns \c true.
247  ///
248  /// check::RegionChanges
251  const InvalidatedSymbols *Invalidated,
252  ArrayRef<const MemRegion *> ExplicitRegions,
254  const CallEvent *Call) const {
255  return State;
256  }
257 
258  /// \brief Called when pointers escape.
259  ///
260  /// This notifies the checkers about pointer escape, which occurs whenever
261  /// the analyzer cannot track the symbol any more. For example, as a
262  /// result of assigning a pointer into a global or when it's passed to a
263  /// function call the analyzer cannot model.
264  ///
265  /// \param State The state at the point of escape.
266  /// \param Escaped The list of escaped symbols.
267  /// \param Call The corresponding CallEvent, if the symbols escape as
268  /// parameters to the given call.
269  /// \param Kind How the symbols have escaped.
270  /// \returns Checkers can modify the state by returning a new state.
272  const InvalidatedSymbols &Escaped,
273  const CallEvent *Call,
274  PointerEscapeKind Kind) const {
275  return State;
276  }
277 
278  /// \brief Called when const pointers escape.
279  ///
280  /// Note: in most cases checkPointerEscape callback is sufficient.
281  /// \sa checkPointerEscape
283  const InvalidatedSymbols &Escaped,
284  const CallEvent *Call,
285  PointerEscapeKind Kind) const {
286  return State;
287  }
288 
289  /// check::Event<ImplicitNullDerefEvent>
290  void checkEvent(ImplicitNullDerefEvent Event) const {}
291 
292  /// \brief Check every declaration in the AST.
293  ///
294  /// An AST traversal callback, which should only be used when the checker is
295  /// not path sensitive. It will be called for every Declaration in the AST and
296  /// can be specialized to only be called on subclasses of Decl, for example,
297  /// FunctionDecl.
298  ///
299  /// check::ASTDecl<FunctionDecl>
300  void checkASTDecl(const FunctionDecl *D,
301  AnalysisManager &Mgr,
302  BugReporter &BR) const {}
303 
304 };
305 
307  CheckerContext &C) const {
308  return;
309 }
310 
311 } // end namespace ento
312 } // end namespace clang
void checkPostCall(const CallEvent &Call, CheckerContext &C) const
Post-visit an abstract "call" event.
ProgramStateRef evalAssume(ProgramStateRef State, SVal Cond, bool Assumption) const
Handles assumptions on symbolic values.
ProgramStateRef checkRegionChanges(ProgramStateRef State, const InvalidatedSymbols *Invalidated, ArrayRef< const MemRegion * > ExplicitRegions, ArrayRef< const MemRegion * > Regions, const CallEvent *Call) const
Called when the contents of one or more regions change.
ProgramStateRef checkPointerEscape(ProgramStateRef State, const InvalidatedSymbols &Escaped, const CallEvent *Call, PointerEscapeKind Kind) const
Called when pointers escape.
void checkPreObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const
Pre-visit the Objective C message.
void checkPreCall(const CallEvent &Call, CheckerContext &C) const
Pre-visit an abstract "call" event.
LineState State
void checkEndAnalysis(ExplodedGraph &G, BugReporter &BR, ExprEngine &Eng) const
Called after all the paths in the ExplodedGraph reach end of path.
Represents any expression that calls an Objective-C method.
Definition: CallEvent.h:791
void checkLocation(SVal Loc, bool IsLoad, const Stmt *S, CheckerContext &) const
Called on a load from and a store to a location.
bool wantsRegionChangeUpdate(ProgramStateRef St) const
Called to determine if the checker currently needs to know if when contents of any regions change...
void checkPostObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const
Post-visit the Objective C message.
We dereferenced a location that may be null.
Definition: Checker.h:512
void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const
bool evalCall(const CallExpr *CE, CheckerContext &C) const
Evaluates function call.
void checkEndFunction(CheckerContext &Ctx) const
Called when the analyzer core reaches the end of a function being analyzed.
void checkEndOfTranslationUnit(const TranslationUnitDecl *TU, AnalysisManager &Mgr, BugReporter &BR) const
Called after analysis of a TranslationUnit is complete.
Kind
A class responsible for cleaning up unused symbols.
ProgramStateRef checkConstPointerEscape(ProgramStateRef State, const InvalidatedSymbols &Escaped, const CallEvent *Call, PointerEscapeKind Kind) const
Called when const pointers escape.
void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const
Pre-visit of the condition statement of a branch (such as IfStmt).
void checkEvent(ImplicitNullDerefEvent Event) const
check::Event<ImplicitNullDerefEvent>
Represents an abstract call to a function or method along a particular path.
Definition: CallEvent.h:113
void checkPostStmt(const DeclStmt *DS, CheckerContext &C) const
Post-visit the Statement.
PointerEscapeKind
Describes the different reasons a pointer escapes during analysis.
void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const
Called on binding of a value to a location.
TranslationUnitDecl - The top declaration context.
Definition: Decl.h:78
void checkASTDecl(const FunctionDecl *D, AnalysisManager &Mgr, BugReporter &BR) const
Check every declaration in the AST.
void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const
Called whenever a symbol becomes dead.
void checkPreStmt(const ReturnStmt *DS, CheckerContext &C) const
Pre-visit the Statement.