blob: cc3cc786c46b339ae60ca404603a670d5d17eac1 [file] [log] [blame]
Greg Claytonf9ab5ea2012-01-22 02:55:08 +00001<!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 Claytonf3edcc02012-01-26 00:32:22 +00006<title>LLDB Python Reference</title>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +00007</head>
8
9<body>
10 <div class="www_title">
Greg Claytonf3edcc02012-01-26 00:32:22 +000011 LLDB Python Reference
Greg Claytonf9ab5ea2012-01-22 02:55:08 +000012 </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 Ingham062a8362012-01-24 02:40:42 +000022 <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 Claytonf9ab5ea2012-01-22 02:55:08 +000029
30 </div>
31 <div class="postfooter"></div>
Greg Claytond47c7922012-06-29 16:25:05 +000032 <div class="post">
33 <h1 class ="postheader">Documentation</h1>
34 <div class="postcontent">
35
Daniel Maleada1becd2013-07-19 19:15:45 +000036 <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 Claytond47c7922012-06-29 16:25:05 +000037<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 Claytonf9ab5ea2012-01-22 02:55:08 +000080
81 <div class="post">
82 <h1 class ="postheader">Embedded Python Interpreter</h1>
83 <div class="postcontent">
84
Jim Ingham062a8362012-01-24 02:40:42 +000085 <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 Claytonf9ab5ea2012-01-22 02:55:08 +000087<code><pre><tt>(lldb) <strong>script</strong>
88Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
89>>> 2+3
905
91>>> hex(12345)
92'0x3039'
93>>>
94</tt></pre></code>
95
Jim Ingham062a8362012-01-24 02:40:42 +000096 <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 Granatab1052dc2013-01-16 22:25:17 +000099 type, the variable's <b>IsValid</b> method will return false. These variables are:</p>
100
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000101 <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 Ingham062a8362012-01-24 02:40:42 +0000116 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000120 </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 Ingham062a8362012-01-24 02:40:42 +0000130 Contains the currently selected target - for instance the one made with the
131 <b>file</b> or selected by the <b>target select &lt;target-index&gt;</b> command.
132 The <b>lldb.SBTarget</b> manages one running process, and all the executable
133 and debug files for the process.
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000134 </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 Ingham062a8362012-01-24 02:40:42 +0000144 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000147 </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 Ingham062a8362012-01-24 02:40:42 +0000157 Contains the currently selected thread.
158 The <b>lldb.SBThread</b> object manages the stack frames in that thread.
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000159 A thread is always selected in the command interpreter when a target stops.
Enrico Granatab1052dc2013-01-16 22:25:17 +0000160 The <b>thread select &lt;thread-index&gt;</b> command can be used to change the
Jim Ingham062a8362012-01-24 02:40:42 +0000161 currently selected thread. So as long as you have a stopped process, there will be
162 some selected thread.
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000163 </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 Ingham062a8362012-01-24 02:40:42 +0000173 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000176 A stack frame is always selected in the command interpreter when a target stops.
Enrico Granatab1052dc2013-01-16 22:25:17 +0000177 The <b>frame select &lt;frame-index&gt;</b> command can be used to change the
Jim Ingham062a8362012-01-24 02:40:42 +0000178 currently selected frame. So as long as you have a stopped process, there will
179 be some selected frame.
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000180 </td>
181 </tr>
182 </table>
183
Enrico Granatab1052dc2013-01-16 22:25:17 +0000184 <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 Ingham062a8362012-01-24 02:40:42 +0000196 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000198<code><pre><tt>(lldb) <b>script</b>
199Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
200>>> <strong>print lldb.debugger</strong>
201Debugger (instance: "debugger_1", id: 1)
202>>> <strong>print lldb.target</strong>
203a.out
204>>> <strong>print lldb.process</strong>
205SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
206>>> <strong>print lldb.thread</strong>
207SBThread: tid = 0x1f03
208>>> <strong>print lldb.frame</strong>
209frame #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 Ingham062a8362012-01-24 02:40:42 +0000220 <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 Claytonf9ab5ea2012-01-22 02:55:08 +0000221 scripts to breakpoints provides a way to create complex breakpoint
222 conditions and also allows for smart logging and data gathering.</p>
Jim Ingham062a8362012-01-24 02:40:42 +0000223 <p>When your process hits a breakpoint to which you have attached some python code, the code is executed as the
Greg Claytonb34ca852012-10-26 17:53:21 +0000224 body of a function which takes three arguments:</p>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000225 <p>
Greg Claytonb34ca852012-10-26 17:53:21 +0000226<code><pre><tt>def breakpoint_function_wrapper(<b>frame</b>, <b>bp_loc</b>, <b>dict</b>):
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000227 <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 Ingham062a8362012-01-24 02:40:42 +0000245 The object will always be valid.
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000246 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 Claytonb34ca852012-10-26 17:53:21 +0000262 <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 Claytonf9ab5ea2012-01-22 02:55:08 +0000273 </table>
Enrico Granata5c7c7812013-05-16 23:17:25 +0000274 <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 Ingham062a8362012-01-24 02:40:42 +0000278 <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 Claytonf9ab5ea2012-01-22 02:55:08 +0000285 This will result in one <b>lldb.SBBreakpoint</b> object
Jim Ingham062a8362012-01-24 02:40:42 +0000286 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000294<code><pre><tt>(lldb) <strong>breakpoint set --func-regex=. --shlib=libfoo.dylib</strong>
295Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
Jim Ingham062a8362012-01-24 02:40:42 +0000296(lldb) <strong>script counter = 0</strong>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000297(lldb) <strong>breakpoint command add --script-type python 1</strong>
298Enter your Python command(s). Type 'DONE' to end.
Jim Ingham062a8362012-01-24 02:40:42 +0000299> <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 Claytonf9ab5ea2012-01-22 02:55:08 +0000302> <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 Ingham062a8362012-01-24 02:40:42 +0000305> <strong>print '[%i] %s' % (counter, name)</strong>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000306> <font color=green># Disable the current breakpoint location so it doesn't get hit again</font>
307> <strong>bp_loc.SetEnabled(False)</strong>
Enrico Granataf812f622013-05-31 22:54:23 +0000308> <font color=green># No need to stop here</font>
309> <strong>return False</strong>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000310> <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 Ingham062a8362012-01-24 02:40:42 +0000321 <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 Claytonf9ab5ea2012-01-22 02:55:08 +0000323 debugging requirements. </p>
Jim Ingham062a8362012-01-24 02:40:42 +0000324 <p>To write a python function that implements a new LDB command define the function to take four arguments as follows:</p>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000325
Enrico Granatac1ca9dc2012-08-08 02:06:30 +0000326 <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>internal_dict</b>):
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000327 <font color=green># Your code goes here</font>
328 </tt></pre></code>
Enrico Granatac0791aa2012-05-02 21:00:41 +0000329
330 Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in:
Enrico Granatac1ca9dc2012-08-08 02:06:30 +0000331 <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>internal_dict</b>):
Enrico Granatac0791aa2012-05-02 21:00:41 +0000332 <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 Claytonf9ab5ea2012-01-22 02:55:08 +0000336 <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 Granataf7340662013-03-25 17:37:39 +0000375 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000378 </td>
379 </tr>
380 <tr>
381 <td class="content">
Enrico Granatac1ca9dc2012-08-08 02:06:30 +0000382 <b>internal_dict</b>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000383 </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 Granataf7340662013-03-25 17:37:39 +0000393 <p>As a convenience, you can treat the result object as a Python file object, and say
Enrico Granataf812f622013-05-31 22:54:23 +0000394 <code><pre><tt>print >>result, "my command does lots of cool stuff"</tt></pre></code>
395 SBCommandReturnObject and SBStream
Enrico Granataf7340662013-03-25 17:37:39 +0000396 both support this file-like behavior by providing write() and flush() calls at the Python layer.</p>
Jim Ingham062a8362012-01-24 02:40:42 +0000397 <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 Granatac1ca9dc2012-08-08 02:06:30 +0000402<code><pre><tt>def __lldb_init_module(<b>debugger</b>, <b>internal_dict</b>):
Greg Clayton261c9742012-01-26 05:36:07 +0000403 <font color=green># Command Initialization code goes here</font>
404</tt></pre></code>
Jim Ingham062a8362012-01-24 02:40:42 +0000405
Enrico Granatac1ca9dc2012-08-08 02:06:30 +0000406 <p>where <b>debugger</b> and <b>internal_dict</b> are as above, that function will get run when the module is loaded
Greg Clayton261c9742012-01-26 05:36:07 +0000407 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()
424elif 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 Ingham062a8362012-01-24 02:40:42 +0000430 can be used by LLDB's python command code:</p>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000431
432<code><pre><tt><font color=green>#!/usr/bin/python</font>
433
434import lldb
435import commands
436import optparse
437import shlex
438
Enrico Granatac1ca9dc2012-08-08 02:06:30 +0000439def ls(debugger, command, result, internal_dict):
Enrico Granatab89642b2013-07-11 21:49:38 +0000440 print >>result, (commands.getoutput('/bin/ls %s' % command))
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000441
Jim Ingham062a8362012-01-24 02:40:42 +0000442<font color=green># And the initialization code to add your commands </font>
Enrico Granatac1ca9dc2012-08-08 02:06:30 +0000443def __lldb_init_module(debugger, internal_dict):
Jim Ingham062a8362012-01-24 02:40:42 +0000444 debugger.HandleCommand('command script add -f ls.ls ls')
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000445 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 Clayton261c9742012-01-26 05:36:07 +0000449(lldb) <strong>command script import ~/ls.py</strong>
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000450The "ls" python command has been installed and is ready for use.
451(lldb) <strong>ls -l /tmp/</strong>
452total 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 Granataac39f3c2013-05-09 01:32:24 +0000456 <p>A more interesting template has been created in the source repository that can help you to create
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000457 lldb command quickly:</p>
458 <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/cmdtemplate.py">cmdtemplate.py</a>
Enrico Granata74566c92012-08-24 21:20:14 +0000459 <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 &lt;Foundation/Foundation.h&gt;
464NSString*
465ModifyString(NSString* src)
466{
467 return [src stringByAppendingString:@"foobar"];
468}
469
470int 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>
481Python 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000492 </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 Ingham062a8362012-01-24 02:40:42 +0000500 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000504 need to tell python where to look in order to find this module. This
Jim Ingham062a8362012-01-24 02:40:42 +0000505 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000508
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 Ingham062a8362012-01-24 02:40:42 +0000514 <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 Claytonf9ab5ea2012-01-22 02:55:08 +0000517 <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
526import lldb
Daniel Malea7a87d522013-02-12 20:01:49 +0000527import os
528
529def disassemble_instructions(insts):
530 for i in insts:
531 print i
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000532
533<font color=green># Set the path to the executable to debug</font>
534exe = "./a.out"
535
536<font color=green># Create a new debugger instance</font>
537debugger = lldb.SBDebugger.Create()
538
539<font color=green># When we step or continue, don't return from the function until the process
Jim Ingham062a8362012-01-24 02:40:42 +0000540# 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 Claytonf9ab5ea2012-01-22 02:55:08 +0000542debugger.SetAsync (False)
543
544<font color=green># Create a target from a file and arch</font>
545print "Creating a target for '%s'" % exe
546
547target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
548
549if 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 Malea7a87d522013-02-12 20:01:49 +0000565 <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 Claytonf9ab5ea2012-01-22 02:55:08 +0000589</tt></pre></code>
590 </div>
591 <div class="postfooter"></div>
592
593 </div>
594 </div>
595</div>
596</body>
597</html>