| blob | 2020853cfd2b17edc1dfaabf72892b05a41f8078 |
1 Python Reference
2 ================
4 The entire LLDB API is available as Python functions through a script bridging
5 interface. This means the LLDB API's can be used directly from python either
6 interactively or to build python apps that provide debugger features.
8 Additionally, Python can be used as a programmatic interface within the lldb
9 command interpreter (we refer to this for brevity as the embedded interpreter).
10 Of course, in this context it has full access to the LLDB API - with some
11 additional conveniences we will call out in the FAQ.
13 .. contents::
14 :local:
16 Documentation
17 --------------
19 The LLDB API is contained in a python module named lldb. A useful resource when
20 writing Python extensions is the lldb Python classes reference guide.
22 The documentation is also accessible in an interactive debugger session with
23 the following command:
25 ::
27 (lldb) script help(lldb)
28 Help on package lldb:
30 NAME
31 lldb - The lldb module contains the public APIs for Python binding.
33 FILE
34 /System/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/Python/lldb/__init__.py
36 DESCRIPTION
37 ...
39 You can also get help using a module class name. The full API that is exposed
40 for that class will be displayed in a man page style window. Below we want to
41 get help on the lldb.SBFrame class:
43 ::
45 (lldb) script help(lldb.SBFrame)
46 Help on class SBFrame in module lldb:
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 ...
57 Or you can get help using any python object, here we use the lldb.process
58 object which is a global variable in the lldb module which represents the
59 currently selected process:
61 ::
63 (lldb) script help(lldb.process)
64 Help on SBProcess in module lldb object:
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 ...
77 Embedded Python Interpreter
78 ---------------------------
80 The embedded python interpreter can be accessed in a variety of ways from
81 within LLDB. The easiest way is to use the lldb command script with no
82 arguments at the lldb command prompt:
84 ::
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 >>>
94 This drops you into the embedded python interpreter. When running under the
95 script command, lldb sets some convenience variables that give you quick access
96 to the currently selected entities that characterize the program and debugger
97 state. In each case, if there is no currently selected entity of the
98 appropriate type, the variable's IsValid method will return false. These
99 variables are:
101 +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
102 | Variable | Type | Equivalent | Description |
103 +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
104 | ``lldb.debugger`` | `lldb.SBDebugger` | `SBTarget.GetDebugger` | 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` | `SBDebugger.GetSelectedTarget` | Contains the currently selected target - for instance the one made with the |
110 | | | | ``file`` or selected by the ``target select <target-index>`` command. |
111 | | | `SBProcess.GetTarget` | The `lldb.SBTarget` manages one running process, and all the executable |
112 | | | | and debug files for the process. |
113 +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
114 | ``lldb.process`` | `lldb.SBProcess` | `SBTarget.GetProcess` | Contains the process of the currently selected target. |
115 | | | | The `lldb.SBProcess` object manages the threads and allows access to |
116 | | | `SBThread.GetProcess` | memory for the process. |
117 +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
118 | ``lldb.thread`` | `lldb.SBThread` | `SBProcess.GetSelectedThread` | Contains the currently selected thread. |
119 | | | | The `lldb.SBThread` object manages the stack frames in that thread. |
120 | | | `SBFrame.GetThread` | 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` | `SBThread.GetSelectedFrame` | 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 +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
134 While extremely convenient, these variables have a couple caveats that you
135 should be aware of. First of all, they hold the values of the selected objects
136 on entry to the embedded interpreter. They do not update as you use the LLDB
137 API's to change, for example, the currently selected stack frame or thread.
139 Moreover, they are only defined and meaningful while in the interactive Python
140 interpreter. There is no guarantee on their value in any other situation, hence
141 you should not use them when defining Python formatters, breakpoint scripts and
142 commands (or any other Python extension point that LLDB provides). For the
143 latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or
144 `SBFrame` instance and you can use the functions from the "Equivalent" column
145 to navigate between them.
147 As a rationale for such behavior, consider that lldb can run in a multithreaded
148 environment, and another thread might call the "script" command, changing the
149 value out from under you.
151 To get started with these objects and LLDB scripting, please note that almost
152 all of the lldb Python objects are able to briefly describe themselves when you
153 pass them to the Python print function:
155 ::
157 (lldb) script
158 Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
159 >>> print lldb.debugger
160 Debugger (instance: "debugger_1", id: 1)
161 >>> print lldb.target
162 a.out
163 >>> print lldb.process
164 SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
165 >>> print lldb.thread
166 SBThread: tid = 0x1f03
167 >>> print lldb.frame
168 frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16
171 Running a python script when a breakpoint gets hit
172 --------------------------------------------------
174 One very powerful use of the lldb Python API is to have a python script run
175 when a breakpoint gets hit. Adding python scripts to breakpoints provides a way
176 to create complex breakpoint conditions and also allows for smart logging and
177 data gathering.
179 When your process hits a breakpoint to which you have attached some python
180 code, the code is executed as the body of a function which takes three
181 arguments:
183 ::
185 def breakpoint_function_wrapper(frame, bp_loc, internal_dict):
186 # Your code goes here
188 or:
190 ::
192 def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict):
193 # Your code goes here
196 +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
197 | Argument | Type | Description |
198 +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
199 | ``frame`` | `lldb.SBFrame` | The current stack frame where the breakpoint got hit. |
200 | | | The object will always be valid. |
201 | | | This ``frame`` argument might *not* match the currently selected stack frame found in the `lldb` module global variable ``lldb.frame``. |
202 +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
203 | ``bp_loc`` | `lldb.SBBreakpointLocation` | The breakpoint location that just got hit. Breakpoints are represented by `lldb.SBBreakpoint` |
204 | | | objects. These breakpoint objects can have one or more locations. These locations |
205 | | | are represented by `lldb.SBBreakpointLocation` objects. |
206 +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
207 | ``extra_args`` | `lldb.SBStructuredData` | ``Optional`` If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its |
208 | | | contents can parametrize this use of the callback. For instance, instead of writing a callback that stops when the caller is "Foo", |
209 | | | you could take the function name from a field in the ``extra_args``, making the callback more general. The ``-k`` and ``-v`` options |
210 | | | 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. |
211 +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
212 | ``internal_dict`` | ``dict`` | The python session dictionary as a standard python dictionary object. |
213 +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
215 Optionally, a Python breakpoint command can return a value. Returning False
216 tells LLDB that you do not want to stop at the breakpoint. Any other return
217 value (including None or leaving out the return statement altogether) is akin
218 to telling LLDB to actually stop at the breakpoint. This can be useful in
219 situations where a breakpoint only needs to stop the process when certain
220 conditions are met, and you do not want to inspect the program state manually
221 at every stop and then continue.
223 An example will show how simple it is to write some python code and attach it
224 to a breakpoint. The following example will allow you to track the order in
225 which the functions in a given shared library are first executed during one run
226 of your program. This is a simple method to gather an order file which can be
227 used to optimize function placement within a binary for execution locality.
229 We do this by setting a regular expression breakpoint that will match every
230 function in the shared library. The regular expression '.' will match any
231 string that has at least one character in it, so we will use that. This will
232 result in one lldb.SBBreakpoint object that contains an
233 lldb.SBBreakpointLocation object for each function. As the breakpoint gets hit,
234 we use a counter to track the order in which the function at this particular
235 breakpoint location got hit. Since our code is passed the location that was
236 hit, we can get the name of the function from the location, disable the
237 location so we won't count this function again; then log some info and continue
238 the process.
240 Note we also have to initialize our counter, which we do with the simple
241 one-line version of the script command.
243 Here is the code:
245 ::
247 (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib
248 Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
249 (lldb) script counter = 0
250 (lldb) breakpoint command add --script-type python 1
251 Enter your Python command(s). Type 'DONE' to end.
252 > # Increment our counter. Since we are in a function, this must be a global python variable
253 > global counter
254 > counter += 1
255 > # Get the name of the function
256 > name = frame.GetFunctionName()
257 > # Print the order and the function name
258 > print '[%i] %s' % (counter, name)
259 > # Disable the current breakpoint location so it doesn't get hit again
260 > bp_loc.SetEnabled(False)
261 > # No need to stop here
262 > return False
263 > DONE
265 The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command:
267 ::
269 (lldb) breakpoint command delete 1
272 Using the python api's to create custom breakpoints
273 ---------------------------------------------------
276 Another use of the Python API's in lldb is to create a custom breakpoint
277 resolver. This facility was added in r342259.
279 It allows you to provide the algorithm which will be used in the breakpoint's
280 search of the space of the code in a given Target to determine where to set the
281 breakpoint locations - the actual places where the breakpoint will trigger. To
282 understand how this works you need to know a little about how lldb handles
283 breakpoints.
285 In lldb, a breakpoint is composed of three parts: the Searcher, the Resolver,
286 and the Stop Options. The Searcher and Resolver cooperate to determine how
287 breakpoint locations are set and differ between each breakpoint type. Stop
288 options determine what happens when a location triggers and includes the
289 commands, conditions, ignore counts, etc. Stop options are common between all
290 breakpoint types, so for our purposes only the Searcher and Resolver are
291 relevant.
293 The Searcher's job is to traverse in a structured way the code in the current
294 target. It proceeds from the Target, to search all the Modules in the Target,
295 in each Module it can recurse into the Compile Units in that module, and within
296 each Compile Unit it can recurse over the Functions it contains.
298 The Searcher can be provided with a SearchFilter that it will use to restrict
299 this search. For instance, if the SearchFilter specifies a list of Modules, the
300 Searcher will not recurse into Modules that aren't on the list. When you pass
301 the -s modulename flag to break set you are creating a Module-based search
302 filter. When you pass -f filename.c to break set -n you are creating a file
303 based search filter. If neither of these is specified, the breakpoint will have
304 a no-op search filter, so all parts of the program are searched and all
305 locations accepted.
307 The Resolver has two functions. The most important one is the callback it
308 provides. This will get called at the appropriate time in the course of the
309 search. The callback is where the job of adding locations to the breakpoint
310 gets done.
312 The other function is specifying to the Searcher at what depth in the above
313 described recursion it wants to be called. Setting a search depth also provides
314 a stop for the recursion. For instance, if you request a Module depth search,
315 then the callback will be called for each Module as it gets added to the
316 Target, but the searcher will not recurse into the Compile Units in the module.
318 One other slight subtlety is that the depth at which you get called back is not
319 necessarily the depth at which the SearchFilter is specified. For instance,
320 if you are doing symbol searches, it is convenient to use the Module depth for
321 the search, since symbols are stored in the module. But the SearchFilter might
322 specify some subset of CompileUnits, so not all the symbols you might find in
323 each module will pass the search. You don't need to handle this situation
324 yourself, since SBBreakpoint::AddLocation will only add locations that pass the
325 Search Filter. This API returns an SBError to inform you whether your location
326 was added.
328 When the breakpoint is originally created, its Searcher will process all the
329 currently loaded modules. The Searcher will also visit any new modules as they
330 are added to the target. This happens, for instance, when a new shared library
331 gets added to the target in the course of running, or on rerunning if any of
332 the currently loaded modules have been changed. Note, in the latter case, all
333 the locations set in the old module will get deleted and you will be asked to
334 recreate them in the new version of the module when your callback gets called
335 with that module. For this reason, you shouldn't try to manage the locations
336 you add to the breakpoint yourself. Note that the Breakpoint takes care of
337 deduplicating equal addresses in AddLocation, so you shouldn't need to worry
338 about that anyway.
340 At present, when adding a scripted Breakpoint type, you can only provide a
341 custom Resolver, not a custom SearchFilter.
343 The custom Resolver is provided as a Python class with the following methods:
345 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
346 | Name | Arguments | Description |
347 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
348 | ``__init__`` | ``bkpt``:`lldb.SBBreakpoint` | This is the constructor for the new Resolver. |
349 | | ``extra_args``:`lldb.SBStructuredData`| |
350 | | | |
351 | | | ``bkpt`` is the breakpoint owning this Resolver. |
352 | | | |
353 | | | |
354 | | | ``extra_args`` is an `SBStructuredData` object that the user can pass in when creating instances of this |
355 | | | breakpoint. It is not required, but is quite handy. For instance if you were implementing a breakpoint on some |
356 | | | symbol name, you could write a generic symbol name based Resolver, and then allow the user to pass |
357 | | | in the particular symbol in the extra_args |
358 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
359 | ``__callback__`` | ``sym_ctx``:`lldb.SBSymbolContext` | This is the Resolver callback. |
360 | | | The ``sym_ctx`` argument will be filled with the current stage |
361 | | | of the search. |
362 | | | |
363 | | | |
364 | | | For instance, if you asked for a search depth of lldb.eSearchDepthCompUnit, then the |
365 | | | target, module and compile_unit fields of the sym_ctx will be filled. The callback should look just in the |
366 | | | context passed in ``sym_ctx`` for new locations. If the callback finds an address of interest, it |
367 | | | can add it to the breakpoint with the `SBBreakpoint.AddLocation` method, using the breakpoint passed |
368 | | | in to the ``__init__`` method. |
369 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
370 | ``__get_depth__`` | ``None`` | Specify the depth at which you wish your callback to get called. The currently supported options are: |
371 | | | |
372 | | | `lldb.eSearchDepthModule` |
373 | | | `lldb.eSearchDepthCompUnit` |
374 | | | `lldb.eSearchDepthFunction` |
375 | | | |
376 | | | For instance, if you are looking |
377 | | | up symbols, which are stored at the Module level, you will want to get called back module by module. |
378 | | | So you would want to return `lldb.eSearchDepthModule`. This method is optional. If not provided the search |
379 | | | will be done at Module depth. |
380 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
381 | ``get_short_help`` | ``None`` | This is an optional method. If provided, the returned string will be printed at the beginning of |
382 | | | the description for this breakpoint. |
383 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
385 To define a new breakpoint command defined by this class from the lldb command
386 line, use the command:
388 ::
390 (lldb) breakpoint set -P MyModule.MyResolverClass
392 You can also populate the extra_args SBStructuredData with a dictionary of
393 key/value pairs with:
395 ::
397 (lldb) breakpoint set -P MyModule.MyResolverClass -k key_1 -v value_1 -k key_2 -v value_2
399 Although you can't write a scripted SearchFilter, both the command line and the
400 SB API's for adding a scripted resolver allow you to specify a SearchFilter
401 restricted to certain modules or certain compile units. When using the command
402 line to create the resolver, you can specify a Module specific SearchFilter by
403 passing the -s ModuleName option - which can be specified multiple times. You
404 can also specify a SearchFilter restricted to certain compile units by passing
405 in the -f CompUnitName option. This can also be specified more than once. And
406 you can mix the two to specify "this comp unit in this module". So, for
407 instance,
409 ::
411 (lldb) breakpoint set -P MyModule.MyResolverClass -s a.out
413 will use your resolver, but will only recurse into or accept new locations in
414 the module a.out.
416 Another option for creating scripted breakpoints is to use the
417 SBTarget.CreateBreakpointFromScript API. This one has the advantage that you
418 can pass in an arbitrary SBStructuredData object, so you can create more
419 complex parametrizations. SBStructuredData has a handy SetFromJSON method which
420 you can use for this purpose. Your __init__ function gets passed this
421 SBStructuredData object. This API also allows you to directly provide the list
422 of Modules and the list of CompileUnits that will make up the SearchFilter. If
423 you pass in empty lists, the breakpoint will use the default "search
424 everywhere,accept everything" filter.
426 Using the python API' to create custom stepping logic
427 -----------------------------------------------------
429 A slightly esoteric use of the Python API's is to construct custom stepping
430 types. LLDB's stepping is driven by a stack of "thread plans" and a fairly
431 simple state machine that runs the plans. You can create a Python class that
432 works as a thread plan, and responds to the requests the state machine makes to
433 run its operations.
435 There is a longer discussion of scripted thread plans and the state machine,
436 and several interesting examples of their use in:
438 https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/scripted_step.py
440 And for a MUCH fuller discussion of the whole state machine, see:
442 https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Target/ThreadPlan.h
444 If you are reading those comments it is useful to know that scripted thread
445 plans are set to be "ControllingPlans", and not "OkayToDiscard".
447 To implement a scripted step, you define a python class that has the following
448 methods:
450 +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
451 | Name | Arguments | Description |
452 +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
453 | ``__init__`` | ``thread_plan``:`lldb.SBThreadPlan`| This is the underlying `SBThreadPlan` that is pushed onto the plan stack. |
454 | | | You will want to store this away in an ivar. Also, if you are going to |
455 | | | use one of the canned thread plans, you can queue it at this point. |
456 +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
457 | ``explains_stop`` | ``event``: `lldb.SBEvent` | Return True if this stop is part of your thread plans logic, false otherwise. |
458 +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
459 | ``is_stale`` | ``None`` | If your plan is no longer relevant (for instance, you were |
460 | | | stepping in a particular stack frame, but some other operation |
461 | | | pushed that frame off the stack) return True and your plan will |
462 | | | get popped. |
463 +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
464 | ``should_step`` | ``None`` | Return ``True`` if you want lldb to instruction step one instruction, |
465 | | | or False to continue till the next breakpoint is hit. |
466 +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
467 | ``should_stop`` | ``event``: `lldb.SBEvent` | If your plan wants to stop and return control to the user at this point, return True. |
468 | | | If your plan is done at this point, call SetPlanComplete on your |
469 | | | thread plan instance. |
470 | | | Also, do any work you need here to set up the next stage of stepping. |
471 +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
473 To use this class to implement a step, use the command:
475 ::
477 (lldb) thread step-scripted -C MyModule.MyStepPlanClass
479 Or use the SBThread.StepUsingScriptedThreadPlan API. The SBThreadPlan passed
480 into your __init__ function can also push several common plans (step
481 in/out/over and run-to-address) in front of itself on the stack, which can be
482 used to compose more complex stepping operations. When you use subsidiary plans
483 your explains_stop and should_stop methods won't get called until the
484 subsidiary plan is done, or the process stops for an event the subsidiary plan
485 doesn't explain. For instance, step over plans don't explain a breakpoint hit
486 while performing the step-over.
489 Create a new lldb command using a Python function
490 -------------------------------------------------
492 Python functions can be used to create new LLDB command interpreter commands,
493 which will work like all the natively defined lldb commands. This provides a
494 very flexible and easy way to extend LLDB to meet your debugging requirements.
496 To write a python function that implements a new LLDB command define the
497 function to take four arguments as follows:
499 ::
501 def command_function(debugger, command, result, internal_dict):
502 # Your code goes here
504 Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in:
506 ::
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
512 Since lldb 3.5.2, LLDB Python commands can also take an SBExecutionContext as an
513 argument. This is useful in cases where the command's notion of where to act is
514 independent of the currently-selected entities in the debugger.
516 This feature is enabled if the command-implementing function can be recognized
517 as taking 5 arguments, or a variable number of arguments, and it alters the
518 signature as such:
520 ::
522 def command_function(debugger, command, exe_ctx, result, internal_dict):
523 # Your code goes here
525 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
526 | Argument | Type | Description |
527 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
528 | ``debugger`` | `lldb.SBDebugger` | The current debugger object. |
529 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
530 | ``command`` | ``python string`` | A python string containing all arguments for your command. If you need to chop up the arguments |
531 | | | try using the ``shlex`` module's ``shlex.split(command)`` to properly extract the |
532 | | | arguments. |
533 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
534 | ``exe_ctx`` | `lldb.SBExecutionContext` | An execution context object carrying around information on the inferior process' context in which the command is expected to act |
535 | | | |
536 | | | *Optional since lldb 3.5.2, unavailable before* |
537 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
538 | ``result`` | `lldb.SBCommandReturnObject` | A return object which encapsulates success/failure information for the command and output text |
539 | | | that needs to be printed as a result of the command. The plain Python "print" command also works but |
540 | | | text won't go in the result by default (it is useful as a temporary logging facility). |
541 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
542 | ``internal_dict`` | ``python dict object`` | The dictionary for the current embedded script session which contains all variables |
543 | | | and functions. |
544 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
546 Since lldb 3.7, Python commands can also be implemented by means of a class
547 which should implement the following interface:
549 ::
551 class CommandObjectType:
552 def __init__(self, debugger, internal_dict):
553 this call should initialize the command with respect to the command interpreter for the passed-in debugger
554 def __call__(self, debugger, command, exe_ctx, result):
555 this is the actual bulk of the command, akin to Python command functions
556 def get_short_help(self):
557 this call should return the short help text for this command[1]
558 def get_long_help(self):
559 this call should return the long help text for this command[1]
561 [1] This method is optional.
563 As a convenience, you can treat the result object as a Python file object, and
564 say
566 ::
568 print >>result, "my command does lots of cool stuff"
570 SBCommandReturnObject and SBStream both support this file-like behavior by
571 providing write() and flush() calls at the Python layer.
573 One other handy convenience when defining lldb command-line commands is the
574 command command script import which will import a module specified by file
575 path, so you don't have to change your PYTHONPATH for temporary scripts. It
576 also has another convenience that if your new script module has a function of
577 the form:
579 ::
581 def __lldb_init_module(debugger, internal_dict):
582 # Command Initialization code goes here
584 where debugger and internal_dict are as above, that function will get run when
585 the module is loaded allowing you to add whatever commands you want into the
586 current debugger. Note that this function will only be run when using the LLDB
587 command ``command script import``, it will not get run if anyone imports your
588 module from another module.
590 The standard test for ``__main__``, like many python modules do, is useful for
591 creating scripts that can be run from the command line. However, for command
592 line scripts, the debugger instance must be created manually. Sample code would
593 look like:
595 ::
597 if __name__ == '__main__':
598 # Initialize the debugger before making any API calls.
599 lldb.SBDebugger.Initialize()
600 # Create a new debugger instance in your module if your module
601 # can be run from the command line. When we run a script from
602 # the command line, we won't have any debugger object in
603 # lldb.debugger, so we can just create it if it will be needed
604 debugger = lldb.SBDebugger.Create()
606 # Next, do whatever work this module should do when run as a command.
607 # ...
609 # Finally, dispose of the debugger you just made.
610 lldb.SBDebugger.Destroy(debugger)
611 # Terminate the debug session
612 lldb.SBDebugger.Terminate()
615 Now we can create a module called ls.py in the file ~/ls.py that will implement
616 a function that can be used by LLDB's python command code:
618 ::
620 #!/usr/bin/env python
622 import lldb
623 import commands
624 import optparse
625 import shlex
627 def ls(debugger, command, result, internal_dict):
628 print >>result, (commands.getoutput('/bin/ls %s' % command))
630 # And the initialization code to add your commands
631 def __lldb_init_module(debugger, internal_dict):
632 debugger.HandleCommand('command script add -f ls.ls ls')
633 print 'The "ls" python command has been installed and is ready for use.'
635 Now we can load the module into LLDB and use it
637 ::
639 $ lldb
640 (lldb) command script import ~/ls.py
641 The "ls" python command has been installed and is ready for use.
642 (lldb) ls -l /tmp/
643 total 365848
644 -rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store
645 -rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log
647 You can also make "container" commands to organize the commands you are adding to
648 lldb. Most of the lldb built-in commands structure themselves this way, and using
649 a tree structure has the benefit of leaving the one-word command space free for user
650 aliases. It can also make it easier to find commands if you are adding more than
651 a few of them. Here's a trivial example of adding two "utility" commands into a
652 "my-utilities" container:
654 ::
656 #!/usr/bin/env python
658 import lldb
660 def first_utility(debugger, command, result, internal_dict):
661 print("I am the first utility")
663 def second_utility(debugger, command, result, internal_dict):
664 print("I am the second utility")
666 # And the initialization code to add your commands
667 def __lldb_init_module(debugger, internal_dict):
668 debugger.HandleCommand('command container add -h "A container for my utilities" my-utilities')
669 debugger.HandleCommand('command script add -f my_utilities.first_utility -h "My first utility" my-utilities first')
670 debugger.HandleCommand('command script add -f my_utilities.second_utility -h "My second utility" my-utilities second')
671 print('The "my-utilities" python command has been installed and its subcommands are ready for use.')
673 Then your new commands are available under the my-utilities node:
675 ::
677 (lldb) help my-utilities
678 A container for my utilities
680 Syntax: my-utilities
682 The following subcommands are supported:
684 first -- My first utility Expects 'raw' input (see 'help raw-input'.)
685 second -- My second utility Expects 'raw' input (see 'help raw-input'.)
687 For more help on any particular subcommand, type 'help <command> <subcommand>'.
688 (lldb) my-utilities first
689 I am the first utility
692 A more interesting template has been created in the source repository that can
693 help you to create lldb command quickly:
695 https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/cmdtemplate.py
697 A commonly required facility is being able to create a command that does some
698 token substitution, and then runs a different debugger command (usually, it
699 po'es the result of an expression evaluated on its argument). For instance,
700 given the following program:
702 ::
704 #import <Foundation/Foundation.h>
705 NSString*
706 ModifyString(NSString* src)
707 {
708 return [src stringByAppendingString:@"foobar"];
709 }
711 int main()
712 {
713 NSString* aString = @"Hello world";
714 NSString* anotherString = @"Let's be friends";
715 return 1;
716 }
718 you may want a pofoo X command, that equates po [ModifyString(X)
719 capitalizedString]. The following debugger interaction shows how to achieve
720 that goal:
722 ::
724 (lldb) script
725 Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
726 >>> def pofoo_funct(debugger, command, result, internal_dict):
727 ... cmd = "po [ModifyString(" + command + ") capitalizedString]"
728 ... debugger.HandleCommand(cmd)
729 ...
730 >>> ^D
731 (lldb) command script add pofoo -f pofoo_funct
732 (lldb) pofoo aString
733 $1 = 0x000000010010aa00 Hello Worldfoobar
734 (lldb) pofoo anotherString
735 $2 = 0x000000010010aba0 Let's Be Friendsfoobar
737 Using the lldb.py module in Python
738 ----------------------------------
740 LLDB has all of its core code build into a shared library which gets used by
741 the `lldb` command line application. On macOS this shared library is a
742 framework: LLDB.framework and on other unix variants the program is a shared
743 library: lldb.so. LLDB also provides an lldb.py module that contains the
744 bindings from LLDB into Python. To use the LLDB.framework to create your own
745 stand-alone python programs, you will need to tell python where to look in
746 order to find this module. This is done by setting the PYTHONPATH environment
747 variable, adding a path to the directory that contains the lldb.py python
748 module. The lldb driver program has an option to report the path to the lldb
749 module. You can use that to point to correct lldb.py:
751 For csh and tcsh:
753 ::
755 % setenv PYTHONPATH `lldb -P`
757 For sh and bash:
759 ::
761 $ export PYTHONPATH=`lldb -P`
763 Alternately, you can append the LLDB Python directory to the sys.path list
764 directly in your Python code before importing the lldb module.
766 Now your python scripts are ready to import the lldb module. Below is a python
767 script that will launch a program from the current working directory called
768 "a.out", set a breakpoint at "main", and then run and hit the breakpoint, and
769 print the process, thread and frame objects if the process stopped:
771 ::
773 #!/usr/bin/env python
775 import lldb
776 import os
778 def disassemble_instructions(insts):
779 for i in insts:
780 print i
782 # Set the path to the executable to debug
783 exe = "./a.out"
785 # Create a new debugger instance
786 debugger = lldb.SBDebugger.Create()
788 # When we step or continue, don't return from the function until the process
789 # stops. Otherwise we would have to handle the process events ourselves which, while doable is
790 #a little tricky. We do this by setting the async mode to false.
791 debugger.SetAsync (False)
793 # Create a target from a file and arch
794 print "Creating a target for '%s'" % exe
796 target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
798 if target:
799 # If the target is valid set a breakpoint at main
800 main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename());
802 print main_bp
804 # Launch the process. Since we specified synchronous mode, we won't return
805 # from this function until we hit the breakpoint at main
806 process = target.LaunchSimple (None, None, os.getcwd())
808 # Make sure the launch went ok
809 if process:
810 # Print some simple process info
811 state = process.GetState ()
812 print process
813 if state == lldb.eStateStopped:
814 # Get the first thread
815 thread = process.GetThreadAtIndex (0)
816 if thread:
817 # Print some simple thread info
818 print thread
819 # Get the first frame
820 frame = thread.GetFrameAtIndex (0)
821 if frame:
822 # Print some simple frame info
823 print frame
824 function = frame.GetFunction()
825 # See if we have debug info (a function)
826 if function:
827 # We do have a function, print some info for the function
828 print function
829 # Now get all instructions for this function and print them
830 insts = function.GetInstructions(target)
831 disassemble_instructions (insts)
832 else:
833 # See if we have a symbol in the symbol table for where we stopped
834 symbol = frame.GetSymbol();
835 if symbol:
836 # We do have a symbol, print some info for the symbol
837 print symbol
839 Writing lldb frame recognizers in Python
840 ----------------------------------------
842 Frame recognizers allow for retrieving information about special frames based
843 on ABI, arguments or other special properties of that frame, even without
844 source code or debug info. Currently, one use case is to extract function
845 arguments that would otherwise be inaccessible, or augment existing arguments.
847 Adding a custom frame recognizer is done by implementing a Python class and
848 using the 'frame recognizer add' command. The Python class should have a
849 'get_recognized_arguments' method and it will receive an argument of type
850 lldb.SBFrame representing the current frame that we are trying to recognize.
851 The method should return a (possibly empty) list of lldb.SBValue objects that
852 represent the recognized arguments.
854 An example of a recognizer that retrieves the file descriptor values from libc
855 functions 'read', 'write' and 'close' follows:
857 ::
859 class LibcFdRecognizer(object):
860 def get_recognized_arguments(self, frame):
861 if frame.name in ["read", "write", "close"]:
862 fd = frame.EvaluateExpression("$arg1").unsigned
863 target = frame.thread.process.target
864 value = target.CreateValueFromExpression("fd", "(int)%d" % fd)
865 return [value]
866 return []
868 The file containing this implementation can be imported via ``command script import``
869 and then we can register this recognizer with ``frame recognizer add``.
870 It's important to restrict the recognizer to the libc library (which is
871 libsystem_kernel.dylib on macOS) to avoid matching functions with the same name
872 in other modules:
874 ::
876 (lldb) command script import .../fd_recognizer.py
877 (lldb) frame recognizer add -l fd_recognizer.LibcFdRecognizer -n read -s libsystem_kernel.dylib
879 When the program is stopped at the beginning of the 'read' function in libc, we can view the recognizer arguments in 'frame variable':
881 ::
883 (lldb) b read
884 (lldb) r
885 Process 1234 stopped
886 * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3
887 frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read
888 (lldb) frame variable
889 (int) fd = 3
891 Writing Target Stop-Hooks in Python:
892 ------------------------------------
894 Stop hooks fire whenever the process stops just before control is returned to the
895 user. Stop hooks can either be a set of lldb command-line commands, or can
896 be implemented by a suitably defined Python class. The Python based stop-hooks
897 can also be passed as set of -key -value pairs when they are added, and those
898 will get packaged up into a SBStructuredData Dictionary and passed to the
899 constructor of the Python object managing the stop hook. This allows for
900 parametrization of the stop hooks.
902 To add a Python-based stop hook, first define a class with the following methods:
904 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
905 | Name | Arguments | Description |
906 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
907 | ``__init__`` | ``target: lldb.SBTarget`` | This is the constructor for the new stop-hook. |
908 | | ``extra_args: lldb.SBStructuredData`` | |
909 | | | |
910 | | | ``target`` is the SBTarget to which the stop hook is added. |
911 | | | |
912 | | | ``extra_args`` is an SBStructuredData object that the user can pass in when creating instances of this |
913 | | | breakpoint. It is not required, but allows for reuse of stop-hook classes. |
914 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
915 | ``handle_stop`` | ``exe_ctx: lldb.SBExecutionContext`` | This is the called when the target stops. |
916 | | ``stream: lldb.SBStream`` | |
917 | | | ``exe_ctx`` argument will be filled with the current stop point for which the stop hook is |
918 | | | being evaluated. |
919 | | | |
920 | | | ``stream`` an lldb.SBStream, anything written to this stream will be written to the debugger console. |
921 | | | |
922 | | | The return value is a "Should Stop" vote from this thread. If the method returns either True or no return |
923 | | | this thread votes to stop. If it returns False, then the thread votes to continue after all the stop-hooks |
924 | | | are evaluated. |
925 | | | Note, the --auto-continue flag to 'target stop-hook add' overrides a True return value from the method. |
926 +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
928 To use this class in lldb, run the command:
930 ::
932 (lldb) command script import MyModule.py
933 (lldb) target stop-hook add -P MyModule.MyStopHook -k first -v 1 -k second -v 2
935 where MyModule.py is the file containing the class definition MyStopHook.