1# If you use the GNU debugger gdb to debug the Python C runtime, you
2# might find some of the following commands useful.  Copy this to your
3# ~/.gdbinit file and it'll get loaded into gdb automatically when you
4# start it up.  Then, at the gdb prompt you can do things like:
5#
6#    (gdb) pyo apyobjectptr
7#    <module 'foobar' (built-in)>
8#    refcounts: 1
9#    address    : 84a7a2c
10#    $1 = void
11#    (gdb)
12#
13# NOTE: If you have gdb 7 or later, it supports debugging of Python directly
14# with embedded macros that you may find superior to what is in here.
15# See Tools/gdb/libpython.py and http://bugs.python.org/issue8032.
16
17# Prints a representation of the object to stderr, along with the
18# number of reference counts it current has and the hex address the
19# object is allocated at.  The argument must be a PyObject*
20define pyo
21    # side effect of calling _PyObject_Dump is to dump the object's
22    # info - assigning just prevents gdb from printing the
23    # NULL return value
24    set $_unused_void = _PyObject_Dump($arg0)
25end
26
27# Prints a representation of the object to stderr, along with the
28# number of reference counts it current has and the hex address the
29# object is allocated at.  The argument must be a PyGC_Head*
30define pyg
31    print _PyGC_Dump($arg0)
32end
33
34# print the local variables of the current frame
35define pylocals
36    set $_i = 0
37    while $_i < f->f_code->co_nlocals
38	if f->f_localsplus + $_i != 0
39	    set $_names = co->co_varnames
40	    set $_name = _PyUnicode_AsString(PyTuple_GetItem($_names, $_i))
41	    printf "%s:\n", $_name
42            pyo f->f_localsplus[$_i]
43	end
44        set $_i = $_i + 1
45    end
46end
47
48# A rewrite of the Python interpreter's line number calculator in GDB's
49# command language
50define lineno
51    set $__continue = 1
52    set $__co = f->f_code
53    set $__lasti = f->f_lasti
54    set $__sz = ((PyVarObject *)$__co->co_lnotab)->ob_size/2
55    set $__p = (unsigned char *)((PyBytesObject *)$__co->co_lnotab)->ob_sval
56    set $__li = $__co->co_firstlineno
57    set $__ad = 0
58    while ($__sz-1 >= 0 && $__continue)
59      set $__sz = $__sz - 1
60      set $__ad = $__ad + *$__p
61      set $__p = $__p + 1
62      if ($__ad > $__lasti)
63	set $__continue = 0
64      else
65        set $__li = $__li + *$__p
66        set $__p = $__p + 1
67      end
68    end
69    printf "%d", $__li
70end
71
72# print the current frame - verbose
73define pyframev
74    pyframe
75    pylocals
76end
77
78define pyframe
79    set $__fn = _PyUnicode_AsString(co->co_filename)
80    set $__n = _PyUnicode_AsString(co->co_name)
81    printf "%s (", $__fn
82    lineno
83    printf "): %s\n", $__n
84### Uncomment these lines when using from within Emacs/XEmacs so it will
85### automatically track/display the current Python source line
86#    printf "%c%c%s:", 032, 032, $__fn
87#    lineno
88#    printf ":1\n"
89end
90
91### Use these at your own risk.  It appears that a bug in gdb causes it
92### to crash in certain circumstances.
93
94#define up
95#    up-silently 1
96#    printframe
97#end
98
99#define down
100#    down-silently 1
101#    printframe
102#end
103
104define printframe
105    if $pc > PyEval_EvalFrameEx && $pc < PyEval_EvalCodeEx
106	pyframe
107    else
108        frame
109    end
110end
111
112# Here's a somewhat fragile way to print the entire Python stack from gdb.
113# It's fragile because the tests for the value of $pc depend on the layout
114# of specific functions in the C source code.
115
116# Explanation of while and if tests: We want to pop up the stack until we
117# land in Py_Main (this is probably an incorrect assumption in an embedded
118# interpreter, but the test can be extended by an interested party).  If
119# Py_Main <= $pc <= Py_GetArgcArv is true, $pc is in Py_Main(), so the while
120# tests succeeds as long as it's not true.  In a similar fashion the if
121# statement tests to see if we are in PyEval_EvalFrameEx().
122
123# Note: The name of the main interpreter function and the function which
124# follow it has changed over time.  This version of pystack works with this
125# version of Python.  If you try using it with older or newer versions of
126# the interpreter you may will have to change the functions you compare with
127# $pc.
128
129# print the entire Python call stack
130define pystack
131    while $pc < Py_Main || $pc > Py_GetArgcArgv
132        if $pc > PyEval_EvalFrameEx && $pc < PyEval_EvalCodeEx
133	    pyframe
134        end
135        up-silently 1
136    end
137    select-frame 0
138end
139
140# print the entire Python call stack - verbose mode
141define pystackv
142    while $pc < Py_Main || $pc > Py_GetArgcArgv
143        if $pc > PyEval_EvalFrameEx && $pc < PyEval_EvalCodeEx
144	    pyframev
145        end
146        up-silently 1
147    end
148    select-frame 0
149end
150
151# generally useful macro to print a Unicode string
152def pu
153  set $uni = $arg0
154  set $i = 0
155  while (*$uni && $i++<100)
156    if (*$uni < 0x80)
157      print *(char*)$uni++
158    else
159      print /x *(short*)$uni++
160    end
161  end
162end
163