Debian Codegraph @

Tools/gdb/libpython.py

raw
1 #!/usr/bin/python
2 '''
3 From gdb 7 onwards, gdb's build can be configured --with-python, allowing gdb
4 to be extended with Python code e.g. for library-specific data visualizations,
5 such as for the C++ STL types. Documentation on this API can be seen at:
6 http://sourceware.org/gdb/current/onlinedocs/gdb/Python-API.html
7
8
9 This python module deals with the case when the process being debugged (the
10 "inferior process" in gdb parlance) is itself python, or more specifically,
11 linked against libpython. In this situation, almost every item of data is a
12 (PyObject*), and having the debugger merely print their addresses is not very
13 enlightening.
14
15 This module embeds knowledge about the implementation details of libpython so
16 that we can emit useful visualizations e.g. a string, a list, a dict, a frame
17 giving file/line information and the state of local variables
18
19 In particular, given a gdb.Value corresponding to a PyObject* in the inferior
20 process, we can generate a "proxy value" within the gdb process. For example,
21 given a PyObject* in the inferior process that is in fact a PyListObject*
22 holding three PyObject* that turn out to be PyBytesObject* instances, we can
23 generate a proxy value within the gdb process that is a list of bytes
24 instances:
25 [b"foo", b"bar", b"baz"]
26
27 Doing so can be expensive for complicated graphs of objects, and could take
28 some time, so we also have a "write_repr" method that writes a representation
29 of the data to a file-like object. This allows us to stop the traversal by
30 having the file-like object raise an exception if it gets too much data.
31
32 With both "proxyval" and "write_repr" we keep track of the set of all addresses
33 visited so far in the traversal, to avoid infinite recursion due to cycles in
34 the graph of object references.
35
36 We try to defer gdb.lookup_type() invocations for python types until as late as
37 possible: for a dynamically linked python binary, when the process starts in
38 the debugger, the libpython.so hasn't been dynamically loaded yet, so none of
39 the type names are known to the debugger
40
41 The module also extends gdb with some python-specific commands.
42 '''
43
44 import gdb
45 import os
46 import sys
47
48
49 # Look up the gdb.Type for some standard types:
50 # Those need to be refreshed as types (pointer sizes) may change when
51 # gdb loads different executables
52
53 def _type_char_ptr():
54 return gdb.lookup_type('char').pointer() # char*
55
56
57 def _type_unsigned_char_ptr():
58 return gdb.lookup_type('unsigned char').pointer() # unsigned char*
59
60
61 def _type_unsigned_short_ptr():
62 return gdb.lookup_type('unsigned short').pointer()
63
64
65 def _type_unsigned_int_ptr():
66 return gdb.lookup_type('unsigned int').pointer()
67
68 def _sizeof_void_p():
69 return gdb.lookup_type('void').pointer().sizeof
70
71 def _sizeof_pyobject():
72 return gdb.lookup_type('PyObject').sizeof
73
74 def _managed_dict_offset():
75 # See pycore_object.h
76 pyobj = gdb.lookup_type("PyObject")
77 if any(field.name == "ob_ref_local" for field in pyobj.fields()):
78 return -1 * _sizeof_void_p()
79 else:
80 return -3 * _sizeof_void_p()
81
82
83 Py_TPFLAGS_INLINE_VALUES = (1 << 2)
84 Py_TPFLAGS_MANAGED_DICT = (1 << 4)
85 Py_TPFLAGS_HEAPTYPE = (1 << 9)
86 Py_TPFLAGS_LONG_SUBCLASS = (1 << 24)
87 Py_TPFLAGS_LIST_SUBCLASS = (1 << 25)
88 Py_TPFLAGS_TUPLE_SUBCLASS = (1 << 26)
89 Py_TPFLAGS_BYTES_SUBCLASS = (1 << 27)
90 Py_TPFLAGS_UNICODE_SUBCLASS = (1 << 28)
91 Py_TPFLAGS_DICT_SUBCLASS = (1 << 29)
92 Py_TPFLAGS_BASE_EXC_SUBCLASS = (1 << 30)
93 Py_TPFLAGS_TYPE_SUBCLASS = (1 << 31)
94
95 #From pycore_frame.h
96 FRAME_OWNED_BY_CSTACK = 3
97
98 MAX_OUTPUT_LEN=1024
99
100 hexdigits = "0123456789abcdef"
101
102 FRAME_INFO_OPTIMIZED_OUT = '(frame information optimized out)'
103 UNABLE_READ_INFO_PYTHON_FRAME = 'Unable to read information on python frame'
104 EVALFRAME = '_PyEval_EvalFrameDefault'
105
106 class NullPyObjectPtr(RuntimeError):
107 pass
108
109
110 def safety_limit(val):
111 # Given an integer value from the process being debugged, limit it to some
112 # safety threshold so that arbitrary breakage within said process doesn't
113 # break the gdb process too much (e.g. sizes of iterations, sizes of lists)
114 return min(val, 1000)
115
116
117 def safe_range(val):
118 # As per range, but don't trust the value too much: cap it to a safety
119 # threshold in case the data was corrupted
120 return range(safety_limit(int(val)))
121
122 class StringTruncated(RuntimeError):
123 pass
124
125 class TruncatedStringIO(object):
126 '''Similar to io.StringIO, but can truncate the output by raising a
127 StringTruncated exception'''
128 def __init__(self, maxlen=None):
129 self._val = ''
130 self.maxlen = maxlen
131
132 def write(self, data):
133 if self.maxlen:
134 if len(data) + len(self._val) > self.maxlen:
135 # Truncation:
136 self._val += data[0:self.maxlen - len(self._val)]
137 raise StringTruncated()
138
139 self._val += data
140
141 def getvalue(self):
142 return self._val
143
144
145 class PyObjectPtr(object):
146 """
147 Class wrapping a gdb.Value that's either a (PyObject*) within the
148 inferior process, or some subclass pointer e.g. (PyBytesObject*)
149
150 There will be a subclass for every refined PyObject type that we care
151 about.
152
153 Note that at every stage the underlying pointer could be NULL, point
154 to corrupt data, etc; this is the debugger, after all.
155 """
156 _typename = 'PyObject'
157
158 def __init__(self, gdbval, cast_to=None):
159 if cast_to:
160 self._gdbval = gdbval.cast(cast_to)
161 else:
162 self._gdbval = gdbval
163
164 def field(self, name):
165 '''
166 Get the gdb.Value for the given field within the PyObject.
167
168 Various libpython types are defined using the "PyObject_HEAD" and
169 "PyObject_VAR_HEAD" macros.
170
171 In Python, this is defined as an embedded PyVarObject type thus:
172 PyVarObject ob_base;
173 so that the "ob_size" field is located insize the "ob_base" field, and
174 the "ob_type" is most easily accessed by casting back to a (PyObject*).
175 '''
176 if self.is_null():
177 raise NullPyObjectPtr(self)
178
179 if name == 'ob_type':
180 pyo_ptr = self._gdbval.cast(PyObjectPtr.get_gdb_type())
181 return pyo_ptr.dereference()[name]
182
183 if name == 'ob_size':
184 pyo_ptr = self._gdbval.cast(PyVarObjectPtr.get_gdb_type())
185 return pyo_ptr.dereference()[name]
186
187 # General case: look it up inside the object:
188 return self._gdbval.dereference()[name]
189
190 def pyop_field(self, name):
191 '''
192 Get a PyObjectPtr for the given PyObject* field within this PyObject.
193 '''
194 return PyObjectPtr.from_pyobject_ptr(self.field(name))
195
196 def write_field_repr(self, name, out, visited):
197 '''
198 Extract the PyObject* field named "name", and write its representation
199 to file-like object "out"
200 '''
201 field_obj = self.pyop_field(name)
202 field_obj.write_repr(out, visited)
203
204 def get_truncated_repr(self, maxlen):
205 '''
206 Get a repr-like string for the data, but truncate it at "maxlen" bytes
207 (ending the object graph traversal as soon as you do)
208 '''
209 out = TruncatedStringIO(maxlen)
210 try:
211 self.write_repr(out, set())
212 except StringTruncated:
213 # Truncation occurred:
214 return out.getvalue() + '...(truncated)'
215
216 # No truncation occurred:
217 return out.getvalue()
218
219 def type(self):
220 return PyTypeObjectPtr(self.field('ob_type'))
221
222 def is_null(self):
223 return 0 == int(self._gdbval)
224
225 def is_optimized_out(self):
226 '''
227 Is the value of the underlying PyObject* visible to the debugger?
228
229 This can vary with the precise version of the compiler used to build
230 Python, and the precise version of gdb.
231
232 See e.g. https://bugzilla.redhat.com/show_bug.cgi?id=556975 with
233 PyEval_EvalFrameEx's "f"
234 '''
235 return self._gdbval.is_optimized_out
236
237 def safe_tp_name(self):
238 try:
239 ob_type = self.type()
240 tp_name = ob_type.field('tp_name')
241 return tp_name.string()
242 # NullPyObjectPtr: NULL tp_name?
243 # RuntimeError: Can't even read the object at all?
244 # UnicodeDecodeError: Failed to decode tp_name bytestring
245 except (NullPyObjectPtr, RuntimeError, UnicodeDecodeError):
246 return 'unknown'
247
248 def proxyval(self, visited):
249 '''
250 Scrape a value from the inferior process, and try to represent it
251 within the gdb process, whilst (hopefully) avoiding crashes when
252 the remote data is corrupt.
253
254 Derived classes will override this.
255
256 For example, a PyLongObjectPtr* with long_value 42 in the inferior process
257 should result in an int(42) in this process.
258
259 visited: a set of all gdb.Value pyobject pointers already visited
260 whilst generating this value (to guard against infinite recursion when
261 visiting object graphs with loops). Analogous to Py_ReprEnter and
262 Py_ReprLeave
263 '''
264
265 class FakeRepr(object):
266 """
267 Class representing a non-descript PyObject* value in the inferior
268 process for when we don't have a custom scraper, intended to have
269 a sane repr().
270 """
271
272 def __init__(self, tp_name, address):
273 self.tp_name = tp_name
274 self.address = address
275
276 def __repr__(self):
277 # For the NULL pointer, we have no way of knowing a type, so
278 # special-case it as per
279 # http://bugs.python.org/issue8032#msg100882
280 if self.address == 0:
281 return '0x0'
282 return '<%s at remote 0x%x>' % (self.tp_name, self.address)
283
284 return FakeRepr(self.safe_tp_name(),
285 int(self._gdbval))
286
287 def write_repr(self, out, visited):
288 '''
289 Write a string representation of the value scraped from the inferior
290 process to "out", a file-like object.
291 '''
292 # Default implementation: generate a proxy value and write its repr
293 # However, this could involve a lot of work for complicated objects,
294 # so for derived classes we specialize this
295 return out.write(repr(self.proxyval(visited)))
296
297 @classmethod
298 def subclass_from_type(cls, t):
299 '''
300 Given a PyTypeObjectPtr instance wrapping a gdb.Value that's a
301 (PyTypeObject*), determine the corresponding subclass of PyObjectPtr
302 to use
303
304 Ideally, we would look up the symbols for the global types, but that
305 isn't working yet:
306 (gdb) python print gdb.lookup_symbol('PyList_Type')[0].value
307 Traceback (most recent call last):
308 File "<string>", line 1, in <module>
309 NotImplementedError: Symbol type not yet supported in Python scripts.
310 Error while executing Python code.
311
312 For now, we use tp_flags, after doing some string comparisons on the
313 tp_name for some special-cases that don't seem to be visible through
314 flags
315 '''
316 try:
317 tp_name = t.field('tp_name').string()
318 tp_flags = int(t.field('tp_flags'))
319 # RuntimeError: NULL pointers
320 # UnicodeDecodeError: string() fails to decode the bytestring
321 except (RuntimeError, UnicodeDecodeError):
322 # Handle any kind of error e.g. NULL ptrs by simply using the base
323 # class
324 return cls
325
326 #print('tp_flags = 0x%08x' % tp_flags)
327 #print('tp_name = %r' % tp_name)
328
329 name_map = {'bool': PyBoolObjectPtr,
330 'classobj': PyClassObjectPtr,
331 'NoneType': PyNoneStructPtr,
332 'frame': PyFrameObjectPtr,
333 'set' : PySetObjectPtr,
334 'frozenset' : PySetObjectPtr,
335 'builtin_function_or_method' : PyCFunctionObjectPtr,
336 'method-wrapper': wrapperobject,
337 }
338 if tp_name in name_map:
339 return name_map[tp_name]
340
341 if tp_flags & Py_TPFLAGS_HEAPTYPE:
342 return HeapTypeObjectPtr
343
344 if tp_flags & Py_TPFLAGS_LONG_SUBCLASS:
345 return PyLongObjectPtr
346 if tp_flags & Py_TPFLAGS_LIST_SUBCLASS:
347 return PyListObjectPtr
348 if tp_flags & Py_TPFLAGS_TUPLE_SUBCLASS:
349 return PyTupleObjectPtr
350 if tp_flags & Py_TPFLAGS_BYTES_SUBCLASS:
351 return PyBytesObjectPtr
352 if tp_flags & Py_TPFLAGS_UNICODE_SUBCLASS:
353 return PyUnicodeObjectPtr
354 if tp_flags & Py_TPFLAGS_DICT_SUBCLASS:
355 return PyDictObjectPtr
356 if tp_flags & Py_TPFLAGS_BASE_EXC_SUBCLASS:
357 return PyBaseExceptionObjectPtr
358 #if tp_flags & Py_TPFLAGS_TYPE_SUBCLASS:
359 # return PyTypeObjectPtr
360
361 # Use the base class:
362 return cls
363
364 @classmethod
365 def from_pyobject_ptr(cls, gdbval):
366 '''
367 Try to locate the appropriate derived class dynamically, and cast
368 the pointer accordingly.
369 '''
370 try:
371 p = PyObjectPtr(gdbval)
372 cls = cls.subclass_from_type(p.type())
373 return cls(gdbval, cast_to=cls.get_gdb_type())
374 except RuntimeError:
375 # Handle any kind of error e.g. NULL ptrs by simply using the base
376 # class
377 pass
378 return cls(gdbval)
379
380 @classmethod
381 def get_gdb_type(cls):
382 return gdb.lookup_type(cls._typename).pointer()
383
384 def as_address(self):
385 return int(self._gdbval)
386
387 class PyVarObjectPtr(PyObjectPtr):
388 _typename = 'PyVarObject'
389
390 class ProxyAlreadyVisited(object):
391 '''
392 Placeholder proxy to use when protecting against infinite recursion due to
393 loops in the object graph.
394
395 Analogous to the values emitted by the users of Py_ReprEnter and Py_ReprLeave
396 '''
397 def __init__(self, rep):
398 self._rep = rep
399
400 def __repr__(self):
401 return self._rep
402
403
404 def _write_instance_repr(out, visited, name, pyop_attrdict, address):
405 '''Shared code for use by all classes:
406 write a representation to file-like object "out"'''
407 out.write('<')
408 out.write(name)
409
410 # Write dictionary of instance attributes:
411 if isinstance(pyop_attrdict, (PyKeysValuesPair, PyDictObjectPtr)):
412 out.write('(')
413 first = True
414 items = pyop_attrdict.iteritems()
415 for pyop_arg, pyop_val in items:
416 if not first:
417 out.write(', ')
418 first = False
419 out.write(pyop_arg.proxyval(visited))
420 out.write('=')
421 pyop_val.write_repr(out, visited)
422 out.write(')')
423 out.write(' at remote 0x%x>' % address)
424
425
426 class InstanceProxy(object):
427
428 def __init__(self, cl_name, attrdict, address):
429 self.cl_name = cl_name
430 self.attrdict = attrdict
431 self.address = address
432
433 def __repr__(self):
434 if isinstance(self.attrdict, dict):
435 kwargs = ', '.join(["%s=%r" % (arg, val)
436 for arg, val in self.attrdict.items()])
437 return '<%s(%s) at remote 0x%x>' % (self.cl_name,
438 kwargs, self.address)
439 else:
440 return '<%s at remote 0x%x>' % (self.cl_name,
441 self.address)
442
443 def _PyObject_VAR_SIZE(typeobj, nitems):
444 if _PyObject_VAR_SIZE._type_size_t is None:
445 _PyObject_VAR_SIZE._type_size_t = gdb.lookup_type('size_t')
446
447 return ( ( typeobj.field('tp_basicsize') +
448 nitems * typeobj.field('tp_itemsize') +
449 (_sizeof_void_p() - 1)
450 ) & ~(_sizeof_void_p() - 1)
451 ).cast(_PyObject_VAR_SIZE._type_size_t)
452 _PyObject_VAR_SIZE._type_size_t = None
453
454 class HeapTypeObjectPtr(PyObjectPtr):
455 _typename = 'PyObject'
456
457 def get_attr_dict(self):
458 '''
459 Get the PyDictObject ptr representing the attribute dictionary
460 (or None if there's a problem)
461 '''
462 try:
463 typeobj = self.type()
464 dictoffset = int_from_int(typeobj.field('tp_dictoffset'))
465 if dictoffset != 0:
466 if dictoffset < 0:
467 if int_from_int(typeobj.field('tp_flags')) & Py_TPFLAGS_MANAGED_DICT:
468 assert dictoffset == -1
469 dictoffset = _managed_dict_offset()
470 else:
471 type_PyVarObject_ptr = gdb.lookup_type('PyVarObject').pointer()
472 tsize = int_from_int(self._gdbval.cast(type_PyVarObject_ptr)['ob_size'])
473 if tsize < 0:
474 tsize = -tsize
475 size = _PyObject_VAR_SIZE(typeobj, tsize)
476 dictoffset += size
477 assert dictoffset % _sizeof_void_p() == 0
478
479 dictptr = self._gdbval.cast(_type_char_ptr()) + dictoffset
480 PyObjectPtrPtr = PyObjectPtr.get_gdb_type().pointer()
481 dictptr = dictptr.cast(PyObjectPtrPtr)
482 if int(dictptr.dereference()) & 1:
483 return None
484 return PyObjectPtr.from_pyobject_ptr(dictptr.dereference())
485 except RuntimeError:
486 # Corrupt data somewhere; fail safe
487 pass
488
489 # Not found, or some kind of error:
490 return None
491
492 def get_keys_values(self):
493 typeobj = self.type()
494 has_values = int_from_int(typeobj.field('tp_flags')) & Py_TPFLAGS_MANAGED_DICT
495 if not has_values:
496 return None
497 obj_ptr = self._gdbval.cast(_type_char_ptr())
498 dict_ptr_ptr = obj_ptr + _managed_dict_offset()
499 dict_ptr = dict_ptr_ptr.cast(_type_char_ptr().pointer()).dereference()
500 if int(dict_ptr):
501 return None
502 char_ptr = obj_ptr + _sizeof_pyobject()
503 values_ptr = char_ptr.cast(gdb.lookup_type("PyDictValues").pointer())
504 values = values_ptr['values']
505 return PyKeysValuesPair(self.get_cached_keys(), values)
506
507 def get_cached_keys(self):
508 typeobj = self.type()
509 HeapTypePtr = gdb.lookup_type("PyHeapTypeObject").pointer()
510 return typeobj._gdbval.cast(HeapTypePtr)['ht_cached_keys']
511
512 def proxyval(self, visited):
513 '''
514 Support for classes.
515
516 Currently we just locate the dictionary using a transliteration to
517 python of _PyObject_GetDictPtr, ignoring descriptors
518 '''
519 # Guard against infinite loops:
520 if self.as_address() in visited:
521 return ProxyAlreadyVisited('<...>')
522 visited.add(self.as_address())
523
524 keys_values = self.get_keys_values()
525 if keys_values:
526 attr_dict = keys_values.proxyval(visited)
527 else:
528 pyop_attr_dict = self.get_attr_dict()
529 if pyop_attr_dict:
530 attr_dict = pyop_attr_dict.proxyval(visited)
531 else:
532 attr_dict = {}
533 tp_name = self.safe_tp_name()
534
535 # Class:
536 return InstanceProxy(tp_name, attr_dict, int(self._gdbval))
537
538 def write_repr(self, out, visited):
539 # Guard against infinite loops:
540 if self.as_address() in visited:
541 out.write('<...>')
542 return
543 visited.add(self.as_address())
544
545 pyop_attrs = self.get_keys_values()
546 if not pyop_attrs:
547 pyop_attrs = self.get_attr_dict()
548 _write_instance_repr(out, visited,
549 self.safe_tp_name(), pyop_attrs, self.as_address())
550
551 class ProxyException(Exception):
552 def __init__(self, tp_name, args):
553 self.tp_name = tp_name
554 self.args = args
555
556 def __repr__(self):
557 return '%s%r' % (self.tp_name, self.args)
558
559 class PyBaseExceptionObjectPtr(PyObjectPtr):
560 """
561 Class wrapping a gdb.Value that's a PyBaseExceptionObject* i.e. an exception
562 within the process being debugged.
563 """
564 _typename = 'PyBaseExceptionObject'
565
566 def proxyval(self, visited):
567 # Guard against infinite loops:
568 if self.as_address() in visited:
569 return ProxyAlreadyVisited('(...)')
570 visited.add(self.as_address())
571 arg_proxy = self.pyop_field('args').proxyval(visited)
572 return ProxyException(self.safe_tp_name(),
573 arg_proxy)
574
575 def write_repr(self, out, visited):
576 # Guard against infinite loops:
577 if self.as_address() in visited:
578 out.write('(...)')
579 return
580 visited.add(self.as_address())
581
582 out.write(self.safe_tp_name())
583 self.write_field_repr('args', out, visited)
584
585 class PyClassObjectPtr(PyObjectPtr):
586 """
587 Class wrapping a gdb.Value that's a PyClassObject* i.e. a <classobj>
588 instance within the process being debugged.
589 """
590 _typename = 'PyClassObject'
591
592
593 class BuiltInFunctionProxy(object):
594 def __init__(self, ml_name):
595 self.ml_name = ml_name
596
597 def __repr__(self):
598 return "<built-in function %s>" % self.ml_name
599
600 class BuiltInMethodProxy(object):
601 def __init__(self, ml_name, pyop_m_self):
602 self.ml_name = ml_name
603 self.pyop_m_self = pyop_m_self
604
605 def __repr__(self):
606 return ('<built-in method %s of %s object at remote 0x%x>'
607 % (self.ml_name,
608 self.pyop_m_self.safe_tp_name(),
609 self.pyop_m_self.as_address())
610 )
611
612 class PyCFunctionObjectPtr(PyObjectPtr):
613 """
614 Class wrapping a gdb.Value that's a PyCFunctionObject*
615 (see Include/methodobject.h and Objects/methodobject.c)
616 """
617 _typename = 'PyCFunctionObject'
618
619 def proxyval(self, visited):
620 m_ml = self.field('m_ml') # m_ml is a (PyMethodDef*)
621 try:
622 ml_name = m_ml['ml_name'].string()
623 except UnicodeDecodeError:
624 ml_name = '<ml_name:UnicodeDecodeError>'
625
626 pyop_m_self = self.pyop_field('m_self')
627 if pyop_m_self.is_null():
628 return BuiltInFunctionProxy(ml_name)
629 else:
630 return BuiltInMethodProxy(ml_name, pyop_m_self)
631
632 # Python implementation of location table parsing algorithm
633 def read(it):
634 return ord(next(it))
635
636 def read_varint(it):
637 b = read(it)
638 val = b & 63;
639 shift = 0;
640 while b & 64:
641 b = read(it)
642 shift += 6
643 val |= (b&63) << shift
644 return val
645
646 def read_signed_varint(it):
647 uval = read_varint(it)
648 if uval & 1:
649 return -(uval >> 1)
650 else:
651 return uval >> 1
652
653 def parse_location_table(firstlineno, linetable):
654 line = firstlineno
655 addr = 0
656 it = iter(linetable)
657 while True:
658 try:
659 first_byte = read(it)
660 except StopIteration:
661 return
662 code = (first_byte >> 3) & 15
663 length = (first_byte & 7) + 1
664 end_addr = addr + length
665 if code == 15:
666 yield addr, end_addr, None
667 addr = end_addr
668 continue
669 elif code == 14: # Long form
670 line_delta = read_signed_varint(it)
671 line += line_delta
672 end_line = line + read_varint(it)
673 col = read_varint(it)
674 end_col = read_varint(it)
675 elif code == 13: # No column
676 line_delta = read_signed_varint(it)
677 line += line_delta
678 elif code in (10, 11, 12): # new line
679 line_delta = code - 10
680 line += line_delta
681 column = read(it)
682 end_column = read(it)
683 else:
684 assert (0 <= code < 10)
685 second_byte = read(it)
686 column = code << 3 | (second_byte >> 4)
687 yield addr, end_addr, line
688 addr = end_addr
689
690 class PyCodeObjectPtr(PyObjectPtr):
691 """
692 Class wrapping a gdb.Value that's a PyCodeObject* i.e. a <code> instance
693 within the process being debugged.
694 """
695 _typename = 'PyCodeObject'
696
697 def addr2line(self, addrq):
698 '''
699 Get the line number for a given bytecode offset
700
701 Analogous to PyCode_Addr2Line; translated from pseudocode in
702 Objects/lnotab_notes.txt
703 '''
704 co_linetable = self.pyop_field('co_linetable').proxyval(set())
705
706 # Initialize lineno to co_firstlineno as per PyCode_Addr2Line
707 # not 0, as lnotab_notes.txt has it:
708 lineno = int_from_int(self.field('co_firstlineno'))
709
710 if addrq < 0:
711 return lineno
712 addr = 0
713 for addr, end_addr, line in parse_location_table(lineno, co_linetable):
714 if addr <= addrq and end_addr > addrq:
715 return line
716 assert False, "Unreachable"
717
718
719 def items_from_keys_and_values(keys, values):
720 entries, nentries = PyDictObjectPtr._get_entries(keys)
721 for i in safe_range(nentries):
722 ep = entries[i]
723 pyop_value = PyObjectPtr.from_pyobject_ptr(values[i])
724 if not pyop_value.is_null():
725 pyop_key = PyObjectPtr.from_pyobject_ptr(ep['me_key'])
726 yield (pyop_key, pyop_value)
727
728 class PyKeysValuesPair:
729
730 def __init__(self, keys, values):
731 self.keys = keys
732 self.values = values
733
734 def iteritems(self):
735 return items_from_keys_and_values(self.keys, self.values)
736
737 def proxyval(self, visited):
738 result = {}
739 for pyop_key, pyop_value in self.iteritems():
740 proxy_key = pyop_key.proxyval(visited)
741 proxy_value = pyop_value.proxyval(visited)
742 result[proxy_key] = proxy_value
743 return result
744
745 class PyDictObjectPtr(PyObjectPtr):
746 """
747 Class wrapping a gdb.Value that's a PyDictObject* i.e. a dict instance
748 within the process being debugged.
749 """
750 _typename = 'PyDictObject'
751
752 def iteritems(self):
753 '''
754 Yields a sequence of (PyObjectPtr key, PyObjectPtr value) pairs,
755 analogous to dict.iteritems()
756 '''
757 keys = self.field('ma_keys')
758 values = self.field('ma_values')
759 has_values = int(values)
760 if has_values:
761 values = values['values']
762 if has_values:
763 for item in items_from_keys_and_values(keys, values):
764 yield item
765 return
766 entries, nentries = self._get_entries(keys)
767 for i in safe_range(nentries):
768 ep = entries[i]
769 pyop_value = PyObjectPtr.from_pyobject_ptr(ep['me_value'])
770 if not pyop_value.is_null():
771 pyop_key = PyObjectPtr.from_pyobject_ptr(ep['me_key'])
772 yield (pyop_key, pyop_value)
773
774 def proxyval(self, visited):
775 # Guard against infinite loops:
776 if self.as_address() in visited:
777 return ProxyAlreadyVisited('{...}')
778 visited.add(self.as_address())
779
780 result = {}
781 for pyop_key, pyop_value in self.iteritems():
782 proxy_key = pyop_key.proxyval(visited)
783 proxy_value = pyop_value.proxyval(visited)
784 result[proxy_key] = proxy_value
785 return result
786
787 def write_repr(self, out, visited):
788 # Guard against infinite loops:
789 if self.as_address() in visited:
790 out.write('{...}')
791 return
792 visited.add(self.as_address())
793
794 out.write('{')
795 first = True
796 for pyop_key, pyop_value in self.iteritems():
797 if not first:
798 out.write(', ')
799 first = False
800 pyop_key.write_repr(out, visited)
801 out.write(': ')
802 pyop_value.write_repr(out, visited)
803 out.write('}')
804
805 @staticmethod
806 def _get_entries(keys):
807 dk_nentries = int(keys['dk_nentries'])
808 dk_size = 1<<int(keys['dk_log2_size'])
809
810 if dk_size <= 0xFF:
811 offset = dk_size
812 elif dk_size <= 0xFFFF:
813 offset = 2 * dk_size
814 elif dk_size <= 0xFFFFFFFF:
815 offset = 4 * dk_size
816 else:
817 offset = 8 * dk_size
818
819 ent_addr = keys['dk_indices'].address
820 ent_addr = ent_addr.cast(_type_unsigned_char_ptr()) + offset
821 if int(keys['dk_kind']) == 0: # DICT_KEYS_GENERAL
822 ent_ptr_t = gdb.lookup_type('PyDictKeyEntry').pointer()
823 else:
824 ent_ptr_t = gdb.lookup_type('PyDictUnicodeEntry').pointer()
825 ent_addr = ent_addr.cast(ent_ptr_t)
826
827 return ent_addr, dk_nentries
828
829
830 class PyListObjectPtr(PyObjectPtr):
831 _typename = 'PyListObject'
832
833 def __getitem__(self, i):
834 # Get the gdb.Value for the (PyObject*) with the given index:
835 field_ob_item = self.field('ob_item')
836 return field_ob_item[i]
837
838 def proxyval(self, visited):
839 # Guard against infinite loops:
840 if self.as_address() in visited:
841 return ProxyAlreadyVisited('[...]')
842 visited.add(self.as_address())
843
844 result = [PyObjectPtr.from_pyobject_ptr(self[i]).proxyval(visited)
845 for i in safe_range(int_from_int(self.field('ob_size')))]
846 return result
847
848 def write_repr(self, out, visited):
849 # Guard against infinite loops:
850 if self.as_address() in visited:
851 out.write('[...]')
852 return
853 visited.add(self.as_address())
854
855 out.write('[')
856 for i in safe_range(int_from_int(self.field('ob_size'))):
857 if i > 0:
858 out.write(', ')
859 element = PyObjectPtr.from_pyobject_ptr(self[i])
860 element.write_repr(out, visited)
861 out.write(']')
862
863 class PyLongObjectPtr(PyObjectPtr):
864 _typename = 'PyLongObject'
865
866 def proxyval(self, visited):
867 '''
868 Python's Include/longinterpr.h has this declaration:
869
870 typedef struct _PyLongValue {
871 uintptr_t lv_tag; /* Number of digits, sign and flags */
872 digit ob_digit[1];
873 } _PyLongValue;
874
875 struct _longobject {
876 PyObject_HEAD
877 _PyLongValue long_value;
878 };
879
880 with this description:
881 The absolute value of a number is equal to
882 SUM(for i=0 through ndigits-1) ob_digit[i] * 2**(PyLong_SHIFT*i)
883 The sign of the value is stored in the lower 2 bits of lv_tag.
884 - 0: Positive
885 - 1: Zero
886 - 2: Negative
887 The third lowest bit of lv_tag is reserved for an immortality flag, but is
888 not currently used.
889
890 where SHIFT can be either:
891 #define PyLong_SHIFT 30
892 #define PyLong_SHIFT 15
893 '''
894 long_value = self.field('long_value')
895 lv_tag = int(long_value['lv_tag'])
896 size = lv_tag >> 3
897 if size == 0:
898 return 0
899
900 ob_digit = long_value['ob_digit']
901
902 if gdb.lookup_type('digit').sizeof == 2:
903 SHIFT = 15
904 else:
905 SHIFT = 30
906
907 digits = [int(ob_digit[i]) * 2**(SHIFT*i)
908 for i in safe_range(size)]
909 result = sum(digits)
910 if (lv_tag & 3) == 2:
911 result = -result
912 return result
913
914 def write_repr(self, out, visited):
915 # Write this out as a Python int literal
916 proxy = self.proxyval(visited)
917 out.write("%s" % proxy)
918
919
920 class PyBoolObjectPtr(PyLongObjectPtr):
921 """
922 Class wrapping a gdb.Value that's a PyBoolObject* i.e. one of the two
923 <bool> instances (Py_True/Py_False) within the process being debugged.
924 """
925 def proxyval(self, visited):
926 if PyLongObjectPtr.proxyval(self, visited):
927 return True
928 else:
929 return False
930
931 class PyNoneStructPtr(PyObjectPtr):
932 """
933 Class wrapping a gdb.Value that's a PyObject* pointing to the
934 singleton (we hope) _Py_NoneStruct with ob_type PyNone_Type
935 """
936 _typename = 'PyObject'
937
938 def proxyval(self, visited):
939 return None
940
941 class PyFrameObjectPtr(PyObjectPtr):
942 _typename = 'PyFrameObject'
943
944 def __init__(self, gdbval, cast_to=None):
945 PyObjectPtr.__init__(self, gdbval, cast_to)
946
947 if not self.is_optimized_out():
948 self._frame = PyFramePtr(self.field('f_frame'))
949
950 def iter_locals(self):
951 '''
952 Yield a sequence of (name,value) pairs of PyObjectPtr instances, for
953 the local variables of this frame
954 '''
955 if self.is_optimized_out():
956 return
957 return self._frame.iter_locals()
958
959 def iter_globals(self):
960 '''
961 Yield a sequence of (name,value) pairs of PyObjectPtr instances, for
962 the global variables of this frame
963 '''
964 if self.is_optimized_out():
965 return ()
966 return self._frame.iter_globals()
967
968 def iter_builtins(self):
969 '''
970 Yield a sequence of (name,value) pairs of PyObjectPtr instances, for
971 the builtin variables
972 '''
973 if self.is_optimized_out():
974 return ()
975 return self._frame.iter_builtins()
976
977 def get_var_by_name(self, name):
978
979 if self.is_optimized_out():
980 return None, None
981 return self._frame.get_var_by_name(name)
982
983 def filename(self):
984 '''Get the path of the current Python source file, as a string'''
985 if self.is_optimized_out():
986 return FRAME_INFO_OPTIMIZED_OUT
987 return self._frame.filename()
988
989 def current_line_num(self):
990 '''Get current line number as an integer (1-based)
991
992 Translated from PyFrame_GetLineNumber and PyCode_Addr2Line
993
994 See Objects/lnotab_notes.txt
995 '''
996 if self.is_optimized_out():
997 return None
998 return self._frame.current_line_num()
999
1000 def current_line(self):
1001 '''Get the text of the current source line as a string, with a trailing
1002 newline character'''
1003 if self.is_optimized_out():
1004 return FRAME_INFO_OPTIMIZED_OUT
1005 return self._frame.current_line()
1006
1007 def write_repr(self, out, visited):
1008 if self.is_optimized_out():
1009 out.write(FRAME_INFO_OPTIMIZED_OUT)
1010 return
1011 return self._frame.write_repr(out, visited)
1012
1013 class PyFramePtr:
1014
1015 def __init__(self, gdbval):
1016 self._gdbval = gdbval
1017 if self.is_optimized_out():
1018 return
1019 self.co = self._f_code()
1020 if self.is_shim():
1021 return
1022 self.co_name = self.co.pyop_field('co_name')
1023 self.co_filename = self.co.pyop_field('co_filename')
1024
1025 self.f_lasti = self._f_lasti()
1026 self.co_nlocals = int_from_int(self.co.field('co_nlocals'))
1027 pnames = self.co.field('co_localsplusnames')
1028 self.co_localsplusnames = PyTupleObjectPtr.from_pyobject_ptr(pnames)
1029
1030 @staticmethod
1031 def get_thread_state():
1032 exprs = [
1033 '_Py_tss_gilstate', # 3.15+
1034 '_Py_tss_tstate', # 3.12+ (and not when GIL is released)
1035 'pthread_getspecific(_PyRuntime.autoTSSkey._key)', # only live programs
1036 '((struct pthread*)$fs_base)->specific_1stblock[_PyRuntime.autoTSSkey._key].data' # x86-64
1037 ]
1038 for expr in exprs:
1039 try:
1040 val = gdb.parse_and_eval(f'(PyThreadState*)({expr})')
1041 except gdb.error:
1042 continue
1043 if int(val) != 0:
1044 return val
1045 return None
1046
1047 @staticmethod
1048 def get_thread_local_frame():
1049 thread_state = PyFramePtr.get_thread_state()
1050 if thread_state is None:
1051 return None
1052 current_frame = thread_state['current_frame']
1053 if int(current_frame) == 0:
1054 return None
1055 return PyFramePtr(current_frame)
1056
1057 def is_optimized_out(self):
1058 return self._gdbval.is_optimized_out
1059
1060 def iter_locals(self):
1061 '''
1062 Yield a sequence of (name,value) pairs of PyObjectPtr instances, for
1063 the local variables of this frame
1064 '''
1065 if self.is_optimized_out():
1066 return
1067
1068
1069 obj_ptr_ptr = gdb.lookup_type("PyObject").pointer().pointer()
1070
1071 localsplus = self._gdbval["localsplus"].cast(obj_ptr_ptr)
1072
1073 for i in safe_range(self.co_nlocals):
1074 pyop_value = PyObjectPtr.from_pyobject_ptr(localsplus[i])
1075 if pyop_value.is_null():
1076 continue
1077 pyop_name = PyObjectPtr.from_pyobject_ptr(self.co_localsplusnames[i])
1078 yield (pyop_name, pyop_value)
1079
1080 def _f_special(self, name, convert=PyObjectPtr.from_pyobject_ptr):
1081 return convert(self._gdbval[name])
1082
1083 def _f_globals(self):
1084 return self._f_special("f_globals")
1085
1086 def _f_builtins(self):
1087 return self._f_special("f_builtins")
1088
1089 def _f_code(self):
1090 return self._f_special("f_executable", PyCodeObjectPtr.from_pyobject_ptr)
1091
1092 def _f_executable(self):
1093 return self._f_special("f_executable")
1094
1095 def _f_nlocalsplus(self):
1096 return self._f_special("nlocalsplus", int_from_int)
1097
1098 def _f_lasti(self):
1099 codeunit_p = gdb.lookup_type("_Py_CODEUNIT").pointer()
1100 instr_ptr = self._gdbval["instr_ptr"]
1101 first_instr = self._f_code().field("co_code_adaptive").cast(codeunit_p)
1102 return int(instr_ptr - first_instr)
1103
1104 def is_shim(self):
1105 return self._f_special("owner", int) == FRAME_OWNED_BY_CSTACK
1106
1107 def previous(self):
1108 if int(self._gdbval['previous']) == 0:
1109 return None
1110 return self._f_special("previous", PyFramePtr)
1111
1112 def iter_globals(self):
1113 '''
1114 Yield a sequence of (name,value) pairs of PyObjectPtr instances, for
1115 the global variables of this frame
1116 '''
1117 if self.is_optimized_out():
1118 return ()
1119
1120 pyop_globals = self._f_globals()
1121 return pyop_globals.iteritems()
1122
1123 def iter_builtins(self):
1124 '''
1125 Yield a sequence of (name,value) pairs of PyObjectPtr instances, for
1126 the builtin variables
1127 '''
1128 if self.is_optimized_out():
1129 return ()
1130
1131 pyop_builtins = self._f_builtins()
1132 return pyop_builtins.iteritems()
1133
1134 def get_var_by_name(self, name):
1135 '''
1136 Look for the named local variable, returning a (PyObjectPtr, scope) pair
1137 where scope is a string 'local', 'global', 'builtin'
1138
1139 If not found, return (None, None)
1140 '''
1141 for pyop_name, pyop_value in self.iter_locals():
1142 if name == pyop_name.proxyval(set()):
1143 return pyop_value, 'local'
1144 for pyop_name, pyop_value in self.iter_globals():
1145 if name == pyop_name.proxyval(set()):
1146 return pyop_value, 'global'
1147 for pyop_name, pyop_value in self.iter_builtins():
1148 if name == pyop_name.proxyval(set()):
1149 return pyop_value, 'builtin'
1150 return None, None
1151
1152 def filename(self):
1153 '''Get the path of the current Python source file, as a string'''
1154 if self.is_optimized_out():
1155 return FRAME_INFO_OPTIMIZED_OUT
1156 return self.co_filename.proxyval(set())
1157
1158 def current_line_num(self):
1159 '''Get current line number as an integer (1-based)
1160
1161 Translated from PyFrame_GetLineNumber and PyCode_Addr2Line
1162
1163 See Objects/lnotab_notes.txt
1164 '''
1165 if self.is_optimized_out():
1166 return None
1167 try:
1168 return self.co.addr2line(self.f_lasti)
1169 except Exception as ex:
1170 # bpo-34989: addr2line() is a complex function, it can fail in many
1171 # ways. For example, it fails with a TypeError on "FakeRepr" if
1172 # gdb fails to load debug symbols. Use a catch-all "except
1173 # Exception" to make the whole function safe. The caller has to
1174 # handle None anyway for optimized Python.
1175 return None
1176
1177 def current_line(self):
1178 '''Get the text of the current source line as a string, with a trailing
1179 newline character'''
1180 if self.is_optimized_out():
1181 return FRAME_INFO_OPTIMIZED_OUT
1182
1183 lineno = self.current_line_num()
1184 if lineno is None:
1185 return '(failed to get frame line number)'
1186
1187 filename = self.filename()
1188 try:
1189 with open(os.fsencode(filename), 'r', encoding="utf-8") as fp:
1190 lines = fp.readlines()
1191 except IOError:
1192 return None
1193
1194 try:
1195 # Convert from 1-based current_line_num to 0-based list offset
1196 return lines[lineno - 1]
1197 except IndexError:
1198 return None
1199
1200 def write_repr(self, out, visited):
1201 if self.is_optimized_out():
1202 out.write(FRAME_INFO_OPTIMIZED_OUT)
1203 return
1204 lineno = self.current_line_num()
1205 lineno = str(lineno) if lineno is not None else "?"
1206 out.write('Frame 0x%x, for file %s, line %s, in %s ('
1207 % (self.as_address(),
1208 self.co_filename.proxyval(visited),
1209 lineno,
1210 self.co_name.proxyval(visited)))
1211 first = True
1212 for pyop_name, pyop_value in self.iter_locals():
1213 if not first:
1214 out.write(', ')
1215 first = False
1216
1217 out.write(pyop_name.proxyval(visited))
1218 out.write('=')
1219 pyop_value.write_repr(out, visited)
1220
1221 out.write(')')
1222
1223 def as_address(self):
1224 return int(self._gdbval)
1225
1226 def print_traceback(self):
1227 if self.is_optimized_out():
1228 sys.stdout.write(' %s\n' % FRAME_INFO_OPTIMIZED_OUT)
1229 return
1230 visited = set()
1231 lineno = self.current_line_num()
1232 lineno = str(lineno) if lineno is not None else "?"
1233 sys.stdout.write(' File "%s", line %s, in %s\n'
1234 % (self.co_filename.proxyval(visited),
1235 lineno,
1236 self.co_name.proxyval(visited)))
1237
1238 def print_traceback_until_shim(self, frame_index=None):
1239 # Print traceback for _PyInterpreterFrame and return previous frame
1240 interp_frame = self
1241 while True:
1242 if not interp_frame:
1243 sys.stdout.write(' (unable to read python frame information)\n')
1244 return None
1245 if interp_frame.is_shim():
1246 return interp_frame.previous()
1247
1248 if frame_index is not None:
1249 line = interp_frame.get_truncated_repr(MAX_OUTPUT_LEN)
1250 sys.stdout.write('#%i %s\n' % (frame_index, line))
1251 else:
1252 interp_frame.print_traceback()
1253 if not interp_frame.is_optimized_out():
1254 line = interp_frame.current_line()
1255 if line is not None:
1256 sys.stdout.write(' %s\n' % line.strip())
1257 interp_frame = interp_frame.previous()
1258
1259 def get_truncated_repr(self, maxlen):
1260 '''
1261 Get a repr-like string for the data, but truncate it at "maxlen" bytes
1262 (ending the object graph traversal as soon as you do)
1263 '''
1264 out = TruncatedStringIO(maxlen)
1265 try:
1266 self.write_repr(out, set())
1267 except StringTruncated:
1268 # Truncation occurred:
1269 return out.getvalue() + '...(truncated)'
1270
1271 # No truncation occurred:
1272 return out.getvalue()
1273
1274 class PySetObjectPtr(PyObjectPtr):
1275 _typename = 'PySetObject'
1276
1277 @classmethod
1278 def _dummy_key(self):
1279 return gdb.lookup_global_symbol('_PySet_Dummy').value()
1280
1281 def __iter__(self):
1282 dummy_ptr = self._dummy_key()
1283 table = self.field('table')
1284 for i in safe_range(self.field('mask') + 1):
1285 setentry = table[i]
1286 key = setentry['key']
1287 if key != 0 and key != dummy_ptr:
1288 yield PyObjectPtr.from_pyobject_ptr(key)
1289
1290 def proxyval(self, visited):
1291 # Guard against infinite loops:
1292 if self.as_address() in visited:
1293 return ProxyAlreadyVisited('%s(...)' % self.safe_tp_name())
1294 visited.add(self.as_address())
1295
1296 members = (key.proxyval(visited) for key in self)
1297 if self.safe_tp_name() == 'frozenset':
1298 return frozenset(members)
1299 else:
1300 return set(members)
1301
1302 def write_repr(self, out, visited):
1303 # Emulate Python's set_repr
1304 tp_name = self.safe_tp_name()
1305
1306 # Guard against infinite loops:
1307 if self.as_address() in visited:
1308 out.write('(...)')
1309 return
1310 visited.add(self.as_address())
1311
1312 # Python's set_repr special-cases the empty set:
1313 if not self.field('used'):
1314 out.write(tp_name)
1315 out.write('()')
1316 return
1317
1318 # Python uses {} for set literals:
1319 if tp_name != 'set':
1320 out.write(tp_name)
1321 out.write('(')
1322
1323 out.write('{')
1324 first = True
1325 for key in self:
1326 if not first:
1327 out.write(', ')
1328 first = False
1329 key.write_repr(out, visited)
1330 out.write('}')
1331
1332 if tp_name != 'set':
1333 out.write(')')
1334
1335
1336 class PyBytesObjectPtr(PyObjectPtr):
1337 _typename = 'PyBytesObject'
1338
1339 def __str__(self):
1340 field_ob_size = self.field('ob_size')
1341 field_ob_sval = self.field('ob_sval')
1342 char_ptr = field_ob_sval.address.cast(_type_unsigned_char_ptr())
1343 return ''.join([chr(char_ptr[i]) for i in safe_range(field_ob_size)])
1344
1345 def proxyval(self, visited):
1346 return str(self)
1347
1348 def write_repr(self, out, visited):
1349 # Write this out as a Python bytes literal, i.e. with a "b" prefix
1350
1351 # Get a PyStringObject* within the Python gdb process:
1352 proxy = self.proxyval(visited)
1353
1354 # Transliteration of Python's Objects/bytesobject.c:PyBytes_Repr
1355 # to Python code:
1356 quote = "'"
1357 if "'" in proxy and not '"' in proxy:
1358 quote = '"'
1359 out.write('b')
1360 out.write(quote)
1361 for byte in proxy:
1362 if byte == quote or byte == '\\':
1363 out.write('\\')
1364 out.write(byte)
1365 elif byte == '\t':
1366 out.write('\\t')
1367 elif byte == '\n':
1368 out.write('\\n')
1369 elif byte == '\r':
1370 out.write('\\r')
1371 elif byte < ' ' or ord(byte) >= 0x7f:
1372 out.write('\\x')
1373 out.write(hexdigits[(ord(byte) & 0xf0) >> 4])
1374 out.write(hexdigits[ord(byte) & 0xf])
1375 else:
1376 out.write(byte)
1377 out.write(quote)
1378
1379 class PyTupleObjectPtr(PyObjectPtr):
1380 _typename = 'PyTupleObject'
1381
1382 def __getitem__(self, i):
1383 # Get the gdb.Value for the (PyObject*) with the given index:
1384 field_ob_item = self.field('ob_item')
1385 return field_ob_item[i]
1386
1387 def proxyval(self, visited):
1388 # Guard against infinite loops:
1389 if self.as_address() in visited:
1390 return ProxyAlreadyVisited('(...)')
1391 visited.add(self.as_address())
1392
1393 result = tuple(PyObjectPtr.from_pyobject_ptr(self[i]).proxyval(visited)
1394 for i in safe_range(int_from_int(self.field('ob_size'))))
1395 return result
1396
1397 def write_repr(self, out, visited):
1398 # Guard against infinite loops:
1399 if self.as_address() in visited:
1400 out.write('(...)')
1401 return
1402 visited.add(self.as_address())
1403
1404 out.write('(')
1405 for i in safe_range(int_from_int(self.field('ob_size'))):
1406 if i > 0:
1407 out.write(', ')
1408 element = PyObjectPtr.from_pyobject_ptr(self[i])
1409 element.write_repr(out, visited)
1410 if self.field('ob_size') == 1:
1411 out.write(',)')
1412 else:
1413 out.write(')')
1414
1415 class PyTypeObjectPtr(PyObjectPtr):
1416 _typename = 'PyTypeObject'
1417
1418
1419 def _unichr_is_printable(char):
1420 # Logic adapted from Python's Tools/unicode/makeunicodedata.py
1421 if char == u" ":
1422 return True
1423 import unicodedata
1424 return unicodedata.category(char) not in ("C", "Z")
1425
1426
1427 class PyUnicodeObjectPtr(PyObjectPtr):
1428 _typename = 'PyUnicodeObject'
1429
1430 def proxyval(self, visited):
1431 compact = self.field('_base')
1432 ascii = compact['_base']
1433 state = ascii['state']
1434 is_compact_ascii = (int(state['ascii']) and int(state['compact']))
1435 field_length = int(ascii['length'])
1436 if is_compact_ascii:
1437 field_str = ascii.address + 1
1438 elif int(state['compact']):
1439 field_str = compact.address + 1
1440 else:
1441 field_str = self.field('data')['any']
1442 repr_kind = int(state['kind'])
1443 if repr_kind == 1:
1444 field_str = field_str.cast(_type_unsigned_char_ptr())
1445 elif repr_kind == 2:
1446 field_str = field_str.cast(_type_unsigned_short_ptr())
1447 elif repr_kind == 4:
1448 field_str = field_str.cast(_type_unsigned_int_ptr())
1449
1450 # Gather a list of ints from the code point array; these are either
1451 # UCS-1, UCS-2 or UCS-4 code points:
1452 code_points = [int(field_str[i]) for i in safe_range(field_length)]
1453
1454 # Convert the int code points to unicode characters, and generate a
1455 # local unicode instance.
1456 result = ''.join(map(chr, code_points))
1457 return result
1458
1459 def write_repr(self, out, visited):
1460 # Write this out as a Python str literal
1461
1462 # gdb writes its output in the host charset, so a character is escaped
1463 # unless it is printable and encodable in that charset.
1464 encoding = gdb.host_charset()
1465
1466 # Get a PyUnicodeObject* within the Python gdb process:
1467 proxy = self.proxyval(visited)
1468
1469 # Transliteration of Python's Object/unicodeobject.c:unicode_repr
1470 # to Python:
1471 if "'" in proxy and '"' not in proxy:
1472 quote = '"'
1473 else:
1474 quote = "'"
1475 out.write(quote)
1476
1477 i = 0
1478 while i < len(proxy):
1479 ch = proxy[i]
1480 i += 1
1481
1482 # Escape quotes and backslashes
1483 if ch == quote or ch == '\\':
1484 out.write('\\')
1485 out.write(ch)
1486
1487 # Map special whitespace to '\t', \n', '\r'
1488 elif ch == '\t':
1489 out.write('\\t')
1490 elif ch == '\n':
1491 out.write('\\n')
1492 elif ch == '\r':
1493 out.write('\\r')
1494
1495 # Map non-printable US ASCII to '\xhh' */
1496 elif ch < ' ' or ord(ch) == 0x7F:
1497 out.write('\\x')
1498 out.write(hexdigits[(ord(ch) >> 4) & 0x000F])
1499 out.write(hexdigits[ord(ch) & 0x000F])
1500
1501 # Copy ASCII characters as-is
1502 elif ord(ch) < 0x7F:
1503 out.write(ch)
1504
1505 # Non-ASCII characters
1506 else:
1507 ucs = ch
1508 ch2 = None
1509
1510 printable = ucs.isprintable()
1511 if printable:
1512 try:
1513 ucs.encode(encoding)
1514 # LookupError or ValueError if the host charset is unknown
1515 # or invalid.
1516 except (UnicodeEncodeError, LookupError, ValueError):
1517 printable = False
1518
1519 # Map Unicode whitespace and control characters
1520 # (categories Z* and C* except ASCII space)
1521 if not printable:
1522 if ch2 is not None:
1523 # Match Python's representation of non-printable
1524 # wide characters.
1525 code = (ord(ch) & 0x03FF) << 10
1526 code |= ord(ch2) & 0x03FF
1527 code += 0x00010000
1528 else:
1529 code = ord(ucs)
1530
1531 # Map 8-bit characters to '\\xhh'
1532 if code <= 0xff:
1533 out.write('\\x')
1534 out.write(hexdigits[(code >> 4) & 0x000F])
1535 out.write(hexdigits[code & 0x000F])
1536 # Map 21-bit characters to '\U00xxxxxx'
1537 elif code >= 0x10000:
1538 out.write('\\U')
1539 out.write(hexdigits[(code >> 28) & 0x0000000F])
1540 out.write(hexdigits[(code >> 24) & 0x0000000F])
1541 out.write(hexdigits[(code >> 20) & 0x0000000F])
1542 out.write(hexdigits[(code >> 16) & 0x0000000F])
1543 out.write(hexdigits[(code >> 12) & 0x0000000F])
1544 out.write(hexdigits[(code >> 8) & 0x0000000F])
1545 out.write(hexdigits[(code >> 4) & 0x0000000F])
1546 out.write(hexdigits[code & 0x0000000F])
1547 # Map 16-bit characters to '\uxxxx'
1548 else:
1549 out.write('\\u')
1550 out.write(hexdigits[(code >> 12) & 0x000F])
1551 out.write(hexdigits[(code >> 8) & 0x000F])
1552 out.write(hexdigits[(code >> 4) & 0x000F])
1553 out.write(hexdigits[code & 0x000F])
1554 else:
1555 # Copy characters as-is
1556 out.write(ch)
1557 if ch2 is not None:
1558 out.write(ch2)
1559
1560 out.write(quote)
1561
1562
1563 class wrapperobject(PyObjectPtr):
1564 _typename = 'wrapperobject'
1565
1566 def safe_name(self):
1567 try:
1568 name = self.field('descr')['d_base']['name'].string()
1569 return repr(name)
1570 except (NullPyObjectPtr, RuntimeError, UnicodeDecodeError):
1571 return '<unknown name>'
1572
1573 def safe_tp_name(self):
1574 try:
1575 return self.field('self')['ob_type']['tp_name'].string()
1576 except (NullPyObjectPtr, RuntimeError, UnicodeDecodeError):
1577 return '<unknown tp_name>'
1578
1579 def safe_self_addresss(self):
1580 try:
1581 address = int(self.field('self'))
1582 return '%#x' % address
1583 except (NullPyObjectPtr, RuntimeError):
1584 return '<failed to get self address>'
1585
1586 def proxyval(self, visited):
1587 name = self.safe_name()
1588 tp_name = self.safe_tp_name()
1589 self_address = self.safe_self_addresss()
1590 return ("<method-wrapper %s of %s object at %s>"
1591 % (name, tp_name, self_address))
1592
1593 def write_repr(self, out, visited):
1594 proxy = self.proxyval(visited)
1595 out.write(proxy)
1596
1597
1598 def int_from_int(gdbval):
1599 return int(gdbval)
1600
1601
1602 def stringify(val):
1603 # TODO: repr() puts everything on one line; pformat can be nicer, but
1604 # can lead to v.long results; this function isolates the choice
1605 if True:
1606 return repr(val)
1607 else:
1608 from pprint import pformat
1609 return pformat(val)
1610
1611
1612 class PyObjectPtrPrinter:
1613 "Prints a (PyObject*)"
1614
1615 def __init__ (self, gdbval):
1616 self.gdbval = gdbval
1617
1618 def to_string (self):
1619 pyop = PyObjectPtr.from_pyobject_ptr(self.gdbval)
1620 if True:
1621 return pyop.get_truncated_repr(MAX_OUTPUT_LEN)
1622 else:
1623 # Generate full proxy value then stringify it.
1624 # Doing so could be expensive
1625 proxyval = pyop.proxyval(set())
1626 return stringify(proxyval)
1627
1628 def pretty_printer_lookup(gdbval):
1629 type = gdbval.type.unqualified()
1630 if type.code != gdb.TYPE_CODE_PTR:
1631 return None
1632
1633 type = type.target().unqualified()
1634 t = str(type)
1635 if t in ("PyObject", "PyFrameObject", "PyUnicodeObject", "wrapperobject"):
1636 return PyObjectPtrPrinter(gdbval)
1637
1638 """
1639 During development, I've been manually invoking the code in this way:
1640 (gdb) python
1641
1642 import sys
1643 sys.path.append('/home/david/coding/python-gdb')
1644 import libpython
1645 end
1646
1647 then reloading it after each edit like this:
1648 (gdb) python reload(libpython)
1649
1650 The following code should ensure that the prettyprinter is registered
1651 if the code is autoloaded by gdb when visiting libpython.so, provided
1652 that this python file is installed to the same path as the library (or its
1653 .debug file) plus a "-gdb.py" suffix, e.g:
1654 /usr/lib/libpython3.12.so.1.0-gdb.py
1655 /usr/lib/debug/usr/lib/libpython3.12.so.1.0.debug-gdb.py
1656 """
1657 def register (obj):
1658 if obj is None:
1659 obj = gdb
1660
1661 # Wire up the pretty-printer
1662 obj.pretty_printers.append(pretty_printer_lookup)
1663
1664 register (gdb.current_objfile ())
1665
1666
1667
1668 # Unfortunately, the exact API exposed by the gdb module varies somewhat
1669 # from build to build
1670 # See http://bugs.python.org/issue8279?#msg102276
1671
1672 class Frame(object):
1673 '''
1674 Wrapper for gdb.Frame, adding various methods
1675 '''
1676 def __init__(self, gdbframe):
1677 self._gdbframe = gdbframe
1678
1679 def older(self):
1680 older = self._gdbframe.older()
1681 if older:
1682 return Frame(older)
1683 else:
1684 return None
1685
1686 def newer(self):
1687 newer = self._gdbframe.newer()
1688 if newer:
1689 return Frame(newer)
1690 else:
1691 return None
1692
1693 def select(self):
1694 '''If supported, select this frame and return True; return False if unsupported
1695
1696 Not all builds have a gdb.Frame.select method; seems to be present on Fedora 12
1697 onwards, but absent on Ubuntu buildbot'''
1698 if not hasattr(self._gdbframe, 'select'):
1699 print ('Unable to select frame: '
1700 'this build of gdb does not expose a gdb.Frame.select method')
1701 return False
1702 self._gdbframe.select()
1703 return True
1704
1705 def get_index(self):
1706 '''Calculate index of frame, starting at 0 for the newest frame within
1707 this thread'''
1708 index = 0
1709 # Go down until you reach the newest frame:
1710 iter_frame = self
1711 while iter_frame.newer():
1712 index += 1
1713 iter_frame = iter_frame.newer()
1714 return index
1715
1716 # We divide frames into:
1717 # - "python frames":
1718 # - "bytecode frames" i.e. PyEval_EvalFrameEx
1719 # - "other python frames": things that are of interest from a python
1720 # POV, but aren't bytecode (e.g. GC, GIL)
1721 # - everything else
1722
1723 def is_python_frame(self):
1724 '''Is this a _PyEval_EvalFrameDefault frame, or some other important
1725 frame? (see is_other_python_frame for what "important" means in this
1726 context)'''
1727 if self.is_evalframe():
1728 return True
1729 if self.is_other_python_frame():
1730 return True
1731 return False
1732
1733 def is_evalframe(self):
1734 '''Is this a _PyEval_EvalFrameDefault frame?'''
1735 if self._gdbframe.name() == EVALFRAME:
1736 '''
1737 I believe we also need to filter on the inline
1738 struct frame_id.inline_depth, only regarding frames with
1739 an inline depth of 0 as actually being this function
1740
1741 So we reject those with type gdb.INLINE_FRAME
1742 '''
1743 if self._gdbframe.type() == gdb.NORMAL_FRAME:
1744 # We have a _PyEval_EvalFrameDefault frame:
1745 return True
1746
1747 return False
1748
1749 def is_other_python_frame(self):
1750 '''Is this frame worth displaying in python backtraces?
1751 Examples:
1752 - waiting on the GIL
1753 - garbage-collecting
1754 - within a CFunction
1755 If it is, return a descriptive string
1756 For other frames, return False
1757 '''
1758 if self.is_waiting_for_gil():
1759 return 'Waiting for the GIL'
1760
1761 if self.is_gc_collect():
1762 return 'Garbage-collecting'
1763
1764 # Detect invocations of PyCFunction instances:
1765 frame = self._gdbframe
1766 caller = frame.name()
1767 if not caller:
1768 return False
1769
1770 if (caller.startswith('cfunction_vectorcall_') or
1771 caller == 'cfunction_call'):
1772 arg_name = 'func'
1773 # Within that frame:
1774 # "func" is the local containing the PyObject* of the
1775 # PyCFunctionObject instance
1776 # "f" is the same value, but cast to (PyCFunctionObject*)
1777 # "self" is the (PyObject*) of the 'self'
1778 try:
1779 # Use the prettyprinter for the func:
1780 func = frame.read_var(arg_name)
1781 return str(func)
1782 except ValueError:
1783 return ('PyCFunction invocation (unable to read %s: '
1784 'missing debuginfos?)' % arg_name)
1785 except RuntimeError:
1786 return 'PyCFunction invocation (unable to read %s)' % arg_name
1787
1788 if caller == 'wrapper_call':
1789 arg_name = 'wp'
1790 try:
1791 func = frame.read_var(arg_name)
1792 return str(func)
1793 except ValueError:
1794 return ('<wrapper_call invocation (unable to read %s: '
1795 'missing debuginfos?)>' % arg_name)
1796 except RuntimeError:
1797 return '<wrapper_call invocation (unable to read %s)>' % arg_name
1798
1799 # This frame isn't worth reporting:
1800 return False
1801
1802 def is_waiting_for_gil(self):
1803 '''Is this frame waiting on the GIL?'''
1804 # This assumes the _POSIX_THREADS version of Python/ceval_gil.c:
1805 name = self._gdbframe.name()
1806 if name:
1807 return (name == 'take_gil')
1808
1809 def is_gc_collect(self):
1810 '''Is this frame a collector within the garbage-collector?'''
1811 return self._gdbframe.name() in (
1812 'collect', 'gc_collect_full', 'gc_collect_main',
1813 'gc_collect_young', 'gc_collect_increment',
1814 )
1815
1816 def get_pyop(self):
1817 try:
1818 frame = self._gdbframe.read_var('frame')
1819 frame = PyFramePtr(frame)
1820 if not frame.is_optimized_out():
1821 return frame
1822 cframe = self._gdbframe.read_var('cframe')
1823 if cframe is None:
1824 return None
1825 frame = PyFramePtr(cframe["current_frame"])
1826 if frame and not frame.is_optimized_out():
1827 return frame
1828 return None
1829 except ValueError:
1830 return None
1831
1832 @classmethod
1833 def get_selected_frame(cls):
1834 _gdbframe = gdb.selected_frame()
1835 if _gdbframe:
1836 return Frame(_gdbframe)
1837 return None
1838
1839 @classmethod
1840 def get_selected_python_frame(cls):
1841 '''Try to obtain the Frame for the python-related code in the selected
1842 frame, or None'''
1843 try:
1844 frame = cls.get_selected_frame()
1845 except gdb.error:
1846 # No frame: Python didn't start yet
1847 return None
1848
1849 while frame:
1850 if frame.is_python_frame():
1851 return frame
1852 frame = frame.older()
1853
1854 # Not found:
1855 return None
1856
1857 @classmethod
1858 def get_selected_bytecode_frame(cls):
1859 '''Try to obtain the Frame for the python bytecode interpreter in the
1860 selected GDB frame, or None'''
1861 frame = cls.get_selected_frame()
1862
1863 while frame:
1864 if frame.is_evalframe():
1865 return frame
1866 frame = frame.older()
1867
1868 # Not found:
1869 return None
1870
1871 def print_summary(self):
1872 if self.is_evalframe():
1873 interp_frame = self.get_pyop()
1874 if interp_frame:
1875 interp_frame.print_traceback_until_shim(self.get_index())
1876 else:
1877 sys.stdout.write('#%i (unable to read python frame information)\n' % self.get_index())
1878 else:
1879 info = self.is_other_python_frame()
1880 if info:
1881 sys.stdout.write('#%i %s\n' % (self.get_index(), info))
1882 else:
1883 sys.stdout.write('#%i\n' % self.get_index())
1884
1885 class PyList(gdb.Command):
1886 '''List the current Python source code, if any
1887
1888 Use
1889 py-list START
1890 to list at a different line number within the python source.
1891
1892 Use
1893 py-list START, END
1894 to list a specific range of lines within the python source.
1895 '''
1896
1897 def __init__(self):
1898 gdb.Command.__init__ (self,
1899 "py-list",
1900 gdb.COMMAND_FILES,
1901 gdb.COMPLETE_NONE)
1902
1903
1904 def invoke(self, args, from_tty):
1905 import re
1906
1907 start = None
1908 end = None
1909
1910 m = re.match(r'\s*(\d+)\s*', args)
1911 if m:
1912 start = int(m.group(0))
1913 end = start + 10
1914
1915 m = re.match(r'\s*(\d+)\s*,\s*(\d+)\s*', args)
1916 if m:
1917 start, end = map(int, m.groups())
1918
1919 # py-list requires an actual PyEval_EvalFrameEx frame:
1920 frame = Frame.get_selected_bytecode_frame()
1921 if not frame:
1922 print('Unable to locate gdb frame for python bytecode interpreter')
1923 return
1924
1925 pyop = frame.get_pyop()
1926 if not pyop or pyop.is_optimized_out():
1927 print(UNABLE_READ_INFO_PYTHON_FRAME)
1928 return
1929
1930 filename = pyop.filename()
1931 lineno = pyop.current_line_num()
1932 if lineno is None:
1933 print('Unable to read python frame line number')
1934 return
1935
1936 if start is None:
1937 start = lineno - 5
1938 end = lineno + 5
1939
1940 if start<1:
1941 start = 1
1942
1943 try:
1944 f = open(os.fsencode(filename), 'r', encoding="utf-8")
1945 except IOError as err:
1946 sys.stdout.write('Unable to open %s: %s\n'
1947 % (filename, err))
1948 return
1949 with f:
1950 all_lines = f.readlines()
1951 # start and end are 1-based, all_lines is 0-based;
1952 # so [start-1:end] as a python slice gives us [start, end] as a
1953 # closed interval
1954 for i, line in enumerate(all_lines[start-1:end]):
1955 linestr = str(i+start)
1956 # Highlight current line:
1957 if i + start == lineno:
1958 linestr = '>' + linestr
1959 sys.stdout.write('%4s %s' % (linestr, line))
1960
1961
1962 # ...and register the command:
1963 PyList()
1964
1965 def move_in_stack(move_up):
1966 '''Move up or down the stack (for the py-up/py-down command)'''
1967 # Important:
1968 # The amount of frames that are printed out depends on how many frames are inlined
1969 # in the same evaluation loop. As this command links directly the C stack with the
1970 # Python stack, the results are sensitive to the number of inlined frames and this
1971 # is likely to change between versions and optimizations.
1972 frame = Frame.get_selected_python_frame()
1973 if not frame:
1974 print('Unable to locate python frame')
1975 return
1976 while frame:
1977 if move_up:
1978 iter_frame = frame.older()
1979 else:
1980 iter_frame = frame.newer()
1981
1982 if not iter_frame:
1983 break
1984
1985 if iter_frame.is_python_frame():
1986 # Result:
1987 if iter_frame.select():
1988 iter_frame.print_summary()
1989 return
1990
1991 frame = iter_frame
1992
1993 if move_up:
1994 print('Unable to find an older python frame')
1995 else:
1996 print('Unable to find a newer python frame')
1997
1998
1999 class PyUp(gdb.Command):
2000 'Select and print all python stack frame in the same eval loop starting from the one that called this one (if any)'
2001 def __init__(self):
2002 gdb.Command.__init__ (self,
2003 "py-up",
2004 gdb.COMMAND_STACK,
2005 gdb.COMPLETE_NONE)
2006
2007
2008 def invoke(self, args, from_tty):
2009 move_in_stack(move_up=True)
2010
2011 class PyDown(gdb.Command):
2012 'Select and print all python stack frame in the same eval loop starting from the one called this one (if any)'
2013 def __init__(self):
2014 gdb.Command.__init__ (self,
2015 "py-down",
2016 gdb.COMMAND_STACK,
2017 gdb.COMPLETE_NONE)
2018
2019
2020 def invoke(self, args, from_tty):
2021 move_in_stack(move_up=False)
2022
2023 # Not all builds of gdb have gdb.Frame.select
2024 if hasattr(gdb.Frame, 'select'):
2025 PyUp()
2026 PyDown()
2027
2028
2029 def print_traceback_helper(full_info):
2030 frame = Frame.get_selected_python_frame()
2031 interp_frame = PyFramePtr.get_thread_local_frame()
2032 if not frame and not interp_frame:
2033 print('Unable to locate python frame')
2034 return
2035
2036 sys.stdout.write('Traceback (most recent call first):\n')
2037 if frame:
2038 while frame:
2039 frame_index = frame.get_index() if full_info else None
2040 if frame.is_evalframe():
2041 pyop = frame.get_pyop()
2042 if pyop is not None:
2043 # Use the _PyInterpreterFrame from the gdb frame
2044 interp_frame = pyop
2045 if interp_frame:
2046 interp_frame = interp_frame.print_traceback_until_shim(frame_index)
2047 else:
2048 sys.stdout.write(' (unable to read python frame information)\n')
2049 else:
2050 info = frame.is_other_python_frame()
2051 if full_info:
2052 if info:
2053 sys.stdout.write('#%i %s\n' % (frame_index, info))
2054 elif info:
2055 sys.stdout.write(' %s\n' % info)
2056 frame = frame.older()
2057 else:
2058 # Fall back to just using the thread-local frame
2059 while interp_frame:
2060 interp_frame = interp_frame.print_traceback_until_shim()
2061
2062
2063 class PyBacktraceFull(gdb.Command):
2064 'Display the current python frame and all the frames within its call stack (if any)'
2065 def __init__(self):
2066 gdb.Command.__init__ (self,
2067 "py-bt-full",
2068 gdb.COMMAND_STACK,
2069 gdb.COMPLETE_NONE)
2070
2071
2072 def invoke(self, args, from_tty):
2073 print_traceback_helper(full_info=True)
2074
2075 PyBacktraceFull()
2076
2077 class PyBacktrace(gdb.Command):
2078 'Display the current python frame and all the frames within its call stack (if any)'
2079 def __init__(self):
2080 gdb.Command.__init__ (self,
2081 "py-bt",
2082 gdb.COMMAND_STACK,
2083 gdb.COMPLETE_NONE)
2084
2085 def invoke(self, args, from_tty):
2086 print_traceback_helper(full_info=False)
2087
2088 PyBacktrace()
2089
2090 class PyPrint(gdb.Command):
2091 'Look up the given python variable name, and print it'
2092 def __init__(self):
2093 gdb.Command.__init__ (self,
2094 "py-print",
2095 gdb.COMMAND_DATA,
2096 gdb.COMPLETE_NONE)
2097
2098
2099 def invoke(self, args, from_tty):
2100 name = str(args)
2101
2102 frame = Frame.get_selected_python_frame()
2103 if not frame:
2104 print('Unable to locate python frame')
2105 return
2106
2107 pyop_frame = frame.get_pyop()
2108 if not pyop_frame:
2109 print(UNABLE_READ_INFO_PYTHON_FRAME)
2110 return
2111
2112 pyop_var, scope = pyop_frame.get_var_by_name(name)
2113
2114 if pyop_var:
2115 print('%s %r = %s'
2116 % (scope,
2117 name,
2118 pyop_var.get_truncated_repr(MAX_OUTPUT_LEN)))
2119 else:
2120 print('%r not found' % name)
2121
2122 PyPrint()
2123
2124 class PyLocals(gdb.Command):
2125 'Look up the given python variable name, and print it'
2126 def __init__(self):
2127 gdb.Command.__init__ (self,
2128 "py-locals",
2129 gdb.COMMAND_DATA,
2130 gdb.COMPLETE_NONE)
2131
2132
2133 def invoke(self, args, from_tty):
2134 name = str(args)
2135
2136 frame = Frame.get_selected_python_frame()
2137 if not frame:
2138 print('Unable to locate python frame')
2139 return
2140
2141 pyop_frame = frame.get_pyop()
2142 while True:
2143 if not pyop_frame:
2144 print(UNABLE_READ_INFO_PYTHON_FRAME)
2145 break
2146 if pyop_frame.is_shim():
2147 break
2148
2149 sys.stdout.write('Locals for %s\n' % (pyop_frame.co_name.proxyval(set())))
2150
2151 for pyop_name, pyop_value in pyop_frame.iter_locals():
2152 print('%s = %s'
2153 % (pyop_name.proxyval(set()),
2154 pyop_value.get_truncated_repr(MAX_OUTPUT_LEN)))
2155
2156
2157 pyop_frame = pyop_frame.previous()
2158
2159 PyLocals()