CheckerDocumentation.cpp revision 243830
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" 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/BugReporter/BugType.h" 20#include "clang/StaticAnalyzer/Core/PathSensitive/ProgramStateTrait.h" 21 22using namespace clang; 23using 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. 28namespace clang { 29namespace 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 37class 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::EndPath, 48 check::EndAnalysis, 49 check::EndOfTranslationUnit, 50 eval::Call, 51 eval::Assume, 52 check::LiveSymbols, 53 check::RegionChanges, 54 check::Event<ImplicitNullDerefEvent>, 55 check::ASTDecl<FunctionDecl> > { 56public: 57 58 /// \brief Pre-visit the Statement. 59 /// 60 /// The method will be called before the analyzer core processes the 61 /// statement. The notification is performed for every explored CFGElement, 62 /// which does not include the control flow statements such as IfStmt. The 63 /// callback can be specialized to be called with any subclass of Stmt. 64 /// 65 /// See checkBranchCondition() callback for performing custom processing of 66 /// the branching statements. 67 /// 68 /// check::PreStmt<ReturnStmt> 69 void checkPreStmt(const ReturnStmt *DS, CheckerContext &C) const {} 70 71 /// \brief Post-visit the Statement. 72 /// 73 /// The method will be called after the analyzer core processes the 74 /// statement. The notification is performed for every explored CFGElement, 75 /// which does not include the control flow statements such as IfStmt. The 76 /// callback can be specialized to be called with any subclass of Stmt. 77 /// 78 /// check::PostStmt<DeclStmt> 79 void checkPostStmt(const DeclStmt *DS, CheckerContext &C) const; 80 81 /// \brief Pre-visit the Objective C message. 82 /// 83 /// This will be called before the analyzer core processes the method call. 84 /// This is called for any action which produces an Objective-C message send, 85 /// including explicit message syntax and property access. 86 /// 87 /// check::PreObjCMessage 88 void checkPreObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 89 90 /// \brief Post-visit the Objective C message. 91 /// \sa checkPreObjCMessage() 92 /// 93 /// check::PostObjCMessage 94 void checkPostObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 95 96 /// \brief Pre-visit an abstract "call" event. 97 /// 98 /// This is used for checkers that want to check arguments or attributed 99 /// behavior for functions and methods no matter how they are being invoked. 100 /// 101 /// Note that this includes ALL cross-body invocations, so if you want to 102 /// limit your checks to, say, function calls, you should test for that at the 103 /// beginning of your callback function. 104 /// 105 /// check::PreCall 106 void checkPreCall(const CallEvent &Call, CheckerContext &C) const {} 107 108 /// \brief Post-visit an abstract "call" event. 109 /// \sa checkPreObjCMessage() 110 /// 111 /// check::PostCall 112 void checkPostCall(const CallEvent &Call, CheckerContext &C) const {} 113 114 /// \brief Pre-visit of the condition statement of a branch (such as IfStmt). 115 void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {} 116 117 /// \brief Called on a load from and a store to a location. 118 /// 119 /// The method will be called each time a location (pointer) value is 120 /// accessed. 121 /// \param Loc The value of the location (pointer). 122 /// \param IsLoad The flag specifying if the location is a store or a load. 123 /// \param S The load is performed while processing the statement. 124 /// 125 /// check::Location 126 void checkLocation(SVal Loc, bool IsLoad, const Stmt *S, 127 CheckerContext &) const {} 128 129 /// \brief Called on binding of a value to a location. 130 /// 131 /// \param Loc The value of the location (pointer). 132 /// \param Val The value which will be stored at the location Loc. 133 /// \param S The bind is performed while processing the statement S. 134 /// 135 /// check::Bind 136 void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {} 137 138 139 /// \brief Called whenever a symbol becomes dead. 140 /// 141 /// This callback should be used by the checkers to aggressively clean 142 /// up/reduce the checker state, which is important for reducing the overall 143 /// memory usage. Specifically, if a checker keeps symbol specific information 144 /// in the sate, it can and should be dropped after the symbol becomes dead. 145 /// In addition, reporting a bug as soon as the checker becomes dead leads to 146 /// more precise diagnostics. (For example, one should report that a malloced 147 /// variable is not freed right after it goes out of scope.) 148 /// 149 /// \param SR The SymbolReaper object can be queried to determine which 150 /// symbols are dead. 151 /// 152 /// check::DeadSymbols 153 void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {} 154 155 /// \brief Called when the analyzer core reaches the end of the top-level 156 /// function being analyzed. 157 /// 158 /// check::EndPath 159 void checkEndPath(CheckerContext &Ctx) const {} 160 161 /// \brief Called after all the paths in the ExplodedGraph reach end of path 162 /// - the symbolic execution graph is fully explored. 163 /// 164 /// This callback should be used in cases when a checker needs to have a 165 /// global view of the information generated on all paths. For example, to 166 /// compare execution summary/result several paths. 167 /// See IdempotentOperationChecker for a usage example. 168 /// 169 /// check::EndAnalysis 170 void checkEndAnalysis(ExplodedGraph &G, 171 BugReporter &BR, 172 ExprEngine &Eng) const {} 173 174 /// \brief Called after analysis of a TranslationUnit is complete. 175 /// 176 /// check::EndOfTranslationUnit 177 void checkEndOfTranslationUnit(const TranslationUnitDecl *TU, 178 AnalysisManager &Mgr, 179 BugReporter &BR) const {} 180 181 182 /// \brief Evaluates function call. 183 /// 184 /// The analysis core threats all function calls in the same way. However, some 185 /// functions have special meaning, which should be reflected in the program 186 /// state. This callback allows a checker to provide domain specific knowledge 187 /// about the particular functions it knows about. 188 /// 189 /// \returns true if the call has been successfully evaluated 190 /// and false otherwise. Note, that only one checker can evaluate a call. If 191 /// more then one checker claim that they can evaluate the same call the 192 /// first one wins. 193 /// 194 /// eval::Call 195 bool evalCall(const CallExpr *CE, CheckerContext &C) const { return true; } 196 197 /// \brief Handles assumptions on symbolic values. 198 /// 199 /// This method is called when a symbolic expression is assumed to be true or 200 /// false. For example, the assumptions are performed when evaluating a 201 /// condition at a branch. The callback allows checkers track the assumptions 202 /// performed on the symbols of interest and change the state accordingly. 203 /// 204 /// eval::Assume 205 ProgramStateRef evalAssume(ProgramStateRef State, 206 SVal Cond, 207 bool Assumption) const { return State; } 208 209 /// Allows modifying SymbolReaper object. For example, checkers can explicitly 210 /// register symbols of interest as live. These symbols will not be marked 211 /// dead and removed. 212 /// 213 /// check::LiveSymbols 214 void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const {} 215 216 /// \brief Called to determine if the checker currently needs to know if when 217 /// contents of any regions change. 218 /// 219 /// Since it is not necessarily cheap to compute which regions are being 220 /// changed, this allows the analyzer core to skip the more expensive 221 /// #checkRegionChanges when no checkers are tracking any state. 222 bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; } 223 224 /// \brief Called when the contents of one or more regions change. 225 /// 226 /// This can occur in many different ways: an explicit bind, a blanket 227 /// invalidation of the region contents, or by passing a region to a function 228 /// call whose behavior the analyzer cannot model perfectly. 229 /// 230 /// \param State The current program state. 231 /// \param Invalidated A set of all symbols potentially touched by the change. 232 /// \param ExplicitRegions The regions explicitly requested for invalidation. 233 /// For a function call, this would be the arguments. For a bind, this 234 /// would be the region being bound to. 235 /// \param Regions The transitive closure of regions accessible from, 236 /// \p ExplicitRegions, i.e. all regions that may have been touched 237 /// by this change. For a simple bind, this list will be the same as 238 /// \p ExplicitRegions, since a bind does not affect the contents of 239 /// anything accessible through the base region. 240 /// \param Call The opaque call triggering this invalidation. Will be 0 if the 241 /// change was not triggered by a call. 242 /// 243 /// Note that this callback will not be invoked unless 244 /// #wantsRegionChangeUpdate returns \c true. 245 /// 246 /// check::RegionChanges 247 ProgramStateRef 248 checkRegionChanges(ProgramStateRef State, 249 const StoreManager::InvalidatedSymbols *Invalidated, 250 ArrayRef<const MemRegion *> ExplicitRegions, 251 ArrayRef<const MemRegion *> Regions, 252 const CallEvent *Call) const { 253 return State; 254 } 255 256 /// check::Event<ImplicitNullDerefEvent> 257 void checkEvent(ImplicitNullDerefEvent Event) const {} 258 259 /// \brief Check every declaration in the AST. 260 /// 261 /// An AST traversal callback, which should only be used when the checker is 262 /// not path sensitive. It will be called for every Declaration in the AST and 263 /// can be specialized to only be called on subclasses of Decl, for example, 264 /// FunctionDecl. 265 /// 266 /// check::ASTDecl<FunctionDecl> 267 void checkASTDecl(const FunctionDecl *D, 268 AnalysisManager &Mgr, 269 BugReporter &BR) const {} 270 271}; 272 273void CheckerDocumentation::checkPostStmt(const DeclStmt *DS, 274 CheckerContext &C) const { 275 return; 276} 277 278} // end namespace ento 279} // end namespace clang 280