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 13.. contents:: 14 :local: 15 16Documentation 17-------------- 18 19The LLDB API is contained in a python module named lldb. A useful resource when 20writing Python extensions is the lldb Python classes reference guide. 21 22The documentation is also accessible in an interactive debugger session with 23the following command: 24 25:: 26 27 (lldb) script help(lldb) 28 Help on package lldb: 29 30 NAME 31 lldb - The lldb module contains the public APIs for Python binding. 32 33 FILE 34 /System/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/Python/lldb/__init__.py 35 36 DESCRIPTION 37 ... 38 39You can also get help using a module class name. The full API that is exposed 40for that class will be displayed in a man page style window. Below we want to 41get help on the lldb.SBFrame class: 42 43:: 44 45 (lldb) script help(lldb.SBFrame) 46 Help on class SBFrame in module lldb: 47 48 class SBFrame(__builtin__.object) 49 | Represents one of the stack frames associated with a thread. 50 | SBThread contains SBFrame(s). For example (from test/lldbutil.py), 51 | 52 | def print_stacktrace(thread, string_buffer = False): 53 | '''Prints a simple stack trace of this thread.''' 54 | 55 ... 56 57Or you can get help using any python object, here we use the lldb.process 58object which is a global variable in the lldb module which represents the 59currently selected process: 60 61:: 62 63 (lldb) script help(lldb.process) 64 Help on SBProcess in module lldb object: 65 66 class SBProcess(__builtin__.object) 67 | Represents the process associated with the target program. 68 | 69 | SBProcess supports thread iteration. For example (from test/lldbutil.py), 70 | 71 | # ================================================== 72 | # Utility functions related to Threads and Processes 73 | # ================================================== 74 | 75 ... 76 77Embedded Python Interpreter 78--------------------------- 79 80The embedded python interpreter can be accessed in a variety of ways from 81within LLDB. The easiest way is to use the lldb command script with no 82arguments at the lldb command prompt: 83 84:: 85 86 (lldb) script 87 Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. 88 >>> 2+3 89 5 90 >>> hex(12345) 91 '0x3039' 92 >>> 93 94This drops you into the embedded python interpreter. When running under the 95script command, lldb sets some convenience variables that give you quick access 96to the currently selected entities that characterize the program and debugger 97state. In each case, if there is no currently selected entity of the 98appropriate type, the variable's IsValid method will return false. These 99variables are: 100 101+-------------------+---------------------+-------------------------------------------------------------------------------------+ 102| Variable | Type | Description | 103+-------------------+---------------------+-------------------------------------------------------------------------------------+ 104| **lldb.debugger** | **lldb.SBDebugger** | Contains the debugger object whose **script** command was invoked. | 105| | | The **lldb.SBDebugger** object owns the command interpreter | 106| | | and all the targets in your debug session. There will always be a | 107| | | Debugger in the embedded interpreter. | 108+-------------------+---------------------+-------------------------------------------------------------------------------------+ 109| **lldb.target** | **lldb.SBTarget** | Contains the currently selected target - for instance the one made with the | 110| | | **file** or selected by the **target select <target-index>** command. | 111| | | The **lldb.SBTarget** manages one running process, and all the executable | 112| | | and debug files for the process. | 113+-------------------+---------------------+-------------------------------------------------------------------------------------+ 114| **lldb.process** | **lldb.SBProcess** | Contains the process of the currently selected target. | 115| | | The **lldb.SBProcess** object manages the threads and allows access to | 116| | | memory for the process. | 117+-------------------+---------------------+-------------------------------------------------------------------------------------+ 118| **lldb.thread** | **lldb.SBThread** | Contains the currently selected thread. | 119| | | The **lldb.SBThread** object manages the stack frames in that thread. | 120| | | A thread is always selected in the command interpreter when a target stops. | 121| | | The **thread select <thread-index>** command can be used to change the | 122| | | currently selected thread. So as long as you have a stopped process, there will be | 123| | | some selected thread. | 124+-------------------+---------------------+-------------------------------------------------------------------------------------+ 125| **lldb.frame** | **lldb.SBFrame** | Contains the currently selected stack frame. | 126| | | The **lldb.SBFrame** object manage the stack locals and the register set for | 127| | | that stack. | 128| | | A stack frame is always selected in the command interpreter when a target stops. | 129| | | The **frame select <frame-index>** command can be used to change the | 130| | | currently selected frame. So as long as you have a stopped process, there will | 131| | | be some selected frame. | 132+-------------------+---------------------+-------------------------------------------------------------------------------------+ 133 134 135While extremely convenient, these variables have a couple caveats that you 136should be aware of. First of all, they hold the values of the selected objects 137on entry to the embedded interpreter. They do not update as you use the LLDB 138API's to change, for example, the currently selected stack frame or thread. 139 140Moreover, they are only defined and meaningful while in the interactive Python 141interpreter. There is no guarantee on their value in any other situation, hence 142you should not use them when defining Python formatters, breakpoint scripts and 143commands (or any other Python extension point that LLDB provides). As a 144rationale 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, dict): 183 # Your code goes here 184 185 186+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 187| Argument | Type | Description | 188+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 189| **frame** | **lldb.SBFrame** | The current stack frame where the breakpoint got hit. | 190| | | The object will always be valid. | 191| | | This **frame** argument might *not* match the currently selected stack frame found in the **lldb** module global variable **lldb.frame**. | 192+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 193| **bp_loc** | **lldb.SBBreakpointLocation** | The breakpoint location that just got hit. Breakpoints are represented by **lldb.SBBreakpoint** | 194| | | objects. These breakpoint objects can have one or more locations. These locations | 195| | | are represented by **lldb.SBBreakpointLocation** objects. | 196+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 197| **dict** | **dict** | The python session dictionary as a standard python dictionary object. | 198+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 199 200Optionally, a Python breakpoint command can return a value. Returning False 201tells LLDB that you do not want to stop at the breakpoint. Any other return 202value (including None or leaving out the return statement altogether) is akin 203to telling LLDB to actually stop at the breakpoint. This can be useful in 204situations where a breakpoint only needs to stop the process when certain 205conditions are met, and you do not want to inspect the program state manually 206at every stop and then continue. 207 208An example will show how simple it is to write some python code and attach it 209to a breakpoint. The following example will allow you to track the order in 210which the functions in a given shared library are first executed during one run 211of your program. This is a simple method to gather an order file which can be 212used to optimize function placement within a binary for execution locality. 213 214We do this by setting a regular expression breakpoint that will match every 215function in the shared library. The regular expression '.' will match any 216string that has at least one character in it, so we will use that. This will 217result in one lldb.SBBreakpoint object that contains an 218lldb.SBBreakpointLocation object for each function. As the breakpoint gets hit, 219we use a counter to track the order in which the function at this particular 220breakpoint location got hit. Since our code is passed the location that was 221hit, we can get the name of the function from the location, disable the 222location so we won't count this function again; then log some info and continue 223the process. 224 225Note we also have to initialize our counter, which we do with the simple 226one-line version of the script command. 227 228Here is the code: 229 230:: 231 232 (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib 233 Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 234 (lldb) script counter = 0 235 (lldb) breakpoint command add --script-type python 1 236 Enter your Python command(s). Type 'DONE' to end. 237 > # Increment our counter. Since we are in a function, this must be a global python variable 238 > global counter 239 > counter += 1 240 > # Get the name of the function 241 > name = frame.GetFunctionName() 242 > # Print the order and the function name 243 > print '[%i] %s' % (counter, name) 244 > # Disable the current breakpoint location so it doesn't get hit again 245 > bp_loc.SetEnabled(False) 246 > # No need to stop here 247 > return False 248 > DONE 249 250The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command: 251 252:: 253 254 (lldb) breakpoint command delete 1 255 256 257Using the python api's to create custom breakpoints 258--------------------------------------------------- 259 260 261Another use of the Python API's in lldb is to create a custom breakpoint 262resolver. This facility was added in r342259. 263 264It allows you to provide the algorithm which will be used in the breakpoint's 265search of the space of the code in a given Target to determine where to set the 266breakpoint locations - the actual places where the breakpoint will trigger. To 267understand how this works you need to know a little about how lldb handles 268breakpoints. 269 270In lldb, a breakpoint is composed of three parts: the Searcher, the Resolver, 271and the Stop Options. The Searcher and Resolver cooperate to determine how 272breakpoint locations are set and differ between each breakpoint type. Stop 273options determine what happens when a location triggers and includes the 274commands, conditions, ignore counts, etc. Stop options are common between all 275breakpoint types, so for our purposes only the Searcher and Resolver are 276relevant. 277 278The Searcher's job is to traverse in a structured way the code in the current 279target. It proceeds from the Target, to search all the Modules in the Target, 280in each Module it can recurse into the Compile Units in that module, and within 281each Compile Unit it can recurse over the Functions it contains. 282 283The Searcher can be provided with a SearchFilter that it will use to restrict 284this search. For instance, if the SearchFilter specifies a list of Modules, the 285Searcher will not recurse into Modules that aren't on the list. When you pass 286the -s modulename flag to break set you are creating a Module-based search 287filter. When you pass -f filename.c to break set -n you are creating a file 288based search filter. If neither of these is specified, the breakpoint will have 289a no-op search filter, so all parts of the program are searched and all 290locations accepted. 291 292The Resolver has two functions. The most important one is the callback it 293provides. This will get called at the appropriate time in the course of the 294search. The callback is where the job of adding locations to the breakpoint 295gets done. 296 297The other function is specifying to the Searcher at what depth in the above 298described recursion it wants to be called. Setting a search depth also provides 299a stop for the recursion. For instance, if you request a Module depth search, 300then the callback will be called for each Module as it gets added to the 301Target, but the searcher will not recurse into the Compile Units in the module. 302 303One other slight sublety is that the depth at which you get called back is not 304necessarily the depth at which the the SearchFilter is specified. For instance, 305if you are doing symbol searches, it is convenient to use the Module depth for 306the search, since symbols are stored in the module. But the SearchFilter might 307specify some subset of CompileUnits, so not all the symbols you might find in 308each module will pass the search. You don't need to handle this situation 309yourself, since SBBreakpoint::AddLocation will only add locations that pass the 310Search Filter. This API returns an SBError to inform you whether your location 311was added. 312 313When the breakpoint is originally created, its Searcher will process all the 314currently loaded modules. The Searcher will also visit any new modules as they 315are added to the target. This happens, for instance, when a new shared library 316gets added to the target in the course of running, or on rerunning if any of 317the currently loaded modules have been changed. Note, in the latter case, all 318the locations set in the old module will get deleted and you will be asked to 319recreate them in the new version of the module when your callback gets called 320with that module. For this reason, you shouldn't try to manage the locations 321you add to the breakpoint yourself. Note that the Breakpoint takes care of 322deduplicating equal addresses in AddLocation, so you shouldn't need to worry 323about that anyway. 324 325At present, when adding a scripted Breakpoint type, you can only provide a 326custom Resolver, not a custom SearchFilter. 327 328The custom Resolver is provided as a Python class with the following methods: 329 330+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 331| Name | Arguments | Description | 332+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 333| **__init__** | **bkpt: lldb.SBBreakpoint** | This is the constructor for the new Resolver. | 334| | **extra_args: lldb.SBStructuredData** | | 335| | | | 336| | | **bkpt** is the breakpoint owning this Resolver. | 337| | | | 338| | | | 339| | | **extra_args** is an SBStructuredData object that the user can pass in when creating instances of this | 340| | | breakpoint. It is not required, but is quite handy. For instance if you were implementing a breakpoint on some | 341| | | symbol name, you could write a generic symbol name based Resolver, and then allow the user to pass | 342| | | in the particular symbol in the extra_args | 343+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 344| **__callback__** | **sym_ctx: lldb.SBSymbolContext** | This is the Resolver callback. | 345| | | The **sym_ctx** argument will be filled with the current stage | 346| | | of the search. | 347| | | | 348| | | | 349| | | For instance, if you asked for a search depth of lldb.eSearchDepthCompUnit, then the | 350| | | target, module and compile_unit fields of the sym_ctx will be filled. The callback should look just in the | 351| | | context passed in **sym_ctx** for new locations. If the callback finds an address of interest, it | 352| | | can add it to the breakpoint with the **SBBreakpoint::AddLocation** method, using the breakpoint passed | 353| | | in to the **__init__** method. | 354+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 355| **__get_depth__** | **None** | Specify the depth at which you wish your callback to get called. The currently supported options are: | 356| | | | 357| | | lldb.eSearchDepthModule | 358| | | lldb.eSearchDepthCompUnit | 359| | | lldb.eSearchDepthFunction | 360| | | | 361| | | For instance, if you are looking | 362| | | up symbols, which are stored at the Module level, you will want to get called back module by module. | 363| | | So you would want to return **lldb.eSearchDepthModule**. This method is optional. If not provided the search | 364| | | will be done at Module depth. | 365+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 366| **get_short_help** | **None** | This is an optional method. If provided, the returned string will be printed at the beginning of | 367| | | the description for this breakpoint. | 368+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ 369 370To define a new breakpoint command defined by this class from the lldb command 371line, use the command: 372 373:: 374 375 (lldb) breakpoint set -P MyModule.MyResolverClass 376 377You can also populate the extra_args SBStructuredData with a dictionary of 378key/value pairs with: 379 380:: 381 382 (lldb) breakpoint set -P MyModule.MyResolverClass -k key_1 -v value_1 -k key_2 -v value_2 383 384Although you can't write a scripted SearchFilter, both the command line and the 385SB API's for adding a scripted resolver allow you to specify a SearchFilter 386restricted to certain modules or certain compile units. When using the command 387line to create the resolver, you can specify a Module specific SearchFilter by 388passing the -s ModuleName option - which can be specified multiple times. You 389can also specify a SearchFilter restricted to certain compile units by passing 390in the -f CompUnitName option. This can also be specified more than once. And 391you can mix the two to specify "this comp unit in this module". So, for 392instance, 393 394:: 395 396 (lldb) breakpoint set -P MyModule.MyResolverClass -s a.out 397 398will use your resolver, but will only recurse into or accept new locations in 399the module a.out. 400 401Another option for creating scripted breakpoints is to use the 402SBTarget.CreateBreakpointFromScript API. This one has the advantage that you 403can pass in an arbitrary SBStructuredData object, so you can create more 404complex parametrizations. SBStructuredData has a handy SetFromJSON method which 405you can use for this purpose. Your __init__ function gets passed this 406SBStructuredData object. This API also allows you to directly provide the list 407of Modules and the list of CompileUnits that will make up the SearchFilter. If 408you pass in empty lists, the breakpoint will use the default "search 409everywhere,accept everything" filter. 410 411Using the python API' to create custom stepping logic 412----------------------------------------------------- 413 414A slightly esoteric use of the Python API's is to construct custom stepping 415types. LLDB's stepping is driven by a stack of "thread plans" and a fairly 416simple state machine that runs the plans. You can create a Python class that 417works as a thread plan, and responds to the requests the state machine makes to 418run its operations. 419 420There is a longer discussion of scripted thread plans and the state machine, 421and several interesting examples of their use in: 422 423https://github.com/llvm/llvm-project/blob/master/lldb/examples/python/scripted_step.py 424 425And for a MUCH fuller discussion of the whole state machine, see: 426 427https://github.com/llvm/llvm-project/blob/master/lldb/include/lldb/Target/ThreadPlan.h 428 429If you are reading those comments it is useful to know that scripted thread 430plans are set to be "MasterPlans", and not "OkayToDiscard". 431 432To implement a scripted step, you define a python class that has the following 433methods: 434 435+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 436| Name | Arguments | Description | 437+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 438| **__init__** | **thread_plan: lldb.SBThreadPlan** | This is the underlying SBThreadPlan that is pushed onto the plan stack. | 439| | | You will want to store this away in an ivar. Also, if you are going to | 440| | | use one of the canned thread plans, you can queue it at this point. | 441+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 442| **explains_stop** | **event: lldb.SBEvent** | Return True if this stop is part of your thread plans logic, false otherwise. | 443+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 444| **is_stale** | **None** | If your plan is no longer relevant (for instance, you were | 445| | | stepping in a particular stack frame, but some other operation | 446| | | pushed that frame off the stack) return True and your plan will | 447| | | get popped. | 448+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 449| **should_step** | **None** | Return True if you want lldb to instruction step one instruction, | 450| | | or False to continue till the next breakpoint is hit. | 451+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 452| **should_stop** | **event: lldb.SBEvent** | If your plan wants to stop and return control to the user at this point, return True. | 453| | | If your plan is done at this point, call SetPlanComplete on your | 454| | | thread plan instance. | 455| | | Also, do any work you need here to set up the next stage of stepping. | 456+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ 457 458To use this class to implement a step, use the command: 459 460:: 461 462 (lldb) thread step-scripted -C MyModule.MyStepPlanClass 463 464Or use the SBThread.StepUsingScriptedThreadPlan API. The SBThreadPlan passed 465into your __init__ function can also push several common plans (step 466in/out/over and run-to-address) in front of itself on the stack, which can be 467used to compose more complex stepping operations. When you use subsidiary plans 468your explains_stop and should_stop methods won't get called until the 469subsidiary plan is done, or the process stops for an event the subsidiary plan 470doesn't explain. For instance, step over plans don't explain a breakpoint hit 471while performing the step-over. 472 473 474Create a new lldb command using a Python function 475------------------------------------------------- 476 477Python functions can be used to create new LLDB command interpreter commands, 478which will work like all the natively defined lldb commands. This provides a 479very flexible and easy way to extend LLDB to meet your debugging requirements. 480 481To write a python function that implements a new LLDB command define the 482function to take four arguments as follows: 483 484:: 485 486 def command_function(debugger, command, result, internal_dict): 487 # Your code goes here 488 489Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in: 490 491:: 492 493 def command_function(debugger, command, result, internal_dict): 494 """This command takes a lot of options and does many fancy things""" 495 # Your code goes here 496 497Starting with SVN revision 218834, LLDB Python commands can also take an 498SBExecutionContext as an argument. This is useful in cases where the command's 499notion of where to act is independent of the currently-selected entities in the 500debugger. 501 502This feature is enabled if the command-implementing function can be recognized 503as taking 5 arguments, or a variable number of arguments, and it alters the 504signature as such: 505 506:: 507 508 def command_function(debugger, command, exe_ctx, result, internal_dict): 509 # Your code goes here 510 511+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 512| Argument | Type | Description | 513+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 514| **debugger** | **lldb.SBDebugger** | The current debugger object. | 515+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 516| **command** | **python string** | A python string containing all arguments for your command. If you need to chop up the arguments | 517| | | try using the **shlex** module's shlex.split(command) to properly extract the | 518| | | arguments. | 519+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 520| **exe_ctx** | **lldb.SBExecutionContext** | An execution context object carrying around information on the inferior process' context in which the command is expected to act | 521| | | | 522| | | *Optional since SVN r218834, unavailable before* | 523+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 524| **result** | **lldb.SBCommandReturnObject** | A return object which encapsulates success/failure information for the command and output text | 525| | | that needs to be printed as a result of the command. The plain Python "print" command also works but | 526| | | text won't go in the result by default (it is useful as a temporary logging facility). | 527+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 528| **internal_dict** | **python dict object** | The dictionary for the current embedded script session which contains all variables | 529| | | and functions. | 530+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 531 532Starting with SVN revision 232224, Python commands can also be implemented by 533means of a class which should implement the following interface: 534 535:: 536 537 class CommandObjectType: 538 def __init__(self, debugger, session_dict): 539 this call should initialize the command with respect to the command interpreter for the passed-in debugger 540 def __call__(self, debugger, command, exe_ctx, result): 541 this is the actual bulk of the command, akin to Python command functions 542 def get_short_help(self): 543 this call should return the short help text for this command[1] 544 def get_long_help(self): 545 this call should return the long help text for this command[1] 546 547[1] This method is optional. 548 549As a convenience, you can treat the result object as a Python file object, and 550say 551 552:: 553 554 print >>result, "my command does lots of cool stuff" 555 556SBCommandReturnObject and SBStream both support this file-like behavior by 557providing write() and flush() calls at the Python layer. 558 559One other handy convenience when defining lldb command-line commands is the 560command command script import which will import a module specified by file 561path, so you don't have to change your PYTHONPATH for temporary scripts. It 562also has another convenience that if your new script module has a function of 563the form: 564 565:: 566 567 def __lldb_init_module(debugger, internal_dict): 568 # Command Initialization code goes here 569 570where debugger and internal_dict are as above, that function will get run when 571the module is loaded allowing you to add whatever commands you want into the 572current debugger. Note that this function will only be run when using the LLDB 573command command script import, it will not get run if anyone imports your 574module from another module. If you want to always run code when your module is 575loaded from LLDB or when loaded via an import statement in python code you can 576test the lldb.debugger object, since you imported the module at the top of the 577python ls.py module. This test must be in code that isn't contained inside of 578any function or class, just like the standard test for __main__ like all python 579modules usually do. Sample code would look like: 580 581:: 582 583 if __name__ == '__main__': 584 # Create a new debugger instance in your module if your module 585 # can be run from the command line. When we run a script from 586 # the command line, we won't have any debugger object in 587 # lldb.debugger, so we can just create it if it will be needed 588 lldb.debugger = lldb.SBDebugger.Create() 589 elif lldb.debugger: 590 # Module is being run inside the LLDB interpreter 591 lldb.debugger.HandleCommand('command script add -f ls.ls ls') 592 print 'The "ls" python command has been installed and is ready for use.' 593 594Now we can create a module called ls.py in the file ~/ls.py that will implement 595a function that can be used by LLDB's python command code: 596 597:: 598 599 #!/usr/bin/python 600 601 import lldb 602 import commands 603 import optparse 604 import shlex 605 606 def ls(debugger, command, result, internal_dict): 607 print >>result, (commands.getoutput('/bin/ls %s' % command)) 608 609 # And the initialization code to add your commands 610 def __lldb_init_module(debugger, internal_dict): 611 debugger.HandleCommand('command script add -f ls.ls ls') 612 print 'The "ls" python command has been installed and is ready for use.' 613 614Now we can load the module into LLDB and use it 615 616:: 617 618 % lldb 619 (lldb) command script import ~/ls.py 620 The "ls" python command has been installed and is ready for use. 621 (lldb) ls -l /tmp/ 622 total 365848 623 -rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store 624 -rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log 625 626A more interesting template has been created in the source repository that can 627help you to create lldb command quickly: 628 629https://github.com/llvm/llvm-project/blob/master/lldb/examples/python/cmdtemplate.py 630 631A commonly required facility is being able to create a command that does some 632token substitution, and then runs a different debugger command (usually, it 633po'es the result of an expression evaluated on its argument). For instance, 634given the following program: 635 636:: 637 638 #import <Foundation/Foundation.h> 639 NSString* 640 ModifyString(NSString* src) 641 { 642 return [src stringByAppendingString:@"foobar"]; 643 } 644 645 int main() 646 { 647 NSString* aString = @"Hello world"; 648 NSString* anotherString = @"Let's be friends"; 649 return 1; 650 } 651 652you may want a pofoo X command, that equates po [ModifyString(X) 653capitalizedString]. The following debugger interaction shows how to achieve 654that goal: 655 656:: 657 658 (lldb) script 659 Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. 660 >>> def pofoo_funct(debugger, command, result, internal_dict): 661 ... cmd = "po [ModifyString(" + command + ") capitalizedString]" 662 ... lldb.debugger.HandleCommand(cmd) 663 ... 664 >>> ^D 665 (lldb) command script add pofoo -f pofoo_funct 666 (lldb) pofoo aString 667 $1 = 0x000000010010aa00 Hello Worldfoobar 668 (lldb) pofoo anotherString 669 $2 = 0x000000010010aba0 Let's Be Friendsfoobar 670 671Using the lldb.py module in Python 672---------------------------------- 673 674LLDB has all of its core code build into a shared library which gets used by 675the lldb command line application. On Mac OS X this shared library is a 676framework: LLDB.framework and on other unix variants the program is a shared 677library: lldb.so. LLDB also provides an lldb.py module that contains the 678bindings from LLDB into Python. To use the LLDB.framework to create your own 679stand-alone python programs, you will need to tell python where to look in 680order to find this module. This is done by setting the PYTHONPATH environment 681variable, adding a path to the directory that contains the lldb.py python 682module. The lldb driver program has an option to report the path to the lldb 683module. You can use that to point to correct lldb.py: 684 685For csh and tcsh: 686 687:: 688 689 % setenv PYTHONPATH `lldb -P` 690 691For sh and bash: 692 693:: 694 695 % export PYTHONPATH=`lldb -P` 696 697Alternately, you can append the LLDB Python directory to the sys.path list 698directly in your Python code before importing the lldb module. 699 700Now your python scripts are ready to import the lldb module. Below is a python 701script that will launch a program from the current working directory called 702"a.out", set a breakpoint at "main", and then run and hit the breakpoint, and 703print the process, thread and frame objects if the process stopped: 704 705:: 706 707 #!/usr/bin/python 708 709 import lldb 710 import os 711 712 def disassemble_instructions(insts): 713 for i in insts: 714 print i 715 716 # Set the path to the executable to debug 717 exe = "./a.out" 718 719 # Create a new debugger instance 720 debugger = lldb.SBDebugger.Create() 721 722 # When we step or continue, don't return from the function until the process 723 # stops. Otherwise we would have to handle the process events ourselves which, while doable is 724 #a little tricky. We do this by setting the async mode to false. 725 debugger.SetAsync (False) 726 727 # Create a target from a file and arch 728 print "Creating a target for '%s'" % exe 729 730 target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT) 731 732 if target: 733 # If the target is valid set a breakpoint at main 734 main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename()); 735 736 print main_bp 737 738 # Launch the process. Since we specified synchronous mode, we won't return 739 # from this function until we hit the breakpoint at main 740 process = target.LaunchSimple (None, None, os.getcwd()) 741 742 # Make sure the launch went ok 743 if process: 744 # Print some simple process info 745 state = process.GetState () 746 print process 747 if state == lldb.eStateStopped: 748 # Get the first thread 749 thread = process.GetThreadAtIndex (0) 750 if thread: 751 # Print some simple thread info 752 print thread 753 # Get the first frame 754 frame = thread.GetFrameAtIndex (0) 755 if frame: 756 # Print some simple frame info 757 print frame 758 function = frame.GetFunction() 759 # See if we have debug info (a function) 760 if function: 761 # We do have a function, print some info for the function 762 print function 763 # Now get all instructions for this function and print them 764 insts = function.GetInstructions(target) 765 disassemble_instructions (insts) 766 else: 767 # See if we have a symbol in the symbol table for where we stopped 768 symbol = frame.GetSymbol(); 769 if symbol: 770 # We do have a symbol, print some info for the symbol 771 print symbol 772 773Writing lldb frame recognizers in Python 774---------------------------------------- 775 776Frame recognizers allow for retrieving information about special frames based 777on ABI, arguments or other special properties of that frame, even without 778source code or debug info. Currently, one use case is to extract function 779arguments that would otherwise be unaccesible, or augment existing arguments. 780 781Adding a custom frame recognizer is done by implementing a Python class and 782using the 'frame recognizer add' command. The Python class should have a 783'get_recognized_arguments' method and it will receive an argument of type 784lldb.SBFrame representing the current frame that we are trying to recognize. 785The method should return a (possibly empty) list of lldb.SBValue objects that 786represent the recognized arguments. 787 788An example of a recognizer that retrieves the file descriptor values from libc 789functions 'read', 'write' and 'close' follows: 790 791:: 792 793 class LibcFdRecognizer(object): 794 def get_recognized_arguments(self, frame): 795 if frame.name in ["read", "write", "close"]: 796 fd = frame.EvaluateExpression("$arg1").unsigned 797 value = lldb.target.CreateValueFromExpression("fd", "(int)%d" % fd) 798 return [value] 799 return [] 800 801The file containing this implementation can be imported via 'command script 802import' and then we can register this recognizer with 'frame recognizer add'. 803It's important to restrict the recognizer to the libc library (which is 804libsystem_kernel.dylib on macOS) to avoid matching functions with the same name 805in other modules: 806 807:: 808 809 (lldb) command script import .../fd_recognizer.py 810 (lldb) frame recognizer add -l fd_recognizer.LibcFdRecognizer -n read -s libsystem_kernel.dylib 811 812When the program is stopped at the beginning of the 'read' function in libc, we can view the recognizer arguments in 'frame variable': 813 814:: 815 816 (lldb) b read 817 (lldb) r 818 Process 1234 stopped 819 * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3 820 frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read 821 (lldb) frame variable 822 (int) fd = 3 823