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