Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===- CallDescription.h - function/method call matching       --*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

//

/// \file This file defines a generic mechanism for matching for function and

/// method calls of C, C++, and Objective-C languages. Instances of these

/// classes are frequently used together with the CallEvent classes.

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_CLANG_STATICANALYZER_CORE_PATHSENSITIVE_CALLDESCRIPTION_H

#define LLVM_CLANG_STATICANALYZER_CORE_PATHSENSITIVE_CALLDESCRIPTION_H

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

#include "llvm/ADT/ArrayRef.h"

#include "llvm/Support/Compiler.h"

#include <optional>

#include <vector>

namespace clang {

class IdentifierInfo;

} // namespace clang

namespace clang {

namespace ento {

enum CallDescriptionFlags : unsigned {

  CDF_None = 0,

  /// Describes a C standard function that is sometimes implemented as a macro

  /// that expands to a compiler builtin with some __builtin prefix.

  /// The builtin may as well have a few extra arguments on top of the requested

  /// number of arguments.

  CDF_MaybeBuiltin = 1 << 0,

};

/// This class represents a description of a function call using the number of

/// arguments and the name of the function.

class CallDescription {

  friend class CallEvent;

  using MaybeCount = std::optional<unsigned>;

  mutable std::optional<const IdentifierInfo *> II;

  // The list of the qualified names used to identify the specified CallEvent,

  // e.g. "{a, b}" represent the qualified names, like "a::b".

  std::vector<std::string> QualifiedName;

  MaybeCount RequiredArgs;

  MaybeCount RequiredParams;

  int Flags;

public:

  /// Constructs a CallDescription object.

  ///

  /// @param QualifiedName The 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().

  ///

  /// @param RequiredArgs The number of arguments that is expected to match a

  /// call. Omit this parameter to match every occurrence of call with a given

  /// name regardless the number of arguments.

  CallDescription(CallDescriptionFlags Flags, ArrayRef<StringRef> QualifiedName,

                  MaybeCount RequiredArgs = std::nullopt,

                  MaybeCount RequiredParams = std::nullopt);

  /// Construct a CallDescription with default flags.

  CallDescription(ArrayRef<StringRef> QualifiedName,

                  MaybeCount RequiredArgs = std::nullopt,

                  MaybeCount RequiredParams = std::nullopt);

  CallDescription(std::nullptr_t) = delete;

  /// Get the name of the function that this object matches.

  StringRef getFunctionName() const { return QualifiedName.back(); }

  /// Get the qualified name parts in reversed order.

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

  auto begin_qualified_name_parts() const {

    return std::next(QualifiedName.rbegin());

  }

  auto end_qualified_name_parts() const { return QualifiedName.rend(); }

  /// 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`.

  bool hasQualifiedNameParts() const { return QualifiedName.size() > 1; }

  /// @name Matching CallDescriptions against a CallEvent

  /// @{

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

  bool matches(const CallEvent &Call) const;

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

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

    return CD1.matches(Call);

  }

  /// \copydoc clang::ento::CallDescription::matchesAny(const CallEvent &, const CallDescription &)

  template <typename... Ts>

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

                         const Ts &...CDs) {

    return CD1.matches(Call) || matchesAny(Call, CDs...);

  }

  /// @}

  /// @name Matching CallDescriptions against a CallExpr

  /// @{

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

  bool matchesAsWritten(const CallExpr &CE) const;

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

  friend bool matchesAnyAsWritten(const CallExpr &CE,

                                  const CallDescription &CD1) {

    return CD1.matchesAsWritten(CE);

  }

  /// \copydoc clang::ento::CallDescription::matchesAnyAsWritten(const CallExpr &, const CallDescription &)

  template <typename... Ts>

  friend bool matchesAnyAsWritten(const CallExpr &CE,

                                  const CallDescription &CD1,

                                  const Ts &...CDs) {

    return CD1.matchesAsWritten(CE) || matchesAnyAsWritten(CE, CDs...);

  }

  /// @}

private:

  bool matchesImpl(const FunctionDecl *Callee, size_t ArgCount,

                   size_t ParamCount) const;

};

/// An immutable map from CallDescriptions to arbitrary data. Provides a unified

/// way for checkers to react on function calls.

template <typename T> class CallDescriptionMap {

  friend class CallDescriptionSet;

  // Some call descriptions aren't easily hashable (eg., the ones with qualified

  // names in which some sections are omitted), so let's put them

  // in a simple vector and use linear lookup.

  // TODO: Implement an actual map for fast lookup for "hashable" call

  // descriptions (eg., the ones for C functions that just match the name).

  std::vector<std::pair<CallDescription, T>> LinearMap;

public:

  CallDescriptionMap(

      std::initializer_list<std::pair<CallDescription, T>> &&List)

      : LinearMap(List) {}

  template <typename InputIt>

  CallDescriptionMap(InputIt First, InputIt Last) : LinearMap(First, Last) {}

  ~CallDescriptionMap() = default;

  // These maps are usually stored once per checker, so let's make sure

  // we don't do redundant copies.

  CallDescriptionMap(const CallDescriptionMap &) = delete;

  CallDescriptionMap &operator=(const CallDescription &) = delete;

  CallDescriptionMap(CallDescriptionMap &&) = default;

  CallDescriptionMap &operator=(CallDescriptionMap &&) = default;

  [[nodiscard]] const T *lookup(const CallEvent &Call) const {

    // Slow path: linear lookup.

    // TODO: Implement some sort of fast path.

    for (const std::pair<CallDescription, T> &I : LinearMap)

      if (I.first.matches(Call))

        return &I.second;

    return nullptr;

  }

  /// When available, always prefer lookup 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.

  [[nodiscard]] const T *lookupAsWritten(const CallExpr &Call) const {

    // Slow path: linear lookup.

    // TODO: Implement some sort of fast path.

    for (const std::pair<CallDescription, T> &I : LinearMap)

      if (I.first.matchesAsWritten(Call))

        return &I.second;

    return nullptr;

  }

};

/// An immutable set of CallDescriptions.

/// Checkers can efficiently decide if a given CallEvent matches any

/// CallDescription in the set.

class CallDescriptionSet {

  CallDescriptionMap<bool /*unused*/> Impl = {};

public:

  CallDescriptionSet(std::initializer_list<CallDescription> &&List);

  CallDescriptionSet(const CallDescriptionSet &) = delete;

  CallDescriptionSet &operator=(const CallDescription &) = delete;

  [[nodiscard]] bool contains(const CallEvent &Call) const;

  /// When available, always prefer lookup 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.

  [[nodiscard]] bool containsAsWritten(const CallExpr &CE) const;

};

} // namespace ento

} // namespace clang

#endif // LLVM_CLANG_STATICANALYZER_CORE_PATHSENSITIVE_CALLDESCRIPTION_H