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"
17
18namespace lldb {
19
21public:
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
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.
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.
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.
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.
98
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
116
119 uint32_t resolve_scope);
120
121 bool GetDescription(lldb::SBStream &description);
122
123 uint32_t GetNumCompileUnits();
124
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
143
144 lldb::SBSymbol FindSymbol(const char *name,
146
147 lldb::SBSymbolContextList FindSymbols(const char *name,
149
150 size_t GetNumSections();
151
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.
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).
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.
222
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.
289
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 /// If this Module represents a specific object or part within a larger file,
300 /// returns the name of that object or part. Otherwise, returns
301 /// nullptr.
302 const char *GetObjectName() const;
303
304private:
305 friend class SBAddress;
306 friend class SBFrame;
307 friend class SBSection;
308 friend class SBSymbolContext;
309 friend class SBPlatform;
310 friend class SBTarget;
311 friend class SBType;
312
313 friend class lldb_private::python::SWIGBridge;
314
315 explicit SBModule(const lldb::ModuleSP &module_sp);
316
317 ModuleSP GetSP() const;
318
319 void SetSP(const ModuleSP &module_sp);
320
322};
323
324} // namespace lldb
325
326#endif // LLDB_API_SBMODULE_H
#define LLDB_API
Definition SBDefines.h:28
bool GetDescription(lldb::SBStream &description)
Definition SBModule.cpp:239
const char * GetTriple()
Definition SBModule.cpp:572
lldb::SBTypeList GetTypes(uint32_t type_mask=lldb::eTypeClassAny)
Get all types matching type_mask from debug info in this module.
Definition SBModule.cpp:523
size_t GetNumSections()
Definition SBModule.cpp:356
lldb::SBValue FindFirstGlobalVariable(lldb::SBTarget &target, const char *name)
Find the first global (or static) variable by name.
Definition SBModule.cpp:426
void SetSP(const ModuleSP &module_sp)
Definition SBModule.cpp:211
lldb::SBType FindFirstType(const char *name)
Definition SBModule.cpp:436
lldb::SBAddress GetObjectFileEntryPointAddress() const
Definition SBModule.cpp:649
uint32_t GetAddressByteSize()
Definition SBModule.cpp:587
uint32_t GetNumCompileUnits()
Definition SBModule.cpp:253
lldb::SBTypeList FindTypes(const char *type)
Definition SBModule.cpp:479
lldb::SBValueList FindGlobalVariables(lldb::SBTarget &target, const char *name, uint32_t max_matches)
Find global and static variables by name.
Definition SBModule.cpp:404
static void GarbageCollectAllocatedModules()
Remove any global modules which are no longer needed.
Definition SBModule.cpp:668
static uint32_t GetNumberAllocatedModules()
Get the number of global modules.
Definition SBModule.cpp:662
lldb::SBFileSpec GetSymbolFileSpec() const
Get accessor for the symbol file specification.
Definition SBModule.cpp:624
friend class SBTarget
Definition SBModule.h:310
lldb::SBSymbol GetSymbolAtIndex(size_t idx)
Definition SBModule.cpp:301
lldb::ModuleSP m_opaque_sp
Definition SBModule.h:321
lldb::SBSymbol FindSymbol(const char *name, lldb::SymbolType type=eSymbolTypeAny)
Definition SBModule.cpp:312
lldb::SBAddress ResolveFileAddress(lldb::addr_t vm_addr)
Definition SBModule.cpp:213
bool IsFileBacked() const
Definition SBModule.cpp:91
friend class SBSymbolContext
Definition SBModule.h:308
friend class SBAddress
Definition SBModule.h:305
const uint8_t * GetUUIDBytes() const
Definition SBModule.cpp:162
lldb::SBFileSpec GetRemoteInstallFileSpec()
Get accessor for the remote install path for a module.
Definition SBModule.cpp:141
uint32_t GetVersion(uint32_t *versions, uint32_t num_versions)
Get the module version numbers.
Definition SBModule.cpp:596
lldb::SBType GetTypeByID(lldb::user_id_t uid)
Get a type using its type ID.
Definition SBModule.cpp:509
lldb::SBSection FindSection(const char *sect_name)
Definition SBModule.cpp:542
lldb::SBCompileUnit GetCompileUnitAtIndex(uint32_t)
Definition SBModule.cpp:263
lldb::SBSection GetSectionAtIndex(size_t idx)
Definition SBModule.cpp:370
lldb::SBSymbolContextList FindSymbols(const char *name, lldb::SymbolType type=eSymbolTypeAny)
Definition SBModule.cpp:328
bool SetRemoteInstallFileSpec(lldb::SBFileSpec &file)
Set accessor for the remote install path for a module.
Definition SBModule.cpp:151
size_t GetNumSymbols()
Definition SBModule.cpp:292
const char * GetObjectName() const
If this Module represents a specific object or part within a larger file, returns the name of that ob...
Definition SBModule.cpp:675
bool operator==(const lldb::SBModule &rhs) const
Definition SBModule.cpp:193
lldb::SBSymbolContextList FindFunctions(const char *name, uint32_t name_type_mask=lldb::eFunctionNameTypeAny)
Find functions by name.
Definition SBModule.cpp:386
lldb::SBAddress GetObjectFileHeaderAddress() const
Definition SBModule.cpp:636
lldb::SBFileSpec GetFileSpec() const
Get const accessor for the module file specification.
Definition SBModule.cpp:105
lldb::SBSymbolContextList FindCompileUnits(const lldb::SBFileSpec &sb_file_spec)
Find compile units related to *this module and passed source file.
Definition SBModule.cpp:275
lldb::ByteOrder GetByteOrder()
Definition SBModule.cpp:563
const SBModule & operator=(const SBModule &rhs)
Definition SBModule.cpp:65
friend class SBFrame
Definition SBModule.h:306
ModuleSP GetSP() const
Definition SBModule.cpp:209
bool operator!=(const lldb::SBModule &rhs) const
Definition SBModule.cpp:201
const char * GetUUIDString() const
Definition SBModule.cpp:173
friend class SBSection
Definition SBModule.h:307
lldb::SBFileSpec GetPlatformFileSpec() const
Get accessor for the module platform file specification.
Definition SBModule.cpp:116
bool IsValid() const
Definition SBModule.cpp:75
lldb::SBSymbolContext ResolveSymbolContextForAddress(const lldb::SBAddress &addr, uint32_t resolve_scope)
Definition SBModule.cpp:227
bool SetPlatformFileSpec(const lldb::SBFileSpec &platform_file)
Definition SBModule.cpp:127
friend class SBType
Definition SBModule.h:311
lldb::SBType GetBasicType(lldb::BasicType type)
Definition SBModule.cpp:462
friend class SBPlatform
Definition SBModule.h:309
BasicType
Basic types enumeration for the public API SBType::GetBasicType().
SymbolType
Symbol types.
ByteOrder
Byte ordering definitions.
uint64_t user_id_t
Definition lldb-types.h:82
uint64_t addr_t
Definition lldb-types.h:80
std::shared_ptr< lldb_private::Module > ModuleSP