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(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
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

source code of clang/include/clang/StaticAnalyzer/Core/PathSensitive/CallDescription.h