clang  3.9.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::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  /// \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 Visit an Objective-C message whose receiver is nil.
99  ///
100  /// This will be called when the analyzer core processes a method call whose
101  /// receiver is definitely nil. In this case, check{Pre/Post}ObjCMessage and
102  /// check{Pre/Post}Call will not be called.
103  ///
104  /// check::ObjCMessageNil
106 
107  /// \brief Pre-visit an abstract "call" event.
108  ///
109  /// This is used for checkers that want to check arguments or attributed
110  /// behavior for functions and methods no matter how they are being invoked.
111  ///
112  /// Note that this includes ALL cross-body invocations, so if you want to
113  /// limit your checks to, say, function calls, you should test for that at the
114  /// beginning of your callback function.
115  ///
116  /// check::PreCall
117  void checkPreCall(const CallEvent &Call, CheckerContext &C) const {}
118 
119  /// \brief Post-visit an abstract "call" event.
120  /// \sa checkPreObjCMessage()
121  ///
122  /// check::PostCall
123  void checkPostCall(const CallEvent &Call, CheckerContext &C) const {}
124 
125  /// \brief Pre-visit of the condition statement of a branch (such as IfStmt).
126  void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {}
127 
128  /// \brief Called on a load from and a store to a location.
129  ///
130  /// The method will be called each time a location (pointer) value is
131  /// accessed.
132  /// \param Loc The value of the location (pointer).
133  /// \param IsLoad The flag specifying if the location is a store or a load.
134  /// \param S The load is performed while processing the statement.
135  ///
136  /// check::Location
137  void checkLocation(SVal Loc, bool IsLoad, const Stmt *S,
138  CheckerContext &) const {}
139 
140  /// \brief Called on binding of a value to a location.
141  ///
142  /// \param Loc The value of the location (pointer).
143  /// \param Val The value which will be stored at the location Loc.
144  /// \param S The bind is performed while processing the statement S.
145  ///
146  /// check::Bind
147  void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {}
148 
149  /// \brief Called whenever a symbol becomes dead.
150  ///
151  /// This callback should be used by the checkers to aggressively clean
152  /// up/reduce the checker state, which is important for reducing the overall
153  /// memory usage. Specifically, if a checker keeps symbol specific information
154  /// in the sate, it can and should be dropped after the symbol becomes dead.
155  /// In addition, reporting a bug as soon as the checker becomes dead leads to
156  /// more precise diagnostics. (For example, one should report that a malloced
157  /// variable is not freed right after it goes out of scope.)
158  ///
159  /// \param SR The SymbolReaper object can be queried to determine which
160  /// symbols are dead.
161  ///
162  /// check::DeadSymbols
164 
165 
166  /// \brief Called when the analyzer core starts analyzing a function,
167  /// regardless of whether it is analyzed at the top level or is inlined.
168  ///
169  /// check::BeginFunction
170  void checkBeginFunction(CheckerContext &Ctx) const {}
171 
172  /// \brief Called when the analyzer core reaches the end of a
173  /// function being analyzed regardless of whether it is analyzed at the top
174  /// level or is inlined.
175  ///
176  /// check::EndFunction
177  void checkEndFunction(CheckerContext &Ctx) const {}
178 
179  /// \brief Called after all the paths in the ExplodedGraph reach end of path
180  /// - the symbolic execution graph is fully explored.
181  ///
182  /// This callback should be used in cases when a checker needs to have a
183  /// global view of the information generated on all paths. For example, to
184  /// compare execution summary/result several paths.
185  /// See IdempotentOperationChecker for a usage example.
186  ///
187  /// check::EndAnalysis
189  BugReporter &BR,
190  ExprEngine &Eng) const {}
191 
192  /// \brief Called after analysis of a TranslationUnit is complete.
193  ///
194  /// check::EndOfTranslationUnit
196  AnalysisManager &Mgr,
197  BugReporter &BR) const {}
198 
199  /// \brief Evaluates function call.
200  ///
201  /// The analysis core threats all function calls in the same way. However, some
202  /// functions have special meaning, which should be reflected in the program
203  /// state. This callback allows a checker to provide domain specific knowledge
204  /// about the particular functions it knows about.
205  ///
206  /// \returns true if the call has been successfully evaluated
207  /// and false otherwise. Note, that only one checker can evaluate a call. If
208  /// more than one checker claims that they can evaluate the same call the
209  /// first one wins.
210  ///
211  /// eval::Call
212  bool evalCall(const CallExpr *CE, CheckerContext &C) const { return true; }
213 
214  /// \brief Handles assumptions on symbolic values.
215  ///
216  /// This method is called when a symbolic expression is assumed to be true or
217  /// false. For example, the assumptions are performed when evaluating a
218  /// condition at a branch. The callback allows checkers track the assumptions
219  /// performed on the symbols of interest and change the state accordingly.
220  ///
221  /// eval::Assume
223  SVal Cond,
224  bool Assumption) const { return State; }
225 
226  /// Allows modifying SymbolReaper object. For example, checkers can explicitly
227  /// register symbols of interest as live. These symbols will not be marked
228  /// dead and removed.
229  ///
230  /// check::LiveSymbols
232 
233  /// \brief Called to determine if the checker currently needs to know if when
234  /// contents of any regions change.
235  ///
236  /// Since it is not necessarily cheap to compute which regions are being
237  /// changed, this allows the analyzer core to skip the more expensive
238  /// #checkRegionChanges when no checkers are tracking any state.
239  bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; }
240 
241  /// \brief Called when the contents of one or more regions change.
242  ///
243  /// This can occur in many different ways: an explicit bind, a blanket
244  /// invalidation of the region contents, or by passing a region to a function
245  /// call whose behavior the analyzer cannot model perfectly.
246  ///
247  /// \param State The current program state.
248  /// \param Invalidated A set of all symbols potentially touched by the change.
249  /// \param ExplicitRegions The regions explicitly requested for invalidation.
250  /// For a function call, this would be the arguments. For a bind, this
251  /// would be the region being bound to.
252  /// \param Regions The transitive closure of regions accessible from,
253  /// \p ExplicitRegions, i.e. all regions that may have been touched
254  /// by this change. For a simple bind, this list will be the same as
255  /// \p ExplicitRegions, since a bind does not affect the contents of
256  /// anything accessible through the base region.
257  /// \param Call The opaque call triggering this invalidation. Will be 0 if the
258  /// change was not triggered by a call.
259  ///
260  /// Note that this callback will not be invoked unless
261  /// #wantsRegionChangeUpdate returns \c true.
262  ///
263  /// check::RegionChanges
266  const InvalidatedSymbols *Invalidated,
267  ArrayRef<const MemRegion *> ExplicitRegions,
269  const CallEvent *Call) const {
270  return State;
271  }
272 
273  /// \brief Called when pointers escape.
274  ///
275  /// This notifies the checkers about pointer escape, which occurs whenever
276  /// the analyzer cannot track the symbol any more. For example, as a
277  /// result of assigning a pointer into a global or when it's passed to a
278  /// function call the analyzer cannot model.
279  ///
280  /// \param State The state at the point of escape.
281  /// \param Escaped The list of escaped symbols.
282  /// \param Call The corresponding CallEvent, if the symbols escape as
283  /// parameters to the given call.
284  /// \param Kind How the symbols have escaped.
285  /// \returns Checkers can modify the state by returning a new state.
287  const InvalidatedSymbols &Escaped,
288  const CallEvent *Call,
289  PointerEscapeKind Kind) const {
290  return State;
291  }
292 
293  /// \brief Called when const pointers escape.
294  ///
295  /// Note: in most cases checkPointerEscape callback is sufficient.
296  /// \sa checkPointerEscape
298  const InvalidatedSymbols &Escaped,
299  const CallEvent *Call,
300  PointerEscapeKind Kind) const {
301  return State;
302  }
303 
304  /// check::Event<ImplicitNullDerefEvent>
305  void checkEvent(ImplicitNullDerefEvent Event) const {}
306 
307  /// \brief Check every declaration in the AST.
308  ///
309  /// An AST traversal callback, which should only be used when the checker is
310  /// not path sensitive. It will be called for every Declaration in the AST and
311  /// can be specialized to only be called on subclasses of Decl, for example,
312  /// FunctionDecl.
313  ///
314  /// check::ASTDecl<FunctionDecl>
315  void checkASTDecl(const FunctionDecl *D,
316  AnalysisManager &Mgr,
317  BugReporter &BR) const {}
318 };
319 
321  CheckerContext &C) const {
322 }
323 
324 } // end namespace ento
325 } // 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:1539
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:880
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:1345
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:432
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).
Dataflow Directional Tag Classes.
void checkEvent(ImplicitNullDerefEvent Event) const
check::Event<ImplicitNullDerefEvent>
Represents an abstract call to a function or method along a particular path.
Definition: CallEvent.h:137
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:2144
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.