CheckerDocumentation.cpp revision 96479da6ad9d921d875e7be29fe1bfa127be8069
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 ento { 29 30/// This checker documents the callback functions checkers can use to implement 31/// the custom handling of the specific events during path exploration as well 32/// as reporting bugs. Most of the callbacks are targeted at path-sensitive 33/// checking. 34/// 35/// \sa CheckerContext 36class CheckerDocumentation : public Checker< check::PreStmt<DeclStmt>, 37 check::PostStmt<CallExpr>, 38 check::PreObjCMessage, 39 check::PostObjCMessage, 40 check::PreCall, 41 check::PostCall, 42 check::BranchCondition, 43 check::Location, 44 check::Bind, 45 check::DeadSymbols, 46 check::EndPath, 47 check::EndAnalysis, 48 check::EndOfTranslationUnit, 49 eval::Call, 50 eval::Assume, 51 check::LiveSymbols, 52 check::RegionChanges, 53 check::Event<ImplicitNullDerefEvent>, 54 check::ASTDecl<FunctionDecl> > { 55public: 56 57 /// \brief Pre-visit the Statement. 58 /// 59 /// The method will be called before the analyzer core processes the 60 /// statement. The notification is performed for every explored CFGElement, 61 /// which does not include the control flow statements such as IfStmt. The 62 /// callback can be specialized to be called with any subclass of Stmt. 63 /// 64 /// See checkBranchCondition() callback for performing custom processing of 65 /// the branching statements. 66 /// 67 /// check::PreStmt<DeclStmt> 68 void checkPreStmt(const DeclStmt *DS, CheckerContext &C) const {} 69 70 /// \brief Post-visit the Statement. 71 /// 72 /// The method will be called after the analyzer core processes the 73 /// statement. The notification is performed for every explored CFGElement, 74 /// which does not include the control flow statements such as IfStmt. The 75 /// callback can be specialized to be called with any subclass of Stmt. 76 /// 77 /// check::PostStmt<CallExpr> 78 void checkPostStmt(const CallExpr *DS, CheckerContext &C) const; 79 80 /// \brief Pre-visit the Objective C message. 81 /// 82 /// This will be called before the analyzer core processes the method call. 83 /// This is called for any action which produces an Objective-C message send, 84 /// including explicit message syntax and property access. See the subclasses 85 /// of ObjCMethodCall for more details. 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 can either test for that 103 /// or fall back to the explicit callback (i.e. check::PreStmt). 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 an end of path is reached in the ExplodedGraph. 156 /// 157 /// This callback should be used to check if the allocated resources are freed. 158 /// 159 /// check::EndPath 160 void checkEndPath(CheckerContext &Ctx) const {} 161 162 /// \brief Called after all the paths in the ExplodedGraph reach end of path 163 /// - the symbolic execution graph is fully explored. 164 /// 165 /// This callback should be used in cases when a checker needs to have a 166 /// global view of the information generated on all paths. For example, to 167 /// compare execution summary/result several paths. 168 /// See IdempotentOperationChecker for a usage example. 169 /// 170 /// check::EndAnalysis 171 void checkEndAnalysis(ExplodedGraph &G, 172 BugReporter &BR, 173 ExprEngine &Eng) const {} 174 175 /// \brief Called after analysis of a TranslationUnit is complete. 176 /// 177 /// check::EndOfTranslationUnit 178 void checkEndOfTranslationUnit(const TranslationUnitDecl *TU, 179 AnalysisManager &Mgr, 180 BugReporter &BR) const {} 181 182 183 /// \brief Evaluates function call. 184 /// 185 /// The analysis core threats all function calls in the same way. However, some 186 /// functions have special meaning, which should be reflected in the program 187 /// state. This callback allows a checker to provide domain specific knowledge 188 /// about the particular functions it knows about. 189 /// 190 /// \returns true if the call has been successfully evaluated 191 /// and false otherwise. Note, that only one checker can evaluate a call. If 192 /// more then one checker claim that they can evaluate the same call the 193 /// first one wins. 194 /// 195 /// eval::Call 196 bool evalCall(const CallExpr *CE, CheckerContext &C) const { return true; } 197 198 /// \brief Handles assumptions on symbolic values. 199 /// 200 /// This method is called when a symbolic expression is assumed to be true or 201 /// false. For example, the assumptions are performed when evaluating a 202 /// condition at a branch. The callback allows checkers track the assumptions 203 /// performed on the symbols of interest and change the state accordingly. 204 /// 205 /// eval::Assume 206 ProgramStateRef evalAssume(ProgramStateRef State, 207 SVal Cond, 208 bool Assumption) const { return State; } 209 210 /// Allows modifying SymbolReaper object. For example, checkers can explicitly 211 /// register symbols of interest as live. These symbols will not be marked 212 /// dead and removed. 213 /// 214 /// check::LiveSymbols 215 void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const {} 216 217 218 bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; } 219 220 /// \brief Allows tracking regions which get invalidated. 221 /// 222 /// \param State The current program state. 223 /// \param Invalidated A set of all symbols potentially touched by the change. 224 /// \param ExplicitRegions The regions explicitly requested for invalidation. 225 /// For example, in the case of a function call, these would be arguments. 226 /// \param Regions The transitive closure of accessible regions, 227 /// i.e. all regions that may have been touched by this change. 228 /// \param Call The call expression wrapper if the regions are invalidated 229 /// by a call, 0 otherwise. 230 /// Note, in order to be notified, the checker should also implement the 231 /// wantsRegionChangeUpdate callback. 232 /// 233 /// check::RegionChanges 234 ProgramStateRef 235 checkRegionChanges(ProgramStateRef State, 236 const StoreManager::InvalidatedSymbols *Invalidated, 237 ArrayRef<const MemRegion *> ExplicitRegions, 238 ArrayRef<const MemRegion *> Regions, 239 const CallEvent *Call) const { 240 return State; 241 } 242 243 /// check::Event<ImplicitNullDerefEvent> 244 void checkEvent(ImplicitNullDerefEvent Event) const {} 245 246 /// \brief Check every declaration in the AST. 247 /// 248 /// An AST traversal callback, which should only be used when the checker is 249 /// not path sensitive. It will be called for every Declaration in the AST and 250 /// can be specialized to only be called on subclasses of Decl, for example, 251 /// FunctionDecl. 252 /// 253 /// check::ASTDecl<FunctionDecl> 254 void checkASTDecl(const FunctionDecl *D, 255 AnalysisManager &Mgr, 256 BugReporter &BR) const {} 257 258}; 259 260void CheckerDocumentation::checkPostStmt(const CallExpr *DS, 261 CheckerContext &C) const { 262 return; 263} 264 265} // end namespace 266