class CheckerDocumentation

Declaration

class CheckerDocumentation : public Checker { /* full declaration omitted */ };

Description

This checker documents the callback functions checkers can use to implement the custom handling of the specific events during path exploration as well as reporting bugs. Most of the callbacks are targeted at path-sensitive checking.

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:36

Inherits from: Checker

Method Overview

  • public void checkASTDecl(const clang::FunctionDecl * D, clang::ento::AnalysisManager & Mgr, clang::ento::BugReporter & BR) const
  • public void checkBeginFunction(clang::ento::CheckerContext & Ctx) const
  • public void checkBind(clang::ento::SVal Loc, clang::ento::SVal Val, const clang::Stmt * S, clang::ento::CheckerContext &) const
  • public void checkBranchCondition(const clang::Stmt * Condition, clang::ento::CheckerContext & Ctx) const
  • public clang::ento::ProgramStateRef checkConstPointerEscape(clang::ento::ProgramStateRef State, const clang::ento::InvalidatedSymbols & Escaped, const clang::ento::CallEvent * Call, clang::ento::PointerEscapeKind Kind) const
  • public void checkDeadSymbols(clang::ento::SymbolReaper & SR, clang::ento::CheckerContext & C) const
  • public void checkEndAnalysis(clang::ento::ExplodedGraph & G, clang::ento::BugReporter & BR, clang::ento::ExprEngine & Eng) const
  • public void checkEndFunction(const clang::ReturnStmt * RS, clang::ento::CheckerContext & Ctx) const
  • public void checkEndOfTranslationUnit(const clang::TranslationUnitDecl * TU, clang::ento::AnalysisManager & Mgr, clang::ento::BugReporter & BR) const
  • public void checkEvent(clang::ento::ImplicitNullDerefEvent Event) const
  • public void checkLiveSymbols(clang::ento::ProgramStateRef State, clang::ento::SymbolReaper & SR) const
  • public void checkLocation(clang::ento::SVal Loc, bool IsLoad, const clang::Stmt * S, clang::ento::CheckerContext &) const
  • public void checkNewAllocator(const clang::CXXNewExpr * NE, clang::ento::SVal Target, clang::ento::CheckerContext &) const
  • public void checkObjCMessageNil(const clang::ento::ObjCMethodCall & M, clang::ento::CheckerContext & C) const
  • public clang::ento::ProgramStateRef checkPointerEscape(clang::ento::ProgramStateRef State, const clang::ento::InvalidatedSymbols & Escaped, const clang::ento::CallEvent * Call, clang::ento::PointerEscapeKind Kind) const
  • public void checkPostCall(const clang::ento::CallEvent & Call, clang::ento::CheckerContext & C) const
  • public void checkPostObjCMessage(const clang::ento::ObjCMethodCall & M, clang::ento::CheckerContext & C) const
  • public void checkPostStmt(const clang::DeclStmt * DS, clang::ento::CheckerContext & C) const
  • public void checkPreCall(const clang::ento::CallEvent & Call, clang::ento::CheckerContext & C) const
  • public void checkPreObjCMessage(const clang::ento::ObjCMethodCall & M, clang::ento::CheckerContext & C) const
  • public void checkPreStmt(const clang::ReturnStmt * DS, clang::ento::CheckerContext & C) const
  • public clang::ento::ProgramStateRef checkRegionChanges(clang::ento::ProgramStateRef State, const clang::ento::InvalidatedSymbols * Invalidated, ArrayRef<const clang::ento::MemRegion *> ExplicitRegions, ArrayRef<const clang::ento::MemRegion *> Regions, const clang::LocationContext * LCtx, const clang::ento::CallEvent * Call) const
  • public clang::ento::ProgramStateRef evalAssume(clang::ento::ProgramStateRef State, clang::ento::SVal Cond, bool Assumption) const
  • public bool evalCall(const clang::CallExpr * CE, clang::ento::CheckerContext & C) const

Methods

void checkASTDecl(
    const clang::FunctionDecl* D,
    clang::ento::AnalysisManager& Mgr,
    clang::ento::BugReporter& BR) const

Description

Check every declaration in the AST. An AST traversal callback, which should only be used when the checker is not path sensitive. It will be called for every Declaration in the AST and can be specialized to only be called on subclasses of Decl, for example, FunctionDecl. check::ASTDecl <FunctionDecl >

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:324

Parameters

const clang::FunctionDecl* D
clang::ento::AnalysisManager& Mgr
clang::ento::BugReporter& BR

void checkBeginFunction(
    clang::ento::CheckerContext& Ctx) const

Description

Called when the analyzer core starts analyzing a function, regardless of whether it is analyzed at the top level or is inlined. check::BeginFunction

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:187

Parameters

clang::ento::CheckerContext& Ctx

void checkBind(clang::ento::SVal Loc,
               clang::ento::SVal Val,
               const clang::Stmt* S,
               clang::ento::CheckerContext&) const

Description

Called on binding of a value to a location. check::Bind

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:164

Parameters

clang::ento::SVal Loc
The value of the location (pointer).
clang::ento::SVal Val
The value which will be stored at the location Loc.
const clang::Stmt* S
The bind is performed while processing the statement S.
clang::ento::CheckerContext& 

void checkBranchCondition(
    const clang::Stmt* Condition,
    clang::ento::CheckerContext& Ctx) const

Description

Pre-visit of the condition statement of a branch (such as IfStmt).

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:127

Parameters

const clang::Stmt* Condition
clang::ento::CheckerContext& Ctx

clang::ento::ProgramStateRef
checkConstPointerEscape(
    clang::ento::ProgramStateRef State,
    const clang::ento::InvalidatedSymbols&
        Escaped,
    const clang::ento::CallEvent* Call,
    clang::ento::PointerEscapeKind Kind) const

Description

Called when const pointers escape. Note: in most cases checkPointerEscape callback is sufficient.

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:306

Parameters

clang::ento::ProgramStateRef State
const clang::ento::InvalidatedSymbols& Escaped
const clang::ento::CallEvent* Call
clang::ento::PointerEscapeKind Kind

void checkDeadSymbols(
    clang::ento::SymbolReaper& SR,
    clang::ento::CheckerContext& C) const

Description

Called whenever a symbol becomes dead. This callback should be used by the checkers to aggressively clean up/reduce the checker state, which is important for reducing the overall memory usage. Specifically, if a checker keeps symbol specific information in the state, it can and should be dropped after the symbol becomes dead. In addition, reporting a bug as soon as the checker becomes dead leads to more precise diagnostics. (For example, one should report that a malloced variable is not freed right after it goes out of scope.) check::DeadSymbols

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:180

Parameters

clang::ento::SymbolReaper& SR
The SymbolReaper object can be queried to determine which symbols are dead.
clang::ento::CheckerContext& C

void checkEndAnalysis(
    clang::ento::ExplodedGraph& G,
    clang::ento::BugReporter& BR,
    clang::ento::ExprEngine& Eng) const

Description

Called after all the paths in the ExplodedGraph reach end of path - the symbolic execution graph is fully explored. This callback should be used in cases when a checker needs to have a global view of the information generated on all paths. For example, to compare execution summary/result several paths. See IdempotentOperationChecker for a usage example. check::EndAnalysis

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:205

Parameters

clang::ento::ExplodedGraph& G
clang::ento::BugReporter& BR
clang::ento::ExprEngine& Eng

void checkEndFunction(
    const clang::ReturnStmt* RS,
    clang::ento::CheckerContext& Ctx) const

Description

Called when the analyzer core reaches the end of a function being analyzed regardless of whether it is analyzed at the top level or is inlined. check::EndFunction

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:194

Parameters

const clang::ReturnStmt* RS
clang::ento::CheckerContext& Ctx

void checkEndOfTranslationUnit(
    const clang::TranslationUnitDecl* TU,
    clang::ento::AnalysisManager& Mgr,
    clang::ento::BugReporter& BR) const

Description

Called after analysis of a TranslationUnit is complete. check::EndOfTranslationUnit

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:212

Parameters

const clang::TranslationUnitDecl* TU
clang::ento::AnalysisManager& Mgr
clang::ento::BugReporter& BR

void checkEvent(
    clang::ento::ImplicitNullDerefEvent Event)
    const

Description

check::Event <ImplicitNullDerefEvent >

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:314

Parameters

clang::ento::ImplicitNullDerefEvent Event

void checkLiveSymbols(
    clang::ento::ProgramStateRef State,
    clang::ento::SymbolReaper& SR) const

Description

Allows modifying SymbolReaper object. For example, checkers can explicitly register symbols of interest as live. These symbols will not be marked dead and removed. check::LiveSymbols

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:248

Parameters

clang::ento::ProgramStateRef State
clang::ento::SymbolReaper& SR

void checkLocation(
    clang::ento::SVal Loc,
    bool IsLoad,
    const clang::Stmt* S,
    clang::ento::CheckerContext&) const

Description

Called on a load from and a store to a location. The method will be called each time a location (pointer) value is accessed. check::Location

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:154

Parameters

clang::ento::SVal Loc
The value of the location (pointer).
bool IsLoad
The flag specifying if the location is a store or a load.
const clang::Stmt* S
The load is performed while processing the statement.
clang::ento::CheckerContext& 

void checkNewAllocator(
    const clang::CXXNewExpr* NE,
    clang::ento::SVal Target,
    clang::ento::CheckerContext&) const

Description

Post-visit the C++ operator new's allocation call. Execution of C++ operator new consists of the following phases: (1) call default or overridden operator new() to allocate memory (2) cast the return value of operator new() from void pointer type to class pointer type, (3) assuming that the value is non-null, call the object's constructor over this pointer, (4) declare that the value of the new-expression is this pointer. This callback is called between steps (2) and (3). Post-call for the allocator is called after step (1). Pre-statement for the new-expression is called on step (4) when the value of the expression is evaluated.

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:142

Parameters

const clang::CXXNewExpr* NE
The C++ new-expression that triggered the allocation.
clang::ento::SVal Target
The allocated region, casted to the class type.
clang::ento::CheckerContext& 

void checkObjCMessageNil(
    const clang::ento::ObjCMethodCall& M,
    clang::ento::CheckerContext& C) const

Description

Visit an Objective-C message whose receiver is nil. This will be called when the analyzer core processes a method call whose receiver is definitely nil. In this case, check{Pre/Post}ObjCMessage and check{Pre/Post}Call will not be called. check::ObjCMessageNil

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:106

Parameters

const clang::ento::ObjCMethodCall& M
clang::ento::CheckerContext& C

clang::ento::ProgramStateRef checkPointerEscape(
    clang::ento::ProgramStateRef State,
    const clang::ento::InvalidatedSymbols&
        Escaped,
    const clang::ento::CallEvent* Call,
    clang::ento::PointerEscapeKind Kind) const

Description

Called when pointers escape. This notifies the checkers about pointer escape, which occurs whenever the analyzer cannot track the symbol any more. For example, as a result of assigning a pointer into a global or when it's passed to a function call the analyzer cannot model.

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:295

Parameters

clang::ento::ProgramStateRef State
The state at the point of escape.
const clang::ento::InvalidatedSymbols& Escaped
The list of escaped symbols.
const clang::ento::CallEvent* Call
The corresponding CallEvent, if the symbols escape as parameters to the given call.
clang::ento::PointerEscapeKind Kind
How the symbols have escaped.

Returns

Checkers can modify the state by returning a new state.

void checkPostCall(
    const clang::ento::CallEvent& Call,
    clang::ento::CheckerContext& C) const

Description

Post-visit an abstract "call" event. check::PostCall

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:124

Parameters

const clang::ento::CallEvent& Call
clang::ento::CheckerContext& C

void checkPostObjCMessage(
    const clang::ento::ObjCMethodCall& M,
    clang::ento::CheckerContext& C) const

Description

Post-visit the Objective C message. check::PostObjCMessage

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:97

Parameters

const clang::ento::ObjCMethodCall& M
clang::ento::CheckerContext& C

void checkPostStmt(
    const clang::DeclStmt* DS,
    clang::ento::CheckerContext& C) const

Description

Post-visit the Statement. The method will be called after the analyzer core processes the statement. The notification is performed for every explored CFGElement, which does not include the control flow statements such as IfStmt. The callback can be specialized to be called with any subclass of Stmt. check::PostStmt <DeclStmt >

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:82

Parameters

const clang::DeclStmt* DS
clang::ento::CheckerContext& C

void checkPreCall(
    const clang::ento::CallEvent& Call,
    clang::ento::CheckerContext& C) const

Description

Pre-visit an abstract "call" event. This is used for checkers that want to check arguments or attributed behavior for functions and methods no matter how they are being invoked. Note that this includes ALL cross-body invocations, so if you want to limit your checks to, say, function calls, you should test for that at the beginning of your callback function. check::PreCall

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:118

Parameters

const clang::ento::CallEvent& Call
clang::ento::CheckerContext& C

void checkPreObjCMessage(
    const clang::ento::ObjCMethodCall& M,
    clang::ento::CheckerContext& C) const

Description

Pre-visit the Objective C message. This will be called before the analyzer core processes the method call. This is called for any action which produces an Objective-C message send, including explicit message syntax and property access. check::PreObjCMessage

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:91

Parameters

const clang::ento::ObjCMethodCall& M
clang::ento::CheckerContext& C

void checkPreStmt(
    const clang::ReturnStmt* DS,
    clang::ento::CheckerContext& C) const

Description

Pre-visit the Statement. The method will be called before the analyzer core processes the statement. The notification is performed for every explored CFGElement, which does not include the control flow statements such as IfStmt. The callback can be specialized to be called with any subclass of Stmt. See checkBranchCondition() callback for performing custom processing of the branching statements. check::PreStmt <ReturnStmt >

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:72

Parameters

const clang::ReturnStmt* DS
clang::ento::CheckerContext& C

clang::ento::ProgramStateRef checkRegionChanges(
    clang::ento::ProgramStateRef State,
    const clang::ento::InvalidatedSymbols*
        Invalidated,
    ArrayRef<const clang::ento::MemRegion*>
        ExplicitRegions,
    ArrayRef<const clang::ento::MemRegion*>
        Regions,
    const clang::LocationContext* LCtx,
    const clang::ento::CallEvent* Call) const

Description

Called when the contents of one or more regions change. This can occur in many different ways: an explicit bind, a blanket invalidation of the region contents, or by passing a region to a function call whose behavior the analyzer cannot model perfectly. check::RegionChanges

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:273

Parameters

clang::ento::ProgramStateRef State
The current program state.
const clang::ento::InvalidatedSymbols* Invalidated
A set of all symbols potentially touched by the change.
ArrayRef<const clang::ento::MemRegion*> ExplicitRegions
The regions explicitly requested for invalidation. For a function call, this would be the arguments. For a bind, this would be the region being bound to.
ArrayRef<const clang::ento::MemRegion*> Regions
The transitive closure of regions accessible from,\p ExplicitRegions, i.e. all regions that may have been touched by this change. For a simple bind, this list will be the same as\p ExplicitRegions, since a bind does not affect the contents of anything accessible through the base region.
const clang::LocationContext* LCtx
LocationContext that is useful for getting various contextual info, like callstack, CFG etc.
const clang::ento::CallEvent* Call
The opaque call triggering this invalidation. Will be 0 if the change was not triggered by a call.

clang::ento::ProgramStateRef evalAssume(
    clang::ento::ProgramStateRef State,
    clang::ento::SVal Cond,
    bool Assumption) const

Description

Handles assumptions on symbolic values. This method is called when a symbolic expression is assumed to be true or false. For example, the assumptions are performed when evaluating a condition at a branch. The callback allows checkers track the assumptions performed on the symbols of interest and change the state accordingly. eval::Assume

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:239

Parameters

clang::ento::ProgramStateRef State
clang::ento::SVal Cond
bool Assumption

bool evalCall(
    const clang::CallExpr* CE,
    clang::ento::CheckerContext& C) const

Description

Evaluates function call. The analysis core treats all function calls in the same way. However, some functions have special meaning, which should be reflected in the program state. This callback allows a checker to provide domain specific knowledge about the particular functions it knows about. eval::Call

Declared at: clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp:229

Parameters

const clang::CallExpr* CE
clang::ento::CheckerContext& C

Returns

true if the call has been successfully evaluated and false otherwise. Note, that only one checker can evaluate a call. If more than one checker claims that they can evaluate the same call the first one wins.