clang 22.0.0git
clang::ento::CheckerDocumentation Class Reference

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. More...

Inheritance diagram for clang::ento::CheckerDocumentation:
[legend]

Public Member Functions

void checkPreStmt (const ReturnStmt *DS, CheckerContext &C) const
 Pre-visit the Statement.
void checkPostStmt (const DeclStmt *DS, CheckerContext &C) const
 Post-visit the Statement.
void checkPreObjCMessage (const ObjCMethodCall &M, CheckerContext &C) const
 Pre-visit the Objective C message.
void checkPostObjCMessage (const ObjCMethodCall &M, CheckerContext &C) const
 Post-visit the Objective C message.
void checkObjCMessageNil (const ObjCMethodCall &M, CheckerContext &C) const
 Visit an Objective-C message whose receiver is nil.
void checkPreCall (const CallEvent &Call, CheckerContext &C) const
 Pre-visit an abstract "call" event.
void checkPostCall (const CallEvent &Call, CheckerContext &C) const
 Post-visit an abstract "call" event.
void checkBranchCondition (const Stmt *Condition, CheckerContext &Ctx) const
 Pre-visit of the condition statement of a branch.
void checkNewAllocator (const CXXAllocatorCall &, CheckerContext &) const
 Post-visit the C++ operator new's allocation call.
void checkLocation (SVal Loc, bool IsLoad, const Stmt *S, CheckerContext &) const
 Called on a load from and a store to a location.
void checkBind (SVal Loc, SVal Val, const Stmt *S, bool AtDeclInit, CheckerContext &) const
 Called on binding of a value to a location.
void checkBlockEntrance (const BlockEntrance &E, CheckerContext &) const
 Called after a CFG edge is taken within a function.
void checkDeadSymbols (SymbolReaper &SR, CheckerContext &C) const
 Called whenever a symbol becomes dead.
void checkBeginFunction (CheckerContext &Ctx) const
 Called when the analyzer core starts analyzing a function, regardless of whether it is analyzed at the top level or is inlined.
void checkEndFunction (const ReturnStmt *RS, CheckerContext &Ctx) const
 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.
void checkEndAnalysis (ExplodedGraph &G, BugReporter &BR, ExprEngine &Eng) const
 Called after all the paths in the ExplodedGraph reach end of path.
void checkEndOfTranslationUnit (const TranslationUnitDecl *TU, AnalysisManager &Mgr, BugReporter &BR) const
 Called after analysis of a TranslationUnit is complete.
bool evalCall (const CallEvent &Call, CheckerContext &C) const
 Evaluates function call.
ProgramStateRef evalAssume (ProgramStateRef State, SVal Cond, bool Assumption) const
 Handles assumptions on symbolic values.
void checkLiveSymbols (ProgramStateRef State, SymbolReaper &SR) const
 Allows modifying SymbolReaper object.
ProgramStateRef checkRegionChanges (ProgramStateRef State, const InvalidatedSymbols *Invalidated, ArrayRef< const MemRegion * > ExplicitRegions, ArrayRef< const MemRegion * > Regions, const LocationContext *LCtx, const CallEvent *Call) const
 Called when the contents of one or more regions change.
ProgramStateRef checkPointerEscape (ProgramStateRef State, const InvalidatedSymbols &Escaped, const CallEvent *Call, PointerEscapeKind Kind) const
 Called when pointers escape.
ProgramStateRef checkConstPointerEscape (ProgramStateRef State, const InvalidatedSymbols &Escaped, const CallEvent *Call, PointerEscapeKind Kind) const
 Called when const pointers escape.
void checkEvent (ImplicitNullDerefEvent Event) const
 check::Event<ImplicitNullDerefEvent>
void checkASTDecl (const FunctionDecl *D, AnalysisManager &Mgr, BugReporter &BR) const
 Check every declaration in the AST.
void checkASTCodeBody (const Decl *D, AnalysisManager &Mgr, BugReporter &BR) const
 Check every declaration that has a statement body in the AST.
Public Member Functions inherited from clang::ento::CheckerBase
StringRef getDebugTag () const override
 Attached to nodes created by this checker class when the ExplodedGraph is dumped for debugging.
Public Member Functions inherited from clang::ento::CheckerFrontend
void enable (CheckerManager &Mgr)
bool isEnabled () const
CheckerNameRef getName () const
Public Member Functions inherited from clang::ento::CheckerBackend
virtual void printState (raw_ostream &Out, ProgramStateRef State, const char *NL, const char *Sep) const
 Debug state dump callback, see CheckerManager::runCheckersForPrintState.
Public Member Functions inherited from clang::ProgramPointTag
 ProgramPointTag (void *tagKind=nullptr)
virtual ~ProgramPointTag ()
const void * getTagKind () const
 Used to implement 'isKind' in subclasses.

Additional Inherited Members

Public Types inherited from clang::ento::Checker< check::ASTCodeBody, check::ASTDecl< FunctionDecl >, check::BeginFunction, check::Bind, check::BlockEntrance, check::BranchCondition, check::ConstPointerEscape, check::DeadSymbols, check::EndAnalysis, check::EndFunction, check::EndOfTranslationUnit, check::Event< ImplicitNullDerefEvent >, check::LiveSymbols, check::Location, check::NewAllocator, check::ObjCMessageNil, check::PointerEscape, check::PostCall, check::PostObjCMessage, check::PostStmt< DeclStmt >, check::PreCall, check::PreObjCMessage, check::PreStmt< ReturnStmt >, check::RegionChanges, eval::Assume, eval::Call >
using BlockEntrance
Static Public Member Functions inherited from clang::ento::Checker< check::ASTCodeBody, check::ASTDecl< FunctionDecl >, check::BeginFunction, check::Bind, check::BlockEntrance, check::BranchCondition, check::ConstPointerEscape, check::DeadSymbols, check::EndAnalysis, check::EndFunction, check::EndOfTranslationUnit, check::Event< ImplicitNullDerefEvent >, check::LiveSymbols, check::Location, check::NewAllocator, check::ObjCMessageNil, check::PointerEscape, check::PostCall, check::PostObjCMessage, check::PostStmt< DeclStmt >, check::PreCall, check::PreObjCMessage, check::PreStmt< ReturnStmt >, check::RegionChanges, eval::Assume, eval::Call >
static void _register (CHECKER *Chk, CheckerManager &Mgr)

Detailed 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.

See also
CheckerContext

Definition at line 35 of file CheckerDocumentation.cpp.

Member Function Documentation

◆ checkASTCodeBody()

void clang::ento::CheckerDocumentation::checkASTCodeBody ( const Decl * D,
AnalysisManager & Mgr,
BugReporter & BR ) const
inline

Check every declaration that has a statement body in the AST.

As 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.

Definition at line 374 of file CheckerDocumentation.cpp.

◆ checkASTDecl()

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

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>

Definition at line 366 of file CheckerDocumentation.cpp.

◆ checkBeginFunction()

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

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

check::BeginFunction

Definition at line 229 of file CheckerDocumentation.cpp.

◆ checkBind()

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

Called on binding of a value to a location.

Parameters
LocThe value of the location (pointer).
ValThe value which will be stored at the location Loc.
SThe bind is performed while processing the statement S.
AtDeclInitWhether the bind is performed during declaration initialization.

check::Bind

Definition at line 182 of file CheckerDocumentation.cpp.

◆ checkBlockEntrance()

void clang::ento::CheckerDocumentation::checkBlockEntrance ( const BlockEntrance & E,
CheckerContext &  ) const
inline

Called after a CFG edge is taken within a function.

This callback can be used to obtain information about potential branching points or any other constructs that involve traversing a CFG edge.

check::BranchCondition is a similar callback, which is only invoked for pre-visiting the condition statement of a branch. Prefer that callback if possible.

Remarks
There is no CFG edge from the caller to a callee, consequently this callback is not invoked for "inlining" a function call.
Once a function call is inlined, we will start from the imaginary "entry" basic block of that CFG. This callback will be invoked for entering the real first basic block of the "inlined" function body from that "entry" basic block.
This callback is also invoked for entering the imaginary "exit" basic block of the CFG when returning from a function.
Parameters
EThe ProgramPoint that describes the transition.

check::BlockEntrance

Definition at line 206 of file CheckerDocumentation.cpp.

◆ checkBranchCondition()

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

Pre-visit of the condition statement of a branch.

For example:

  • logical operators (&&, ||)
  • if, do, while, for, ranged-for statements
  • ternary operators (?:), gnu conditionals, gnu choose expressions Interestingly, switch statements don't seem to trigger BranchCondition.

check::BlockEntrance is a similar callback, which is strictly more generic. Prefer check::BranchCondition to check::BlockEntrance if pre-visiting conditional statements is enough for the checker. Note that check::BlockEntrance is also invoked for leaving basic blocks while entering the next.

check::BranchCondition

Definition at line 146 of file CheckerDocumentation.cpp.

References clang::Condition.

◆ checkConstPointerEscape()

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

Called when const pointers escape.

Note: in most cases checkPointerEscape callback is sufficient.

See also
checkPointerEscape

Definition at line 348 of file CheckerDocumentation.cpp.

References clang::Call.

◆ checkDeadSymbols()

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

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.)

Parameters
SRThe SymbolReaper object can be queried to determine which symbols are dead.

check::DeadSymbols

Definition at line 222 of file CheckerDocumentation.cpp.

References clang::C.

◆ checkEndAnalysis()

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

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

Definition at line 247 of file CheckerDocumentation.cpp.

◆ checkEndFunction()

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

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

Definition at line 236 of file CheckerDocumentation.cpp.

◆ checkEndOfTranslationUnit()

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

Called after analysis of a TranslationUnit is complete.

check::EndOfTranslationUnit

Definition at line 254 of file CheckerDocumentation.cpp.

◆ checkEvent()

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

◆ checkLiveSymbols()

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

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

Definition at line 290 of file CheckerDocumentation.cpp.

◆ checkLocation()

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

Called on a load from and a store to a location.

The method will be called each time a location (pointer) value is accessed.

Parameters
LocThe value of the location (pointer).
IsLoadThe flag specifying if the location is a store or a load.
SThe load is performed while processing the statement.

check::Location

Definition at line 170 of file CheckerDocumentation.cpp.

◆ checkNewAllocator()

void clang::ento::CheckerDocumentation::checkNewAllocator ( const CXXAllocatorCall & ,
CheckerContext &  ) const
inline

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.

Definition at line 159 of file CheckerDocumentation.cpp.

◆ checkObjCMessageNil()

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

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

Definition at line 112 of file CheckerDocumentation.cpp.

References clang::C.

◆ checkPointerEscape()

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

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.

Parameters
StateThe state at the point of escape.
EscapedThe list of escaped symbols.
CallThe corresponding CallEvent, if the symbols escape as parameters to the given call.
KindHow the symbols have escaped.
Returns
Checkers can modify the state by returning a new state.

Definition at line 337 of file CheckerDocumentation.cpp.

References clang::Call.

◆ checkPostCall()

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

Post-visit an abstract "call" event.

See also
checkPreObjCMessage()

check::PostCall

Definition at line 130 of file CheckerDocumentation.cpp.

References clang::C, and clang::Call.

◆ checkPostObjCMessage()

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

Post-visit the Objective C message.

See also
checkPreObjCMessage()

check::PostObjCMessage

Definition at line 103 of file CheckerDocumentation.cpp.

References clang::C.

◆ checkPostStmt()

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

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>

Definition at line 378 of file CheckerDocumentation.cpp.

References clang::C.

◆ checkPreCall()

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

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

Definition at line 124 of file CheckerDocumentation.cpp.

References clang::C, and clang::Call.

◆ checkPreObjCMessage()

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

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

Definition at line 97 of file CheckerDocumentation.cpp.

References clang::C.

◆ checkPreStmt()

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

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>

Definition at line 78 of file CheckerDocumentation.cpp.

References clang::C.

◆ checkRegionChanges()

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

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.

Parameters
StateThe current program state.
InvalidatedA set of all symbols potentially touched by the change.
ExplicitRegionsThe 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.
RegionsThe transitive closure of regions accessible from, ExplicitRegions, i.e. all regions that may have been touched by this change. For a simple bind, this list will be the same as ExplicitRegions, since a bind does not affect the contents of anything accessible through the base region.
LCtxLocationContext that is useful for getting various contextual info, like callstack, CFG etc.
CallThe opaque call triggering this invalidation. Will be 0 if the change was not triggered by a call.

check::RegionChanges

Definition at line 315 of file CheckerDocumentation.cpp.

References clang::Call.

◆ evalAssume()

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

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

Definition at line 281 of file CheckerDocumentation.cpp.

References clang::Cond.

◆ evalCall()

bool clang::ento::CheckerDocumentation::evalCall ( const CallEvent & Call,
CheckerContext & C ) const
inline

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.

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.

eval::Call

Definition at line 271 of file CheckerDocumentation.cpp.

References clang::C, and clang::Call.


The documentation for this class was generated from the following file: