261000760f
This pages improve the LLDB website documentation readability and discoverability by breaking down the very long python-reference page into multiple subpages each explaining a specific topic. The long term goal is to have tutorials for every scripting extension. This also converts the pages to markdown, since it's easier to write. Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
4.2 KiB
Embedded Python Interpreter
The embedded python interpreter can be accessed in a variety of ways from within LLDB. The easiest way is to use the lldb command script with no arguments at the lldb command prompt:
(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> 2+3
5
>>> hex(12345)
'0x3039'
>>>
This drops you into the embedded python interpreter. When running under the script command, lldb sets some convenience variables that give you quick access to the currently selected entities that characterize the program and debugger state. In each case, if there is no currently selected entity of the appropriate type, the variable's IsValid method will return false. These variables are:
| Variable | Type | Equivalent | Description |
|---|---|---|---|
lldb.debugger |
lldb.SBDebugger |
SBTarget.GetDebugger |
Contains the debugger object whose script command was invoked. The lldb.SBDebugger object owns the command interpreter and all the targets in your debug session. There will always be a Debugger in the embedded interpreter. |
lldb.target |
lldb.SBTarget |
SBDebugger.GetSelectedTarget SBProcess.GetTarget |
Contains the currently selected target - for instance the one made with the file or selected by the target select <target-index> command. The lldb.SBTarget manages one running process, and all the executable and debug files for the process. |
lldb.process |
lldb.SBProcess |
SBTarget.GetProcess SBThread.GetProcess |
Contains the process of the currently selected target. The lldb.SBProcess object manages the threads and allows access to memory for the process. |
lldb.thread |
lldb.SBThread |
SBProcess.GetSelectedThread SBFrame.GetThread |
Contains the currently selected thread. The lldb.SBThread object manages the stack frames in that thread. A thread is always selected in the command interpreter when a target stops. The thread select <thread-index> command can be used to change the currently selected thread. So as long as you have a stopped process, there will be some selected thread. |
lldb.frame |
lldb.SBFrame |
SBThread.GetSelectedFrame |
Contains the currently selected stack frame. The lldb.SBFrame object manage the stack locals and the register set for that stack. A stack frame is always selected in the command interpreter when a target stops. The frame select <frame-index> command can be used to change the currently selected frame. So as long as you have a stopped process, there will be some selected frame. |
While extremely convenient, these variables have a couple caveats that you should be aware of. First of all, they hold the values of the selected objects on entry to the embedded interpreter. They do not update as you use the LLDB API's to change, for example, the currently selected stack frame or thread.
Moreover, they are only defined and meaningful while in the interactive Python
interpreter. There is no guarantee on their value in any other situation, hence
you should not use them when defining Python formatters, breakpoint scripts and
commands (or any other Python extension point that LLDB provides). For the
latter you'll be passed an SBDebugger, SBTarget, SBProcess, SBThread or
SBFrame instance and you can use the functions from the "Equivalent" column
to navigate between them.
As a rationale for such behavior, consider that lldb can run in a multithreaded environment, and another thread might call the "script" command, changing the value out from under you.
To get started with these objects and LLDB scripting, please note that almost all of the lldb Python objects are able to briefly describe themselves when you pass them to the Python print function:
(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> print(lldb.debugger)
Debugger (instance: "debugger_1", id: 1)
>>> print(lldb.target)
a.out
>>> print(lldb.process)
SBProcess: pid = 58842, state = stopped, threads = 1, executable = a.out
>>> print(lldb.thread)
thread #1: tid = 0x2265ce3, 0x0000000100000334 a.out`main at t.c:2:3, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
>>> print(lldb.frame)
frame #0: 0x0000000100000334 a.out`main at t.c:2:3