1Python Reference 2================ 3 4The entire LLDB API is available as Python functions through a script bridging 5interface. This means the LLDB API's can be used directly from python either 6interactively or to build python apps that provide debugger features. 7 8Additionally, Python can be used as a programmatic interface within the lldb 9command interpreter (we refer to this for brevity as the embedded interpreter). 10Of course, in this context it has full access to the LLDB API - with some 11additional conveniences we will call out in the FAQ. 12 13Documentation 14-------------- 15 16The LLDB API is contained in a python module named lldb. A useful resource when 17writing Python extensions is the lldb Python classes reference guide. 18 19The documentation is also accessible in an interactive debugger session with 20the following command: 21 22:: 23 24 (lldb) script help(lldb) 25 Help on package lldb: 26 27 NAME 28 lldb - The lldb module contains the public APIs for Python binding. 29 30 FILE 31 /System/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/Python/lldb/__init__.py 32 33 DESCRIPTION 34 ... 35 36You can also get help using a module class name. The full API that is exposed 37for that class will be displayed in a man page style window. Below we want to 38get help on the lldb.SBFrame class: 39 40:: 41 42 (lldb) script help(lldb.SBFrame) 43 Help on class SBFrame in module lldb: 44 45 class SBFrame(__builtin__.object) 46 | Represents one of the stack frames associated with a thread. 47 | SBThread contains SBFrame(s). For example (from test/lldbutil.py), 48 | 49 | def print_stacktrace(thread, string_buffer = False): 50 | '''Prints a simple stack trace of this thread.''' 51 | 52 ... 53 54Or you can get help using any python object, here we use the lldb.process 55object which is a global variable in the lldb module which represents the 56currently selected process: 57 58:: 59 60 (lldb) script help(lldb.process) 61 Help on SBProcess in module lldb object: 62 63 class SBProcess(__builtin__.object) 64 | Represents the process associated with the target program. 65 | 66 | SBProcess supports thread iteration. For example (from test/lldbutil.py), 67 | 68 | # ================================================== 69 | # Utility functions related to Threads and Processes 70 | # ================================================== 71 | 72 ... 73 74Embedded Python Interpreter 75--------------------------- 76 77The embedded python interpreter can be accessed in a variety of ways from 78within LLDB. The easiest way is to use the lldb command script with no 79arguments at the lldb command prompt: 80 81:: 82 83 (lldb) script 84 Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. 85 >>> 2+3 86 5 87 >>> hex(12345) 88 '0x3039' 89 >>> 90 91This drops you into the embedded python interpreter. When running under the 92script command, lldb sets some convenience variables that give you quick access 93to the currently selected entities that characterize the program and debugger 94state. In each case, if there is no currently selected entity of the 95appropriate type, the variable's IsValid method will return false. These 96variables are: 97 98+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ 99| Variable | Type | Equivalent | Description | 100+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ 101| ``lldb.debugger`` | `lldb.SBDebugger` | `SBTarget.GetDebugger` | Contains the debugger object whose ``script`` command was invoked. | 102| | | | The `lldb.SBDebugger` object owns the command interpreter | 103| | | | and all the targets in your debug session. There will always be a | 104| | | | Debugger in the embedded interpreter. | 105+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ 106| ``lldb.target`` | `lldb.SBTarget` | `SBDebugger.GetSelectedTarget` | Contains the currently selected target - for instance the one made with the | 107| | | | ``file`` or selected by the ``target select <target-index>`` command. | 108| | | `SBProcess.GetTarget` | The `lldb.SBTarget` manages one running process, and all the executable | 109| | | | and debug files for the process. | 110+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ 111| ``lldb.process`` | `lldb.SBProcess` | `SBTarget.GetProcess` | Contains the process of the currently selected target. | 112| | | | The `lldb.SBProcess` object manages the threads and allows access to | 113| | | `SBThread.GetProcess` | memory for the process. | 114+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ 115| ``lldb.thread`` | `lldb.SBThread` | `SBProcess.GetSelectedThread` | Contains the currently selected thread. | 116| | | | The `lldb.SBThread` object manages the stack frames in that thread. | 117| | | `SBFrame.GetThread` | A thread is always selected in the command interpreter when a target stops. | 118| | | | The ``thread select <thread-index>`` command can be used to change the | 119| | | | currently selected thread. So as long as you have a stopped process, there will be | 120| | | | some selected thread. | 121+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ 122| ``lldb.frame`` | `lldb.SBFrame` | `SBThread.GetSelectedFrame` | Contains the currently selected stack frame. | 123| | | | The `lldb.SBFrame` object manage the stack locals and the register set for | 124| | | | that stack. | 125| | | | A stack frame is always selected in the command interpreter when a target stops. | 126| | | | The ``frame select <frame-index>`` command can be used to change the | 127| | | | currently selected frame. So as long as you have a stopped process, there will | 128| | | | be some selected frame. | 129+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ 130 131While extremely convenient, these variables have a couple caveats that you 132should be aware of. First of all, they hold the values of the selected objects 133on entry to the embedded interpreter. They do not update as you use the LLDB 134API's to change, for example, the currently selected stack frame or thread. 135 136Moreover, they are only defined and meaningful while in the interactive Python 137interpreter. There is no guarantee on their value in any other situation, hence 138you should not use them when defining Python formatters, breakpoint scripts and 139commands (or any other Python extension point that LLDB provides). For the 140latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or 141`SBFrame` instance and you can use the functions from the "Equivalent" column 142to navigate between them. 143 144As a rationale for such behavior, consider that lldb can run in a multithreaded 145environment, and another thread might call the "script" command, changing the 146value out from under you. 147 148To get started with these objects and LLDB scripting, please note that almost 149all of the lldb Python objects are able to briefly describe themselves when you 150pass them to the Python print function: 151 152:: 153 154 (lldb) script 155 Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. 156 >>> print lldb.debugger 157 Debugger (instance: "debugger_1", id: 1) 158 >>> print lldb.target 159 a.out 160 >>> print lldb.process 161 SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out 162 >>> print lldb.thread 163 SBThread: tid = 0x1f03 164 >>> print lldb.frame 165 frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16 166 167 168Running a python script when a breakpoint gets hit 169-------------------------------------------------- 170 171One very powerful use of the lldb Python API is to have a python script run 172when a breakpoint gets hit. Adding python scripts to breakpoints provides a way 173to create complex breakpoint conditions and also allows for smart logging and 174data gathering. 175 176When your process hits a breakpoint to which you have attached some python 177code, the code is executed as the body of a function which takes three 178arguments: 179 180:: 181 182 def breakpoint_function_wrapper(frame, bp_loc, internal_dict): 183 # Your code goes here 184 185or: 186 187:: 188 189 def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict): 190 # Your code goes here 191 192 193+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 194| Argument | Type | Description | 195+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 196| ``frame`` | `lldb.SBFrame` | The current stack frame where the breakpoint got hit. | 197| | | The object will always be valid. | 198| | | This ``frame`` argument might *not* match the currently selected stack frame found in the `lldb` module global variable ``lldb.frame``. | 199+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 200| ``bp_loc`` | `lldb.SBBreakpointLocation` | The breakpoint location that just got hit. Breakpoints are represented by `lldb.SBBreakpoint` | 201| | | objects. These breakpoint objects can have one or more locations. These locations | 202| | | are represented by `lldb.SBBreakpointLocation` objects. | 203+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 204| ``extra_args`` | `lldb.SBStructuredData` | ``Optional`` If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its | 205| | | contents can parametrize this use of the callback. For instance, instead of writing a callback that stops when the caller is "Foo", | 206| | | you could take the function name from a field in the ``extra_args``, making the callback more general. The ``-k`` and ``-v`` options | 207| | | to ``breakpoint command add`` will be passed as a Dictionary in the ``extra_args`` parameter, or you can provide it with the SB API's. | 208+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 209| ``internal_dict`` | ``dict`` | The python session dictionary as a standard python dictionary object. | 210+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 211 212Optionally, a Python breakpoint command can return a value. Returning False 213tells LLDB that you do not want to stop at the breakpoint. Any other return 214value (including None or leaving out the return statement altogether) is akin 215to telling LLDB to actually stop at the breakpoint. This can be useful in 216situations where a breakpoint only needs to stop the process when certain 217conditions are met, and you do not want to inspect the program state manually 218at every stop and then continue. 219 220An example will show how simple it is to write some python code and attach it 221to a breakpoint. The following example will allow you to track the order in 222which the functions in a given shared library are first executed during one run 223of your program. This is a simple method to gather an order file which can be 224used to optimize function placement within a binary for execution locality. 225 226We do this by setting a regular expression breakpoint that will match every 227function in the shared library. The regular expression '.' will match any 228string that has at least one character in it, so we will use that. This will 229result in one lldb.SBBreakpoint object that contains an 230lldb.SBBreakpointLocation object for each function. As the breakpoint gets hit, 231we use a counter to track the order in which the function at this particular 232breakpoint location got hit. Since our code is passed the location that was 233hit, we can get the name of the function from the location, disable the 234location so we won't count this function again; then log some info and continue 235the process. 236 237Note we also have to initialize our counter, which we do with the simple 238one-line version of the script command. 239 240Here is the code: 241 242:: 243 244 (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib 245 Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 246 (lldb) script counter = 0 247 (lldb) breakpoint command add --script-type python 1 248 Enter your Python command(s). Type 'DONE' to end. 249 > # Increment our counter. Since we are in a function, this must be a global python variable 250 > global counter 251 > counter += 1 252 > # Get the name of the function 253 > name = frame.GetFunctionName() 254 > # Print the order and the function name 255 > print '[%i] %s' % (counter, name) 256 > # Disable the current breakpoint location so it doesn't get hit again 257 > bp_loc.SetEnabled(False) 258 > # No need to stop here 259 > return False 260 > DONE 261 262The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command: 263 264:: 265 266 (lldb) breakpoint command delete 1 267 268 269Using the python api's to create custom breakpoints 270--------------------------------------------------- 271 272 273Another use of the Python API's in lldb is to create a custom breakpoint 274resolver. This facility was added in r342259. 275 276It allows you to provide the algorithm which will be used in the breakpoint's 277search of the space of the code in a given Target to determine where to set the 278breakpoint locations - the actual places where the breakpoint will trigger. To 279understand how this works you need to know a little about how lldb handles 280breakpoints. 281 282In lldb, a breakpoint is composed of three parts: the Searcher, the Resolver, 283and the Stop Options. The Searcher and Resolver cooperate to determine how 284breakpoint locations are set and differ between each breakpoint type. Stop 285options determine what happens when a location triggers and includes the 286commands, conditions, ignore counts, etc. Stop options are common between all 287breakpoint types, so for our purposes only the Searcher and Resolver are 288relevant. 289 290The Searcher's job is to traverse in a structured way the code in the current 291target. It proceeds from the Target, to search all the Modules in the Target, 292in each Module it can recurse into the Compile Units in that module, and within 293each Compile Unit it can recurse over the Functions it contains. 294 295The Searcher can be provided with a SearchFilter that it will use to restrict 296this search. For instance, if the SearchFilter specifies a list of Modules, the 297Searcher will not recurse into Modules that aren't on the list. When you pass 298the -s modulename flag to break set you are creating a Module-based search 299filter. When you pass -f filename.c to break set -n you are creating a file 300based search filter. If neither of these is specified, the breakpoint will have 301a no-op search filter, so all parts of the program are searched and all 302locations accepted. 303 304The Resolver has two functions. The most important one is the callback it 305provides. This will get called at the appropriate time in the course of the 306search. The callback is where the job of adding locations to the breakpoint 307gets done. 308 309The other function is specifying to the Searcher at what depth in the above 310described recursion it wants to be called. Setting a search depth also provides 311a stop for the recursion. For instance, if you request a Module depth search, 312then the callback will be called for each Module as it gets added to the 313Target, but the searcher will not recurse into the Compile Units in the module. 314 315One other slight subtlety is that the depth at which you get called back is not 316necessarily the depth at which the SearchFilter is specified. For instance, 317if you are doing symbol searches, it is convenient to use the Module depth for 318the search, since symbols are stored in the module. But the SearchFilter might 319specify some subset of CompileUnits, so not all the symbols you might find in 320each module will pass the search. You don't need to handle this situation 321yourself, since SBBreakpoint::AddLocation will only add locations that pass the 322Search Filter. This API returns an SBError to inform you whether your location 323was added. 324 325When the breakpoint is originally created, its Searcher will process all the 326currently loaded modules. The Searcher will also visit any new modules as they 327are added to the target. This happens, for instance, when a new shared library 328gets added to the target in the course of running, or on rerunning if any of 329the currently loaded modules have been changed. Note, in the latter case, all 330the locations set in the old module will get deleted and you will be asked to 331recreate them in the new version of the module when your callback gets called 332with that module. For this reason, you shouldn't try to manage the locations 333you add to the breakpoint yourself. Note that the Breakpoint takes care of 334deduplicating equal addresses in AddLocation, so you shouldn't need to worry 335about that anyway. 336 337At present, when adding a scripted Breakpoint type, you can only provide a 338custom Resolver, not a custom SearchFilter. 339 340The custom Resolver is provided as a Python class with the following methods: 341 342+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 343| Name | Arguments | Description | 344+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 345| ``__init__`` | ``bkpt``:`lldb.SBBreakpoint` | This is the constructor for the new Resolver. | 346| | ``extra_args``:`lldb.SBStructuredData`| | 347| | | | 348| | | ``bkpt`` is the breakpoint owning this Resolver. | 349| | | | 350| | | | 351| | | ``extra_args`` is an `SBStructuredData` object that the user can pass in when creating instances of this | 352| | | breakpoint. It is not required, but is quite handy. For instance if you were implementing a breakpoint on some | 353| | | symbol name, you could write a generic symbol name based Resolver, and then allow the user to pass | 354| | | in the particular symbol in the extra_args | 355+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 356| ``__callback__`` | ``sym_ctx``:`lldb.SBSymbolContext` | This is the Resolver callback. | 357| | | The ``sym_ctx`` argument will be filled with the current stage | 358| | | of the search. | 359| | | | 360| | | | 361| | | For instance, if you asked for a search depth of lldb.eSearchDepthCompUnit, then the | 362| | | target, module and compile_unit fields of the sym_ctx will be filled. The callback should look just in the | 363| | | context passed in ``sym_ctx`` for new locations. If the callback finds an address of interest, it | 364| | | can add it to the breakpoint with the `SBBreakpoint.AddLocation` method, using the breakpoint passed | 365| | | in to the ``__init__`` method. | 366+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 367| ``__get_depth__`` | ``None`` | Specify the depth at which you wish your callback to get called. The currently supported options are: | 368| | | | 369| | | `lldb.eSearchDepthModule` | 370| | | `lldb.eSearchDepthCompUnit` | 371| | | `lldb.eSearchDepthFunction` | 372| | | | 373| | | For instance, if you are looking | 374| | | up symbols, which are stored at the Module level, you will want to get called back module by module. | 375| | | So you would want to return `lldb.eSearchDepthModule`. This method is optional. If not provided the search | 376| | | will be done at Module depth. | 377+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 378| ``get_short_help`` | ``None`` | This is an optional method. If provided, the returned string will be printed at the beginning of | 379| | | the description for this breakpoint. | 380+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 381 382To define a new breakpoint command defined by this class from the lldb command 383line, use the command: 384 385:: 386 387 (lldb) breakpoint set -P MyModule.MyResolverClass 388 389You can also populate the extra_args SBStructuredData with a dictionary of 390key/value pairs with: 391 392:: 393 394 (lldb) breakpoint set -P MyModule.MyResolverClass -k key_1 -v value_1 -k key_2 -v value_2 395 396Although you can't write a scripted SearchFilter, both the command line and the 397SB API's for adding a scripted resolver allow you to specify a SearchFilter 398restricted to certain modules or certain compile units. When using the command 399line to create the resolver, you can specify a Module specific SearchFilter by 400passing the -s ModuleName option - which can be specified multiple times. You 401can also specify a SearchFilter restricted to certain compile units by passing 402in the -f CompUnitName option. This can also be specified more than once. And 403you can mix the two to specify "this comp unit in this module". So, for 404instance, 405 406:: 407 408 (lldb) breakpoint set -P MyModule.MyResolverClass -s a.out 409 410will use your resolver, but will only recurse into or accept new locations in 411the module a.out. 412 413Another option for creating scripted breakpoints is to use the 414SBTarget.CreateBreakpointFromScript API. This one has the advantage that you 415can pass in an arbitrary SBStructuredData object, so you can create more 416complex parametrizations. SBStructuredData has a handy SetFromJSON method which 417you can use for this purpose. Your __init__ function gets passed this 418SBStructuredData object. This API also allows you to directly provide the list 419of Modules and the list of CompileUnits that will make up the SearchFilter. If 420you pass in empty lists, the breakpoint will use the default "search 421everywhere,accept everything" filter. 422 423Using the python API' to create custom stepping logic 424----------------------------------------------------- 425 426A slightly esoteric use of the Python API's is to construct custom stepping 427types. LLDB's stepping is driven by a stack of "thread plans" and a fairly 428simple state machine that runs the plans. You can create a Python class that 429works as a thread plan, and responds to the requests the state machine makes to 430run its operations. 431 432There is a longer discussion of scripted thread plans and the state machine, 433and several interesting examples of their use in: 434 435https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/scripted_step.py 436 437And for a MUCH fuller discussion of the whole state machine, see: 438 439https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Target/ThreadPlan.h 440 441If you are reading those comments it is useful to know that scripted thread 442plans are set to be "ControllingPlans", and not "OkayToDiscard". 443 444To implement a scripted step, you define a python class that has the following 445methods: 446 447+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 448| Name | Arguments | Description | 449+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 450| ``__init__`` | ``thread_plan``:`lldb.SBThreadPlan`| This is the underlying `SBThreadPlan` that is pushed onto the plan stack. | 451| | | You will want to store this away in an ivar. Also, if you are going to | 452| | | use one of the canned thread plans, you can queue it at this point. | 453+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 454| ``explains_stop`` | ``event``: `lldb.SBEvent` | Return True if this stop is part of your thread plans logic, false otherwise. | 455+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 456| ``is_stale`` | ``None`` | If your plan is no longer relevant (for instance, you were | 457| | | stepping in a particular stack frame, but some other operation | 458| | | pushed that frame off the stack) return True and your plan will | 459| | | get popped. | 460+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 461| ``should_step`` | ``None`` | Return ``True`` if you want lldb to instruction step one instruction, | 462| | | or False to continue till the next breakpoint is hit. | 463+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 464| ``should_stop`` | ``event``: `lldb.SBEvent` | If your plan wants to stop and return control to the user at this point, return True. | 465| | | If your plan is done at this point, call SetPlanComplete on your | 466| | | thread plan instance. | 467| | | Also, do any work you need here to set up the next stage of stepping. | 468+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 469 470To use this class to implement a step, use the command: 471 472:: 473 474 (lldb) thread step-scripted -C MyModule.MyStepPlanClass 475 476Or use the SBThread.StepUsingScriptedThreadPlan API. The SBThreadPlan passed 477into your __init__ function can also push several common plans (step 478in/out/over and run-to-address) in front of itself on the stack, which can be 479used to compose more complex stepping operations. When you use subsidiary plans 480your explains_stop and should_stop methods won't get called until the 481subsidiary plan is done, or the process stops for an event the subsidiary plan 482doesn't explain. For instance, step over plans don't explain a breakpoint hit 483while performing the step-over. 484 485 486Create a new lldb command using a Python function 487------------------------------------------------- 488 489Python functions can be used to create new LLDB command interpreter commands, 490which will work like all the natively defined lldb commands. This provides a 491very flexible and easy way to extend LLDB to meet your debugging requirements. 492 493To write a python function that implements a new LLDB command define the 494function to take five arguments as follows: 495 496:: 497 498 def command_function(debugger, command, exe_ctx, result, internal_dict): 499 # Your code goes here 500 501The meaning of the arguments is given in the table below. 502 503If you provide a Python docstring in your command function LLDB will use it 504when providing "long help" for your command, as in: 505 506:: 507 508 def command_function(debugger, command, result, internal_dict): 509 """This command takes a lot of options and does many fancy things""" 510 # Your code goes here 511 512though providing help can also be done programmatically (see below). 513 514Prior to lldb 3.5.2 (April 2015), LLDB Python command definitions didn't take the SBExecutionContext 515argument. So you may still see commands where the command definition is: 516 517:: 518 519 def command_function(debugger, command, result, internal_dict): 520 # Your code goes here 521 522Using this form is strongly discouraged because it can only operate on the "currently selected" 523target, process, thread, frame. The command will behave as expected when run 524directly on the command line. But if the command is used in a stop-hook, breakpoint 525callback, etc. where the response to the callback determines whether we will select 526this or that particular process/frame/thread, the global "currently selected" 527entity is not necessarily the one the callback is meant to handle. In that case, this 528command definition form can't do the right thing. 529 530+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 531| Argument | Type | Description | 532+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 533| ``debugger`` | `lldb.SBDebugger` | The current debugger object. | 534+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 535| ``command`` | ``python string`` | A python string containing all arguments for your command. If you need to chop up the arguments | 536| | | try using the ``shlex`` module's ``shlex.split(command)`` to properly extract the | 537| | | arguments. | 538+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 539| ``exe_ctx`` | `lldb.SBExecutionContext` | An execution context object carrying around information on the inferior process' context in which the command is expected to act | 540| | | | 541| | | *Optional since lldb 3.5.2, unavailable before* | 542+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 543| ``result`` | `lldb.SBCommandReturnObject` | A return object which encapsulates success/failure information for the command and output text | 544| | | that needs to be printed as a result of the command. The plain Python "print" command also works but | 545| | | text won't go in the result by default (it is useful as a temporary logging facility). | 546+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 547| ``internal_dict`` | ``python dict object`` | The dictionary for the current embedded script session which contains all variables | 548| | | and functions. | 549+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 550 551Since lldb 3.7, Python commands can also be implemented by means of a class 552which should implement the following interface: 553 554.. code-block:: python 555 556 class CommandObjectType: 557 def __init__(self, debugger, internal_dict): 558 this call should initialize the command with respect to the command interpreter for the passed-in debugger 559 def __call__(self, debugger, command, exe_ctx, result): 560 this is the actual bulk of the command, akin to Python command functions 561 def get_short_help(self): 562 this call should return the short help text for this command[1] 563 def get_long_help(self): 564 this call should return the long help text for this command[1] 565 def get_flags(self): 566 this will be called when the command is added to the command interpreter, 567 and should return a flag field made from or-ing together the appropriate 568 elements of the lldb.CommandFlags enum to specify the requirements of this command. 569 The CommandInterpreter will make sure all these requirements are met, and will 570 return the standard lldb error if they are not.[1] 571 def get_repeat_command(self, command): 572 The auto-repeat command is what will get executed when the user types just 573 a return at the next prompt after this command is run. Even if your command 574 was run because it was specified as a repeat command, that invocation will still 575 get asked for IT'S repeat command, so you can chain a series of repeats, for instance 576 to implement a pager. 577 578 The command argument is the command that is about to be executed. 579 580 If this call returns None, then the ordinary repeat mechanism will be used 581 If this call returns an empty string, then auto-repeat is disabled 582 If this call returns any other string, that will be the repeat command [1] 583 584[1] This method is optional. 585 586As a convenience, you can treat the result object as a Python file object, and 587say 588 589.. code-block:: python 590 591 print >>result, "my command does lots of cool stuff" 592 593SBCommandReturnObject and SBStream both support this file-like behavior by 594providing write() and flush() calls at the Python layer. 595 596The commands that are added using this class definition are what lldb calls 597"raw" commands. The command interpreter doesn't attempt to parse the command, 598doesn't handle option values, neither generating help for them, or their 599completion. Raw commands are useful when the arguments passed to the command 600are unstructured, and having to protect them against lldb command parsing would 601be onerous. For instance, "expr" is a raw command. 602 603You can also add scripted commands that implement the "parsed command", where 604the options and their types are specified, as well as the argument and argument 605types. These commands look and act like the majority of lldb commands, and you 606can also add custom completions for the options and/or the arguments if you have 607special needs. 608 609The easiest way to do this is to derive your new command from the lldb.ParsedCommand 610class. That responds in the same way to the help & repeat command interfaces, and 611provides some convenience methods, and most importantly an LLDBOptionValueParser, 612accessed throught lldb.ParsedCommand.get_parser(). The parser is used to set 613your command definitions, and to retrieve option values in the __call__ method. 614 615To set up the command definition, implement the ParsedCommand abstract method: 616 617.. code-block:: python 618 619 def setup_command_definition(self): 620 621This is called when your command is added to lldb. In this method you add the 622options and their types, the option help strings, etc. to the command using the API: 623 624.. code-block:: python 625 626 def add_option(self, short_option, long_option, help, default, 627 dest = None, required=False, groups = None, 628 value_type=lldb.eArgTypeNone, completion_type=None, 629 enum_values=None): 630 """ 631 short_option: one character, must be unique, not required 632 long_option: no spaces, must be unique, required 633 help: a usage string for this option, will print in the command help 634 default: the initial value for this option (if it has a value) 635 dest: the name of the property that gives you access to the value for 636 this value. Defaults to the long option if not provided. 637 required: if true, this option must be provided or the command will error out 638 groups: Which "option groups" does this option belong to. This can either be 639 a simple list (e.g. [1, 3, 4, 5]) or you can specify ranges by sublists: 640 so [1, [3,5]] is the same as [1, 3, 4, 5]. 641 value_type: one of the lldb.eArgType enum values. Some of the common arg 642 types also have default completers, which will be applied automatically. 643 completion_type: currently these are values form the lldb.CompletionType enum. If 644 you need custom completions, implement handle_option_argument_completion. 645 enum_values: An array of duples: ["element_name", "element_help"]. If provided, 646 only one of the enum elements is allowed. The value will be the 647 element_name for the chosen enum element as a string. 648 """ 649 650Similarly, you can add argument types to the command: 651 652.. code-block:: python 653 654 def make_argument_element(self, arg_type, repeat = "optional", groups = None): 655 """ 656 arg_type: The argument type, one of the lldb.eArgType enum values. 657 repeat: Choose from the following options: 658 "plain" - one value 659 "optional" - zero or more values 660 "plus" - one or more values 661 groups: As with add_option. 662 """ 663 664Then implement the body of the command by defining: 665 666.. code-block:: python 667 668 def __call__(self, debugger, args_array, exe_ctx, result): 669 """This is the command callback. The option values are 670 provided by the 'dest' properties on the parser. 671 672 args_array: This is the list of arguments provided. 673 exe_ctx: Gives the SBExecutionContext on which the 674 command should operate. 675 result: Any results of the command should be 676 written into this SBCommandReturnObject. 677 """ 678 679This differs from the "raw" command's __call__ in that the arguments are already 680parsed into the args_array, and the option values are set in the parser, and 681can be accessed using their property name. The LLDBOptionValueParser class has 682a couple of other handy methods: 683 684.. code-block:: python 685 def was_set(self, long_option_name): 686 687returns True if the option was specified on the command line. 688 689.. code-block:: python 690 691 def dest_for_option(self, long_option_name): 692 """ 693 This will return the value of the dest variable you defined for opt_name. 694 Mostly useful for handle_completion where you get passed the long option. 695 """ 696 697lldb will handle completing your option names, and all your enum values 698automatically. If your option or argument types have associated built-in completers, 699then lldb will also handle that completion for you. But if you have a need for 700custom completions, either in your arguments or option values, you can handle 701completion by hand as well. To handle completion of option value arguments, 702your lldb.ParsedCommand subclass should implement: 703 704.. code-block:: python 705 706 def handle_option_argument_completion(self, long_option, cursor_pos): 707 """ 708 long_option: The long option name of the option whose value you are 709 asked to complete. 710 cursor_pos: The cursor position in the value for that option - which 711 you can get from the option parser. 712 """ 713 714And to handle the completion of arguments: 715 716.. code-block:: python 717 718 def handle_argument_completion(self, args, arg_pos, cursor_pos): 719 """ 720 args: A list of the arguments to the command 721 arg_pos: An index into the args list of the argument with the cursor 722 cursor_pos: The cursor position in the arg specified by arg_pos 723 """ 724 725When either of these API's is called, the command line will have been parsed up to 726the word containing the cursor, and any option values set in that part of the command 727string are available from the option value parser. That's useful for instance 728if you have a --shared-library option that would constrain the completions for, 729say, a symbol name option or argument. 730 731The return value specifies what the completion options are. You have four 732choices: 733 734- `True`: the completion was handled with no completions. 735 736- `False`: the completion was not handled, forward it to the regular 737completion machinery. 738 739- A dictionary with the key: "completion": there is one candidate, 740whose value is the value of the "completion" key. Optionally you can pass a 741"mode" key whose value is either "partial" or "complete". Return partial if 742the "completion" string is a prefix for all the completed value. 743 744For instance, if the string you are completing is "Test" and the available completions are: 745"Test1", "Test11" and "Test111", you should return the dictionary: 746 747.. code-block:: python 748 749 return {"completion": "Test1", "mode" : "partial"} 750 751and then lldb will add the "1" at the curson and advance it after the added string, 752waiting for more completions. But if "Test1" is the only completion, return: 753 754.. code-block:: python 755 756 {"completion": "Test1", "mode": "complete"} 757 758and lldb will add "1 " at the cursor, indicating the command string is complete. 759 760The default is "complete", you don't need to specify a "mode" in that case. 761 762- A dictionary with the key: "values" whose value is a list of candidate completion 763strings. The command interpreter will present those strings as the available choices. 764You can optionally include a "descriptions" key, whose value is a parallel array 765of description strings, and the completion will show the description next to 766each completion. 767 768 769One other handy convenience when defining lldb command-line commands is the 770command "command script import" which will import a module specified by file 771path, so you don't have to change your PYTHONPATH for temporary scripts. It 772also has another convenience that if your new script module has a function of 773the form: 774 775.. code-block python 776 777 def __lldb_init_module(debugger, internal_dict): 778 # Command Initialization code goes here 779 780where debugger and internal_dict are as above, that function will get run when 781the module is loaded allowing you to add whatever commands you want into the 782current debugger. Note that this function will only be run when using the LLDB 783command ``command script import``, it will not get run if anyone imports your 784module from another module. 785 786The standard test for ``__main__``, like many python modules do, is useful for 787creating scripts that can be run from the command line. However, for command 788line scripts, the debugger instance must be created manually. Sample code would 789look like: 790 791.. code-block:: python 792 793 if __name__ == '__main__': 794 # Initialize the debugger before making any API calls. 795 lldb.SBDebugger.Initialize() 796 # Create a new debugger instance in your module if your module 797 # can be run from the command line. When we run a script from 798 # the command line, we won't have any debugger object in 799 # lldb.debugger, so we can just create it if it will be needed 800 debugger = lldb.SBDebugger.Create() 801 802 # Next, do whatever work this module should do when run as a command. 803 # ... 804 805 # Finally, dispose of the debugger you just made. 806 lldb.SBDebugger.Destroy(debugger) 807 # Terminate the debug session 808 lldb.SBDebugger.Terminate() 809 810 811Now we can create a module called ls.py in the file ~/ls.py that will implement 812a function that can be used by LLDB's python command code: 813 814.. code-block:: python 815 816 #!/usr/bin/env python 817 818 import lldb 819 import commands 820 import optparse 821 import shlex 822 823 def ls(debugger, command, result, internal_dict): 824 print >>result, (commands.getoutput('/bin/ls %s' % command)) 825 826 # And the initialization code to add your commands 827 def __lldb_init_module(debugger, internal_dict): 828 debugger.HandleCommand('command script add -f ls.ls ls') 829 print 'The "ls" python command has been installed and is ready for use.' 830 831Now we can load the module into LLDB and use it 832 833:: 834 835 $ lldb 836 (lldb) command script import ~/ls.py 837 The "ls" python command has been installed and is ready for use. 838 (lldb) ls -l /tmp/ 839 total 365848 840 -rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store 841 -rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log 842 843You can also make "container" commands to organize the commands you are adding to 844lldb. Most of the lldb built-in commands structure themselves this way, and using 845a tree structure has the benefit of leaving the one-word command space free for user 846aliases. It can also make it easier to find commands if you are adding more than 847a few of them. Here's a trivial example of adding two "utility" commands into a 848"my-utilities" container: 849 850:: 851 852 #!/usr/bin/env python 853 854 import lldb 855 856 def first_utility(debugger, command, result, internal_dict): 857 print("I am the first utility") 858 859 def second_utility(debugger, command, result, internal_dict): 860 print("I am the second utility") 861 862 # And the initialization code to add your commands 863 def __lldb_init_module(debugger, internal_dict): 864 debugger.HandleCommand('command container add -h "A container for my utilities" my-utilities') 865 debugger.HandleCommand('command script add -f my_utilities.first_utility -h "My first utility" my-utilities first') 866 debugger.HandleCommand('command script add -f my_utilities.second_utility -h "My second utility" my-utilities second') 867 print('The "my-utilities" python command has been installed and its subcommands are ready for use.') 868 869Then your new commands are available under the my-utilities node: 870 871:: 872 873 (lldb) help my-utilities 874 A container for my utilities 875 876 Syntax: my-utilities 877 878 The following subcommands are supported: 879 880 first -- My first utility Expects 'raw' input (see 'help raw-input'.) 881 second -- My second utility Expects 'raw' input (see 'help raw-input'.) 882 883 For more help on any particular subcommand, type 'help <command> <subcommand>'. 884 (lldb) my-utilities first 885 I am the first utility 886 887 888A more interesting template has been created in the source repository that can 889help you to create lldb command quickly: 890 891https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/cmdtemplate.py 892 893A commonly required facility is being able to create a command that does some 894token substitution, and then runs a different debugger command (usually, it 895po'es the result of an expression evaluated on its argument). For instance, 896given the following program: 897 898:: 899 900 #import <Foundation/Foundation.h> 901 NSString* 902 ModifyString(NSString* src) 903 { 904 return [src stringByAppendingString:@"foobar"]; 905 } 906 907 int main() 908 { 909 NSString* aString = @"Hello world"; 910 NSString* anotherString = @"Let's be friends"; 911 return 1; 912 } 913 914you may want a pofoo X command, that equates po [ModifyString(X) 915capitalizedString]. The following debugger interaction shows how to achieve 916that goal: 917 918:: 919 920 (lldb) script 921 Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. 922 >>> def pofoo_funct(debugger, command, result, internal_dict): 923 ... cmd = "po [ModifyString(" + command + ") capitalizedString]" 924 ... debugger.HandleCommand(cmd) 925 ... 926 >>> ^D 927 (lldb) command script add pofoo -f pofoo_funct 928 (lldb) pofoo aString 929 $1 = 0x000000010010aa00 Hello Worldfoobar 930 (lldb) pofoo anotherString 931 $2 = 0x000000010010aba0 Let's Be Friendsfoobar 932 933Using the lldb.py module in Python 934---------------------------------- 935 936LLDB has all of its core code build into a shared library which gets used by 937the `lldb` command line application. On macOS this shared library is a 938framework: LLDB.framework and on other unix variants the program is a shared 939library: lldb.so. LLDB also provides an lldb.py module that contains the 940bindings from LLDB into Python. To use the LLDB.framework to create your own 941stand-alone python programs, you will need to tell python where to look in 942order to find this module. This is done by setting the PYTHONPATH environment 943variable, adding a path to the directory that contains the lldb.py python 944module. The lldb driver program has an option to report the path to the lldb 945module. You can use that to point to correct lldb.py: 946 947For csh and tcsh: 948 949:: 950 951 % setenv PYTHONPATH `lldb -P` 952 953For sh and bash: 954 955:: 956 957 $ export PYTHONPATH=`lldb -P` 958 959Alternately, you can append the LLDB Python directory to the sys.path list 960directly in your Python code before importing the lldb module. 961 962Now your python scripts are ready to import the lldb module. Below is a python 963script that will launch a program from the current working directory called 964"a.out", set a breakpoint at "main", and then run and hit the breakpoint, and 965print the process, thread and frame objects if the process stopped: 966 967:: 968 969 #!/usr/bin/env python 970 971 import lldb 972 import os 973 974 def disassemble_instructions(insts): 975 for i in insts: 976 print i 977 978 # Set the path to the executable to debug 979 exe = "./a.out" 980 981 # Create a new debugger instance 982 debugger = lldb.SBDebugger.Create() 983 984 # When we step or continue, don't return from the function until the process 985 # stops. Otherwise we would have to handle the process events ourselves which, while doable is 986 #a little tricky. We do this by setting the async mode to false. 987 debugger.SetAsync (False) 988 989 # Create a target from a file and arch 990 print "Creating a target for '%s'" % exe 991 992 target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT) 993 994 if target: 995 # If the target is valid set a breakpoint at main 996 main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename()); 997 998 print main_bp 999 1000 # Launch the process. Since we specified synchronous mode, we won't return 1001 # from this function until we hit the breakpoint at main 1002 process = target.LaunchSimple (None, None, os.getcwd()) 1003 1004 # Make sure the launch went ok 1005 if process: 1006 # Print some simple process info 1007 state = process.GetState () 1008 print process 1009 if state == lldb.eStateStopped: 1010 # Get the first thread 1011 thread = process.GetThreadAtIndex (0) 1012 if thread: 1013 # Print some simple thread info 1014 print thread 1015 # Get the first frame 1016 frame = thread.GetFrameAtIndex (0) 1017 if frame: 1018 # Print some simple frame info 1019 print frame 1020 function = frame.GetFunction() 1021 # See if we have debug info (a function) 1022 if function: 1023 # We do have a function, print some info for the function 1024 print function 1025 # Now get all instructions for this function and print them 1026 insts = function.GetInstructions(target) 1027 disassemble_instructions (insts) 1028 else: 1029 # See if we have a symbol in the symbol table for where we stopped 1030 symbol = frame.GetSymbol(); 1031 if symbol: 1032 # We do have a symbol, print some info for the symbol 1033 print symbol 1034 1035Writing lldb frame recognizers in Python 1036---------------------------------------- 1037 1038Frame recognizers allow for retrieving information about special frames based 1039on ABI, arguments or other special properties of that frame, even without 1040source code or debug info. Currently, one use case is to extract function 1041arguments that would otherwise be inaccessible, or augment existing arguments. 1042 1043Adding a custom frame recognizer is done by implementing a Python class and 1044using the 'frame recognizer add' command. The Python class should have a 1045'get_recognized_arguments' method and it will receive an argument of type 1046lldb.SBFrame representing the current frame that we are trying to recognize. 1047The method should return a (possibly empty) list of lldb.SBValue objects that 1048represent the recognized arguments. 1049 1050An example of a recognizer that retrieves the file descriptor values from libc 1051functions 'read', 'write' and 'close' follows: 1052 1053:: 1054 1055 class LibcFdRecognizer(object): 1056 def get_recognized_arguments(self, frame): 1057 if frame.name in ["read", "write", "close"]: 1058 fd = frame.EvaluateExpression("$arg1").unsigned 1059 target = frame.thread.process.target 1060 value = target.CreateValueFromExpression("fd", "(int)%d" % fd) 1061 return [value] 1062 return [] 1063 1064The file containing this implementation can be imported via ``command script import`` 1065and then we can register this recognizer with ``frame recognizer add``. 1066It's important to restrict the recognizer to the libc library (which is 1067libsystem_kernel.dylib on macOS) to avoid matching functions with the same name 1068in other modules: 1069 1070:: 1071 1072 (lldb) command script import .../fd_recognizer.py 1073 (lldb) frame recognizer add -l fd_recognizer.LibcFdRecognizer -n read -s libsystem_kernel.dylib 1074 1075When the program is stopped at the beginning of the 'read' function in libc, we can view the recognizer arguments in 'frame variable': 1076 1077:: 1078 1079 (lldb) b read 1080 (lldb) r 1081 Process 1234 stopped 1082 * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3 1083 frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read 1084 (lldb) frame variable 1085 (int) fd = 3 1086 1087Writing Target Stop-Hooks in Python 1088----------------------------------- 1089 1090Stop hooks fire whenever the process stops just before control is returned to the 1091user. Stop hooks can either be a set of lldb command-line commands, or can 1092be implemented by a suitably defined Python class. The Python based stop-hooks 1093can also be passed as set of -key -value pairs when they are added, and those 1094will get packaged up into a SBStructuredData Dictionary and passed to the 1095constructor of the Python object managing the stop hook. This allows for 1096parametrization of the stop hooks. 1097 1098To add a Python-based stop hook, first define a class with the following methods: 1099 1100+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 1101| Name | Arguments | Description | 1102+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 1103| ``__init__`` | ``target: lldb.SBTarget`` | This is the constructor for the new stop-hook. | 1104| | ``extra_args: lldb.SBStructuredData`` | | 1105| | | | 1106| | | ``target`` is the SBTarget to which the stop hook is added. | 1107| | | | 1108| | | ``extra_args`` is an SBStructuredData object that the user can pass in when creating instances of this | 1109| | | breakpoint. It is not required, but allows for reuse of stop-hook classes. | 1110+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 1111| ``handle_stop`` | ``exe_ctx: lldb.SBExecutionContext`` | This is the called when the target stops. | 1112| | ``stream: lldb.SBStream`` | | 1113| | | ``exe_ctx`` argument will be filled with the current stop point for which the stop hook is | 1114| | | being evaluated. | 1115| | | | 1116| | | ``stream`` an lldb.SBStream, anything written to this stream will be written to the debugger console. | 1117| | | | 1118| | | The return value is a "Should Stop" vote from this thread. If the method returns either True or no return | 1119| | | this thread votes to stop. If it returns False, then the thread votes to continue after all the stop-hooks | 1120| | | are evaluated. | 1121| | | Note, the --auto-continue flag to 'target stop-hook add' overrides a True return value from the method. | 1122+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 1123 1124To use this class in lldb, run the command: 1125 1126:: 1127 1128 (lldb) command script import MyModule.py 1129 (lldb) target stop-hook add -P MyModule.MyStopHook -k first -v 1 -k second -v 2 1130 1131where MyModule.py is the file containing the class definition MyStopHook. 1132