lldb/API/SBModule.h

//===-- SBModule.h ----------------------------------------------*- 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
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_API_SBMODULE_H
#define LLDB_API_SBMODULE_H

#include "lldb/API/SBDefines.h"
#include "lldb/API/SBError.h"
#include "lldb/API/SBSection.h"
#include "lldb/API/SBSymbolContext.h"
#include "lldb/API/SBValueList.h"

namespace lldb {

class LLDB_API SBModule {
public:
  SBModule();

  SBModule(const SBModule &rhs);

  SBModule(const SBModuleSpec &module_spec);

  const SBModule &operator=(const SBModule &rhs);

  SBModule(lldb::SBProcess &process, lldb::addr_t header_addr);

  ~SBModule();

  explicit operator bool() const;

  bool IsValid() const;

  void Clear();

  bool IsFileBacked() const;

  /// Get const accessor for the module file specification.
  ///
  /// This function returns the file for the module on the host system
  /// that is running LLDB. This can differ from the path on the
  /// platform since we might be doing remote debugging.
  ///
  /// \return
  ///     A const reference to the file specification object.
  lldb::SBFileSpec GetFileSpec() const;

  /// Get accessor for the module platform file specification.
  ///
  /// Platform file refers to the path of the module as it is known on
  /// the remote system on which it is being debugged. For local
  /// debugging this is always the same as Module::GetFileSpec(). But
  /// remote debugging might mention a file '/usr/lib/liba.dylib'
  /// which might be locally downloaded and cached. In this case the
  /// platform file could be something like:
  /// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
  /// The file could also be cached in a local developer kit directory.
  ///
  /// \return
  ///     A const reference to the file specification object.
  lldb::SBFileSpec GetPlatformFileSpec() const;

  bool SetPlatformFileSpec(const lldb::SBFileSpec &platform_file);

  /// Get accessor for the remote install path for a module.
  ///
  /// When debugging to a remote platform by connecting to a remote
  /// platform, the install path of the module can be set. If the
  /// install path is set, every time the process is about to launch
  /// the target will install this module on the remote platform prior
  /// to launching.
  ///
  /// \return
  ///     A file specification object.
  lldb::SBFileSpec GetRemoteInstallFileSpec();

  /// Set accessor for the remote install path for a module.
  ///
  /// When debugging to a remote platform by connecting to a remote
  /// platform, the install path of the module can be set. If the
  /// install path is set, every time the process is about to launch
  /// the target will install this module on the remote platform prior
  /// to launching.
  ///
  /// If \a file specifies a full path to an install location, the
  /// module will be installed to this path. If the path is relative
  /// (no directory specified, or the path is partial like "usr/lib"
  /// or "./usr/lib", then the install path will be resolved using
  /// the platform's current working directory as the base path.
  ///
  /// \param[in] file
  ///     A file specification object.
  bool SetRemoteInstallFileSpec(lldb::SBFileSpec &file);

  lldb::ByteOrder GetByteOrder();

  uint32_t GetAddressByteSize();

  const char *GetTriple();

  const uint8_t *GetUUIDBytes() const;

  const char *GetUUIDString() const;

  bool operator==(const lldb::SBModule &rhs) const;

  bool operator!=(const lldb::SBModule &rhs) const;

  lldb::SBSection FindSection(const char *sect_name);

  lldb::SBAddress ResolveFileAddress(lldb::addr_t vm_addr);

  lldb::SBSymbolContext
  ResolveSymbolContextForAddress(const lldb::SBAddress &addr,
                                 uint32_t resolve_scope);

  bool GetDescription(lldb::SBStream &description);

  uint32_t GetNumCompileUnits();

  lldb::SBCompileUnit GetCompileUnitAtIndex(uint32_t);

  /// Find compile units related to *this module and passed source
  /// file.
  ///
  /// \param[in] sb_file_spec
  ///     A lldb::SBFileSpec object that contains source file
  ///     specification.
  ///
  /// \return
  ///     A lldb::SBSymbolContextList that gets filled in with all of
  ///     the symbol contexts for all the matches.
  lldb::SBSymbolContextList
  FindCompileUnits(const lldb::SBFileSpec &sb_file_spec);

  size_t GetNumSymbols();

  lldb::SBSymbol GetSymbolAtIndex(size_t idx);

  lldb::SBSymbol FindSymbol(const char *name,
                            lldb::SymbolType type = eSymbolTypeAny);

  lldb::SBSymbolContextList FindSymbols(const char *name,
                                        lldb::SymbolType type = eSymbolTypeAny);

  size_t GetNumSections();

  lldb::SBSection GetSectionAtIndex(size_t idx);
  /// Find functions by name.
  ///
  /// \param[in] name
  ///     The name of the function we are looking for.
  ///
  /// \param[in] name_type_mask
  ///     A logical OR of one or more FunctionNameType enum bits that
  ///     indicate what kind of names should be used when doing the
  ///     lookup. Bits include fully qualified names, base names,
  ///     C++ methods, or ObjC selectors.
  ///     See FunctionNameType for more details.
  ///
  /// \return
  ///     A lldb::SBSymbolContextList that gets filled in with all of
  ///     the symbol contexts for all the matches.
  lldb::SBSymbolContextList
  FindFunctions(const char *name,
                uint32_t name_type_mask = lldb::eFunctionNameTypeAny);

  /// Find global and static variables by name.
  ///
  /// \param[in] target
  ///     A valid SBTarget instance representing the debuggee.
  ///
  /// \param[in] name
  ///     The name of the global or static variable we are looking
  ///     for.
  ///
  /// \param[in] max_matches
  ///     Allow the number of matches to be limited to \a max_matches.
  ///
  /// \return
  ///     A list of matched variables in an SBValueList.
  lldb::SBValueList FindGlobalVariables(lldb::SBTarget &target,
                                        const char *name, uint32_t max_matches);

  /// Find the first global (or static) variable by name.
  ///
  /// \param[in] target
  ///     A valid SBTarget instance representing the debuggee.
  ///
  /// \param[in] name
  ///     The name of the global or static variable we are looking
  ///     for.
  ///
  /// \return
  ///     An SBValue that gets filled in with the found variable (if any).
  lldb::SBValue FindFirstGlobalVariable(lldb::SBTarget &target,
                                        const char *name);

  lldb::SBType FindFirstType(const char *name);

  lldb::SBTypeList FindTypes(const char *type);

  /// Get a type using its type ID.
  ///
  /// Each symbol file reader will assign different user IDs to their
  /// types, but it is sometimes useful when debugging type issues to
  /// be able to grab a type using its type ID.
  ///
  /// For DWARF debug info, the type ID is the DIE offset.
  ///
  /// \param[in] uid
  ///     The type user ID.
  ///
  /// \return
  ///     An SBType for the given type ID, or an empty SBType if the
  ///     type was not found.
  lldb::SBType GetTypeByID(lldb::user_id_t uid);

  lldb::SBType GetBasicType(lldb::BasicType type);

  /// Get all types matching \a type_mask from debug info in this
  /// module.
  ///
  /// \param[in] type_mask
  ///     A bitfield that consists of one or more bits logically OR'ed
  ///     together from the lldb::TypeClass enumeration. This allows
  ///     you to request only structure types, or only class, struct
  ///     and union types. Passing in lldb::eTypeClassAny will return
  ///     all types found in the debug information for this module.
  ///
  /// \return
  ///     A list of types in this module that match \a type_mask
  lldb::SBTypeList GetTypes(uint32_t type_mask = lldb::eTypeClassAny);

  /// Get the module version numbers.
  ///
  /// Many object files have a set of version numbers that describe
  /// the version of the executable or shared library. Typically there
  /// are major, minor and build, but there may be more. This function
  /// will extract the versions from object files if they are available.
  ///
  /// If \a versions is NULL, or if \a num_versions is 0, the return
  /// value will indicate how many version numbers are available in
  /// this object file. Then a subsequent call can be made to this
  /// function with a value of \a versions and \a num_versions that
  /// has enough storage to store some or all version numbers.
  ///
  /// \param[out] versions
  ///     A pointer to an array of uint32_t types that is \a num_versions
  ///     long. If this value is NULL, the return value will indicate
  ///     how many version numbers are required for a subsequent call
  ///     to this function so that all versions can be retrieved. If
  ///     the value is non-NULL, then at most \a num_versions of the
  ///     existing versions numbers will be filled into \a versions.
  ///     If there is no version information available, \a versions
  ///     will be filled with \a num_versions UINT32_MAX values
  ///     and zero will be returned.
  ///
  /// \param[in] num_versions
  ///     The maximum number of entries to fill into \a versions. If
  ///     this value is zero, then the return value will indicate
  ///     how many version numbers there are in total so another call
  ///     to this function can be make with adequate storage in
  ///     \a versions to get all of the version numbers. If \a
  ///     num_versions is less than the actual number of version
  ///     numbers in this object file, only \a num_versions will be
  ///     filled into \a versions (if \a versions is non-NULL).
  ///
  /// \return
  ///     This function always returns the number of version numbers
  ///     that this object file has regardless of the number of
  ///     version numbers that were copied into \a versions.
  uint32_t GetVersion(uint32_t *versions, uint32_t num_versions);

  /// Get accessor for the symbol file specification.
  ///
  /// When debugging an object file an additional debug information can
  /// be provided in separate file. Therefore if you debugging something
  /// like '/usr/lib/liba.dylib' then debug information can be located
  /// in folder like '/usr/lib/liba.dylib.dSYM/'.
  ///
  /// \return
  ///     A const reference to the file specification object.
  lldb::SBFileSpec GetSymbolFileSpec() const;

  lldb::SBAddress GetObjectFileHeaderAddress() const;
  lldb::SBAddress GetObjectFileEntryPointAddress() const;

  /// Get the number of global modules.
  static uint32_t GetNumberAllocatedModules();

  /// Remove any global modules which are no longer needed.
  static void GarbageCollectAllocatedModules();

private:
  friend class SBAddress;
  friend class SBFrame;
  friend class SBSection;
  friend class SBSymbolContext;
  friend class SBTarget;
  friend class SBType;

  explicit SBModule(const lldb::ModuleSP &module_sp);

  ModuleSP GetSP() const;

  void SetSP(const ModuleSP &module_sp);

  lldb::ModuleSP m_opaque_sp;
};

} // namespace lldb

#endif // LLDB_API_SBMODULE_H