clang  4.0.0svn
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::BeginFunction,
49  check::EndFunction,
50  check::EndAnalysis,
51  check::EndOfTranslationUnit,
52  eval::Call,
53  eval::Assume,
54  check::LiveSymbols,
55  check::RegionChanges,
56  check::PointerEscape,
57  check::ConstPointerEscape,
58  check::Event<ImplicitNullDerefEvent>,
59  check::ASTDecl<FunctionDecl> > {
60 public:
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  /// \brief Called whenever a symbol becomes dead.
151  ///
152  /// This callback should be used by the checkers to aggressively clean
153  /// up/reduce the checker state, which is important for reducing the overall
154  /// memory usage. Specifically, if a checker keeps symbol specific information
155  /// in the sate, it can and should be dropped after the symbol becomes dead.
156  /// In addition, reporting a bug as soon as the checker becomes dead leads to
157  /// more precise diagnostics. (For example, one should report that a malloced
158  /// variable is not freed right after it goes out of scope.)
159  ///
160  /// \param SR The SymbolReaper object can be queried to determine which
161  /// symbols are dead.
162  ///
163  /// check::DeadSymbols
165 
166 
167  /// \brief Called when the analyzer core starts analyzing a function,
168  /// regardless of whether it is analyzed at the top level or is inlined.
169  ///
170  /// check::BeginFunction
171  void checkBeginFunction(CheckerContext &Ctx) const {}
172 
173  /// \brief Called when the analyzer core reaches the end of a
174  /// function being analyzed regardless of whether it is analyzed at the top
175  /// level or is inlined.
176  ///
177  /// check::EndFunction
178  void checkEndFunction(CheckerContext &Ctx) const {}
179 
180  /// \brief Called after all the paths in the ExplodedGraph reach end of path
181  /// - the symbolic execution graph is fully explored.
182  ///
183  /// This callback should be used in cases when a checker needs to have a
184  /// global view of the information generated on all paths. For example, to
185  /// compare execution summary/result several paths.
186  /// See IdempotentOperationChecker for a usage example.
187  ///
188  /// check::EndAnalysis
190  BugReporter &BR,
191  ExprEngine &Eng) const {}
192 
193  /// \brief Called after analysis of a TranslationUnit is complete.
194  ///
195  /// check::EndOfTranslationUnit
197  AnalysisManager &Mgr,
198  BugReporter &BR) const {}
199 
200  /// \brief Evaluates function call.
201  ///
202  /// The analysis core threats all function calls in the same way. However, some
203  /// functions have special meaning, which should be reflected in the program
204  /// state. This callback allows a checker to provide domain specific knowledge
205  /// about the particular functions it knows about.
206  ///
207  /// \returns true if the call has been successfully evaluated
208  /// and false otherwise. Note, that only one checker can evaluate a call. If
209  /// more than one checker claims that they can evaluate the same call the
210  /// first one wins.
211  ///
212  /// eval::Call
213  bool evalCall(const CallExpr *CE, CheckerContext &C) const { return true; }
214 
215  /// \brief Handles assumptions on symbolic values.
216  ///
217  /// This method is called when a symbolic expression is assumed to be true or
218  /// false. For example, the assumptions are performed when evaluating a
219  /// condition at a branch. The callback allows checkers track the assumptions
220  /// performed on the symbols of interest and change the state accordingly.
221  ///
222  /// eval::Assume
224  SVal Cond,
225  bool Assumption) const { return State; }
226 
227  /// Allows modifying SymbolReaper object. For example, checkers can explicitly
228  /// register symbols of interest as live. These symbols will not be marked
229  /// dead and removed.
230  ///
231  /// check::LiveSymbols
233 
234  /// \brief Called to determine if the checker currently needs to know if when
235  /// contents of any regions change.
236  ///
237  /// Since it is not necessarily cheap to compute which regions are being
238  /// changed, this allows the analyzer core to skip the more expensive
239  /// #checkRegionChanges when no checkers are tracking any state.
240  bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; }
241 
242  /// \brief Called when the contents of one or more regions change.
243  ///
244  /// This can occur in many different ways: an explicit bind, a blanket
245  /// invalidation of the region contents, or by passing a region to a function
246  /// call whose behavior the analyzer cannot model perfectly.
247  ///
248  /// \param State The current program state.
249  /// \param Invalidated A set of all symbols potentially touched by the change.
250  /// \param ExplicitRegions The regions explicitly requested for invalidation.
251  /// For a function call, this would be the arguments. For a bind, this
252  /// would be the region being bound to.
253  /// \param Regions The transitive closure of regions accessible from,
254  /// \p ExplicitRegions, i.e. all regions that may have been touched
255  /// by this change. For a simple bind, this list will be the same as
256  /// \p ExplicitRegions, since a bind does not affect the contents of
257  /// anything accessible through the base region.
258  /// \param Call The opaque call triggering this invalidation. Will be 0 if the
259  /// change was not triggered by a call.
260  ///
261  /// Note that this callback will not be invoked unless
262  /// #wantsRegionChangeUpdate returns \c true.
263  ///
264  /// check::RegionChanges
267  const InvalidatedSymbols *Invalidated,
268  ArrayRef<const MemRegion *> ExplicitRegions,
270  const CallEvent *Call) const {
271  return State;
272  }
273 
274  /// \brief Called when pointers escape.
275  ///
276  /// This notifies the checkers about pointer escape, which occurs whenever
277  /// the analyzer cannot track the symbol any more. For example, as a
278  /// result of assigning a pointer into a global or when it's passed to a
279  /// function call the analyzer cannot model.
280  ///
281  /// \param State The state at the point of escape.
282  /// \param Escaped The list of escaped symbols.
283  /// \param Call The corresponding CallEvent, if the symbols escape as
284  /// parameters to the given call.
285  /// \param Kind How the symbols have escaped.
286  /// \returns Checkers can modify the state by returning a new state.
288  const InvalidatedSymbols &Escaped,
289  const CallEvent *Call,
290  PointerEscapeKind Kind) const {
291  return State;
292  }
293 
294  /// \brief Called when const pointers escape.
295  ///
296  /// Note: in most cases checkPointerEscape callback is sufficient.
297  /// \sa checkPointerEscape
299  const InvalidatedSymbols &Escaped,
300  const CallEvent *Call,
301  PointerEscapeKind Kind) const {
302  return State;
303  }
304 
305  /// check::Event<ImplicitNullDerefEvent>
306  void checkEvent(ImplicitNullDerefEvent Event) const {}
307 
308  /// \brief Check every declaration in the AST.
309  ///
310  /// An AST traversal callback, which should only be used when the checker is
311  /// not path sensitive. It will be called for every Declaration in the AST and
312  /// can be specialized to only be called on subclasses of Decl, for example,
313  /// FunctionDecl.
314  ///
315  /// check::ASTDecl<FunctionDecl>
316  void checkASTDecl(const FunctionDecl *D,
317  AnalysisManager &Mgr,
318  BugReporter &BR) const {}
319 };
320 
322  CheckerContext &C) const {
323 }
324 
325 } // end namespace ento
326 } // 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:1561
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:881
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:541
void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const
Allows modifying SymbolReaper object.
void checkBeginFunction(CheckerContext &Ctx) const
Called when the analyzer core starts analyzing a function, regardless of whether it is analyzed at th...
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 regardless of whether it i...
ReturnStmt - This represents a return, optionally of an expression: return; return 4;...
Definition: Stmt.h:1368
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:363
Kind
DeclStmt - Adaptor class for mixing declarations with statements and expressions. ...
Definition: Stmt.h:443
SVal - This represents a symbolic expression, which can be either an L-value or an R-value...
Definition: SVals.h:46
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).
/file This file defines classes for searching and anlyzing source code clones.
void checkEvent(ImplicitNullDerefEvent Event) const
check::Event<ImplicitNullDerefEvent>
Represents an abstract call to a function or method along a particular path.
Definition: CallEvent.h:138
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:2148
TranslationUnitDecl - The top declaration context.
Definition: Decl.h:80
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.