The embedded python interpreter can be accessed in a variety of ways from within LLDB. The easiest way is to use the lldb command script with no arguments at the lldb command prompt:

(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> 2+3
5
>>> hex(12345)
'0x3039'
>>> 

This drops you into the embedded python interpreter. When running under the script command, lldb sets some convenience variables that give you quick access to the currently selected entities that characterize the program and debugger state. In each case, if there is no currently selected entity of the appropriate type, the variable's IsValid method will return false.

Note also, these variables hold the values of the selected objects on entry to the embedded interpreter. They do not update as you use the LLDB API's to change, for example, the currently selected stack frame or thread.

Once in the embedded interpreter, these objects can be used. To get started, note that almost all of the lldb Python objects are able to briefly describe themselves when you pass them to the Python print function:

(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> print lldb.debugger
Debugger (instance: "debugger_1", id: 1)
>>> print lldb.target
a.out
>>> print lldb.process
SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
>>> print lldb.thread
SBThread: tid = 0x1f03
>>> print lldb.frame
frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16

One very powerful use of the lldb Python API is to have a python script run when a breakpoint gets hit. Adding python scripts to breakpoints provides a way to create complex breakpoint conditions and also allows for smart logging and data gathering.

When your process hits a breakpoint to which you have attached some python code, the code is executed as the body of a function which takes two arguments:

def breakpoint_function_wrapper(frame, bp_loc):
  # Your code goes here

An example will show how simple it is to write some python code and attach it to a breakpoint. The following example will allow you to track the order in which the functions in a given shared library are first executed during one run of your program. This is a simple method to gather an order file which can be used to optimize function placement within a binary for execution locality.

We do this by setting a regular expression breakpoint that will match every function in the shared library. The regular expression '.' will match any string that has at least one character in it, so we will use that. This will result in one lldb.SBBreakpoint object that contains an lldb.SBBreakpointLocation object for each function. As the breakpoint gets hit, we use a counter to track the order in which the function at this particular breakpoint location got hit. Since our code is passed the location that was hit, we can get the name of the function from the location, disable the location so we won't count this function again; then log some info and continue the process.

Note we also have to initialize our counter, which we do with the simple one-line version of the script command.

Here is the code:

(lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib
Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
(lldb) script counter = 0
(lldb) breakpoint command add --script-type python 1
Enter your Python command(s). Type 'DONE' to end.
> # Increment our counter.  Since we are in a function, this must be a global python variable
> global counter 
> counter += 1
> # Get the name of the function
> name = frame.GetFunctionName()
> # Print the order and the function name
> print '[%i] %s' % (counter, name)
> # Disable the current breakpoint location so it doesn't get hit again
> bp_loc.SetEnabled(False)
> # How continue the process
> frame.GetThread().GetProcess().Continue()
> DONE

The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command:

(lldb) breakpoint command delete 1

Python functions can be used to create new LLDB command interpreter commands, which will work like all the natively defined lldb commands. This provides a very flexible and easy way to extend LLDB to meet your debugging requirements.

To write a python function that implements a new LDB command define the function to take four arguments as follows:

def command_function(debugger, command, result, dict):
          # Your code goes here
        

One other handy convenience when defining lldb command-line commands is the command command script import which will import a module specified by file path - so you don't have to change your PYTHONPATH for temporary scripts. It also has another convenience that if your new script module has a function of the form:

def __lldb_module_init(debugger, dict):
    # Command Initialization code goes here

where debugger and dict are as above, that function will get run when the module is loaded allowing you to add whatever commands you want into the current debugger. Note that this function will only be run when using the LLDB comand command script import, it will not get run if anyone imports your module from another module. If you want to always run code when your module is loaded from LLDB or when loaded via an import statement in python code you can test the lldb.debugger object, since you imported the module at the top of the python ls.py module. This test must be in code that isn't contained inside of any function or class, just like the standard test for __main__ like all python modules usally do. Sample code would look like:

if __name__ == '__main__':
    # Create a new debugger instance in your module if your module 
    # can be run from the command line. When we run a script from
    # the command line, we won't have any debugger object in
    # lldb.debugger, so we can just create it if it will be needed
    lldb.debugger = lldb.SBDebugger.Create()
elif lldb.debugger:
    # Module is being run inside the LLDB interpreter
    lldb.debugger.HandleCommand('command script add -f ls.ls ls')
    print 'The "ls" python command has been installed and is ready for use.'

Now we can create a module called ls.py in the file ~/ls.py that will implement a function that can be used by LLDB's python command code:

#!/usr/bin/python

import lldb
import commands
import optparse
import shlex

def ls(debugger, command, result, dict):
    result.PutCString(commands.getoutput('/bin/ls %s' % command))

# And the initialization code to add your commands 
def __lldb_module_init(debugger, dict):
    debugger.HandleCommand('command script add -f ls.ls ls')
    print 'The "ls" python command has been installed and is ready for use.'

Now we can load the module into LLDB and use it

% lldb
(lldb) command script import ~/ls.py
The "ls" python command has been installed and is ready for use.
(lldb) ls -l /tmp/
total 365848
-rw-r--r--@  1 someuser  wheel         6148 Jan 19 17:27 .DS_Store
-rw-------   1 someuser  wheel         7331 Jan 19 15:37 crash.log

A template has been created in the source repository that can help you to create lldb command quickly: