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_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"
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  /// 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 
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.
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,
144 
145  lldb::SBSymbolContextList FindSymbols(const char *name,
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.
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_
bool LLDB_API operator==(const SBAddress &lhs, const SBAddress &rhs)
Definition: SBAddress.cpp:66
class LLDB_API SBModule
Definition: SBDefines.h:57
uint64_t user_id_t
Definition: lldb-types.h:84
bool operator!=(const Address &lhs, const Address &rhs)
Definition: Address.cpp:979
#define LLDB_API
Definition: lldb-defines.h:23
uint64_t addr_t
Definition: lldb-types.h:83
Definition: SBAddress.h:15