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. 85 /// 86 /// check::PreObjCMessage 87 void checkPreObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 88 89 /// \brief Post-visit the Objective C message. 90 /// \sa checkPreObjCMessage() 91 /// 92 /// check::PostObjCMessage 93 void checkPostObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 94 95 /// \brief Pre-visit an abstract "call" event. 96 /// 97 /// This is used for checkers that want to check arguments or attributed 98 /// behavior for functions and methods no matter how they are being invoked. 99 /// 100 /// Note that this includes ALL cross-body invocations, so if you want to 101 /// limit your checks to, say, function calls, you can either test for that 102 /// or fall back to the explicit callback (i.e. check::PreStmt). 103 /// 104 /// check::PreCall 105 void checkPreCall(const CallEvent &Call, CheckerContext &C) const {} 106 107 /// \brief Post-visit an abstract "call" event. 108 /// \sa checkPreObjCMessage() 109 /// 110 /// check::PostCall 111 void checkPostCall(const CallEvent &Call, CheckerContext &C) const {} 112 113 /// \brief Pre-visit of the condition statement of a branch (such as IfStmt). 114 void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {} 115 116 /// \brief Called on a load from and a store to a location. 117 /// 118 /// The method will be called each time a location (pointer) value is 119 /// accessed. 120 /// \param Loc The value of the location (pointer). 121 /// \param IsLoad The flag specifying if the location is a store or a load. 122 /// \param S The load is performed while processing the statement. 123 /// 124 /// check::Location 125 void checkLocation(SVal Loc, bool IsLoad, const Stmt *S, 126 CheckerContext &) const {} 127 128 /// \brief Called on binding of a value to a location. 129 /// 130 /// \param Loc The value of the location (pointer). 131 /// \param Val The value which will be stored at the location Loc. 132 /// \param S The bind is performed while processing the statement S. 133 /// 134 /// check::Bind 135 void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {} 136 137 138 /// \brief Called whenever a symbol becomes dead. 139 /// 140 /// This callback should be used by the checkers to aggressively clean 141 /// up/reduce the checker state, which is important for reducing the overall 142 /// memory usage. Specifically, if a checker keeps symbol specific information 143 /// in the sate, it can and should be dropped after the symbol becomes dead. 144 /// In addition, reporting a bug as soon as the checker becomes dead leads to 145 /// more precise diagnostics. (For example, one should report that a malloced 146 /// variable is not freed right after it goes out of scope.) 147 /// 148 /// \param SR The SymbolReaper object can be queried to determine which 149 /// symbols are dead. 150 /// 151 /// check::DeadSymbols 152 void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {} 153 154 /// \brief Called when an end of path is reached in the ExplodedGraph. 155 /// 156 /// This callback should be used to check if the allocated resources are freed. 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 217 bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; } 218 219 /// \brief Allows tracking regions which get invalidated. 220 /// 221 /// \param State The current program state. 222 /// \param Invalidated A set of all symbols potentially touched by the change. 223 /// \param ExplicitRegions The regions explicitly requested for invalidation. 224 /// For example, in the case of a function call, these would be arguments. 225 /// \param Regions The transitive closure of accessible regions, 226 /// i.e. all regions that may have been touched by this change. 227 /// \param Call The call expression wrapper if the regions are invalidated 228 /// by a call, 0 otherwise. 229 /// Note, in order to be notified, the checker should also implement the 230 /// wantsRegionChangeUpdate callback. 231 /// 232 /// check::RegionChanges 233 ProgramStateRef 234 checkRegionChanges(ProgramStateRef State, 235 const StoreManager::InvalidatedSymbols *Invalidated, 236 ArrayRef<const MemRegion *> ExplicitRegions, 237 ArrayRef<const MemRegion *> Regions, 238 const CallEvent *Call) const { 239 return State; 240 } 241 242 /// check::Event<ImplicitNullDerefEvent> 243 void checkEvent(ImplicitNullDerefEvent Event) const {} 244 245 /// \brief Check every declaration in the AST. 246 /// 247 /// An AST traversal callback, which should only be used when the checker is 248 /// not path sensitive. It will be called for every Declaration in the AST and 249 /// can be specialized to only be called on subclasses of Decl, for example, 250 /// FunctionDecl. 251 /// 252 /// check::ASTDecl<FunctionDecl> 253 void checkASTDecl(const FunctionDecl *D, 254 AnalysisManager &Mgr, 255 BugReporter &BR) const {} 256 257}; 258 259void CheckerDocumentation::checkPostStmt(const CallExpr *DS, 260 CheckerContext &C) const { 261 return; 262} 263 264} // end namespace 265