1239310Sdim//= CheckerDocumentation.cpp - Documentation checker ---------------*- C++ -*-// 2239310Sdim// 3239310Sdim// The LLVM Compiler Infrastructure 4239310Sdim// 5239310Sdim// This file is distributed under the University of Illinois Open Source 6239310Sdim// License. See LICENSE.TXT for details. 7239310Sdim// 8239310Sdim//===----------------------------------------------------------------------===// 9239310Sdim// 10239310Sdim// This checker lists all the checker callbacks and provides documentation for 11239310Sdim// checker writers. 12239310Sdim// 13239310Sdim//===----------------------------------------------------------------------===// 14239310Sdim 15249423Sdim#include "ClangSACheckers.h" 16249423Sdim#include "clang/StaticAnalyzer/Core/BugReporter/BugType.h" 17249423Sdim#include "clang/StaticAnalyzer/Core/Checker.h" 18239310Sdim#include "clang/StaticAnalyzer/Core/CheckerManager.h" 19239310Sdim#include "clang/StaticAnalyzer/Core/PathSensitive/CheckerContext.h" 20249423Sdim#include "clang/StaticAnalyzer/Core/PathSensitive/ProgramStateTrait.h" 21239310Sdim 22239310Sdimusing namespace clang; 23239310Sdimusing namespace ento; 24239310Sdim 25239310Sdim// All checkers should be placed into anonymous namespace. 26239310Sdim// We place the CheckerDocumentation inside ento namespace to make the 27239310Sdim// it visible in doxygen. 28249423Sdimnamespace clang { 29249423Sdimnamespace ento { 30249423Sdim 31249423Sdim/// This checker documents the callback functions checkers can use to implement 32239310Sdim/// the custom handling of the specific events during path exploration as well 33239310Sdim/// as reporting bugs. Most of the callbacks are targeted at path-sensitive 34249423Sdim/// checking. 35239310Sdim/// 36249423Sdim/// \sa CheckerContext 37249423Sdimclass CheckerDocumentation : public Checker< check::PreStmt<ReturnStmt>, 38239310Sdim check::PostStmt<DeclStmt>, 39249423Sdim check::PreObjCMessage, 40249423Sdim check::PostObjCMessage, 41249423Sdim check::PreCall, 42249423Sdim check::PostCall, 43249423Sdim check::BranchCondition, 44239310Sdim check::Location, 45251662Sdim check::Bind, 46251662Sdim check::DeadSymbols, 47251662Sdim check::EndFunction, 48251662Sdim check::EndAnalysis, 49251662Sdim check::EndOfTranslationUnit, 50239310Sdim eval::Call, 51239310Sdim eval::Assume, 52239310Sdim check::LiveSymbols, 53239310Sdim check::RegionChanges, 54239310Sdim check::PointerEscape, 55239310Sdim check::ConstPointerEscape, 56239310Sdim check::Event<ImplicitNullDerefEvent>, 57239310Sdim check::ASTDecl<FunctionDecl> > { 58239310Sdimpublic: 59249423Sdim 60249423Sdim /// \brief Pre-visit the Statement. 61239310Sdim /// 62239310Sdim /// The method will be called before the analyzer core processes the 63239310Sdim /// statement. The notification is performed for every explored CFGElement, 64239310Sdim /// which does not include the control flow statements such as IfStmt. The 65239310Sdim /// callback can be specialized to be called with any subclass of Stmt. 66239310Sdim /// 67249423Sdim /// See checkBranchCondition() callback for performing custom processing of 68249423Sdim /// the branching statements. 69249423Sdim /// 70249423Sdim /// check::PreStmt<ReturnStmt> 71249423Sdim void checkPreStmt(const ReturnStmt *DS, CheckerContext &C) const {} 72249423Sdim 73239310Sdim /// \brief Post-visit the Statement. 74239310Sdim /// 75239310Sdim /// The method will be called after the analyzer core processes the 76239310Sdim /// statement. The notification is performed for every explored CFGElement, 77239310Sdim /// which does not include the control flow statements such as IfStmt. The 78239310Sdim /// callback can be specialized to be called with any subclass of Stmt. 79239310Sdim /// 80239310Sdim /// check::PostStmt<DeclStmt> 81239310Sdim void checkPostStmt(const DeclStmt *DS, CheckerContext &C) const; 82251662Sdim 83251662Sdim /// \brief Pre-visit the Objective C message. 84239310Sdim /// 85239310Sdim /// This will be called before the analyzer core processes the method call. 86239310Sdim /// This is called for any action which produces an Objective-C message send, 87239310Sdim /// including explicit message syntax and property access. 88239310Sdim /// 89239310Sdim /// check::PreObjCMessage 90239310Sdim void checkPreObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 91239310Sdim 92249423Sdim /// \brief Post-visit the Objective C message. 93239310Sdim /// \sa checkPreObjCMessage() 94239310Sdim /// 95249423Sdim /// check::PostObjCMessage 96239310Sdim void checkPostObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 97239310Sdim 98239310Sdim /// \brief Pre-visit an abstract "call" event. 99239310Sdim /// 100239310Sdim /// This is used for checkers that want to check arguments or attributed 101239310Sdim /// behavior for functions and methods no matter how they are being invoked. 102239310Sdim /// 103239310Sdim /// Note that this includes ALL cross-body invocations, so if you want to 104239310Sdim /// limit your checks to, say, function calls, you should test for that at the 105249423Sdim /// beginning of your callback function. 106249423Sdim /// 107249423Sdim /// check::PreCall 108249423Sdim void checkPreCall(const CallEvent &Call, CheckerContext &C) const {} 109249423Sdim 110249423Sdim /// \brief Post-visit an abstract "call" event. 111249423Sdim /// \sa checkPreObjCMessage() 112249423Sdim /// 113249423Sdim /// check::PostCall 114249423Sdim void checkPostCall(const CallEvent &Call, CheckerContext &C) const {} 115249423Sdim 116249423Sdim /// \brief Pre-visit of the condition statement of a branch (such as IfStmt). 117249423Sdim void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {} 118249423Sdim 119249423Sdim /// \brief Called on a load from and a store to a location. 120249423Sdim /// 121239310Sdim /// The method will be called each time a location (pointer) value is 122239310Sdim /// accessed. 123239310Sdim /// \param Loc The value of the location (pointer). 124239310Sdim /// \param IsLoad The flag specifying if the location is a store or a load. 125239310Sdim /// \param S The load is performed while processing the statement. 126239310Sdim /// 127249423Sdim /// check::Location 128249423Sdim void checkLocation(SVal Loc, bool IsLoad, const Stmt *S, 129239310Sdim CheckerContext &) const {} 130239310Sdim 131239310Sdim /// \brief Called on binding of a value to a location. 132239310Sdim /// 133239310Sdim /// \param Loc The value of the location (pointer). 134239310Sdim /// \param Val The value which will be stored at the location Loc. 135249423Sdim /// \param S The bind is performed while processing the statement S. 136249423Sdim /// 137249423Sdim /// check::Bind 138249423Sdim void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {} 139249423Sdim 140249423Sdim 141239310Sdim /// \brief Called whenever a symbol becomes dead. 142239310Sdim /// 143249423Sdim /// This callback should be used by the checkers to aggressively clean 144249423Sdim /// up/reduce the checker state, which is important for reducing the overall 145249423Sdim /// memory usage. Specifically, if a checker keeps symbol specific information 146249423Sdim /// in the sate, it can and should be dropped after the symbol becomes dead. 147239310Sdim /// In addition, reporting a bug as soon as the checker becomes dead leads to 148239310Sdim /// more precise diagnostics. (For example, one should report that a malloced 149239310Sdim /// variable is not freed right after it goes out of scope.) 150239310Sdim /// 151239310Sdim /// \param SR The SymbolReaper object can be queried to determine which 152239310Sdim /// symbols are dead. 153239310Sdim /// 154239310Sdim /// check::DeadSymbols 155239310Sdim void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {} 156239310Sdim 157249423Sdim /// \brief Called when the analyzer core reaches the end of a 158249423Sdim /// function being analyzed. 159239310Sdim /// 160239310Sdim /// check::EndFunction 161239310Sdim void checkEndFunction(CheckerContext &Ctx) const {} 162239310Sdim 163239310Sdim /// \brief Called after all the paths in the ExplodedGraph reach end of path 164249423Sdim /// - the symbolic execution graph is fully explored. 165239310Sdim /// 166239310Sdim /// This callback should be used in cases when a checker needs to have a 167239310Sdim /// global view of the information generated on all paths. For example, to 168249423Sdim /// compare execution summary/result several paths. 169239310Sdim /// See IdempotentOperationChecker for a usage example. 170239310Sdim /// 171239310Sdim /// check::EndAnalysis 172239310Sdim void checkEndAnalysis(ExplodedGraph &G, 173239310Sdim BugReporter &BR, 174239310Sdim ExprEngine &Eng) const {} 175239310Sdim 176239310Sdim /// \brief Called after analysis of a TranslationUnit is complete. 177239310Sdim /// 178239310Sdim /// check::EndOfTranslationUnit 179239310Sdim void checkEndOfTranslationUnit(const TranslationUnitDecl *TU, 180239310Sdim AnalysisManager &Mgr, 181239310Sdim BugReporter &BR) const {} 182239310Sdim 183239310Sdim 184239310Sdim /// \brief Evaluates function call. 185239310Sdim /// 186239310Sdim /// The analysis core threats all function calls in the same way. However, some 187239310Sdim /// functions have special meaning, which should be reflected in the program 188239310Sdim /// state. This callback allows a checker to provide domain specific knowledge 189239310Sdim /// about the particular functions it knows about. 190239310Sdim /// 191239310Sdim /// \returns true if the call has been successfully evaluated 192239310Sdim /// and false otherwise. Note, that only one checker can evaluate a call. If 193239310Sdim /// more than one checker claims that they can evaluate the same call the 194239310Sdim /// first one wins. 195239310Sdim /// 196239310Sdim /// eval::Call 197239310Sdim bool evalCall(const CallExpr *CE, CheckerContext &C) const { return true; } 198239310Sdim 199239310Sdim /// \brief Handles assumptions on symbolic values. 200239310Sdim /// 201239310Sdim /// This method is called when a symbolic expression is assumed to be true or 202239310Sdim /// false. For example, the assumptions are performed when evaluating a 203239310Sdim /// condition at a branch. The callback allows checkers track the assumptions 204239310Sdim /// performed on the symbols of interest and change the state accordingly. 205239310Sdim /// 206239310Sdim /// eval::Assume 207239310Sdim ProgramStateRef evalAssume(ProgramStateRef State, 208249423Sdim SVal Cond, 209239310Sdim bool Assumption) const { return State; } 210239310Sdim 211239310Sdim /// Allows modifying SymbolReaper object. For example, checkers can explicitly 212239310Sdim /// register symbols of interest as live. These symbols will not be marked 213239310Sdim /// dead and removed. 214239310Sdim /// 215239310Sdim /// check::LiveSymbols 216239310Sdim void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const {} 217239310Sdim 218239310Sdim /// \brief Called to determine if the checker currently needs to know if when 219239310Sdim /// contents of any regions change. 220239310Sdim /// 221239310Sdim /// Since it is not necessarily cheap to compute which regions are being 222239310Sdim /// changed, this allows the analyzer core to skip the more expensive 223239310Sdim /// #checkRegionChanges when no checkers are tracking any state. 224239310Sdim bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; } 225239310Sdim 226239310Sdim /// \brief Called when the contents of one or more regions change. 227249423Sdim /// 228249423Sdim /// This can occur in many different ways: an explicit bind, a blanket 229249423Sdim /// invalidation of the region contents, or by passing a region to a function 230249423Sdim /// call whose behavior the analyzer cannot model perfectly. 231249423Sdim /// 232249423Sdim /// \param State The current program state. 233249423Sdim /// \param Invalidated A set of all symbols potentially touched by the change. 234249423Sdim /// \param ExplicitRegions The regions explicitly requested for invalidation. 235249423Sdim /// For a function call, this would be the arguments. For a bind, this 236249423Sdim /// would be the region being bound to. 237249423Sdim /// \param Regions The transitive closure of regions accessible from, 238249423Sdim /// \p ExplicitRegions, i.e. all regions that may have been touched 239249423Sdim /// by this change. For a simple bind, this list will be the same as 240249423Sdim /// \p ExplicitRegions, since a bind does not affect the contents of 241249423Sdim /// anything accessible through the base region. 242249423Sdim /// \param Call The opaque call triggering this invalidation. Will be 0 if the 243249423Sdim /// change was not triggered by a call. 244249423Sdim /// 245249423Sdim /// Note that this callback will not be invoked unless 246249423Sdim /// #wantsRegionChangeUpdate returns \c true. 247239310Sdim /// 248249423Sdim /// check::RegionChanges 249249423Sdim ProgramStateRef 250249423Sdim checkRegionChanges(ProgramStateRef State, 251251662Sdim const InvalidatedSymbols *Invalidated, 252249423Sdim ArrayRef<const MemRegion *> ExplicitRegions, 253249423Sdim ArrayRef<const MemRegion *> Regions, 254249423Sdim const CallEvent *Call) const { 255239310Sdim return State; 256249423Sdim } 257249423Sdim 258249423Sdim /// \brief Called when pointers escape. 259249423Sdim /// 260249423Sdim /// This notifies the checkers about pointer escape, which occurs whenever 261249423Sdim /// the analyzer cannot track the symbol any more. For example, as a 262249423Sdim /// result of assigning a pointer into a global or when it's passed to a 263249423Sdim /// function call the analyzer cannot model. 264249423Sdim /// 265249423Sdim /// \param State The state at the point of escape. 266249423Sdim /// \param Escaped The list of escaped symbols. 267249423Sdim /// \param Call The corresponding CallEvent, if the symbols escape as 268249423Sdim /// parameters to the given call. 269249423Sdim /// \param Kind How the symbols have escaped. 270249423Sdim /// \returns Checkers can modify the state by returning a new state. 271249423Sdim ProgramStateRef checkPointerEscape(ProgramStateRef State, 272249423Sdim const InvalidatedSymbols &Escaped, 273249423Sdim const CallEvent *Call, 274249423Sdim PointerEscapeKind Kind) const { 275249423Sdim return State; 276239310Sdim } 277249423Sdim 278249423Sdim /// \brief Called when const pointers escape. 279249423Sdim /// 280251662Sdim /// Note: in most cases checkPointerEscape callback is sufficient. 281249423Sdim /// \sa checkPointerEscape 282249423Sdim ProgramStateRef checkConstPointerEscape(ProgramStateRef State, 283249423Sdim const InvalidatedSymbols &Escaped, 284249423Sdim const CallEvent *Call, 285249423Sdim PointerEscapeKind Kind) const { 286249423Sdim return State; 287249423Sdim } 288249423Sdim 289249423Sdim /// check::Event<ImplicitNullDerefEvent> 290249423Sdim void checkEvent(ImplicitNullDerefEvent Event) const {} 291249423Sdim 292249423Sdim /// \brief Check every declaration in the AST. 293249423Sdim /// 294249423Sdim /// An AST traversal callback, which should only be used when the checker is 295249423Sdim /// not path sensitive. It will be called for every Declaration in the AST and 296249423Sdim /// can be specialized to only be called on subclasses of Decl, for example, 297249423Sdim /// FunctionDecl. 298249423Sdim /// 299249423Sdim /// check::ASTDecl<FunctionDecl> 300249423Sdim void checkASTDecl(const FunctionDecl *D, 301249423Sdim AnalysisManager &Mgr, 302249423Sdim BugReporter &BR) const {} 303249423Sdim 304249423Sdim}; 305249423Sdim 306249423Sdimvoid CheckerDocumentation::checkPostStmt(const DeclStmt *DS, 307249423Sdim CheckerContext &C) const { 308249423Sdim return; 309249423Sdim} 310249423Sdim 311249423Sdim} // end namespace ento 312249423Sdim} // end namespace clang 313249423Sdim