CheckerDocumentation.cpp revision 239462
150724Scg//= CheckerDocumentation.cpp - Documentation checker ---------------*- C++ -*-// 250724Scg// 350724Scg// The LLVM Compiler Infrastructure 450724Scg// 550724Scg// This file is distributed under the University of Illinois Open Source 650724Scg// License. See LICENSE.TXT for details. 750724Scg// 850724Scg//===----------------------------------------------------------------------===// 950724Scg// 1050724Scg// This checker lists all the checker callbacks and provides documentation for 1150724Scg// checker writers. 1250724Scg// 1350724Scg//===----------------------------------------------------------------------===// 1450724Scg 1550724Scg#include "ClangSACheckers.h" 1650724Scg#include "clang/StaticAnalyzer/Core/Checker.h" 1750724Scg#include "clang/StaticAnalyzer/Core/CheckerManager.h" 1850724Scg#include "clang/StaticAnalyzer/Core/PathSensitive/CheckerContext.h" 1950724Scg#include "clang/StaticAnalyzer/Core/BugReporter/BugType.h" 2050724Scg#include "clang/StaticAnalyzer/Core/PathSensitive/ProgramStateTrait.h" 2150724Scg 2250724Scgusing namespace clang; 2350724Scgusing namespace ento; 2450724Scg 2550724Scg// All checkers should be placed into anonymous namespace. 2650724Scg// We place the CheckerDocumentation inside ento namespace to make the 2753465Scg// it visible in doxygen. 2853465Scgnamespace ento { 2953465Scg 3050724Scg/// This checker documents the callback functions checkers can use to implement 3150724Scg/// the custom handling of the specific events during path exploration as well 3250724Scg/// as reporting bugs. Most of the callbacks are targeted at path-sensitive 3350724Scg/// checking. 3482180Scg/// 3582180Scg/// \sa CheckerContext 3650724Scgclass CheckerDocumentation : public Checker< check::PreStmt<DeclStmt>, 3750724Scg check::PostStmt<CallExpr>, 3854459Scg check::PreObjCMessage, 3954459Scg check::PostObjCMessage, 4082490Sgreid check::PreCall, 4182363Sgreid check::PostCall, 4254459Scg check::BranchCondition, 4384658Scg check::Location, 4454459Scg check::Bind, 4554459Scg check::DeadSymbols, 4654459Scg check::EndPath, 4750724Scg check::EndAnalysis, 4850724Scg check::EndOfTranslationUnit, 4950724Scg eval::Call, 5050724Scg eval::Assume, 5150724Scg check::LiveSymbols, 5250724Scg check::RegionChanges, 5350724Scg check::Event<ImplicitNullDerefEvent>, 5450724Scg check::ASTDecl<FunctionDecl> > { 5550724Scgpublic: 5686870Siwasaki 5771503Scg /// \brief Pre-visit the Statement. 5874763Scg /// 5974763Scg /// The method will be called before the analyzer core processes the 6050724Scg /// statement. The notification is performed for every explored CFGElement, 6150724Scg /// which does not include the control flow statements such as IfStmt. The 6250724Scg /// callback can be specialized to be called with any subclass of Stmt. 6370325Scg /// 6470325Scg /// See checkBranchCondition() callback for performing custom processing of 6586870Siwasaki /// the branching statements. 6674763Scg /// 6774763Scg /// check::PreStmt<DeclStmt> 6870325Scg void checkPreStmt(const DeclStmt *DS, CheckerContext &C) const {} 6970325Scg 7070325Scg /// \brief Post-visit the Statement. 7150724Scg /// 7250724Scg /// The method will be called after the analyzer core processes the 7350724Scg /// statement. The notification is performed for every explored CFGElement, 74105100Scognet /// which does not include the control flow statements such as IfStmt. The 7550724Scg /// callback can be specialized to be called with any subclass of Stmt. 7650724Scg /// 7750724Scg /// check::PostStmt<CallExpr> 7850724Scg void checkPostStmt(const CallExpr *DS, CheckerContext &C) const; 7950724Scg 8050724Scg /// \brief Pre-visit the Objective C message. 8184658Scg /// 8284658Scg /// This will be called before the analyzer core processes the method call. 8350724Scg /// This is called for any action which produces an Objective-C message send, 84107285Scg /// including explicit message syntax and property access. 8574763Scg /// 8650724Scg /// check::PreObjCMessage 8784658Scg void checkPreObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 8884658Scg 8950724Scg /// \brief Post-visit the Objective C message. 9070325Scg /// \sa checkPreObjCMessage() 9150724Scg /// 9250724Scg /// check::PostObjCMessage 9350724Scg void checkPostObjCMessage(const ObjCMethodCall &M, CheckerContext &C) const {} 9450724Scg 9564881Scg /// \brief Pre-visit an abstract "call" event. 9664881Scg /// 9764881Scg /// This is used for checkers that want to check arguments or attributed 9864881Scg /// behavior for functions and methods no matter how they are being invoked. 9964881Scg /// 10064881Scg /// Note that this includes ALL cross-body invocations, so if you want to 10164881Scg /// limit your checks to, say, function calls, you can either test for that 10264881Scg /// or fall back to the explicit callback (i.e. check::PreStmt). 10364881Scg /// 10464881Scg /// check::PreCall 10550724Scg void checkPreCall(const CallEvent &Call, CheckerContext &C) const {} 10674763Scg 10750724Scg /// \brief Post-visit an abstract "call" event. 10864881Scg /// \sa checkPreObjCMessage() 10964881Scg /// 11064881Scg /// check::PostCall 11164881Scg void checkPostCall(const CallEvent &Call, CheckerContext &C) const {} 11264881Scg 11364881Scg /// \brief Pre-visit of the condition statement of a branch (such as IfStmt). 11464881Scg void checkBranchCondition(const Stmt *Condition, CheckerContext &Ctx) const {} 11564881Scg 11664881Scg /// \brief Called on a load from and a store to a location. 11764881Scg /// 11850724Scg /// The method will be called each time a location (pointer) value is 11974763Scg /// accessed. 12050724Scg /// \param Loc The value of the location (pointer). 12150724Scg /// \param IsLoad The flag specifying if the location is a store or a load. 12250724Scg /// \param S The load is performed while processing the statement. 12350724Scg /// 12450724Scg /// check::Location 12550724Scg void checkLocation(SVal Loc, bool IsLoad, const Stmt *S, 12650724Scg CheckerContext &) const {} 12750724Scg 12850724Scg /// \brief Called on binding of a value to a location. 12950724Scg /// 13050724Scg /// \param Loc The value of the location (pointer). 13150724Scg /// \param Val The value which will be stored at the location Loc. 13250724Scg /// \param S The bind is performed while processing the statement S. 13350724Scg /// 13450724Scg /// check::Bind 13550724Scg void checkBind(SVal Loc, SVal Val, const Stmt *S, CheckerContext &) const {} 13650724Scg 13750724Scg 13850724Scg /// \brief Called whenever a symbol becomes dead. 13950724Scg /// 14050724Scg /// This callback should be used by the checkers to aggressively clean 14150724Scg /// up/reduce the checker state, which is important for reducing the overall 14250724Scg /// memory usage. Specifically, if a checker keeps symbol specific information 14350724Scg /// in the sate, it can and should be dropped after the symbol becomes dead. 14450724Scg /// In addition, reporting a bug as soon as the checker becomes dead leads to 14550724Scg /// more precise diagnostics. (For example, one should report that a malloced 14650724Scg /// variable is not freed right after it goes out of scope.) 14750724Scg /// 14850724Scg /// \param SR The SymbolReaper object can be queried to determine which 14950724Scg /// symbols are dead. 15050724Scg /// 15150724Scg /// check::DeadSymbols 15250724Scg void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {} 15350724Scg 15450724Scg /// \brief Called when an end of path is reached in the ExplodedGraph. 15550724Scg /// 15670134Scg /// This callback should be used to check if the allocated resources are freed. 15750724Scg /// 15850724Scg /// check::EndPath 15970134Scg void checkEndPath(CheckerContext &Ctx) const {} 16070134Scg 16150724Scg /// \brief Called after all the paths in the ExplodedGraph reach end of path 16250724Scg /// - the symbolic execution graph is fully explored. 16350724Scg /// 16450724Scg /// This callback should be used in cases when a checker needs to have a 16550724Scg /// global view of the information generated on all paths. For example, to 16682363Sgreid /// compare execution summary/result several paths. 16782363Sgreid /// See IdempotentOperationChecker for a usage example. 16882363Sgreid /// 16982363Sgreid /// check::EndAnalysis 17082490Sgreid void checkEndAnalysis(ExplodedGraph &G, 171105100Scognet BugReporter &BR, 172105100Scognet ExprEngine &Eng) const {} 173105100Scognet 174105100Scognet /// \brief Called after analysis of a TranslationUnit is complete. 175105100Scognet /// 176105100Scognet /// check::EndOfTranslationUnit 17750724Scg void checkEndOfTranslationUnit(const TranslationUnitDecl *TU, 17850724Scg AnalysisManager &Mgr, 17950724Scg BugReporter &BR) const {} 18050724Scg 18150724Scg 18250724Scg /// \brief Evaluates function call. 18350724Scg /// 18450724Scg /// The analysis core threats all function calls in the same way. However, some 18550724Scg /// functions have special meaning, which should be reflected in the program 18650724Scg /// state. This callback allows a checker to provide domain specific knowledge 18770134Scg /// about the particular functions it knows about. 18850724Scg /// 18950724Scg /// \returns true if the call has been successfully evaluated 190105308Smarcel /// and false otherwise. Note, that only one checker can evaluate a call. If 191105308Smarcel /// more then one checker claim that they can evaluate the same call the 19250724Scg /// first one wins. 19374763Scg /// 194105100Scognet /// eval::Call 195105100Scognet bool evalCall(const CallExpr *CE, CheckerContext &C) const { return true; } 196105100Scognet 197105100Scognet /// \brief Handles assumptions on symbolic values. 198105100Scognet /// 199105100Scognet /// This method is called when a symbolic expression is assumed to be true or 200105100Scognet /// false. For example, the assumptions are performed when evaluating a 201105100Scognet /// condition at a branch. The callback allows checkers track the assumptions 202105100Scognet /// performed on the symbols of interest and change the state accordingly. 203105100Scognet /// 204105100Scognet /// eval::Assume 205105100Scognet ProgramStateRef evalAssume(ProgramStateRef State, 206105100Scognet SVal Cond, 207105100Scognet bool Assumption) const { return State; } 208105100Scognet 209105100Scognet /// Allows modifying SymbolReaper object. For example, checkers can explicitly 210105100Scognet /// register symbols of interest as live. These symbols will not be marked 211105100Scognet /// dead and removed. 212105100Scognet /// 21374763Scg /// check::LiveSymbols 21450724Scg void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const {} 21550724Scg 21650724Scg 21750724Scg bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; } 21870134Scg 21970134Scg /// \brief Allows tracking regions which get invalidated. 22050724Scg /// 22150724Scg /// \param State The current program state. 22250724Scg /// \param Invalidated A set of all symbols potentially touched by the change. 22350724Scg /// \param ExplicitRegions The regions explicitly requested for invalidation. 22450724Scg /// For example, in the case of a function call, these would be arguments. 22582363Sgreid /// \param Regions The transitive closure of accessible regions, 22682363Sgreid /// i.e. all regions that may have been touched by this change. 22782363Sgreid /// \param Call The call expression wrapper if the regions are invalidated 22882363Sgreid /// by a call, 0 otherwise. 22982490Sgreid /// Note, in order to be notified, the checker should also implement the 23050724Scg /// wantsRegionChangeUpdate callback. 23150724Scg /// 23250724Scg /// check::RegionChanges 23350724Scg ProgramStateRef 23450724Scg checkRegionChanges(ProgramStateRef State, 23550724Scg const StoreManager::InvalidatedSymbols *Invalidated, 23650724Scg ArrayRef<const MemRegion *> ExplicitRegions, 23750724Scg ArrayRef<const MemRegion *> Regions, 23850724Scg const CallEvent *Call) const { 23950724Scg return State; 24070134Scg } 24150724Scg 24250724Scg /// check::Event<ImplicitNullDerefEvent> 243105308Smarcel void checkEvent(ImplicitNullDerefEvent Event) const {} 244105308Smarcel 24550724Scg /// \brief Check every declaration in the AST. 24650724Scg /// 24750724Scg /// An AST traversal callback, which should only be used when the checker is 24850724Scg /// not path sensitive. It will be called for every Declaration in the AST and 24950724Scg /// can be specialized to only be called on subclasses of Decl, for example, 25074763Scg /// FunctionDecl. 251105100Scognet /// 252105100Scognet /// check::ASTDecl<FunctionDecl> 253105100Scognet void checkASTDecl(const FunctionDecl *D, 254105100Scognet AnalysisManager &Mgr, 255105100Scognet BugReporter &BR) const {} 256105100Scognet 257105100Scognet}; 258105100Scognet 259105100Scognetvoid CheckerDocumentation::checkPostStmt(const CallExpr *DS, 260105100Scognet CheckerContext &C) const { 261105100Scognet return; 262105100Scognet} 263105100Scognet 264105100Scognet} // end namespace 265107285Scg