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 | |
24 | namespace clang { |
25 | class IdentifierInfo; |
26 | } // namespace clang |
27 | |
28 | namespace clang { |
29 | namespace ento { |
30 | |
31 | enum 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. |
43 | class 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 | |
55 | public: |
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(x: 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 | |
157 | private: |
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. |
164 | template <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 | |
174 | public: |
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. |
228 | class CallDescriptionSet { |
229 | CallDescriptionMap<bool /*unused*/> Impl = {}; |
230 | |
231 | public: |
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 | |