blob: 44d3a86d6672885e80e7a5903beae37c2cce479d [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 ();
242
243 %pythoncode %{
Greg Claytonb302dff2012-02-01 08:09:32 +0000244 class symbols_access(object):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000245 re_compile_type = type(re.compile('.'))
Greg Claytonb302dff2012-02-01 08:09:32 +0000246 '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
247 def __init__(self, sbmodule):
248 self.sbmodule = sbmodule
249
250 def __len__(self):
251 if self.sbmodule:
252 return self.sbmodule.GetNumSymbols()
253 return 0
254
255 def __getitem__(self, key):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000256 count = len(self)
Greg Claytonb302dff2012-02-01 08:09:32 +0000257 if type(key) is int:
258 if key < count:
259 return self.sbmodule.GetSymbolAtIndex(key)
260 elif type(key) is str:
261 matches = []
262 for idx in range(count):
263 symbol = self.sbmodule.GetSymbolAtIndex(idx)
264 if symbol.name == key or symbol.mangled == key:
265 matches.append(symbol)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000266 return matches
267 elif isinstance(key, self.re_compile_type):
Greg Claytonb302dff2012-02-01 08:09:32 +0000268 matches = []
269 for idx in range(count):
270 symbol = self.sbmodule.GetSymbolAtIndex(idx)
271 added = False
272 name = symbol.name
273 if name:
274 re_match = key.search(name)
275 if re_match:
276 matches.append(symbol)
277 added = True
278 if not added:
279 mangled = symbol.mangled
280 if mangled:
281 re_match = key.search(mangled)
282 if re_match:
283 matches.append(symbol)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000284 return matches
Greg Claytonb302dff2012-02-01 08:09:32 +0000285 else:
286 print "error: unsupported item type: %s" % type(key)
287 return None
288
289 def get_symbols_access_object(self):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000290 '''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 +0000291 return self.symbols_access (self)
292
293 def get_symbols_array(self):
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000294 '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.'''
Greg Claytonb302dff2012-02-01 08:09:32 +0000295 symbols = []
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000296 for idx in range(self.num_symbols):
Greg Claytonb302dff2012-02-01 08:09:32 +0000297 symbols.append(self.GetSymbolAtIndex(idx))
298 return symbols
299
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000300 class sections_access(object):
301 re_compile_type = type(re.compile('.'))
302 '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.'''
303 def __init__(self, sbmodule):
304 self.sbmodule = sbmodule
305
306 def __len__(self):
307 if self.sbmodule:
308 return self.sbmodule.GetNumSections()
309 return 0
310
311 def __getitem__(self, key):
312 count = len(self)
313 if type(key) is int:
314 if key < count:
315 return self.sbmodule.GetSectionAtIndex(key)
316 elif type(key) is str:
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000317 for idx in range(count):
318 section = self.sbmodule.GetSectionAtIndex(idx)
319 if section.name == key:
Greg Clayton39f54ea2012-02-04 02:58:17 +0000320 return section
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000321 elif isinstance(key, self.re_compile_type):
322 matches = []
323 for idx in range(count):
324 section = self.sbmodule.GetSectionAtIndex(idx)
325 name = section.name
326 if name:
327 re_match = key.search(name)
328 if re_match:
329 matches.append(section)
330 return matches
331 else:
332 print "error: unsupported item type: %s" % type(key)
333 return None
334
335 def get_sections_access_object(self):
336 '''An accessor function that returns a sections_access() object which allows lazy section array access.'''
337 return self.sections_access (self)
338
339 def get_sections_array(self):
340 '''An accessor function that returns an array object that contains all sections in this module object.'''
341 if not hasattr(self, 'sections'):
342 self.sections = []
343 for idx in range(self.num_sections):
344 self.sections.append(self.GetSectionAtIndex(idx))
345 return self.sections
346
Greg Claytonb302dff2012-02-01 08:09:32 +0000347 __swig_getmethods__["symbols"] = get_symbols_array
348 if _newclass: x = property(get_symbols_array, None)
349
350 __swig_getmethods__["symbol"] = get_symbols_access_object
351 if _newclass: x = property(get_symbols_access_object, None)
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000352
353 __swig_getmethods__["sections"] = get_sections_array
354 if _newclass: x = property(get_sections_array, None)
Greg Claytonb302dff2012-02-01 08:09:32 +0000355
Greg Claytonb6a5ba62012-02-03 03:22:53 +0000356 __swig_getmethods__["section"] = get_sections_access_object
357 if _newclass: x = property(get_sections_access_object, None)
358
Greg Claytonb302dff2012-02-01 08:09:32 +0000359 def get_uuid(self):
360 return uuid.UUID (self.GetUUIDString())
361
362 __swig_getmethods__["uuid"] = get_uuid
363 if _newclass: x = property(get_uuid, None)
364
Greg Clayton1b925202012-01-29 06:07:39 +0000365 __swig_getmethods__["file"] = GetFileSpec
366 if _newclass: x = property(GetFileSpec, None)
367
368 __swig_getmethods__["platform_file"] = GetPlatformFileSpec
369 if _newclass: x = property(GetPlatformFileSpec, None)
370
Greg Clayton1b925202012-01-29 06:07:39 +0000371 __swig_getmethods__["byte_order"] = GetByteOrder
372 if _newclass: x = property(GetByteOrder, None)
373
374 __swig_getmethods__["addr_size"] = GetAddressByteSize
375 if _newclass: x = property(GetAddressByteSize, None)
376
377 __swig_getmethods__["triple"] = GetTriple
378 if _newclass: x = property(GetTriple, None)
379
380 __swig_getmethods__["num_symbols"] = GetNumSymbols
381 if _newclass: x = property(GetNumSymbols, None)
382
383 __swig_getmethods__["num_sections"] = GetNumSections
384 if _newclass: x = property(GetNumSections, None)
385
386 %}
387
Johnny Chenfb35e2a2011-07-18 23:11:07 +0000388};
389
390} // namespace lldb