1 //===- CheckerDocumentation.cpp - Documentation checker ---------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // This checker lists all the checker callbacks and provides documentation for 10 // checker writers. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #include "clang/StaticAnalyzer/Checkers/BuiltinCheckerRegistration.h" 15 #include "clang/StaticAnalyzer/Core/BugReporter/BugType.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/PathSensitive/ProgramStateTrait.h" 20 21 using namespace clang; 22 using namespace ento; 23 24 // All checkers should be placed into anonymous namespace. 25 // We place the CheckerDocumentation inside ento namespace to make the 26 // it visible in doxygen. 27 namespace clang { 28 namespace 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 36 class CheckerDocumentation 37 : public Checker< 38 // clang-format off 39 check::ASTCodeBody, 40 check::ASTDecl<FunctionDecl>, 41 check::BeginFunction, 42 check::Bind, 43 check::BranchCondition, 44 check::ConstPointerEscape, 45 check::DeadSymbols, 46 check::EndAnalysis, 47 check::EndFunction, 48 check::EndOfTranslationUnit, 49 check::Event<ImplicitNullDerefEvent>, 50 check::LiveSymbols, 51 check::Location, 52 check::NewAllocator, 53 check::ObjCMessageNil, 54 check::PointerEscape, 55 check::PostCall, 56 check::PostObjCMessage, 57 check::PostStmt<DeclStmt>, 58 check::PreCall, 59 check::PreObjCMessage, 60 check::PreStmt<ReturnStmt>, 61 check::RegionChanges, 62 eval::Assume, 63 eval::Call 64 // clang-format on 65 > { 66 public: 67 /// Pre-visit the Statement. 68 /// 69 /// The method will be called before the analyzer core processes the 70 /// statement. The notification is performed for every explored CFGElement, 71 /// which does not include the control flow statements such as IfStmt. The 72 /// callback can be specialized to be called with any subclass of Stmt. 73 /// 74 /// See checkBranchCondition() callback for performing custom processing of 75 /// the branching statements. 76 /// 77 /// check::PreStmt<ReturnStmt> 78 void checkPreStmt(const ReturnStmt *DS, CheckerContext &C) const {} 79 80 /// Post-visit the Statement. 81 /// 82 /// The method will be called after the analyzer core processes the 83 /// statement. The notification is performed for every explored CFGElement, 84 /// which does not include the control flow statements such as IfStmt. The 85 /// callback can be specialized to be called with any subclass of Stmt. 86 /// 87 /// check::PostStmt<DeclStmt> 88 void checkPostStmt(const DeclStmt *DS, CheckerContext &C) const; 89 90 /// Pre-visit the Objective C message. 91 /// 92 /// This will be called before the analyzer core processes the method call. 93 /// This is called for any action which produces an Objective-C message send, 94 /// including explicit message syntax and property access. 95 /// 96 /// check::PreObjCMessage 97 void checkPreObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 98 99 /// Post-visit the Objective C message. 100 /// \sa checkPreObjCMessage() 101 /// 102 /// check::PostObjCMessage 103 void checkPostObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 104 105 /// Visit an Objective-C message whose receiver is nil. 106 /// 107 /// This will be called when the analyzer core processes a method call whose 108 /// receiver is definitely nil. In this case, check{Pre/Post}ObjCMessage and 109 /// check{Pre/Post}Call will not be called. 110 /// 111 /// check::ObjCMessageNil 112 void checkObjCMessageNil(const ObjCMethodCall &M, CheckerContext &C) const {} 113 114 /// Pre-visit an abstract "call" event. 115 /// 116 /// This is used for checkers that want to check arguments or attributed 117 /// behavior for functions and methods no matter how they are being invoked. 118 /// 119 /// Note that this includes ALL cross-body invocations, so if you want to 120 /// limit your checks to, say, function calls, you should test for that at the 121 /// beginning of your callback function. 122 /// 123 /// check::PreCall 124 void checkPreCall(const CallEvent &Call, CheckerContext &C) const {} 125 126 /// Post-visit an abstract "call" event. 127 /// \sa checkPreObjCMessage() 128 /// 129 /// check::PostCall 130 void checkPostCall(const CallEvent &Call, CheckerContext &C) const {} 131 132 /// Pre-visit of the condition statement of a branch (such as IfStmt). 133 void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {} 134 135 /// Post-visit the C++ operator new's allocation call. 136 /// 137 /// Execution of C++ operator new consists of the following phases: (1) call 138 /// default or overridden operator new() to allocate memory (2) cast the 139 /// return value of operator new() from void pointer type to class pointer 140 /// type, (3) assuming that the value is non-null, call the object's 141 /// constructor over this pointer, (4) declare that the value of the 142 /// new-expression is this pointer. This callback is called between steps 143 /// (2) and (3). Post-call for the allocator is called after step (1). 144 /// Pre-statement for the new-expression is called on step (4) when the value 145 /// of the expression is evaluated. 146 void checkNewAllocator(const CXXAllocatorCall &, CheckerContext &) const {} 147 148 /// Called on a load from and a store to a location. 149 /// 150 /// The method will be called each time a location (pointer) value is 151 /// accessed. 152 /// \param Loc The value of the location (pointer). 153 /// \param IsLoad The flag specifying if the location is a store or a load. 154 /// \param S The load is performed while processing the statement. 155 /// 156 /// check::Location 157 void checkLocation(SVal Loc, bool IsLoad, const Stmt *S, 158 CheckerContext &) const {} 159 160 /// Called on binding of a value to a location. 161 /// 162 /// \param Loc The value of the location (pointer). 163 /// \param Val The value which will be stored at the location Loc. 164 /// \param S The bind is performed while processing the statement S. 165 /// 166 /// check::Bind 167 void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {} 168 169 /// Called whenever a symbol becomes dead. 170 /// 171 /// This callback should be used by the checkers to aggressively clean 172 /// up/reduce the checker state, which is important for reducing the overall 173 /// memory usage. Specifically, if a checker keeps symbol specific information 174 /// in the state, it can and should be dropped after the symbol becomes dead. 175 /// In addition, reporting a bug as soon as the checker becomes dead leads to 176 /// more precise diagnostics. (For example, one should report that a malloced 177 /// variable is not freed right after it goes out of scope.) 178 /// 179 /// \param SR The SymbolReaper object can be queried to determine which 180 /// symbols are dead. 181 /// 182 /// check::DeadSymbols 183 void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {} 184 185 186 /// Called when the analyzer core starts analyzing a function, 187 /// regardless of whether it is analyzed at the top level or is inlined. 188 /// 189 /// check::BeginFunction 190 void checkBeginFunction(CheckerContext &Ctx) const {} 191 192 /// Called when the analyzer core reaches the end of a 193 /// function being analyzed regardless of whether it is analyzed at the top 194 /// level or is inlined. 195 /// 196 /// check::EndFunction 197 void checkEndFunction(const ReturnStmt *RS, CheckerContext &Ctx) const {} 198 199 /// Called after all the paths in the ExplodedGraph reach end of path 200 /// - the symbolic execution graph is fully explored. 201 /// 202 /// This callback should be used in cases when a checker needs to have a 203 /// global view of the information generated on all paths. For example, to 204 /// compare execution summary/result several paths. 205 /// See IdempotentOperationChecker for a usage example. 206 /// 207 /// check::EndAnalysis 208 void checkEndAnalysis(ExplodedGraph &G, 209 BugReporter &BR, 210 ExprEngine &Eng) const {} 211 212 /// Called after analysis of a TranslationUnit is complete. 213 /// 214 /// check::EndOfTranslationUnit 215 void checkEndOfTranslationUnit(const TranslationUnitDecl *TU, 216 AnalysisManager &Mgr, 217 BugReporter &BR) const {} 218 219 /// Evaluates function call. 220 /// 221 /// The analysis core treats all function calls in the same way. However, some 222 /// functions have special meaning, which should be reflected in the program 223 /// state. This callback allows a checker to provide domain specific knowledge 224 /// about the particular functions it knows about. 225 /// 226 /// \returns true if the call has been successfully evaluated 227 /// and false otherwise. Note, that only one checker can evaluate a call. If 228 /// more than one checker claims that they can evaluate the same call the 229 /// first one wins. 230 /// 231 /// eval::Call 232 bool evalCall(const CallEvent &Call, CheckerContext &C) const { return true; } 233 234 /// Handles assumptions on symbolic values. 235 /// 236 /// This method is called when a symbolic expression is assumed to be true or 237 /// false. For example, the assumptions are performed when evaluating a 238 /// condition at a branch. The callback allows checkers track the assumptions 239 /// performed on the symbols of interest and change the state accordingly. 240 /// 241 /// eval::Assume 242 ProgramStateRef evalAssume(ProgramStateRef State, 243 SVal Cond, 244 bool Assumption) const { return State; } 245 246 /// Allows modifying SymbolReaper object. For example, checkers can explicitly 247 /// register symbols of interest as live. These symbols will not be marked 248 /// dead and removed. 249 /// 250 /// check::LiveSymbols 251 void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const {} 252 253 /// Called when the contents of one or more regions change. 254 /// 255 /// This can occur in many different ways: an explicit bind, a blanket 256 /// invalidation of the region contents, or by passing a region to a function 257 /// call whose behavior the analyzer cannot model perfectly. 258 /// 259 /// \param State The current program state. 260 /// \param Invalidated A set of all symbols potentially touched by the change. 261 /// \param ExplicitRegions The regions explicitly requested for invalidation. 262 /// For a function call, this would be the arguments. For a bind, this 263 /// would be the region being bound to. 264 /// \param Regions The transitive closure of regions accessible from, 265 /// \p ExplicitRegions, i.e. all regions that may have been touched 266 /// by this change. For a simple bind, this list will be the same as 267 /// \p ExplicitRegions, since a bind does not affect the contents of 268 /// anything accessible through the base region. 269 /// \param LCtx LocationContext that is useful for getting various contextual 270 /// info, like callstack, CFG etc. 271 /// \param Call The opaque call triggering this invalidation. Will be 0 if the 272 /// change was not triggered by a call. 273 /// 274 /// check::RegionChanges 275 ProgramStateRef 276 checkRegionChanges(ProgramStateRef State, 277 const InvalidatedSymbols *Invalidated, 278 ArrayRef<const MemRegion *> ExplicitRegions, 279 ArrayRef<const MemRegion *> Regions, 280 const LocationContext *LCtx, 281 const CallEvent *Call) const { 282 return State; 283 } 284 285 /// Called when pointers escape. 286 /// 287 /// This notifies the checkers about pointer escape, which occurs whenever 288 /// the analyzer cannot track the symbol any more. For example, as a 289 /// result of assigning a pointer into a global or when it's passed to a 290 /// function call the analyzer cannot model. 291 /// 292 /// \param State The state at the point of escape. 293 /// \param Escaped The list of escaped symbols. 294 /// \param Call The corresponding CallEvent, if the symbols escape as 295 /// parameters to the given call. 296 /// \param Kind How the symbols have escaped. 297 /// \returns Checkers can modify the state by returning a new state. 298 ProgramStateRef checkPointerEscape(ProgramStateRef State, 299 const InvalidatedSymbols &Escaped, 300 const CallEvent *Call, 301 PointerEscapeKind Kind) const { 302 return State; 303 } 304 305 /// Called when const pointers escape. 306 /// 307 /// Note: in most cases checkPointerEscape callback is sufficient. 308 /// \sa checkPointerEscape 309 ProgramStateRef checkConstPointerEscape(ProgramStateRef State, 310 const InvalidatedSymbols &Escaped, 311 const CallEvent *Call, 312 PointerEscapeKind Kind) const { 313 return State; 314 } 315 316 /// check::Event<ImplicitNullDerefEvent> 317 void checkEvent(ImplicitNullDerefEvent Event) const {} 318 319 /// Check every declaration in the AST. 320 /// 321 /// An AST traversal callback, which should only be used when the checker is 322 /// not path sensitive. It will be called for every Declaration in the AST and 323 /// can be specialized to only be called on subclasses of Decl, for example, 324 /// FunctionDecl. 325 /// 326 /// check::ASTDecl<FunctionDecl> 327 void checkASTDecl(const FunctionDecl *D, 328 AnalysisManager &Mgr, 329 BugReporter &BR) const {} 330 331 /// Check every declaration that has a statement body in the AST. 332 /// 333 /// As AST traversal callback, which should only be used when the checker is 334 /// not path sensitive. It will be called for every Declaration in the AST. 335 void checkASTCodeBody(const Decl *D, AnalysisManager &Mgr, 336 BugReporter &BR) const {} 337 }; 338 339 void CheckerDocumentation::checkPostStmt(const DeclStmt *DS, 340 CheckerContext &C) const { 341 } 342 343 void registerCheckerDocumentationChecker(CheckerManager &Mgr) { 344 Mgr.registerChecker<CheckerDocumentation>(); 345 } 346 347 bool shouldRegisterCheckerDocumentationChecker(const CheckerManager &) { 348 return false; 349 } 350 351 } // end namespace ento 352 } // end namespace clang 353