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/BugReporter/BugType.h" 17 #include "clang/StaticAnalyzer/Core/Checker.h" 18 #include "clang/StaticAnalyzer/Core/CheckerManager.h" 19 #include "clang/StaticAnalyzer/Core/PathSensitive/CheckerContext.h" 20 #include "clang/StaticAnalyzer/Core/PathSensitive/ProgramStateTrait.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::PreCall, 42 check::PostCall, 43 check::BranchCondition, 44 check::Location, 45 check::Bind, 46 check::DeadSymbols, 47 check::EndFunction, 48 check::EndAnalysis, 49 check::EndOfTranslationUnit, 50 eval::Call, 51 eval::Assume, 52 check::LiveSymbols, 53 check::RegionChanges, 54 check::PointerEscape, 55 check::Event<ImplicitNullDerefEvent>, 56 check::ASTDecl<FunctionDecl> > { 57 public: 58 59 /// \brief Pre-visit the Statement. 60 /// 61 /// The method will be called before the analyzer core processes the 62 /// statement. The notification is performed for every explored CFGElement, 63 /// which does not include the control flow statements such as IfStmt. The 64 /// callback can be specialized to be called with any subclass of Stmt. 65 /// 66 /// See checkBranchCondition() callback for performing custom processing of 67 /// the branching statements. 68 /// 69 /// check::PreStmt<ReturnStmt> 70 void checkPreStmt(const ReturnStmt *DS, CheckerContext &C) const {} 71 72 /// \brief Post-visit the Statement. 73 /// 74 /// The method will be called after the analyzer core processes the 75 /// statement. The notification is performed for every explored CFGElement, 76 /// which does not include the control flow statements such as IfStmt. The 77 /// callback can be specialized to be called with any subclass of Stmt. 78 /// 79 /// check::PostStmt<DeclStmt> 80 void checkPostStmt(const DeclStmt *DS, CheckerContext &C) const; 81 82 /// \brief Pre-visit the Objective C message. 83 /// 84 /// This will be called before the analyzer core processes the method call. 85 /// This is called for any action which produces an Objective-C message send, 86 /// including explicit message syntax and property access. 87 /// 88 /// check::PreObjCMessage 89 void checkPreObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 90 91 /// \brief Post-visit the Objective C message. 92 /// \sa checkPreObjCMessage() 93 /// 94 /// check::PostObjCMessage 95 void checkPostObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 96 97 /// \brief Pre-visit an abstract "call" event. 98 /// 99 /// This is used for checkers that want to check arguments or attributed 100 /// behavior for functions and methods no matter how they are being invoked. 101 /// 102 /// Note that this includes ALL cross-body invocations, so if you want to 103 /// limit your checks to, say, function calls, you should test for that at the 104 /// beginning of your callback function. 105 /// 106 /// check::PreCall 107 void checkPreCall(const CallEvent &Call, CheckerContext &C) const {} 108 109 /// \brief Post-visit an abstract "call" event. 110 /// \sa checkPreObjCMessage() 111 /// 112 /// check::PostCall 113 void checkPostCall(const CallEvent &Call, CheckerContext &C) const {} 114 115 /// \brief Pre-visit of the condition statement of a branch (such as IfStmt). 116 void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {} 117 118 /// \brief Called on a load from and a store to a location. 119 /// 120 /// The method will be called each time a location (pointer) value is 121 /// accessed. 122 /// \param Loc The value of the location (pointer). 123 /// \param IsLoad The flag specifying if the location is a store or a load. 124 /// \param S The load is performed while processing the statement. 125 /// 126 /// check::Location 127 void checkLocation(SVal Loc, bool IsLoad, const Stmt *S, 128 CheckerContext &) const {} 129 130 /// \brief Called on binding of a value to a location. 131 /// 132 /// \param Loc The value of the location (pointer). 133 /// \param Val The value which will be stored at the location Loc. 134 /// \param S The bind is performed while processing the statement S. 135 /// 136 /// check::Bind 137 void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {} 138 139 140 /// \brief Called whenever a symbol becomes dead. 141 /// 142 /// This callback should be used by the checkers to aggressively clean 143 /// up/reduce the checker state, which is important for reducing the overall 144 /// memory usage. Specifically, if a checker keeps symbol specific information 145 /// in the sate, it can and should be dropped after the symbol becomes dead. 146 /// In addition, reporting a bug as soon as the checker becomes dead leads to 147 /// more precise diagnostics. (For example, one should report that a malloced 148 /// variable is not freed right after it goes out of scope.) 149 /// 150 /// \param SR The SymbolReaper object can be queried to determine which 151 /// symbols are dead. 152 /// 153 /// check::DeadSymbols 154 void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {} 155 156 /// \brief Called when the analyzer core reaches the end of a 157 /// function being analyzed. 158 /// 159 /// check::EndFunction 160 void checkEndFunction(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 /// \brief Called to determine if the checker currently needs to know if when 218 /// contents of any regions change. 219 /// 220 /// Since it is not necessarily cheap to compute which regions are being 221 /// changed, this allows the analyzer core to skip the more expensive 222 /// #checkRegionChanges when no checkers are tracking any state. 223 bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; } 224 225 /// \brief Called when the contents of one or more regions change. 226 /// 227 /// This can occur in many different ways: an explicit bind, a blanket 228 /// invalidation of the region contents, or by passing a region to a function 229 /// call whose behavior the analyzer cannot model perfectly. 230 /// 231 /// \param State The current program state. 232 /// \param Invalidated A set of all symbols potentially touched by the change. 233 /// \param ExplicitRegions The regions explicitly requested for invalidation. 234 /// For a function call, this would be the arguments. For a bind, this 235 /// would be the region being bound to. 236 /// \param Regions The transitive closure of regions accessible from, 237 /// \p ExplicitRegions, i.e. all regions that may have been touched 238 /// by this change. For a simple bind, this list will be the same as 239 /// \p ExplicitRegions, since a bind does not affect the contents of 240 /// anything accessible through the base region. 241 /// \param Call The opaque call triggering this invalidation. Will be 0 if the 242 /// change was not triggered by a call. 243 /// 244 /// Note that this callback will not be invoked unless 245 /// #wantsRegionChangeUpdate returns \c true. 246 /// 247 /// check::RegionChanges 248 ProgramStateRef 249 checkRegionChanges(ProgramStateRef State, 250 const InvalidatedSymbols *Invalidated, 251 ArrayRef<const MemRegion *> ExplicitRegions, 252 ArrayRef<const MemRegion *> Regions, 253 const CallEvent *Call) const { 254 return State; 255 } 256 257 /// \brief Called when pointers escape. 258 /// 259 /// This notifies the checkers about pointer escape, which occurs whenever 260 /// the analyzer cannot track the symbol any more. For example, as a 261 /// result of assigning a pointer into a global or when it's passed to a 262 /// function call the analyzer cannot model. 263 /// 264 /// \param State The state at the point of escape. 265 /// \param Escaped The list of escaped symbols. 266 /// \param Call The corresponding CallEvent, if the symbols escape as 267 /// parameters to the given call. 268 /// \param Kind How the symbols have escaped. 269 /// \returns Checkers can modify the state by returning a new state. 270 ProgramStateRef checkPointerEscape(ProgramStateRef State, 271 const InvalidatedSymbols &Escaped, 272 const CallEvent *Call, 273 PointerEscapeKind Kind) const { 274 return State; 275 } 276 277 /// check::Event<ImplicitNullDerefEvent> 278 void checkEvent(ImplicitNullDerefEvent Event) const {} 279 280 /// \brief Check every declaration in the AST. 281 /// 282 /// An AST traversal callback, which should only be used when the checker is 283 /// not path sensitive. It will be called for every Declaration in the AST and 284 /// can be specialized to only be called on subclasses of Decl, for example, 285 /// FunctionDecl. 286 /// 287 /// check::ASTDecl<FunctionDecl> 288 void checkASTDecl(const FunctionDecl *D, 289 AnalysisManager &Mgr, 290 BugReporter &BR) const {} 291 292 }; 293 294 void CheckerDocumentation::checkPostStmt(const DeclStmt *DS, 295 CheckerContext &C) const { 296 return; 297 } 298 299 } // end namespace ento 300 } // end namespace clang 301
