Index: lldb/docs/use/python-reference.rst =================================================================== --- lldb/docs/use/python-reference.rst +++ lldb/docs/use/python-reference.rst @@ -98,39 +98,38 @@ appropriate type, the variable's IsValid method will return false. These variables are: -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| Variable | Type | Description | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.debugger** | **lldb.SBDebugger** | 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** | Contains the currently selected target - for instance the one made with the | -| | | **file** or selected by the **target select ** command. | -| | | The **lldb.SBTarget** manages one running process, and all the executable | -| | | and debug files for the process. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ -| **lldb.process** | **lldb.SBProcess** | 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** | 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 ** 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** | 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 ** 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. | -+-------------------+---------------------+-------------------------------------------------------------------------------------+ - ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| 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()** | Contains the currently selected target - for instance the one made with the | +| | | **SBProcess.GetTarget()** | **file** or selected by the **target select ** command. | +| | | | The **lldb.SBTarget** manages one running process, and all the executable | +| | | | and debug files for the process. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.process** | **lldb.SBProcess** | **SBTarget.GetProcess()** | Contains the process of the currently selected target. | +| | | **SBThread.GetProcess()** | The **lldb.SBProcess** object manages the threads and allows access to | +| | | | memory for the process. | ++-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +| **lldb.thread** | **lldb.SBThread** | **SBProcess.GetSelectedThread()** | Contains the currently selected thread. | +| | | **SBFrame.GetThread()** | 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 ** 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 ** 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 @@ -140,8 +139,12 @@ 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). As a -rationale for such behavior, consider that lldb can run in a multithreaded +commands (or any other Python extension point that LLDB provides). For the +latter you'll be passed a 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.