Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
| 2 | <html xmlns="http://www.w3.org/1999/xhtml">
|
| 3 | <head>
|
| 4 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
| 5 | <link href="style.css" rel="stylesheet" type="text/css" />
|
Greg Clayton | f3edcc0 | 2012-01-26 00:32:22 +0000 | [diff] [blame] | 6 | <title>LLDB Python Reference</title>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 7 | </head>
|
| 8 |
|
| 9 | <body>
|
| 10 | <div class="www_title">
|
Greg Clayton | f3edcc0 | 2012-01-26 00:32:22 +0000 | [diff] [blame] | 11 | LLDB Python Reference
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 12 | </div>
|
| 13 |
|
| 14 | <div id="container">
|
| 15 | <div id="content">
|
| 16 | <!--#include virtual="sidebar.incl"-->
|
| 17 | <div id="middle">
|
| 18 | <div class="post">
|
| 19 | <h1 class ="postheader">Introduction</h1>
|
| 20 | <div class="postcontent">
|
| 21 |
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 22 | <p>The entire LLDB API is available as Python functions through a script bridging interface.
|
| 23 | This means the LLDB API's can be used directly from python either interactively or to build python apps that
|
| 24 | provide debugger features. </p>
|
| 25 | <p>Additionally, Python can be used as a programmatic interface within the
|
| 26 | lldb command interpreter (we refer to this for brevity as the embedded interpreter). Of course,
|
| 27 | in this context it has full access to the LLDB API - with some additional conveniences we will
|
| 28 | call out in the FAQ.</p>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 29 |
|
| 30 | </div>
|
| 31 | <div class="postfooter"></div>
|
Greg Clayton | d47c792 | 2012-06-29 16:25:05 +0000 | [diff] [blame] | 32 | <div class="post">
|
| 33 | <h1 class ="postheader">Documentation</h1>
|
| 34 | <div class="postcontent">
|
| 35 |
|
Daniel Malea | da1becd | 2013-07-19 19:15:45 +0000 | [diff] [blame] | 36 | <p>The LLDB API is contained in a python module named <b>lldb</b> documented <a href="python_reference/index.html">here</a>. The documentation is also accessible in an interactive debugger session with the following command:</p>
|
Greg Clayton | d47c792 | 2012-06-29 16:25:05 +0000 | [diff] [blame] | 37 | <code><pre><tt>(lldb) <b>script help(lldb)</b>
|
| 38 | Help on package lldb:
|
| 39 |
|
| 40 | NAME
|
| 41 | lldb - The lldb module contains the public APIs for Python binding.
|
| 42 |
|
| 43 | FILE
|
| 44 | /System/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/Python/lldb/__init__.py
|
| 45 |
|
| 46 | DESCRIPTION
|
| 47 | ...
|
| 48 | </tt></pre></code>
|
| 49 | <p>You can also get help using a module class name. The full API that is exposed for that class will be displayed in a man page style window. Below we want to get help on the lldb.SBFrame class:</p>
|
| 50 | <code><pre><tt>(lldb) <b>script help(lldb.SBFrame)</b>
|
| 51 | Help on class SBFrame in module lldb:
|
| 52 |
|
| 53 | class SBFrame(__builtin__.object)
|
| 54 | | Represents one of the stack frames associated with a thread.
|
| 55 | | SBThread contains SBFrame(s). For example (from test/lldbutil.py),
|
| 56 | |
|
| 57 | | def print_stacktrace(thread, string_buffer = False):
|
| 58 | | '''Prints a simple stack trace of this thread.'''
|
| 59 | |
|
| 60 | ...
|
| 61 | </tt></pre></code>
|
| 62 | <p>Or you can get help using any python object, here we use the <b>lldb.process</b> object which is a global variable in the <b>lldb</b> module which represents the currently selected process:</p>
|
| 63 | <code><pre><tt>(lldb) <b>script help(lldb.process)</b>
|
| 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 | </tt></pre></code>
|
| 77 |
|
| 78 | </div>
|
| 79 | <div class="postfooter"></div>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 80 |
|
| 81 | <div class="post">
|
| 82 | <h1 class ="postheader">Embedded Python Interpreter</h1>
|
| 83 | <div class="postcontent">
|
| 84 |
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 85 | <p>The embedded python interpreter can be accessed in a variety of ways from within LLDB. The
|
| 86 | easiest way is to use the lldb command <b>script</b> with no arguments at the lldb command prompt:</p>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 87 | <code><pre><tt>(lldb) <strong>script</strong>
|
| 88 | Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
|
| 89 | >>> 2+3
|
| 90 | 5
|
| 91 | >>> hex(12345)
|
| 92 | '0x3039'
|
| 93 | >>>
|
| 94 | </tt></pre></code>
|
| 95 |
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 96 | <p>This drops you into the embedded python interpreter. When running under the <b>script</b> command,
|
| 97 | lldb sets some convenience variables that give you quick access to the currently selected entities that characterize
|
| 98 | the program and debugger state. In each case, if there is no currently selected entity of the appropriate
|
Enrico Granata | b1052dc | 2013-01-16 22:25:17 +0000 | [diff] [blame] | 99 | type, the variable's <b>IsValid</b> method will return false. These variables are:</p>
|
| 100 |
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 101 | <table class="stats" width="620" cellspacing="0">
|
| 102 | <tr>
|
| 103 | <td class="hed" width="20%">Variable</td>
|
| 104 | <td class="hed" width="10%">Type</td>
|
| 105 | <td class="hed" width="70%">Description</td>
|
| 106 | </tr>
|
| 107 |
|
| 108 | <tr>
|
| 109 | <td class="content">
|
| 110 | <b>lldb.debugger</b>
|
| 111 | </td>
|
| 112 | <td class="content">
|
| 113 | <b>lldb.SBDebugger</b>
|
| 114 | </td>
|
| 115 | <td class="content">
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 116 | Contains the debugger object whose <b>script</b> command was invoked.
|
| 117 | The <b>lldb.SBDebugger</b> object owns the command interpreter
|
| 118 | and all the targets in your debug session. There will always be a
|
| 119 | Debugger in the embedded interpreter.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 120 | </td>
|
| 121 | </tr>
|
| 122 | <tr>
|
| 123 | <td class="content">
|
| 124 | <b>lldb.target</b>
|
| 125 | </td>
|
| 126 | <td class="content">
|
| 127 | <b>lldb.SBTarget</b>
|
| 128 | </td>
|
| 129 | <td class="content">
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 130 | Contains the currently selected target - for instance the one made with the
|
| 131 | <b>file</b> or selected by the <b>target select <target-index></b> command.
|
| 132 | The <b>lldb.SBTarget</b> manages one running process, and all the executable
|
| 133 | and debug files for the process.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 134 | </td>
|
| 135 | </tr>
|
| 136 | <tr>
|
| 137 | <td class="content">
|
| 138 | <b>lldb.process</b>
|
| 139 | </td>
|
| 140 | <td class="content">
|
| 141 | <b>lldb.SBProcess</b>
|
| 142 | </td>
|
| 143 | <td class="content">
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 144 | Contains the process of the currently selected target.
|
| 145 | The <b>lldb.SBProcess</b> object manages the threads and allows access to
|
| 146 | memory for the process.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 147 | </td>
|
| 148 | </tr>
|
| 149 | <tr>
|
| 150 | <td class="content">
|
| 151 | <b>lldb.thread</b>
|
| 152 | </td>
|
| 153 | <td class="content">
|
| 154 | <b>lldb.SBThread</b>
|
| 155 | </td>
|
| 156 | <td class="content">
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 157 | Contains the currently selected thread.
|
| 158 | The <b>lldb.SBThread</b> object manages the stack frames in that thread.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 159 | A thread is always selected in the command interpreter when a target stops.
|
Enrico Granata | b1052dc | 2013-01-16 22:25:17 +0000 | [diff] [blame] | 160 | The <b>thread select <thread-index></b> command can be used to change the
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 161 | currently selected thread. So as long as you have a stopped process, there will be
|
| 162 | some selected thread.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 163 | </td>
|
| 164 | </tr>
|
| 165 | <tr>
|
| 166 | <td class="content">
|
| 167 | <b>lldb.frame</b>
|
| 168 | </td>
|
| 169 | <td class="content">
|
| 170 | <b>lldb.SBFrame</b>
|
| 171 | </td>
|
| 172 | <td class="content">
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 173 | Contains the currently selected stack frame.
|
| 174 | The <b>lldb.SBFrame</b> object manage the stack locals and the register set for
|
| 175 | that stack.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 176 | A stack frame is always selected in the command interpreter when a target stops.
|
Enrico Granata | b1052dc | 2013-01-16 22:25:17 +0000 | [diff] [blame] | 177 | The <b>frame select <frame-index></b> command can be used to change the
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 178 | currently selected frame. So as long as you have a stopped process, there will
|
| 179 | be some selected frame.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 180 | </td>
|
| 181 | </tr>
|
| 182 | </table>
|
| 183 |
|
Enrico Granata | b1052dc | 2013-01-16 22:25:17 +0000 | [diff] [blame] | 184 | <p>While extremely convenient, these variables have a couple caveats that you should be aware of.
|
| 185 | First of all, they hold the values
|
| 186 | of the selected objects on entry to the embedded interpreter. They do not update as you use the LLDB
|
| 187 | API's to change, for example, the currently selected stack frame or thread.
|
| 188 | <p>Moreover, they are only defined and meaningful while in the interactive Python interpreter.
|
| 189 | There is no guarantee on their value in any other situation, hence you should not use them when defining
|
| 190 | Python formatters, breakpoint scripts and commands (or any other Python extension point that LLDB provides).
|
| 191 | As a rationale for such behavior, consider that lldb can
|
| 192 | run in a multithreaded environment, and another thread might call the "script" command, changing the value out
|
| 193 | from under you.</p>
|
| 194 |
|
| 195 | <p>To get started with these objects and LLDB scripting, please note that almost
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 196 | all of the <b>lldb</b> Python objects are able to briefly describe themselves when you pass them
|
| 197 | to the Python <b>print</b> function:
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 198 | <code><pre><tt>(lldb) <b>script</b>
|
| 199 | Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
|
| 200 | >>> <strong>print lldb.debugger</strong>
|
| 201 | Debugger (instance: "debugger_1", id: 1)
|
| 202 | >>> <strong>print lldb.target</strong>
|
| 203 | a.out
|
| 204 | >>> <strong>print lldb.process</strong>
|
| 205 | SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
|
| 206 | >>> <strong>print lldb.thread</strong>
|
| 207 | SBThread: tid = 0x1f03
|
| 208 | >>> <strong>print lldb.frame</strong>
|
| 209 | frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16
|
| 210 | </tt></pre></code>
|
| 211 |
|
| 212 | </div>
|
| 213 | <div class="postfooter"></div>
|
| 214 |
|
| 215 | </div>
|
| 216 | <div class="post">
|
| 217 | <h1 class ="postheader">Running a Python script when a breakpoint gets hit</h1>
|
| 218 | <div class="postcontent">
|
| 219 |
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 220 | <p>One very powerful use of the lldb Python API is to have a python script run when a breakpoint gets hit. Adding python
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 221 | scripts to breakpoints provides a way to create complex breakpoint
|
| 222 | conditions and also allows for smart logging and data gathering.</p>
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 223 | <p>When your process hits a breakpoint to which you have attached some python code, the code is executed as the
|
Greg Clayton | b34ca85 | 2012-10-26 17:53:21 +0000 | [diff] [blame] | 224 | body of a function which takes three arguments:</p>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 225 | <p>
|
Greg Clayton | b34ca85 | 2012-10-26 17:53:21 +0000 | [diff] [blame] | 226 | <code><pre><tt>def breakpoint_function_wrapper(<b>frame</b>, <b>bp_loc</b>, <b>dict</b>):
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 227 | <font color=green># Your code goes here</font>
|
| 228 | </tt></pre></code>
|
| 229 | <p><table class="stats" width="620" cellspacing="0">
|
| 230 | <tr>
|
| 231 | <td class="hed" width="10%">Argument</td>
|
| 232 | <td class="hed" width="10%">Type</td>
|
| 233 | <td class="hed" width="80%">Description</td>
|
| 234 | </tr>
|
| 235 |
|
| 236 | <tr>
|
| 237 | <td class="content">
|
| 238 | <b>frame</b>
|
| 239 | </td>
|
| 240 | <td class="content">
|
| 241 | <b>lldb.SBFrame</b>
|
| 242 | </td>
|
| 243 | <td class="content">
|
| 244 | The current stack frame where the breakpoint got hit.
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 245 | The object will always be valid.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 246 | This <b>frame</b> argument might <i>not</i> match the currently selected stack frame found in the <b>lldb</b> module global variable <b>lldb.frame</b>.
|
| 247 | </td>
|
| 248 | </tr>
|
| 249 | <tr>
|
| 250 | <td class="content">
|
| 251 | <b>bp_loc</b>
|
| 252 | </td>
|
| 253 | <td class="content">
|
| 254 | <b>lldb.SBBreakpointLocation</b>
|
| 255 | </td>
|
| 256 | <td class="content">
|
| 257 | The breakpoint location that just got hit. Breakpoints are represented by <b>lldb.SBBreakpoint</b>
|
| 258 | objects. These breakpoint objects can have one or more locations. These locations
|
| 259 | are represented by <b>lldb.SBBreakpointLocation</b> objects.
|
| 260 | </td>
|
| 261 | </tr>
|
Greg Clayton | b34ca85 | 2012-10-26 17:53:21 +0000 | [diff] [blame] | 262 | <tr>
|
| 263 | <td class="content">
|
| 264 | <b>dict</b>
|
| 265 | </td>
|
| 266 | <td class="content">
|
| 267 | <b>dict</b>
|
| 268 | </td>
|
| 269 | <td class="content">
|
| 270 | The python session dictionary as a standard python dictionary object.
|
| 271 | </td>
|
| 272 | </tr>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 273 | </table>
|
Enrico Granata | 5c7c781 | 2013-05-16 23:17:25 +0000 | [diff] [blame] | 274 | <p>Optionally, a Python breakpoint command can return a value. Returning False tells LLDB that you do not want to stop at the breakpoint.
|
| 275 | Any other return value (including None or leaving out the return statement altogether) is akin to telling LLDB to actually stop at the breakpoint.
|
| 276 | This can be useful in situations where a breakpoint only needs to stop the process when certain conditions are met, and you do not want to inspect the
|
| 277 | program state manually at every stop and then continue.
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 278 | <p>An example will show how simple it is to write some python code and attach it to a breakpoint.
|
| 279 | The following example will allow you to track the order in which the functions in a given shared library
|
| 280 | are first executed during one run of your program. This is a simple method to gather an order file which
|
| 281 | can be used to optimize function placement within a binary for execution locality.</p>
|
| 282 | <p>We do this by setting a regular expression breakpoint
|
| 283 | that will match every function in the shared library. The regular expression '.' will match
|
| 284 | any string that has at least one character in it, so we will use that.
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 285 | This will result in one <b>lldb.SBBreakpoint</b> object
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 286 | that contains an <b>lldb.SBBreakpointLocation</b> object for each function. As the breakpoint gets
|
| 287 | hit, we use a counter to track the order in which the function at this particular breakpoint location got hit.
|
| 288 | Since our code is passed the location that was hit, we can get the name of the function from the location,
|
| 289 | disable the location so we won't count this function again; then log some info and continue the process.</p>
|
| 290 | <p>Note we also have to initialize our counter, which we do with the simple one-line version of the <b>script</b>
|
| 291 | command.
|
| 292 | <p>Here is the code:
|
| 293 |
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 294 | <code><pre><tt>(lldb) <strong>breakpoint set --func-regex=. --shlib=libfoo.dylib</strong>
|
| 295 | Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 296 | (lldb) <strong>script counter = 0</strong>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 297 | (lldb) <strong>breakpoint command add --script-type python 1</strong>
|
| 298 | Enter your Python command(s). Type 'DONE' to end.
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 299 | > <font color=green># Increment our counter. Since we are in a function, this must be a global python variable</font>
|
| 300 | > <strong>global counter</strong>
|
| 301 | > <strong>counter += 1</strong>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 302 | > <font color=green># Get the name of the function</font>
|
| 303 | > <strong>name = frame.GetFunctionName()</strong>
|
| 304 | > <font color=green># Print the order and the function name</font>
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 305 | > <strong>print '[%i] %s' % (counter, name)</strong>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 306 | > <font color=green># Disable the current breakpoint location so it doesn't get hit again</font>
|
| 307 | > <strong>bp_loc.SetEnabled(False)</strong>
|
Enrico Granata | f812f62 | 2013-05-31 22:54:23 +0000 | [diff] [blame] | 308 | > <font color=green># No need to stop here</font>
|
| 309 | > <strong>return False</strong>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 310 | > <strong>DONE</strong>
|
| 311 | </tt></pre></code>
|
| 312 | <p>The <b>breakpoint command add</b> command above attaches a python script to breakpoint 1.
|
| 313 | To remove the breakpoint command:
|
| 314 | <p><code>(lldb) <strong>breakpoint command delete 1</strong></code>
|
| 315 | </div>
|
| 316 | </div>
|
| 317 | <div class="post">
|
| 318 | <h1 class ="postheader">Create a new LLDB command using a python function</h1>
|
| 319 | <div class="postcontent">
|
| 320 |
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 321 | <p>Python functions can be used to create new LLDB command interpreter commands, which will work
|
| 322 | like all the natively defined lldb commands. This provides a very flexible and easy way to extend LLDB to meet your
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 323 | debugging requirements. </p>
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 324 | <p>To write a python function that implements a new LDB command define the function to take four arguments as follows:</p>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 325 |
|
Enrico Granata | c1ca9dc | 2012-08-08 02:06:30 +0000 | [diff] [blame] | 326 | <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>internal_dict</b>):
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 327 | <font color=green># Your code goes here</font>
|
| 328 | </tt></pre></code>
|
Enrico Granata | c0791aa | 2012-05-02 21:00:41 +0000 | [diff] [blame] | 329 |
|
| 330 | Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in:
|
Enrico Granata | c1ca9dc | 2012-08-08 02:06:30 +0000 | [diff] [blame] | 331 | <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>internal_dict</b>):
|
Enrico Granata | c0791aa | 2012-05-02 21:00:41 +0000 | [diff] [blame] | 332 | <font color=green>"""This command takes a lot of options and does many fancy things"""</font>
|
| 333 | <font color=green># Your code goes here</font>
|
| 334 | </tt></pre></code>
|
| 335 |
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 336 | <p><table class="stats" width="620" cellspacing="0">
|
| 337 | <tr>
|
| 338 | <td class="hed" width="10%">Argument</td>
|
| 339 | <td class="hed" width="10%">Type</td>
|
| 340 | <td class="hed" width="80%">Description</td>
|
| 341 | </tr>
|
| 342 |
|
| 343 | <tr>
|
| 344 | <td class="content">
|
| 345 | <b>debugger</b>
|
| 346 | </td>
|
| 347 | <td class="content">
|
| 348 | <b>lldb.SBDebugger</b>
|
| 349 | </td>
|
| 350 | <td class="content">
|
| 351 | The current debugger object.
|
| 352 | </td>
|
| 353 | </tr>
|
| 354 | <tr>
|
| 355 | <td class="content">
|
| 356 | <b>command</b>
|
| 357 | </td>
|
| 358 | <td class="content">
|
| 359 | <b>python string</b>
|
| 360 | </td>
|
| 361 | <td class="content">
|
| 362 | A python string containing all arguments for your command. If you need to chop up the arguments
|
| 363 | try using the <b>shlex</b> module's <code>shlex.split(command)</code> to properly extract the
|
| 364 | arguments.
|
| 365 | </td>
|
| 366 | </tr>
|
| 367 | <tr>
|
| 368 | <td class="content">
|
| 369 | <b>result</b>
|
| 370 | </td>
|
| 371 | <td class="content">
|
| 372 | <b>lldb.SBCommandReturnObject</b>
|
| 373 | </td>
|
| 374 | <td class="content">
|
Enrico Granata | f734066 | 2013-03-25 17:37:39 +0000 | [diff] [blame] | 375 | A return object which encapsulates success/failure information for the command and output text
|
| 376 | that needs to be printed as a result of the command. The plain Python "print" command also works but
|
| 377 | text won't go in the result by default (it is useful as a temporary logging facility).
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 378 | </td>
|
| 379 | </tr>
|
| 380 | <tr>
|
| 381 | <td class="content">
|
Enrico Granata | c1ca9dc | 2012-08-08 02:06:30 +0000 | [diff] [blame] | 382 | <b>internal_dict</b>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 383 | </td>
|
| 384 | <td class="content">
|
| 385 | <b>python dict object</b>
|
| 386 | </td>
|
| 387 | <td class="content">
|
| 388 | The dictionary for the current embedded script session which contains all variables
|
| 389 | and functions.
|
| 390 | </td>
|
| 391 | </tr>
|
| 392 | </table>
|
Enrico Granata | f734066 | 2013-03-25 17:37:39 +0000 | [diff] [blame] | 393 | <p>As a convenience, you can treat the result object as a Python file object, and say
|
Enrico Granata | f812f62 | 2013-05-31 22:54:23 +0000 | [diff] [blame] | 394 | <code><pre><tt>print >>result, "my command does lots of cool stuff"</tt></pre></code>
|
| 395 | SBCommandReturnObject and SBStream
|
Enrico Granata | f734066 | 2013-03-25 17:37:39 +0000 | [diff] [blame] | 396 | both support this file-like behavior by providing write() and flush() calls at the Python layer.</p>
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 397 | <p>One other handy convenience when defining lldb command-line commands is the command
|
| 398 | <b>command script import</b> which will import a module specified by file path - so you
|
| 399 | don't have to change your PYTHONPATH for temporary scripts. It also has another convenience
|
| 400 | that if your new script module has a function of the form:</p>
|
| 401 |
|
Enrico Granata | c1ca9dc | 2012-08-08 02:06:30 +0000 | [diff] [blame] | 402 | <code><pre><tt>def __lldb_init_module(<b>debugger</b>, <b>internal_dict</b>):
|
Greg Clayton | 261c974 | 2012-01-26 05:36:07 +0000 | [diff] [blame] | 403 | <font color=green># Command Initialization code goes here</font>
|
| 404 | </tt></pre></code>
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 405 |
|
Enrico Granata | c1ca9dc | 2012-08-08 02:06:30 +0000 | [diff] [blame] | 406 | <p>where <b>debugger</b> and <b>internal_dict</b> are as above, that function will get run when the module is loaded
|
Greg Clayton | 261c974 | 2012-01-26 05:36:07 +0000 | [diff] [blame] | 407 | allowing you to add whatever commands you want into the current debugger. Note that
|
| 408 | this function will only be run when using the LLDB comand <b>command script import</b>,
|
| 409 | it will not get run if anyone imports your module from another module.
|
| 410 | If you want to always run code when your module is loaded from LLDB
|
| 411 | <u>or</u> when loaded via an <b>import</b> statement in python code
|
| 412 | you can test the <b>lldb.debugger</b> object, since you imported the
|
| 413 | <lldb> module at the top of the python <b>ls.py</b> module. This test
|
| 414 | must be in code that isn't contained inside of any function or class,
|
| 415 | just like the standard test for <b>__main__</b> like all python modules
|
| 416 | usally do. Sample code would look like:
|
| 417 |
|
| 418 | <code><pre><tt>if __name__ == '__main__':
|
| 419 | <font color=green># Create a new debugger instance in your module if your module
|
| 420 | # can be run from the command line. When we run a script from
|
| 421 | # the command line, we won't have any debugger object in
|
| 422 | # lldb.debugger, so we can just create it if it will be needed</font>
|
| 423 | lldb.debugger = lldb.SBDebugger.Create()
|
| 424 | elif lldb.debugger:
|
| 425 | <font color=green># Module is being run inside the LLDB interpreter</font>
|
| 426 | lldb.debugger.HandleCommand('command script add -f ls.ls ls')
|
| 427 | print 'The "ls" python command has been installed and is ready for use.'
|
| 428 | </tt></pre></code>
|
| 429 | <p>Now we can create a module called <b>ls.py</b> in the file <b>~/ls.py</b> that will implement a function that
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 430 | can be used by LLDB's python command code:</p>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 431 |
|
| 432 | <code><pre><tt><font color=green>#!/usr/bin/python</font>
|
| 433 |
|
| 434 | import lldb
|
| 435 | import commands
|
| 436 | import optparse
|
| 437 | import shlex
|
| 438 |
|
Enrico Granata | c1ca9dc | 2012-08-08 02:06:30 +0000 | [diff] [blame] | 439 | def ls(debugger, command, result, internal_dict):
|
Enrico Granata | b89642b | 2013-07-11 21:49:38 +0000 | [diff] [blame] | 440 | print >>result, (commands.getoutput('/bin/ls %s' % command))
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 441 |
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 442 | <font color=green># And the initialization code to add your commands </font>
|
Enrico Granata | c1ca9dc | 2012-08-08 02:06:30 +0000 | [diff] [blame] | 443 | def __lldb_init_module(debugger, internal_dict):
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 444 | debugger.HandleCommand('command script add -f ls.ls ls')
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 445 | print 'The "ls" python command has been installed and is ready for use.'
|
| 446 | </tt></pre></code>
|
| 447 | <p>Now we can load the module into LLDB and use it</p>
|
| 448 | <code><pre><tt>% lldb
|
Greg Clayton | 261c974 | 2012-01-26 05:36:07 +0000 | [diff] [blame] | 449 | (lldb) <strong>command script import ~/ls.py</strong>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 450 | The "ls" python command has been installed and is ready for use.
|
| 451 | (lldb) <strong>ls -l /tmp/</strong>
|
| 452 | total 365848
|
| 453 | -rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store
|
| 454 | -rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log
|
| 455 | </tt></pre></code>
|
Enrico Granata | ac39f3c | 2013-05-09 01:32:24 +0000 | [diff] [blame] | 456 | <p>A more interesting template has been created in the source repository that can help you to create
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 457 | lldb command quickly:</p>
|
| 458 | <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/cmdtemplate.py">cmdtemplate.py</a>
|
Enrico Granata | 74566c9 | 2012-08-24 21:20:14 +0000 | [diff] [blame] | 459 | <p>
|
| 460 | A commonly required facility is being able to create a command that does some token substitution, and then runs a different debugger command
|
| 461 | (usually, it po'es the result of an expression evaluated on its argument). For instance, given the following program:
|
| 462 | <code><pre><tt>
|
| 463 | #import <Foundation/Foundation.h>
|
| 464 | NSString*
|
| 465 | ModifyString(NSString* src)
|
| 466 | {
|
| 467 | return [src stringByAppendingString:@"foobar"];
|
| 468 | }
|
| 469 |
|
| 470 | int main()
|
| 471 | {
|
| 472 | NSString* aString = @"Hello world";
|
| 473 | NSString* anotherString = @"Let's be friends";
|
| 474 | return 1;
|
| 475 | }
|
| 476 | </tt></pre></code>
|
| 477 | you may want a pofoo X command, that equates po [ModifyString(X) capitalizedString].
|
| 478 | The following debugger interaction shows how to achieve that goal:
|
| 479 | <code><pre><tt>
|
| 480 | (lldb) <b>script</b>
|
| 481 | Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
|
| 482 | >>> <b>def pofoo_funct(debugger, command, result, internal_dict):</b>
|
| 483 | ... <b>cmd = "po [ModifyString(" + command + ") capitalizedString]"</b>
|
| 484 | ... <b>lldb.debugger.HandleCommand(cmd)</b>
|
| 485 | ...
|
| 486 | >>> ^D
|
| 487 | (lldb) <b>command script add pofoo -f pofoo_funct</b>
|
| 488 | (lldb) <b>pofoo aString</b>
|
| 489 | $1 = 0x000000010010aa00 Hello Worldfoobar
|
| 490 | (lldb) <b>pofoo anotherString</b>
|
| 491 | $2 = 0x000000010010aba0 Let's Be Friendsfoobar</tt></pre></code>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 492 | </div>
|
| 493 | <div class="post">
|
| 494 | <h1 class ="postheader">Using the lldb.py module in python</h1>
|
| 495 | <div class="postcontent">
|
| 496 |
|
| 497 | <p>LLDB has all of its core code build into a shared library which gets
|
| 498 | used by the <b>lldb</b> command line application. On Mac OS X this
|
| 499 | shared library is a framework: <b>LLDB.framework</b> and on other
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 500 | unix variants the program is a shared library: <b>lldb.so</b>. LLDB also
|
| 501 | provides an lldb.py module that contains the bindings from LLDB into Python.
|
| 502 | To use the
|
| 503 | <b>LLDB.framework</b> to create your own stand-alone python programs, you will
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 504 | need to tell python where to look in order to find this module. This
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 505 | is done by setting the <b>PYTHONPATH</b> environment variable, adding
|
| 506 | a path to the directory that contains the <b>lldb.py</b> python module. On
|
| 507 | Mac OS X, this is contained inside the LLDB.framework, so you would do:
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 508 |
|
| 509 | <p>For csh and tcsh:</p>
|
| 510 | <p><code>% <b>setenv PYTHONPATH /Developer/Library/PrivateFrameworks/LLDB.framework/Resources/Python</b></code></p>
|
| 511 | <p>For sh and bash:
|
| 512 | <p><code>% <b>export PYTHONPATH=/Developer/Library/PrivateFrameworks/LLDB.framework/Resources/Python</b></code></p>
|
| 513 |
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 514 | <p> Alternately, you can append the LLDB Python directory to the <b>sys.path</b> list directly in
|
| 515 | your Python code before importing the lldb module.</p>
|
| 516 |
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 517 | <p>
|
| 518 | Now your python scripts are ready to import the lldb module. Below is a
|
| 519 | python script that will launch a program from the current working directory
|
| 520 | called "a.out", set a breakpoint at "main", and then run and hit the breakpoint,
|
| 521 | and print the process, thread and frame objects if the process stopped:
|
| 522 |
|
| 523 | </p>
|
| 524 | <code><pre><tt><font color=green>#!/usr/bin/python</font>
|
| 525 |
|
| 526 | import lldb
|
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 527 | import os
|
| 528 |
|
| 529 | def disassemble_instructions(insts):
|
| 530 | for i in insts:
|
| 531 | print i
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 532 |
|
| 533 | <font color=green># Set the path to the executable to debug</font>
|
| 534 | exe = "./a.out"
|
| 535 |
|
| 536 | <font color=green># Create a new debugger instance</font>
|
| 537 | debugger = lldb.SBDebugger.Create()
|
| 538 |
|
| 539 | <font color=green># When we step or continue, don't return from the function until the process
|
Jim Ingham | 062a836 | 2012-01-24 02:40:42 +0000 | [diff] [blame] | 540 | # stops. Otherwise we would have to handle the process events ourselves which, while doable is
|
| 541 | #a little tricky. We do this by setting the async mode to false.</font>
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 542 | debugger.SetAsync (False)
|
| 543 |
|
| 544 | <font color=green># Create a target from a file and arch</font>
|
| 545 | print "Creating a target for '%s'" % exe
|
| 546 |
|
| 547 | target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
|
| 548 |
|
| 549 | if target:
|
| 550 | <font color=green># If the target is valid set a breakpoint at main</font>
|
| 551 | main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename());
|
| 552 |
|
| 553 | print main_bp
|
| 554 |
|
| 555 | <font color=green># Launch the process. Since we specified synchronous mode, we won't return
|
| 556 | # from this function until we hit the breakpoint at main</font>
|
| 557 | process = target.LaunchSimple (None, None, os.getcwd())
|
| 558 |
|
| 559 | <font color=green># Make sure the launch went ok</font>
|
| 560 | if process:
|
| 561 | <font color=green># Print some simple process info</font>
|
| 562 | state = process.GetState ()
|
| 563 | print process
|
| 564 | if state == lldb.eStateStopped:
|
Daniel Malea | 7a87d52 | 2013-02-12 20:01:49 +0000 | [diff] [blame] | 565 | <font color=green># Get the first thread</font>
|
| 566 | thread = process.GetThreadAtIndex (0)
|
| 567 | if thread:
|
| 568 | <font color=green># Print some simple thread info</font>
|
| 569 | print thread
|
| 570 | <font color=green># Get the first frame</font>
|
| 571 | frame = thread.GetFrameAtIndex (0)
|
| 572 | if frame:
|
| 573 | <font color=green># Print some simple frame info</font>
|
| 574 | print frame
|
| 575 | function = frame.GetFunction()
|
| 576 | <font color=green># See if we have debug info (a function)</font>
|
| 577 | if function:
|
| 578 | <font color=green># We do have a function, print some info for the function</font>
|
| 579 | print function
|
| 580 | <font color=green># Now get all instructions for this function and print them</font>
|
| 581 | insts = function.GetInstructions(target)
|
| 582 | disassemble_instructions (insts)
|
| 583 | else:
|
| 584 | <font color=green># See if we have a symbol in the symbol table for where we stopped</font>
|
| 585 | symbol = frame.GetSymbol();
|
| 586 | if symbol:
|
| 587 | <font color=green># We do have a symbol, print some info for the symbol</font>
|
| 588 | print symbol
|
Greg Clayton | f9ab5ea | 2012-01-22 02:55:08 +0000 | [diff] [blame] | 589 | </tt></pre></code>
|
| 590 | </div>
|
| 591 | <div class="postfooter"></div>
|
| 592 |
|
| 593 | </div>
|
| 594 | </div>
|
| 595 | </div>
|
| 596 | </body>
|
| 597 | </html>
|