1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
# Implementing Standalone Scripts
### Configuring `PYTHONPATH`
LLDB has all of its core code built into a shared library which gets used by
the `lldb` command line application.
- On macOS this shared library is a framework: `LLDB.framework`.
- On other unix variants the program is a shared library: lldb.so.
LLDB also provides an `lldb.py` module that contains the bindings from LLDB
into Python. To use the `LLDB.framework` to create your own stand-alone python
programs, you will need to tell python where to look in order to find this
module. This is done by setting the `PYTHONPATH` environment variable,
adding a path to the directory that contains the `lldb.py` python
module. The lldb driver program has an option to report the path to the lldb
module. You can use that to point to correct lldb.py:
For csh and tcsh:
```csh
% setenv PYTHONPATH `lldb -P`
```
For sh and bash:
```bash
$ export PYTHONPATH=`lldb -P`
```
Alternatively, you can append the LLDB Python directory to the sys.path list
directly in your Python code before importing the lldb module.
### Initialization
The standard test for `__main__`, like many python modules do, is useful for
creating scripts that can be run from the command line. However, for command
line scripts, the debugger instance must be created manually. Sample code would
look like:
```python3
if __name__ == '__main__':
# Initialize the debugger before making any API calls.
lldb.SBDebugger.Initialize()
# Create a new debugger instance in your module if your module
# can be run from the command line. When we run a script from
# the command line, we won't have any debugger object in
# lldb.debugger, so we can just create it if it will be needed
debugger = lldb.SBDebugger.Create()
# Next, do whatever work this module should do when run as a command.
# ...
# Finally, dispose of the debugger you just made.
lldb.SBDebugger.Destroy(debugger)
# Terminate the debug session
lldb.SBDebugger.Terminate()
```
### Example
Now your python scripts are ready to import the lldb module. Below is a python
script that will launch a program from the current working directory called
`a.out`, set a breakpoint at `main`, and then run and hit the breakpoint, and
print the process, thread and frame objects if the process stopped:
```python3
#!/usr/bin/env python3
import lldb
import os
def disassemble_instructions(insts):
for i in insts:
print(i)
# Set the path to the executable to debug
exe = "./a.out"
# Create a new debugger instance
debugger = lldb.SBDebugger.Create()
# When we step or continue, don't return from the function until the process
# stops. Otherwise we would have to handle the process events ourselves which, while doable is
# a little tricky. We do this by setting the async mode to false.
debugger.SetAsync(False)
# Create a target from a file and arch
print("Creating a target for '%s'" % exe)
target = debugger.CreateTargetWithFileAndArch(exe, lldb.LLDB_ARCH_DEFAULT)
if target:
# If the target is valid set a breakpoint at main
main_bp = target.BreakpointCreateByName(
"main", target.GetExecutable().GetFilename()
)
print(main_bp)
# Launch the process. Since we specified synchronous mode, we won't return
# from this function until we hit the breakpoint at main
process = target.LaunchSimple(None, None, os.getcwd())
# Make sure the launch went ok
if process:
# Print some simple process info
state = process.GetState()
print(process)
if state == lldb.eStateStopped:
# Get the first thread
thread = process.GetThreadAtIndex(0)
if thread:
# Print some simple thread info
print(thread)
# Get the first frame
frame = thread.GetFrameAtIndex(0)
if frame:
# Print some simple frame info
print(frame)
function = frame.GetFunction()
# See if we have debug info (a function)
if function:
# We do have a function, print some info for the function
print(function)
# Now get all instructions for this function and print them
insts = function.GetInstructions(target)
disassemble_instructions(insts)
else:
# See if we have a symbol in the symbol table for where we stopped
symbol = frame.GetSymbol()
if symbol:
# We do have a symbol, print some info for the symbol
print(symbol)
```
|
