1//===- CallDescription.h - function/method call matching --*- C++ -*-===// 2// 3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4// See https://llvm.org/LICENSE.txt for license information. 5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6// 7//===----------------------------------------------------------------------===// 8// 9/// \file This file defines a generic mechanism for matching for function and 10/// method calls of C, C++, and Objective-C languages. Instances of these 11/// classes are frequently used together with the CallEvent classes. 12// 13//===----------------------------------------------------------------------===// 14 15#ifndef LLVM_CLANG_STATICANALYZER_CORE_PATHSENSITIVE_CALLDESCRIPTION_H 16#define LLVM_CLANG_STATICANALYZER_CORE_PATHSENSITIVE_CALLDESCRIPTION_H 17 18#include "clang/StaticAnalyzer/Core/PathSensitive/CallEvent.h" 19#include "llvm/ADT/ArrayRef.h" 20#include "llvm/Support/Compiler.h" 21#include <optional> 22#include <vector> 23 24namespace clang { 25class IdentifierInfo; 26} // namespace clang 27 28namespace clang { 29namespace ento { 30 31enum CallDescriptionFlags : unsigned { 32 CDF_None = 0, 33 34 /// Describes a C standard function that is sometimes implemented as a macro 35 /// that expands to a compiler builtin with some __builtin prefix. 36 /// The builtin may as well have a few extra arguments on top of the requested 37 /// number of arguments. 38 CDF_MaybeBuiltin = 1 << 0, 39}; 40 41/// This class represents a description of a function call using the number of 42/// arguments and the name of the function. 43class CallDescription { 44 friend class CallEvent; 45 using MaybeCount = std::optional<unsigned>; 46 47 mutable std::optional<const IdentifierInfo *> II; 48 // The list of the qualified names used to identify the specified CallEvent, 49 // e.g. "{a, b}" represent the qualified names, like "a::b". 50 std::vector<std::string> QualifiedName; 51 MaybeCount RequiredArgs; 52 MaybeCount RequiredParams; 53 int Flags; 54 55public: 56 /// Constructs a CallDescription object. 57 /// 58 /// @param QualifiedName The list of the name qualifiers of the function that 59 /// will be matched. The user is allowed to skip any of the qualifiers. 60 /// For example, {"std", "basic_string", "c_str"} would match both 61 /// std::basic_string<...>::c_str() and std::__1::basic_string<...>::c_str(). 62 /// 63 /// @param RequiredArgs The number of arguments that is expected to match a 64 /// call. Omit this parameter to match every occurrence of call with a given 65 /// name regardless the number of arguments. 66 CallDescription(CallDescriptionFlags Flags, ArrayRef<StringRef> QualifiedName, 67 MaybeCount RequiredArgs = std::nullopt, 68 MaybeCount RequiredParams = std::nullopt); 69 70 /// Construct a CallDescription with default flags. 71 CallDescription(ArrayRef<StringRef> QualifiedName, 72 MaybeCount RequiredArgs = std::nullopt, 73 MaybeCount RequiredParams = std::nullopt); 74 75 CallDescription(std::nullptr_t) = delete; 76 77 /// Get the name of the function that this object matches. 78 StringRef getFunctionName() const { return QualifiedName.back(); } 79 80 /// Get the qualified name parts in reversed order. 81 /// E.g. { "std", "vector", "data" } -> "vector", "std" 82 auto begin_qualified_name_parts() const { 83 return std::next(QualifiedName.rbegin()); 84 } 85 auto end_qualified_name_parts() const { return QualifiedName.rend(); } 86 87 /// It's false, if and only if we expect a single identifier, such as 88 /// `getenv`. It's true for `std::swap`, or `my::detail::container::data`. 89 bool hasQualifiedNameParts() const { return QualifiedName.size() > 1; } 90 91 /// @name Matching CallDescriptions against a CallEvent 92 /// @{ 93 94 /// Returns true if the CallEvent is a call to a function that matches 95 /// the CallDescription. 96 /// 97 /// \note This function is not intended to be used to match Obj-C method 98 /// calls. 99 bool matches(const CallEvent &Call) const; 100 101 /// Returns true whether the CallEvent matches on any of the CallDescriptions 102 /// supplied. 103 /// 104 /// \note This function is not intended to be used to match Obj-C method 105 /// calls. 106 friend bool matchesAny(const CallEvent &Call, const CallDescription &CD1) { 107 return CD1.matches(Call); 108 } 109 110 /// \copydoc clang::ento::CallDescription::matchesAny(const CallEvent &, const CallDescription &) 111 template <typename... Ts> 112 friend bool matchesAny(const CallEvent &Call, const CallDescription &CD1, 113 const Ts &...CDs) { 114 return CD1.matches(Call) || matchesAny(Call, CDs...); 115 } 116 /// @} 117 118 /// @name Matching CallDescriptions against a CallExpr 119 /// @{ 120 121 /// Returns true if the CallExpr is a call to a function that matches the 122 /// CallDescription. 123 /// 124 /// When available, always prefer matching with a CallEvent! This function 125 /// exists only when that is not available, for example, when _only_ 126 /// syntactic check is done on a piece of code. 127 /// 128 /// Also, StdLibraryFunctionsChecker::Signature is likely a better candicade 129 /// for syntactic only matching if you are writing a new checker. This is 130 /// handy if a CallDescriptionMap is already there. 131 /// 132 /// The function is imprecise because CallEvent may know path sensitive 133 /// information, such as the precise argument count (see comments for 134 /// CallEvent::getNumArgs), the called function if it was called through a 135 /// function pointer, and other information not available syntactically. 136 bool matchesAsWritten(const CallExpr &CE) const; 137 138 /// Returns true whether the CallExpr matches on any of the CallDescriptions 139 /// supplied. 140 /// 141 /// \note This function is not intended to be used to match Obj-C method 142 /// calls. 143 friend bool matchesAnyAsWritten(const CallExpr &CE, 144 const CallDescription &CD1) { 145 return CD1.matchesAsWritten(CE); 146 } 147 148 /// \copydoc clang::ento::CallDescription::matchesAnyAsWritten(const CallExpr &, const CallDescription &) 149 template <typename... Ts> 150 friend bool matchesAnyAsWritten(const CallExpr &CE, 151 const CallDescription &CD1, 152 const Ts &...CDs) { 153 return CD1.matchesAsWritten(CE) || matchesAnyAsWritten(CE, CDs...); 154 } 155 /// @} 156 157private: 158 bool matchesImpl(const FunctionDecl *Callee, size_t ArgCount, 159 size_t ParamCount) const; 160}; 161 162/// An immutable map from CallDescriptions to arbitrary data. Provides a unified 163/// way for checkers to react on function calls. 164template <typename T> class CallDescriptionMap { 165 friend class CallDescriptionSet; 166 167 // Some call descriptions aren't easily hashable (eg., the ones with qualified 168 // names in which some sections are omitted), so let's put them 169 // in a simple vector and use linear lookup. 170 // TODO: Implement an actual map for fast lookup for "hashable" call 171 // descriptions (eg., the ones for C functions that just match the name). 172 std::vector<std::pair<CallDescription, T>> LinearMap; 173 174public: 175 CallDescriptionMap( 176 std::initializer_list<std::pair<CallDescription, T>> &&List) 177 : LinearMap(List) {} 178 179 template <typename InputIt> 180 CallDescriptionMap(InputIt First, InputIt Last) : LinearMap(First, Last) {} 181 182 ~CallDescriptionMap() = default; 183 184 // These maps are usually stored once per checker, so let's make sure 185 // we don't do redundant copies. 186 CallDescriptionMap(const CallDescriptionMap &) = delete; 187 CallDescriptionMap &operator=(const CallDescription &) = delete; 188 189 CallDescriptionMap(CallDescriptionMap &&) = default; 190 CallDescriptionMap &operator=(CallDescriptionMap &&) = default; 191 192 [[nodiscard]] const T *lookup(const CallEvent &Call) const { 193 // Slow path: linear lookup. 194 // TODO: Implement some sort of fast path. 195 for (const std::pair<CallDescription, T> &I : LinearMap) 196 if (I.first.matches(Call)) 197 return &I.second; 198 199 return nullptr; 200 } 201 202 /// When available, always prefer lookup with a CallEvent! This function 203 /// exists only when that is not available, for example, when _only_ 204 /// syntactic check is done on a piece of code. 205 /// 206 /// Also, StdLibraryFunctionsChecker::Signature is likely a better candicade 207 /// for syntactic only matching if you are writing a new checker. This is 208 /// handy if a CallDescriptionMap is already there. 209 /// 210 /// The function is imprecise because CallEvent may know path sensitive 211 /// information, such as the precise argument count (see comments for 212 /// CallEvent::getNumArgs), the called function if it was called through a 213 /// function pointer, and other information not available syntactically. 214 [[nodiscard]] const T *lookupAsWritten(const CallExpr &Call) const { 215 // Slow path: linear lookup. 216 // TODO: Implement some sort of fast path. 217 for (const std::pair<CallDescription, T> &I : LinearMap) 218 if (I.first.matchesAsWritten(Call)) 219 return &I.second; 220 221 return nullptr; 222 } 223}; 224 225/// An immutable set of CallDescriptions. 226/// Checkers can efficiently decide if a given CallEvent matches any 227/// CallDescription in the set. 228class CallDescriptionSet { 229 CallDescriptionMap<bool /*unused*/> Impl = {}; 230 231public: 232 CallDescriptionSet(std::initializer_list<CallDescription> &&List); 233 234 CallDescriptionSet(const CallDescriptionSet &) = delete; 235 CallDescriptionSet &operator=(const CallDescription &) = delete; 236 237 [[nodiscard]] bool contains(const CallEvent &Call) const; 238 239 /// When available, always prefer lookup with a CallEvent! This function 240 /// exists only when that is not available, for example, when _only_ 241 /// syntactic check is done on a piece of code. 242 /// 243 /// Also, StdLibraryFunctionsChecker::Signature is likely a better candicade 244 /// for syntactic only matching if you are writing a new checker. This is 245 /// handy if a CallDescriptionMap is already there. 246 /// 247 /// The function is imprecise because CallEvent may know path sensitive 248 /// information, such as the precise argument count (see comments for 249 /// CallEvent::getNumArgs), the called function if it was called through a 250 /// function pointer, and other information not available syntactically. 251 [[nodiscard]] bool containsAsWritten(const CallExpr &CE) const; 252}; 253 254} // namespace ento 255} // namespace clang 256 257#endif // LLVM_CLANG_STATICANALYZER_CORE_PATHSENSITIVE_CALLDESCRIPTION_H 258