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