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