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"
15#include "lldb/API/SBSymbolContext.h"
16#include "lldb/API/SBValueList.h"
17
18namespace lldb {
19
20class LLDB_API SBModule {
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
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
117 lldb::SBSymbolContext
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.
137 lldb::SBSymbolContextList
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,
145 lldb::SymbolType type = eSymbolTypeAny);
146
147 lldb::SBSymbolContextList FindSymbols(const char *name,
148 lldb::SymbolType type = eSymbolTypeAny);
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.
168 lldb::SBSymbolContextList
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
299private:
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
319

source code of lldb/include/lldb/API/SBModule.h