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