blob: c826134ff42023ee5dc4748322fd86d8d73fac92 [file] [log] [blame]
Johnny Chenfb35e2a2011-07-18 23:11:07 +00001//===-- SWIG Interface for SBModule -----------------------------*- C++ -*-===//
2//
3// The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10namespace lldb {
11
12%feature("docstring",
13"Represents an executable image and its associated object and symbol files.
14
15The module is designed to be able to select a single slice of an
16executable image as it would appear on disk and during program
17execution.
18
19You can retrieve SBModule from SBSymbolContext, which in turn is available
20from SBFrame.
21
22SBModule supports symbol iteration, for example,
23
24 for symbol in module:
25 name = symbol.GetName()
26 saddr = symbol.GetStartAddress()
27 eaddr = symbol.GetEndAddress()
28
29and rich comparion methods which allow the API program to use,
30
31 if thisModule == thatModule:
32 print 'This module is the same as that module'
33
Johnny Chendc0cbd12011-09-24 04:51:43 +000034to test module equality. A module also contains object file sections, namely
Johnny Chenbf338e62011-09-30 00:42:49 +000035SBSection. SBModule supports section iteration through section_iter(), for
36example,
37
38 print 'Number of sections: %d' % module.GetNumSections()
39 for sec in module.section_iter():
40 print sec
41
42And to iterate the symbols within a SBSection, use symbol_in_section_iter(),
43
44 # Iterates the text section and prints each symbols within each sub-section.
45 for subsec in text_sec:
46 print INDENT + repr(subsec)
47 for sym in exe_module.symbol_in_section_iter(subsec):
48 print INDENT2 + repr(sym)
49 print INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType())
50
Johnny Chen5cac6a52011-10-01 01:19:45 +000051produces this following output:
Johnny Chenbf338e62011-09-30 00:42:49 +000052
53 [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text
54 id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870)
55 symbol type: code
56 id = {0x00000008}, name = 'thread_func(void*)', range = [0x0000000100001870-0x00000001000019b0)
57 symbol type: code
58 id = {0x0000000c}, name = 'main', range = [0x00000001000019b0-0x0000000100001d5c)
59 symbol type: code
60 id = {0x00000023}, name = 'start', address = 0x0000000100001780
61 symbol type: code
62 [0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs
63 id = {0x00000024}, name = '__stack_chk_fail', range = [0x0000000100001d5c-0x0000000100001d62)
64 symbol type: trampoline
65 id = {0x00000028}, name = 'exit', range = [0x0000000100001d62-0x0000000100001d68)
66 symbol type: trampoline
67 id = {0x00000029}, name = 'fflush', range = [0x0000000100001d68-0x0000000100001d6e)
68 symbol type: trampoline
69 id = {0x0000002a}, name = 'fgets', range = [0x0000000100001d6e-0x0000000100001d74)
70 symbol type: trampoline
71 id = {0x0000002b}, name = 'printf', range = [0x0000000100001d74-0x0000000100001d7a)
72 symbol type: trampoline
73 id = {0x0000002c}, name = 'pthread_create', range = [0x0000000100001d7a-0x0000000100001d80)
74 symbol type: trampoline
75 id = {0x0000002d}, name = 'pthread_join', range = [0x0000000100001d80-0x0000000100001d86)
76 symbol type: trampoline
77 id = {0x0000002e}, name = 'pthread_mutex_lock', range = [0x0000000100001d86-0x0000000100001d8c)
78 symbol type: trampoline
79 id = {0x0000002f}, name = 'pthread_mutex_unlock', range = [0x0000000100001d8c-0x0000000100001d92)
80 symbol type: trampoline
81 id = {0x00000030}, name = 'rand', range = [0x0000000100001d92-0x0000000100001d98)
82 symbol type: trampoline
83 id = {0x00000031}, name = 'strtoul', range = [0x0000000100001d98-0x0000000100001d9e)
84 symbol type: trampoline
85 id = {0x00000032}, name = 'usleep', range = [0x0000000100001d9e-0x0000000100001da4)
86 symbol type: trampoline
87 [0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper
88 [0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring
89 [0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info
90 [0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame
91"
Johnny Chenfb35e2a2011-07-18 23:11:07 +000092) SBModule;
93class SBModule
94{
95public:
96
97 SBModule ();
98
99 SBModule (const SBModule &rhs);
100
Greg Claytonb5a8f142012-02-05 02:38:54 +0000101 SBModule (lldb::SBProcess &process,
102 lldb::addr_t header_addr);
103
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000104 ~SBModule ();
105
106 bool
107 IsValid () const;
108
Jim Inghame0bd5712011-12-19 20:39:44 +0000109 void
110 Clear();
111
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000112 %feature("docstring", "
113 //------------------------------------------------------------------
114 /// Get const accessor for the module file specification.
115 ///
116 /// This function returns the file for the module on the host system
117 /// that is running LLDB. This can differ from the path on the
118 /// platform since we might be doing remote debugging.
119 ///
120 /// @return
121 /// A const reference to the file specification object.
122 //------------------------------------------------------------------
123 ") GetFileSpec;
124 lldb::SBFileSpec
125 GetFileSpec () const;
126
127 %feature("docstring", "
128 //------------------------------------------------------------------
129 /// Get accessor for the module platform file specification.
130 ///
131 /// Platform file refers to the path of the module as it is known on
132 /// the remote system on which it is being debugged. For local
133 /// debugging this is always the same as Module::GetFileSpec(). But
134 /// remote debugging might mention a file '/usr/lib/liba.dylib'
135 /// which might be locally downloaded and cached. In this case the
136 /// platform file could be something like:
137 /// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
138 /// The file could also be cached in a local developer kit directory.
139 ///
140 /// @return
141 /// A const reference to the file specification object.
142 //------------------------------------------------------------------
143 ") GetPlatformFileSpec;
144 lldb::SBFileSpec
145 GetPlatformFileSpec () const;
146
147 bool
148 SetPlatformFileSpec (const lldb::SBFileSpec &platform_file);
149
150 %feature("docstring", "Returns the UUID of the module as a Python string."
151 ) GetUUIDString;
152 const char *
153 GetUUIDString () const;
154
Greg Clayton3e8c25f2011-09-24 00:52:29 +0000155 lldb::SBSection
156 FindSection (const char *sect_name);
157
158 lldb::SBAddress
159 ResolveFileAddress (lldb::addr_t vm_addr);
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000160
161 lldb::SBSymbolContext
162 ResolveSymbolContextForAddress (const lldb::SBAddress& addr,
163 uint32_t resolve_scope);
164
165 bool
166 GetDescription (lldb::SBStream &description);
167
168 size_t
169 GetNumSymbols ();
170
171 lldb::SBSymbol
172 GetSymbolAtIndex (size_t idx);
173
Greg Clayton3e8c25f2011-09-24 00:52:29 +0000174 size_t
175 GetNumSections ();
176
177 lldb::SBSection
178 GetSectionAtIndex (size_t idx);
179
180
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000181 %feature("docstring", "
182 //------------------------------------------------------------------
183 /// Find functions by name.
184 ///
185 /// @param[in] name
186 /// The name of the function we are looking for.
187 ///
188 /// @param[in] name_type_mask
189 /// A logical OR of one or more FunctionNameType enum bits that
190 /// indicate what kind of names should be used when doing the
191 /// lookup. Bits include fully qualified names, base names,
192 /// C++ methods, or ObjC selectors.
193 /// See FunctionNameType for more details.
194 ///
Greg Clayton7dd5c512012-02-06 01:44:54 +0000195 /// @return
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000196 /// A symbol context list that gets filled in with all of the
197 /// matches.
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000198 //------------------------------------------------------------------
199 ") FindFunctions;
Greg Clayton7dd5c512012-02-06 01:44:54 +0000200 lldb::SBSymbolContextList
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000201 FindFunctions (const char *name,
Greg Clayton7dd5c512012-02-06 01:44:54 +0000202 uint32_t name_type_mask = lldb::eFunctionNameTypeAny);
Enrico Granata979e20d2011-07-29 19:53:35 +0000203
204 lldb::SBType
205 FindFirstType (const char* name);
206
207 lldb::SBTypeList
208 FindTypes (const char* type);
209
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000210
211 %feature("docstring", "
212 //------------------------------------------------------------------
213 /// Find global and static variables by name.
214 ///
215 /// @param[in] target
216 /// A valid SBTarget instance representing the debuggee.
217 ///
218 /// @param[in] name
219 /// The name of the global or static variable we are looking
220 /// for.
221 ///
222 /// @param[in] max_matches
223 /// Allow the number of matches to be limited to \a max_matches.
224 ///
225 /// @return
226 /// A list of matched variables in an SBValueList.
227 //------------------------------------------------------------------
228 ") FindGlobalVariables;
229 lldb::SBValueList
230 FindGlobalVariables (lldb::SBTarget &target,
231 const char *name,
232 uint32_t max_matches);
Greg Clayton1b925202012-01-29 06:07:39 +0000233
234 lldb::ByteOrder
235 GetByteOrder ();
236
237 uint32_t
238 GetAddressByteSize();
239
240 const char *
241 GetTriple ();
Greg Clayton49f4bf22012-02-22 19:41:02 +0000242
243 uint32_t
244 GetVersion (uint32_t *versions,
245 uint32_t num_versions);
Greg Clayton1b925202012-01-29 06:07:39 +0000246
247 %pythoncode %{
Greg Claytonb302dff2012-02-01 08:09:32 +0000248 class symbols_access(object):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000249 re_compile_type = type(re.compile('.'))
Greg Claytonb302dff2012-02-01 08:09:32 +0000250 '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
251 def __init__(self, sbmodule):
252 self.sbmodule = sbmodule
253
254 def __len__(self):
255 if self.sbmodule:
256 return self.sbmodule.GetNumSymbols()
257 return 0
258
259 def __getitem__(self, key):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000260 count = len(self)
Greg Claytonb302dff2012-02-01 08:09:32 +0000261 if type(key) is int:
262 if key < count:
263 return self.sbmodule.GetSymbolAtIndex(key)
264 elif type(key) is str:
265 matches = []
266 for idx in range(count):
267 symbol = self.sbmodule.GetSymbolAtIndex(idx)
268 if symbol.name == key or symbol.mangled == key:
269 matches.append(symbol)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000270 return matches
271 elif isinstance(key, self.re_compile_type):
Greg Claytonb302dff2012-02-01 08:09:32 +0000272 matches = []
273 for idx in range(count):
274 symbol = self.sbmodule.GetSymbolAtIndex(idx)
275 added = False
276 name = symbol.name
277 if name:
278 re_match = key.search(name)
279 if re_match:
280 matches.append(symbol)
281 added = True
282 if not added:
283 mangled = symbol.mangled
284 if mangled:
285 re_match = key.search(mangled)
286 if re_match:
287 matches.append(symbol)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000288 return matches
Greg Claytonb302dff2012-02-01 08:09:32 +0000289 else:
290 print "error: unsupported item type: %s" % type(key)
291 return None
292
293 def get_symbols_access_object(self):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000294 '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.'''
Greg Claytonb302dff2012-02-01 08:09:32 +0000295 return self.symbols_access (self)
296
297 def get_symbols_array(self):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000298 '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.'''
Greg Claytonb302dff2012-02-01 08:09:32 +0000299 symbols = []
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000300 for idx in range(self.num_symbols):
Greg Claytonb302dff2012-02-01 08:09:32 +0000301 symbols.append(self.GetSymbolAtIndex(idx))
302 return symbols
303
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000304 class sections_access(object):
305 re_compile_type = type(re.compile('.'))
306 '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
307 def __init__(self, sbmodule):
308 self.sbmodule = sbmodule
309
310 def __len__(self):
311 if self.sbmodule:
312 return self.sbmodule.GetNumSections()
313 return 0
314
315 def __getitem__(self, key):
316 count = len(self)
317 if type(key) is int:
318 if key < count:
319 return self.sbmodule.GetSectionAtIndex(key)
320 elif type(key) is str:
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000321 for idx in range(count):
322 section = self.sbmodule.GetSectionAtIndex(idx)
323 if section.name == key:
Greg Clayton39f54ea2012-02-04 02:58:17 +0000324 return section
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000325 elif isinstance(key, self.re_compile_type):
326 matches = []
327 for idx in range(count):
328 section = self.sbmodule.GetSectionAtIndex(idx)
329 name = section.name
330 if name:
331 re_match = key.search(name)
332 if re_match:
333 matches.append(section)
334 return matches
335 else:
336 print "error: unsupported item type: %s" % type(key)
337 return None
338
339 def get_sections_access_object(self):
340 '''An accessor function that returns a sections_access() object which allows lazy section array access.'''
341 return self.sections_access (self)
342
343 def get_sections_array(self):
344 '''An accessor function that returns an array object that contains all sections in this module object.'''
345 if not hasattr(self, 'sections'):
346 self.sections = []
347 for idx in range(self.num_sections):
348 self.sections.append(self.GetSectionAtIndex(idx))
349 return self.sections
350
Greg Claytonb302dff2012-02-01 08:09:32 +0000351 __swig_getmethods__["symbols"] = get_symbols_array
352 if _newclass: x = property(get_symbols_array, None)
353
354 __swig_getmethods__["symbol"] = get_symbols_access_object
355 if _newclass: x = property(get_symbols_access_object, None)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000356
357 __swig_getmethods__["sections"] = get_sections_array
358 if _newclass: x = property(get_sections_array, None)
Greg Claytonb302dff2012-02-01 08:09:32 +0000359
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000360 __swig_getmethods__["section"] = get_sections_access_object
361 if _newclass: x = property(get_sections_access_object, None)
362
Greg Claytonb302dff2012-02-01 08:09:32 +0000363 def get_uuid(self):
364 return uuid.UUID (self.GetUUIDString())
365
366 __swig_getmethods__["uuid"] = get_uuid
367 if _newclass: x = property(get_uuid, None)
368
Greg Clayton1b925202012-01-29 06:07:39 +0000369 __swig_getmethods__["file"] = GetFileSpec
370 if _newclass: x = property(GetFileSpec, None)
371
372 __swig_getmethods__["platform_file"] = GetPlatformFileSpec
373 if _newclass: x = property(GetPlatformFileSpec, None)
374
Greg Clayton1b925202012-01-29 06:07:39 +0000375 __swig_getmethods__["byte_order"] = GetByteOrder
376 if _newclass: x = property(GetByteOrder, None)
377
378 __swig_getmethods__["addr_size"] = GetAddressByteSize
379 if _newclass: x = property(GetAddressByteSize, None)
380
381 __swig_getmethods__["triple"] = GetTriple
382 if _newclass: x = property(GetTriple, None)
383
384 __swig_getmethods__["num_symbols"] = GetNumSymbols
385 if _newclass: x = property(GetNumSymbols, None)
386
387 __swig_getmethods__["num_sections"] = GetNumSections
388 if _newclass: x = property(GetNumSections, None)
389
390 %}
391
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000392};
393
394} // namespace lldb