include/lldb/API/SBModule.h

   1 //===-- SBModule.h ----------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLDB_SBModule_h_
  11 #define LLDB_SBModule_h_
  12
  13 #include "lldb/API/SBDefines.h"
  14 #include "lldb/API/SBError.h"
  15 #include "lldb/API/SBSection.h"
  16 #include "lldb/API/SBSymbolContext.h"
  17 #include "lldb/API/SBValueList.h"
  18
  19 namespace lldb {
  20
  21 class LLDB_API SBModule {
  22 public:
  23   SBModule();
  24
  25   SBModule(const SBModule &rhs);
  26
  27   SBModule(const SBModuleSpec &module_spec);
  28
  29   const SBModule &operator=(const SBModule &rhs);
  30
  31   SBModule(lldb::SBProcess &process, lldb::addr_t header_addr);
  32
  33   ~SBModule();
  34
  35   bool IsValid() const;
  36
  37   void Clear();
  38
  39   //------------------------------------------------------------------
  40   /// Get const accessor for the module file specification.
  41   ///
  42   /// This function returns the file for the module on the host system
  43   /// that is running LLDB. This can differ from the path on the
  44   /// platform since we might be doing remote debugging.
  45   ///
  46   /// @return
  47   ///     A const reference to the file specification object.
  48   //------------------------------------------------------------------
  49   lldb::SBFileSpec GetFileSpec() const;
  50
  51   //------------------------------------------------------------------
  52   /// Get accessor for the module platform file specification.
  53   ///
  54   /// Platform file refers to the path of the module as it is known on
  55   /// the remote system on which it is being debugged. For local
  56   /// debugging this is always the same as Module::GetFileSpec(). But
  57   /// remote debugging might mention a file '/usr/lib/liba.dylib'
  58   /// which might be locally downloaded and cached. In this case the
  59   /// platform file could be something like:
  60   /// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
  61   /// The file could also be cached in a local developer kit directory.
  62   ///
  63   /// @return
  64   ///     A const reference to the file specification object.
  65   //------------------------------------------------------------------
  66   lldb::SBFileSpec GetPlatformFileSpec() const;
  67
  68   bool SetPlatformFileSpec(const lldb::SBFileSpec &platform_file);
  69
  70   //------------------------------------------------------------------
  71   /// Get accessor for the remote install path for a module.
  72   ///
  73   /// When debugging to a remote platform by connecting to a remote
  74   /// platform, the install path of the module can be set. If the
  75   /// install path is set, every time the process is about to launch
  76   /// the target will install this module on the remote platform prior
  77   /// to launching.
  78   ///
  79   /// @return
  80   ///     A file specification object.
  81   //------------------------------------------------------------------
  82   lldb::SBFileSpec GetRemoteInstallFileSpec();
  83
  84   //------------------------------------------------------------------
  85   /// Set accessor for the remote install path for a module.
  86   ///
  87   /// When debugging to a remote platform by connecting to a remote
  88   /// platform, the install path of the module can be set. If the
  89   /// install path is set, every time the process is about to launch
  90   /// the target will install this module on the remote platform prior
  91   /// to launching.
  92   ///
  93   /// If \a file specifies a full path to an install location, the
  94   /// module will be installed to this path. If the path is relative
  95   /// (no directory specified, or the path is partial like "usr/lib"
  96   /// or "./usr/lib", then the install path will be resolved using
  97   /// the platform's current working directory as the base path.
  98   ///
  99   /// @param[in] file
 100   ///     A file specification object.
 101   //------------------------------------------------------------------
 102   bool SetRemoteInstallFileSpec(lldb::SBFileSpec &file);
 103
 104   lldb::ByteOrder GetByteOrder();
 105
 106   uint32_t GetAddressByteSize();
 107
 108   const char *GetTriple();
 109
 110   const uint8_t *GetUUIDBytes() const;
 111
 112   const char *GetUUIDString() const;
 113
 114   bool operator==(const lldb::SBModule &rhs) const;
 115
 116   bool operator!=(const lldb::SBModule &rhs) const;
 117
 118   lldb::SBSection FindSection(const char *sect_name);
 119
 120   lldb::SBAddress ResolveFileAddress(lldb::addr_t vm_addr);
 121
 122   lldb::SBSymbolContext
 123   ResolveSymbolContextForAddress(const lldb::SBAddress &addr,
 124                                  uint32_t resolve_scope);
 125
 126   bool GetDescription(lldb::SBStream &description);
 127
 128   uint32_t GetNumCompileUnits();
 129
 130   lldb::SBCompileUnit GetCompileUnitAtIndex(uint32_t);
 131
 132   //------------------------------------------------------------------
 133   /// Find compile units related to *this module and passed source
 134   /// file.
 135   ///
 136   /// @param[in] sb_file_spec
 137   ///     A lldb::SBFileSpec object that contains source file
 138   ///     specification.
 139   ///
 140   /// @return
 141   ///     A lldb::SBSymbolContextList that gets filled in with all of
 142   ///     the symbol contexts for all the matches.
 143   //------------------------------------------------------------------
 144   lldb::SBSymbolContextList
 145   FindCompileUnits(const lldb::SBFileSpec &sb_file_spec);
 146
 147   size_t GetNumSymbols();
 148
 149   lldb::SBSymbol GetSymbolAtIndex(size_t idx);
 150
 151   lldb::SBSymbol FindSymbol(const char *name,
 152                             lldb::SymbolType type = eSymbolTypeAny);
 153
 154   lldb::SBSymbolContextList FindSymbols(const char *name,
 155                                         lldb::SymbolType type = eSymbolTypeAny);
 156
 157   size_t GetNumSections();
 158
 159   lldb::SBSection GetSectionAtIndex(size_t idx);
 160   //------------------------------------------------------------------
 161   /// Find functions by name.
 162   ///
 163   /// @param[in] name
 164   ///     The name of the function we are looking for.
 165   ///
 166   /// @param[in] name_type_mask
 167   ///     A logical OR of one or more FunctionNameType enum bits that
 168   ///     indicate what kind of names should be used when doing the
 169   ///     lookup. Bits include fully qualified names, base names,
 170   ///     C++ methods, or ObjC selectors.
 171   ///     See FunctionNameType for more details.
 172   ///
 173   /// @return
 174   ///     A lldb::SBSymbolContextList that gets filled in with all of
 175   ///     the symbol contexts for all the matches.
 176   //------------------------------------------------------------------
 177   lldb::SBSymbolContextList
 178   FindFunctions(const char *name,
 179                 uint32_t name_type_mask = lldb::eFunctionNameTypeAny);
 180
 181   //------------------------------------------------------------------
 182   /// Find global and static variables by name.
 183   ///
 184   /// @param[in] target
 185   ///     A valid SBTarget instance representing the debuggee.
 186   ///
 187   /// @param[in] name
 188   ///     The name of the global or static variable we are looking
 189   ///     for.
 190   ///
 191   /// @param[in] max_matches
 192   ///     Allow the number of matches to be limited to \a max_matches.
 193   ///
 194   /// @return
 195   ///     A list of matched variables in an SBValueList.
 196   //------------------------------------------------------------------
 197   lldb::SBValueList FindGlobalVariables(lldb::SBTarget &target,
 198                                         const char *name, uint32_t max_matches);
 199
 200   //------------------------------------------------------------------
 201   /// Find the first global (or static) variable by name.
 202   ///
 203   /// @param[in] target
 204   ///     A valid SBTarget instance representing the debuggee.
 205   ///
 206   /// @param[in] name
 207   ///     The name of the global or static variable we are looking
 208   ///     for.
 209   ///
 210   /// @return
 211   ///     An SBValue that gets filled in with the found variable (if any).
 212   //------------------------------------------------------------------
 213   lldb::SBValue FindFirstGlobalVariable(lldb::SBTarget &target,
 214                                         const char *name);
 215
 216   lldb::SBType FindFirstType(const char *name);
 217
 218   lldb::SBTypeList FindTypes(const char *type);
 219
 220   //------------------------------------------------------------------
 221   /// Get a type using its type ID.
 222   ///
 223   /// Each symbol file reader will assign different user IDs to their
 224   /// types, but it is sometimes useful when debugging type issues to
 225   /// be able to grab a type using its type ID.
 226   ///
 227   /// For DWARF debug info, the type ID is the DIE offset.
 228   ///
 229   /// @param[in] uid
 230   ///     The type user ID.
 231   ///
 232   /// @return
 233   ///     An SBType for the given type ID, or an empty SBType if the
 234   ///     type was not found.
 235   //------------------------------------------------------------------
 236   lldb::SBType GetTypeByID(lldb::user_id_t uid);
 237
 238   lldb::SBType GetBasicType(lldb::BasicType type);
 239
 240   //------------------------------------------------------------------
 241   /// Get all types matching \a type_mask from debug info in this
 242   /// module.
 243   ///
 244   /// @param[in] type_mask
 245   ///     A bitfield that consists of one or more bits logically OR'ed
 246   ///     together from the lldb::TypeClass enumeration. This allows
 247   ///     you to request only structure types, or only class, struct
 248   ///     and union types. Passing in lldb::eTypeClassAny will return
 249   ///     all types found in the debug information for this module.
 250   ///
 251   /// @return
 252   ///     A list of types in this module that match \a type_mask
 253   //------------------------------------------------------------------
 254   lldb::SBTypeList GetTypes(uint32_t type_mask = lldb::eTypeClassAny);
 255
 256   //------------------------------------------------------------------
 257   /// Get the module version numbers.
 258   ///
 259   /// Many object files have a set of version numbers that describe
 260   /// the version of the executable or shared library. Typically there
 261   /// are major, minor and build, but there may be more. This function
 262   /// will extract the versions from object files if they are available.
 263   ///
 264   /// If \a versions is NULL, or if \a num_versions is 0, the return
 265   /// value will indicate how many version numbers are available in
 266   /// this object file. Then a subsequent call can be made to this
 267   /// function with a value of \a versions and \a num_versions that
 268   /// has enough storage to store some or all version numbers.
 269   ///
 270   /// @param[out] versions
 271   ///     A pointer to an array of uint32_t types that is \a num_versions
 272   ///     long. If this value is NULL, the return value will indicate
 273   ///     how many version numbers are required for a subsequent call
 274   ///     to this function so that all versions can be retrieved. If
 275   ///     the value is non-NULL, then at most \a num_versions of the
 276   ///     existing versions numbers will be filled into \a versions.
 277   ///     If there is no version information available, \a versions
 278   ///     will be filled with \a num_versions UINT32_MAX values
 279   ///     and zero will be returned.
 280   ///
 281   /// @param[in] num_versions
 282   ///     The maximum number of entries to fill into \a versions. If
 283   ///     this value is zero, then the return value will indicate
 284   ///     how many version numbers there are in total so another call
 285   ///     to this function can be make with adequate storage in
 286   ///     \a versions to get all of the version numbers. If \a
 287   ///     num_versions is less than the actual number of version
 288   ///     numbers in this object file, only \a num_versions will be
 289   ///     filled into \a versions (if \a versions is non-NULL).
 290   ///
 291   /// @return
 292   ///     This function always returns the number of version numbers
 293   ///     that this object file has regardless of the number of
 294   ///     version numbers that were copied into \a versions.
 295   //------------------------------------------------------------------
 296   uint32_t GetVersion(uint32_t *versions, uint32_t num_versions);
 297
 298   //------------------------------------------------------------------
 299   /// Get accessor for the symbol file specification.
 300   ///
 301   /// When debugging an object file an additional debug information can
 302   /// be provided in separate file. Therefore if you debugging something
 303   /// like '/usr/lib/liba.dylib' then debug information can be located
 304   /// in folder like '/usr/lib/liba.dylib.dSYM/'.
 305   ///
 306   /// @return
 307   ///     A const reference to the file specification object.
 308   //------------------------------------------------------------------
 309   lldb::SBFileSpec GetSymbolFileSpec() const;
 310
 311   lldb::SBAddress GetObjectFileHeaderAddress() const;
 312   lldb::SBAddress GetObjectFileEntryPointAddress() const;
 313
 314 private:
 315   friend class SBAddress;
 316   friend class SBFrame;
 317   friend class SBSection;
 318   friend class SBSymbolContext;
 319   friend class SBTarget;
 320
 321   explicit SBModule(const lldb::ModuleSP &module_sp);
 322
 323   ModuleSP GetSP() const;
 324
 325   void SetSP(const ModuleSP &module_sp);
 326
 327   lldb::ModuleSP m_opaque_sp;
 328 };
 329
 330 } // namespace lldb
 331
 332 #endif // LLDB_SBModule_h_