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