clang 19.0.0git
Public Types | Public Member Functions | Friends | List of all members
clang::ento::CallDescription Class Reference

A CallDescription is a pattern that can be used to match calls based on the qualified name and the argument/parameter counts. More...

#include "clang/StaticAnalyzer/Core/PathSensitive/CallDescription.h"

Public Types

enum class  Mode { CLibrary , SimpleFunc , CXXMethod , Unspecified }
 

Public Member Functions

 CallDescription (Mode MatchAs, ArrayRef< StringRef > QualifiedName, MaybeCount RequiredArgs=std::nullopt, MaybeCount RequiredParams=std::nullopt)
 Constructs a CallDescription object.
 
 CallDescription (ArrayRef< StringRef > QualifiedName, MaybeCount RequiredArgs=std::nullopt, MaybeCount RequiredParams=std::nullopt)
 Construct a CallDescription with default flags.
 
 CallDescription (std::nullptr_t)=delete
 
StringRef getFunctionName () const
 Get the name of the function that this object matches.
 
auto begin_qualified_name_parts () const
 Get the qualified name parts in reversed order.
 
auto end_qualified_name_parts () const
 
bool hasQualifiedNameParts () const
 It's false, if and only if we expect a single identifier, such as getenv.
 

Friends

class CallEvent
 

Matching CallDescriptions against a CallEvent

bool matchesAny (const CallEvent &Call, const CallDescription &CD1)
 Returns true whether the CallEvent matches on any of the CallDescriptions supplied.
 
template<typename... Ts>
bool matchesAny (const CallEvent &Call, const CallDescription &CD1, const Ts &...CDs)
 Returns true whether the CallEvent matches on any of the CallDescriptions supplied.
 
bool matches (const CallEvent &Call) const
 Returns true if the CallEvent is a call to a function that matches the CallDescription.
 

Matching CallDescriptions against a CallExpr

bool matchesAnyAsWritten (const CallExpr &CE, const CallDescription &CD1)
 Returns true whether the CallExpr matches on any of the CallDescriptions supplied.
 
template<typename... Ts>
bool matchesAnyAsWritten (const CallExpr &CE, const CallDescription &CD1, const Ts &...CDs)
 Returns true whether the CallExpr matches on any of the CallDescriptions supplied.
 
bool matchesAsWritten (const CallExpr &CE) const
 Returns true if the CallExpr is a call to a function that matches the CallDescription.
 

Detailed Description

A CallDescription is a pattern that can be used to match calls based on the qualified name and the argument/parameter counts.

Definition at line 32 of file CallDescription.h.

Member Enumeration Documentation

◆ Mode

Enumerator
CLibrary 

Match calls to functions from the C standard library.

On some platforms some functions may be implemented as macros that expand to calls to built-in variants of the given functions, so in this mode we use some heuristics to recognize these implementation-defined variants:

  • We also accept calls where the name is derived from the specified name by adding "__builtin" or similar prefixes/suffixes.
  • We also accept calls where the number of arguments or parameters is greater than the specified value. For the exact heuristics, see CheckerContext::isCLibraryFunction(). (This mode only matches functions that are declared either directly within a TU or in the namespace std.)
SimpleFunc 

Matches "simple" functions that are not methods.

(Static methods are methods.)

CXXMethod 

Matches a C++ method (may be static, may be virtual, may be an overloaded operator, a constructor or a destructor).

Unspecified 

Match any CallEvent that is not an ObjCMethodCall.

FIXME: Previously this was the default behavior of CallDescription, but its use should be replaced by a more specific mode almost everywhere.

Definition at line 34 of file CallDescription.h.

Constructor & Destructor Documentation

◆ CallDescription() [1/3]

ento::CallDescription::CallDescription ( Mode  MatchAs,
ArrayRef< StringRef >  QualifiedName,
MaybeCount  RequiredArgs = std::nullopt,
MaybeCount  RequiredParams = std::nullopt 
)

Constructs a CallDescription object.

Parameters
MatchAsSpecifies the kind of the call that should be matched.
QualifiedNameThe list of the name qualifiers of the function that will be matched. The user is allowed to skip any of the qualifiers. For example, {"std", "basic_string", "c_str"} would match both std::basic_string<...>::c_str() and std::__1::basic_string<...>::c_str().
RequiredArgsThe expected number of arguments that are passed to the function. Omit this parameter (or pass std::nullopt) to match every occurrence without checking the argument count in the call.
RequiredParamsThe expected number of parameters in the function definition that is called. Omit this parameter to match every occurrence without checking the parameter count in the definition.

Definition at line 38 of file CallDescription.cpp.

◆ CallDescription() [2/3]

ento::CallDescription::CallDescription ( ArrayRef< StringRef >  QualifiedName,
MaybeCount  RequiredArgs = std::nullopt,
MaybeCount  RequiredParams = std::nullopt 
)

Construct a CallDescription with default flags.

Definition at line 52 of file CallDescription.cpp.

◆ CallDescription() [3/3]

clang::ento::CallDescription::CallDescription ( std::nullptr_t  )
delete

Member Function Documentation

◆ begin_qualified_name_parts()

auto clang::ento::CallDescription::begin_qualified_name_parts ( ) const
inline

Get the qualified name parts in reversed order.

E.g. { "std", "vector", "data" } -> "vector", "std"

Definition at line 112 of file CallDescription.h.

◆ end_qualified_name_parts()

auto clang::ento::CallDescription::end_qualified_name_parts ( ) const
inline

Definition at line 115 of file CallDescription.h.

◆ getFunctionName()

StringRef clang::ento::CallDescription::getFunctionName ( ) const
inline

Get the name of the function that this object matches.

Definition at line 108 of file CallDescription.h.

◆ hasQualifiedNameParts()

bool clang::ento::CallDescription::hasQualifiedNameParts ( ) const
inline

It's false, if and only if we expect a single identifier, such as getenv.

It's true for std::swap, or my::detail::container::data.

Definition at line 119 of file CallDescription.h.

◆ matches()

bool ento::CallDescription::matches ( const CallEvent Call) const

Returns true if the CallEvent is a call to a function that matches the CallDescription.

Note
This function is not intended to be used to match Obj-C method calls.

Definition at line 58 of file CallDescription.cpp.

References clang::Call, and clang::ento::CE_ObjCMessage.

Referenced by StdVariantChecker::evalCall().

◆ matchesAsWritten()

bool ento::CallDescription::matchesAsWritten ( const CallExpr CE) const

Returns true if the CallExpr is a call to a function that matches the CallDescription.

When available, always prefer matching with a CallEvent! This function exists only when that is not available, for example, when only syntactic check is done on a piece of code.

Also, StdLibraryFunctionsChecker::Signature is likely a better candicade for syntactic only matching if you are writing a new checker. This is handy if a CallDescriptionMap is already there.

The function is imprecise because CallEvent may know path sensitive information, such as the precise argument count (see comments for CallEvent::getNumArgs), the called function if it was called through a function pointer, and other information not available syntactically.

Definition at line 70 of file CallDescription.cpp.

References clang::CallExpr::getCalleeDecl(), and clang::CallExpr::getNumArgs().

Friends And Related Function Documentation

◆ CallEvent

friend class CallEvent
friend

Definition at line 68 of file CallDescription.h.

◆ matchesAny [1/2]

bool matchesAny ( const CallEvent Call,
const CallDescription CD1 
)
friend

Returns true whether the CallEvent matches on any of the CallDescriptions supplied.

Note
This function is not intended to be used to match Obj-C method calls.

Definition at line 136 of file CallDescription.h.

◆ matchesAny [2/2]

template<typename... Ts>
bool matchesAny ( const CallEvent Call,
const CallDescription CD1,
const Ts &...  CDs 
)
friend

Returns true whether the CallEvent matches on any of the CallDescriptions supplied.

Note
This function is not intended to be used to match Obj-C method calls.

Definition at line 142 of file CallDescription.h.

◆ matchesAnyAsWritten [1/2]

bool matchesAnyAsWritten ( const CallExpr CE,
const CallDescription CD1 
)
friend

Returns true whether the CallExpr matches on any of the CallDescriptions supplied.

Note
This function is not intended to be used to match Obj-C method calls.

Definition at line 173 of file CallDescription.h.

◆ matchesAnyAsWritten [2/2]

template<typename... Ts>
bool matchesAnyAsWritten ( const CallExpr CE,
const CallDescription CD1,
const Ts &...  CDs 
)
friend

Returns true whether the CallExpr matches on any of the CallDescriptions supplied.

Note
This function is not intended to be used to match Obj-C method calls.

Definition at line 180 of file CallDescription.h.


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