Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / lldb / 9f97e62c1730eef7013824e4fe63c73d66ca5fc1 / . / www / tutorial.html
blob: 3524011263a73b129f22c7675bd7c2d28b69ae2e [file] [log] [blame]
Greg Claytonb01a6542011-03-30 01:02:37 +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" />
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]6<title>LLDB Tutorial</title>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]7</head>
8
9<body>
10 <div class="www_title">
11 The <strong>LLDB</strong> Debugger
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">Getting Started</h1>
20 <div class="postcontent">
21
22 <p>Here's a short precis of how to run lldb if you are familiar with the gdb command set.
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]23 We will start with some details on lldb command structure and syntax to help orient you.</p>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]24
25 </div>
26 <div class="postfooter"></div>
27
28 <div class="post">
29 <h1 class ="postheader">Command Structure</h1>
30 <div class="postcontent">
31
32 <p>Unlike gdb's command set, which is rather free-form, we tried to make
33 the lldb command syntax fairly structured. The commands are all of the
34 form:</p>
35
36 <code color=#ff0000>
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]37 &lt;noun&gt; &lt;verb&gt; [-options [option-value]] [argument [argument...]]
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]38 </code>
39
40 <p>The command line parsing is done before command execution, so it is
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]41 uniform across all the commands. The command syntax for basic commands is very simple,
42 arguments, options and option values are all white-space
43 separated, and double-quotes are used to protect white-spaces in an argument.
44 If you need to put a backslash or double-quote character
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]45 in an argument you back-slash it in the argument. That makes the
46 command syntax more regular, but it also means you may have to
47 quote some arguments in lldb that you wouldn't in gdb.</p>
48
49 <p>Options can be placed anywhere on the command line, but if the arguments
50 begin with a "<code>-</code>" then you have to tell lldb that you're done with options
51 for the current command by adding an option termination: "<code>--</code>"
52 So for instance if you want to launch a process and give the "process launch" command
53 the "<code>--stop-at-entry</code>" option, yet you want the
54 process you are about to launch to be launched with the arguments
55 "<code>-program_arg value</code>", you would type:</p>
56
57 <code>
58 (lldb) process launch --stop-at-entry -- -program_arg value
59 </code>
60
61 <p>We also tried to reduce the number of special purpose argument
62 parsers, which sometimes forces the user to be a little more explicit
63 about stating their intentions. The first instance you'll note of
64 this is the breakpoint command. In gdb, to set a breakpoint, you
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]65 might enter</p>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]66
67 <code>
68 (gdb) break foo.c:12
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]69 </code>
70 <p>to break at line 12 of foo.c, and:</p>
71 <code>
72 (gdb) break foo
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]73 </code>
74
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]75 <p>to break at the function <code>foo</code>. As time went on, the parser that tells <code>foo.c:12</code>
76 from <code>foo</code> from <code>foo.c::foo</code> (which means the function foo in the file
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]77 foo.c) got more and more complex and bizarre, and especially in C++
78 there are times where there's really no way to specify the function
79 you want to break on. The lldb commands are more verbose but also more precise
80 and allow for intellegent auto completion.
81
82 <p>To set the same file and line breakpoint in LLDB you can enter either of:</p>
83
84 <code>
85 (lldb) breakpoint set --file foo.c --line 12
86 <br>(lldb) breakpoint set -f foo.c -l 12
87 </code>
88
89 <p>To set a breakpoint on a function named <code>foo</code> in LLDB you can enter either of:</p>
90
91 <code>
92 (lldb) breakpoint set --name foo
93 <br>(lldb) breakpoint set -n foo
94 </code>
95
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]96 <p>Setting breakpoints by name is even more specialized in LLDB as you can specify
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]97 that you want to set a breakpoint at a function by method name. To set a breakpoint
Johnny Chen9faf3272011-08-04 21:01:04 +0000[diff] [blame]98 on all C++ methods named <code>foo</code> you can enter either of:</p>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]99
100 <code>
101 (lldb) breakpoint set --method foo
102 <br>(lldb) breakpoint set -M foo
103 </code>
104
Johnny Chen9faf3272011-08-04 21:01:04 +0000[diff] [blame]105 <p>To set a breakpoint Objective C selectors named <code>alignLeftEdges:</code> you can enter either of:</p>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]106
107 <code>
108 (lldb) breakpoint set --selector alignLeftEdges:
109 <br>(lldb) breakpoint set -S alignLeftEdges:
110 </code>
111
112 <p>You can limit any breakpoints to a specific executable image by using
113 the "<code>--shlib &lt;path&gt;</code>" ("<code>-s &lt;path&gt;</code>" for short):</p>
114
115 <code>
116 (lldb) breakpoint set --shlib foo.dylib --name foo
117 <br>(lldb) breakpoint set -s foo.dylib -n foo
118 </code>
119
120 <p>Suggestions on more interesting primitives of this sort are also very welcome.</p>
121
122 <p>Just like gdb, the lldb command interpreter does a shortest unique
123 string match on command names, so the following two commands will
124 both execute the same command:</p>
125
126 <code>
127 (lldb) breakpoint set -n "-[SKTGraphicView alignLeftEdges:]"
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]128 <br>(lldb) br s -n "-[SKTGraphicView alignLeftEdges:]"
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]129 </code>
130
131 <p>lldb also supports command completion for source file names, symbol
132 names, file names, etc. Completion is initiated by a hitting a <b>TAB</b>.
133 Individual options in a command can have different completers, so for
134 instance the "<code>--file &lt;path&gt;</code>" option in "breakpoint" completes to source files, the
135 "<code>--shlib &lt;path&gt;</code>" option to currently loaded shared libraries, etc. We can even do
136 things like if you specify "<code>--shlib &lt;path&gt;</code>", and are completing on "<code>--file &lt;path&gt;</code>", we will only
137 list source files in the shared library specified by "<code>--shlib &lt;path&gt;</code>".</p>
138
139 <p>The individual commands are pretty extensively documented, using
140 the <code>help</code> command. And there is an <code>apropos</code> command that will
141 search the help for a particular word and dump a summary help string
142 for each matching command.</p>
143
144 <p>Finally, there is a mechanism to construct aliases for commonly used
145 commands. So for instance if you get annoyed typing:</p>
146
147 <code>
148 (lldb) breakpoint set --file foo.c --line 12
149 </code>
150
151 <p>you can do:</p>
152
153 <code>
154 (lldb) command alias bfl breakpoint set -f %1 -l %2
155 <br>(lldb) bfl foo.c 12
156 </code>
157
158 <p>We have added a few aliases for commonly used commands (e.g. "step",
159 "next" and "continue") but we haven't tried to be exhaustive because
160 in our experience it is more convenient to make the basic commands
161 unique down to a letter or two, and then learn these sequences than
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]162 to fill the namespace with lots of aliases, and then have to type them
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]163 all the way out.</p>
164
165 <p>However, users are free to customize lldb's command set however they
166 like, and since lldb reads the file ~/.lldbinit at startup, you can
167 store all your aliases there and they will be generally available to
168 you. Your aliases are also documented in the help command so you can
169 remind yourself of what you've set up.</p>
170
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]171 <p> One alias of note that we do include by popular demand is a weak emulator
172 of gdb's &quot;break&quot; command. It doesn't try to do everything that gdb's
173 break command does (for instance, it doesn't handle <code>foo.c::bar</code>. But
174 it mostly works, and makes the transition easier. Also by popular demand, it
175 is aliased to <code>b</code>. If you actually want to learn the lldb command
176 set natively, that means it will get in the way of the rest of the breakpoint
177 commands. Fortunately, if you don't like one of our aliases, you an easily
178 get rid of it by running (for example):</p>
179
180 <code>
181 (lldb) command unalias b
182 </code>
183
184 <p>I actually also do:</p>
185
186 <code>
187 (lldb) command alias b breakpoint
188 </code>
189
190 <p>so I can run the native lldb breakpoint command with just <code>b</code></p>
191
192 <p>The lldb command parser also supports "raw" commands, where, after command options
193 are stripped off, the rest of the command string is passed uninterpreted to the command.
194 This is convenient for commands whose arguments might be some complex expression that would
195 be painful to backslash protect.
196 For instance the "expression" command is a "raw" command for obvious reasons. The
197 "help" output for a command will tell you if it is "raw" or not, so you know what to expect.
198 The one thing you have to watch out for is that since raw commands still can have options,
199 if your command string has dashes in it, you'll have to indicate these are not option
200 markers by putting "--" after the command name, but before your command string.
201
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]202 <p>lldb also has a built-in Python interpreter, which is accessible by
203 the "script" command. All the functionality of the debugger is
204 available as classes in the Python interpreter, so the more complex
205 commands that in gdb you would introduce with the "define" command can
206 be done by writing Python functions using the lldb-Python library,
207 then loading the scripts into your running session and accessing them
208 with the "script" command.</p>
209
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]210 <p>Having given an overview of lldb's command syntax, we proceed to lay out the stages
211 of a standard debug session.</p>
212
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]213 </div>
214 <div class="postfooter"></div>
215
216
217 <div class="post">
218 <h1 class ="postheader">Loading a program into lldb</h1>
219 <div class="postcontent">
220
221 <p>First we need to set the program to debug. As with gdb, you
222 can start lldb and specify the file you wish to debug on the command line:</p>
223
224 <code>
225 $ lldb /Projects/Sketch/build/Debug/Sketch.app
226 <br>Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).
227 </code>
228
229 <p>or you can specify it after the fact with the "file" command:</p>
230
231 <code>
232 $ lldb
233 <br>(lldb) file /Projects/Sketch/build/Debug/Sketch.app
234 <br>Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).
235 </code>
236 <p>
237 </div>
238 <div class="postfooter"></div>
239
240 <div class="post">
241 <h1 class ="postheader">Setting breakpoints</h1>
242 <div class="postcontent">
243
244 <p>We've discussed how to set breakpoints above. You can use <code>help breakpoint set</code>
245 to see all the options for breakpoint setting. For instance, we might do:</p>
246
247 <code>
248 (lldb) breakpoint set --selector alignLeftEdges:
249 <br>Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1
250 </code>
251
252 <p>You can find out about the breakpoints you've set with:</p>
253
254 <pre><tt>(lldb) breakpoint list
255Current breakpoints:
2561: name = 'alignLeftEdges:', locations = 1, resolved = 1
257 1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x0000000100010d5b, resolved, hit count = 0
258</tt></pre>
259
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]260 <p>Note that setting a breakpoint creates a <i>logical</i> breakpoint, which could
261 resolve to one or more <i>locations</i>. For instance, break by selector would
262 set a breakpoint on all the methods that implement that selector in the classes in
263 your program. Similarly, a file and line breakpoint might result in multiple
264 locations if that file and line were inlined in different places in your code.</p>
265
266 <p>The logical breakpoint has an integer id, and it's locations have an
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]267 id within their parent breakpoint (the two are joined by a ".",
268 e.g. 1.1 in the example above.) </p>
269
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]270 <p>Also the logical breakpoints remain <i>live</i> so that if another shared library
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]271 were to be loaded that had another implementation of the
272 "<code>alignLeftEdges:</code>" selector, the new location would be added to
273 breakpoint 1 (e.g. a "1.2" breakpoint would be set on the newly loaded
274 selector).</p>
275
276 <p>The other piece of information in the breakpoint listing is whether the
277 breakpoint location was <i>resolved</i> or not. A location gets resolved when
278 the file address it corresponds to gets loaded into the program you are
279 debugging. For instance if you set a breakpoint in a shared library that
280 then gets unloaded, that breakpoint location will remain, but it will no
281 longer be <i>resolved</i>.</p>
282
283 <p>One other thing to note for gdb users is that lldb acts like gdb with:</p>
284
285 <code>
286 (gdb) set breakpoint pending on
287 </code>
288
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]289 <p>That is, lldb will always make a breakpoint from your specification, even
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]290 if it couldn't find any locations that match the specification. You can tell
291 whether the expression was resolved or not by checking the locations field
292 in "breakpoint list", and we report the breakpoint as "pending" when you
293 set it so you can tell you've made a typo more easily, if that was indeed
294 the reason no locations were found:</p>
295
296 <code>
297 (lldb) breakpoint set --file foo.c --line 12
298 <br>Breakpoint created: 2: file ='foo.c', line = 12, locations = 0 (pending)
299 <br>WARNING: Unable to resolve breakpoint to any actual locations.
300 </code>
301
302 <p>You can delete, disable, set conditions and ignore counts either on all the
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]303 locations generated by your logical breakpoint, or on any one of the particular locations
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]304 your specification resolved to. For instance if we wanted to add a command
305 to print a backtrace when we hit this breakpoint we could do:</p>
306
307 <code>
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]308 (lldb) breakpoint command add 1.1
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]309 <br>Enter your debugger command(s). Type 'DONE' to end.
310 <br>&gt; bt
311 <br>&gt; DONE
312 </code>
313
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]314 <p>By default, the <code> breakpoint command add</code> command takes lldb command line commands.
315 You can also specify this explicitly by passing the "<code>--command</code>" option.
316 Use "<code>--script</code>" if you want to implement your breakpoint command using the Python script instead.</p>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]317
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]318 <p>This is an convenient point to bring up another feature of the lldb command help. Do:</p>
319
320 <code>
321 (lldb) help break command add
322 <br>Add a set of commands to a breakpoint, to be executed whenever the breakpoint is hit.
323 <br>
324 <br>Syntax: breakpoint command add &lt;cmd-options&gt; &lt;breakpt-id&gt;
325 <br> etc...
326 </code>
327
328 <p>When you see arguments to commands specified in the Syntax in angle
329 brackets like <code>&lt;breakpt-id&gt;</code>, that indicates that
330 that is some common argument type that you can get further help on from the command system.
331 So in this case you could do:</p>
332
333 <code>
334 (lldb) help &lt;breakpt-id&gt;
335 <br>&lt;breakpt-id&gt; -- Breakpoint ID's consist major and minor numbers; the major
336 <br> etc...
337 </code>
338
339 </div>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]340 <div class="postfooter"></div>
341
342 <div class="post">
343 <h1 class ="postheader">Starting or attaching to your Program</h1>
344 <div class="postcontent">
345
346 <p>To launch a program in lldb we use the "<code>process launch</code>" command or
347 one of its built in aliases:</p>
348
349 <code>
350 (lldb) process launch
351 <br>(lldb) run
352 <br>(lldb) r
353 </code>
354
355 <p>You can also attach to a process by process ID or process name.
356 When attaching to a process by name, lldb also supports the "<code>--waitfor</code>" option which waits for the
357 next process that has that name to show up, and attaches to it</p>
358
359 <code>
360 (lldb) process attach --pid 123
361 <br>(lldb) process attach --name Sketch
362 <br>(lldb) process attach --name Sketch --waitfor
363 </code>
364
365 <p>After you launch or attach to a process, your process might stop
366 somewhere:</p>
367 <code>
368 (lldb) process attach -p 12345
369 <br>Process 46915 Attaching
370 <br>Process 46915 Stopped
371 <br>1 of 3 threads stopped with reasons:
372 <br>* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread
373 </code>
374
375
376 <p>Note the line that says "<code>1 of 3 threads stopped with reasons:</code>" and the
377 lines that follow it. In a multi-threaded environment it is very
378 common for more than one thread to hit your breakpoint(s) before the
379 kernel actually returns control to the debugger. In that case, you
380 will see all the threads that stopped for some interesting reason
381 listed in the stop message.</p>
382
383 </div>
384 <div class="postfooter"></div>
385
386 <div class="post">
387 <h1 class ="postheader">Controlling your Program</h1>
388 <div class="postcontent">
389
390
391 <p>After launching, we can continue until we hit our breakpoint. The primitive
392 commands for process control all exist under the "thread" command:</p>
393
394 <code>
395 (lldb) thread continue
396 <br>Resuming thread 0x2c03 in process 46915
397 <br>Resuming process 46915
398 <br>(lldb)
399 </code>
400
401 <p>At present you can only operate on one thread at a time, but the
402 design will ultimately support saying "step over the function in
403 Thread 1, and step into the function in Thread 2, and continue Thread
404 3" etc. When we eventually support keeping some threads running while
405 others are stopped this will be particularly important. For
406 convenience, however, all the stepping commands have easy aliases.
407 So "thread continue" is just "c", etc.</p>
408
409 <p>The other program stepping commands are pretty much the same as in gdb.
410 You've got:</p>
411
412 <pre><tt>(lldb) thread step-in // The same as gdb's "step" or "s"
413(lldb) thread step-over // The same as gdb's "next" or "n"
414(lldb) thread step-out // The same as gdb's "finish" or "f"
415</tt></pre>
416
417 <p>By default, lldb does defined aliases to all common gdb process control
418 commands ("<code>s</code>", "<code>step</code>", "<code>n</code>", "<code>next</code>", "<code>finish</code>").
419 If we have missed any, please add them to your <code>~/.lldbinit</code> file
420 using the "<code>command alias</code>" command.
421
422 <p>lldb also supported the <i>step by instruction</i> versions:</p>
423 <pre><tt>(lldb) thread step-inst // The same as gdb's "stepi" / "si"
424(lldb) thread step-over-inst // The same as gdb's "nexti" / "ni"
425</tt></pre>
426
427 <p>Finally, lldb has a <i>run until line or frame exit</i> stepping mode:</p>
428
429 <code>
430 (lldb) thread until 100
431 </code>
432
433 <p>This command will run the thread in the current frame till it reaches line 100 in
434 this frame or stops if it leaves the current frame. This is a pretty
435 close equivalent to gdb's "<code>until</code>" command.</p>
436
437 <p>A process, by default, will shared the lldb terminal with the inferior
438 process. When in this mode, much like when debugging with gdb, when
439 the process is running anything you type will go to the STDIN of the
440 inferior process. To interrupt your inferior program, type CTRL+C.</p>
441
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]442 <p>If you attach to a process, or launch a process with the &quot;<code>--no-stdin</code>&quot;
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]443 option, the command interpreter is always available to enter commands. This
444 might be a little disconcerting to gdb users when always have an <code>(lldb)</code>
445 prompt. This allows you to set a breakpoint, etc without having to explicitly interrupt
446 the program you are debugging:</p>
447
448 <code>
449 (lldb) process continue
450 <br>(lldb) breakpoint set --name stop_here
451 </code>
452
453 <p>There are many commands that won't work while running, and the command
454 interpreter should do a good job of letting you know when this is the
455 case. If you find any instances where the command interpreter isn't
456 doing its job, please file a bug. This way of operation will set us
457 up for a future debugging mode called <i>thread centric debugging</i>.
458 This mode will allow us to run all threads and only stop the threads
459 that are at breakpoints or have exceptions or signals.</p>
460
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]461 <p>The commands that currently work while running include
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]462 interrupting the process to halt execution ("<code>process interrupt</code>"),
463 getting the process status ("<code>process status</code>"),
464 breakpoint setting and clearing ("<code> breakpoint [set|clear|enable|disable|list] ...</code>"),
465 and memory reading and writing ("<code> memory [read|write] ...</code>").
466 </p>
467
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]468 <p>The question of disabling stdio when running brings up a good opportunity to
469 show how to set debugger properties in general.
470 If you always want to run in the <code>--no-stdin</code> mode, you can set this
471 as a generic process property using the lldb &quot;<code>settings</code>&qout; command,
472 which is equivalent to gdb's &quot;<code>set</code>&quot; command. For instance,
473 in this case you would say:</p>
474
475 <code>
476 (lldb) settings set target.process.disable-stdio true
477 </code>
478
479 <p>Over time, gdb's &quot;<code>set</code> command became a wilderness of disordered options,
480 so that there were useful options that even experienced gdb users didn't know about
481 because they were too hard to find. We tried to organize the settings hierarchically
482 using the structure of the basic entities in the debugger. For the most part anywhere
483 you can specify a setting on a generic entity (threads, for example) you can also apply
484 the option to a particular instance, which can also be convenient at times.
485 You can view the available settings with &quot;<code>settings list</code>&quot; and
486 there is help on the settings command explaining how it works more generally.</p>
487
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]488 </div>
489 <div class="postfooter"></div>
490
491 <div class="post">
492 <h1 class ="postheader">Examining Thread State</h1>
493 <div class="postcontent">
494
495 <p>Once you've stopped, lldb will choose a current thread, usually the
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]496 one that stopped "for a reason", and a current frame in that thread (on stop this is always the bottom-most frame).
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]497 Many the commands for inspecting state work on this current
498 thread/frame.</p>
499
500 <p>To inspect the current state of your process, you can start with the
501 threads:</p>
502
503 <pre><tt>(lldb) thread list
504Process 46915 state is Stopped
505* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread
506 thread #2: tid = 0x2e03, 0x00007fff85cbb08a, where = libSystem.B.dylib`kevent + 10, queue = com.apple.libdispatch-manager
507 thread #3: tid = 0x2f03, 0x00007fff85cbbeaa, where = libSystem.B.dylib`__workq_kernreturn + 10
508</tt></pre>
509
510 <p>The * indicates that Thread 1 is the current thread. To get a
511 backtrace for that thread, do:</p>
512
513 <pre><tt>(lldb) thread backtrace
514thread #1: tid = 0x2c03, stop reason = breakpoint 1.1, queue = com.apple.main-thread
515 frame #0: 0x0000000100010d5b, where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405
516 frame #1: 0x00007fff8602d152, where = AppKit`-[NSApplication sendAction:to:from:] + 95
517 frame #2: 0x00007fff860516be, where = AppKit`-[NSMenuItem _corePerformAction] + 365
518 frame #3: 0x00007fff86051428, where = AppKit`-[NSCarbonMenuImpl performActionWithHighlightingForItemAtIndex:] + 121
519 frame #4: 0x00007fff860370c1, where = AppKit`-[NSMenu performKeyEquivalent:] + 272
520 frame #5: 0x00007fff86035e69, where = AppKit`-[NSApplication _handleKeyEquivalent:] + 559
521 frame #6: 0x00007fff85f06aa1, where = AppKit`-[NSApplication sendEvent:] + 3630
522 frame #7: 0x00007fff85e9d922, where = AppKit`-[NSApplication run] + 474
523 frame #8: 0x00007fff85e965f8, where = AppKit`NSApplicationMain + 364
524 frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11
525 frame #10: 0x0000000100000f20, where = Sketch`start + 52
526</tt></pre>
527
528 <p>You can also provide a list of threads to backtrace, or the keyword
529 "all" to see all threads:</p>
530
531 <code>
532 (lldb) thread backtrace all
533 </code>
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]534
535 <p>You can select the current thread, which will be used by default in all the commands in
536 the next section, with the "thread select" command:</p>
537
538 <code>
539 (lldb) thread select 2
540 </code>
541
542 <p>where the thread index is just the one shown in the &quot;<code>thread list</code>&quot listing.
543
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]544 </div>
545 <div class="postfooter"></div>
546
547 <div class="post">
548 <h1 class ="postheader">Examining Stack Frame State</h1>
549 <div class="postcontent">
550
551
552 <p>The most convenient way to inspect a frame's arguments and local variables is to use the "<code>frame variable</code>" command:</p>
553
554 <code>
555 (lldb) frame variable
556 <br>self = (SKTGraphicView *) 0x0000000100208b40
557 <br>_cmd = (struct objc_selector *) 0x000000010001bae1
558 <br>sender = (id) 0x00000001001264e0
559 <br>selection = (NSArray *) 0x00000001001264e0
560 <br>i = (NSUInteger) 0x00000001001264e0
561 <br>c = (NSUInteger) 0x00000001001253b0
562 </code>
563
564 <p>As you see above, if you don't specify any variable names, all arguments
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]565 and locals will be shown. If you call "<code>frame variable</code>"
566 passing in the names of a particular local(s), only those variables
567 will be printed. For instance:
568 </p>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]569
570 <code>
571 (lldb) frame variable self
572 <br>(SKTGraphicView *) self = 0x0000000100208b40
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]573 </code>
574
575 <p>You can also pass in a path to some subelement of one of the available locals,
576 and that sub-element will be printed. For instance:
577 </p>
578
579 <code>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]580 <br>(lldb) frame variable self.isa
581 <br>(struct objc_class *) self.isa = 0x0000000100023730
582 </code>
583
584 <p>The "<code>frame variable</code>" command is not a full expression
585 parser but it does support a few simple operations like &amp;, *, ->, [] (no overloaded
586 operators). The array brackets can be used on pointers to treat pointers
587 as arrays:</p>
588
589 <code>
590 (lldb) frame variable *self
591 <br>(SKTGraphicView *) self = 0x0000000100208b40
592 <br>(NSView) NSView = {
593 <br>(NSResponder) NSResponder = {
594 <br>...
595 <br>
596 <br>(lldb) frame variable &amp;self
597 <br>(SKTGraphicView **) &amp;self = 0x0000000100304ab
598 <br>
599 <br>(lldb) frame variable argv[0]
600 <br>(char const *) argv[0] = 0x00007fff5fbffaf8 "/Projects/Sketch/build/Debug/Sketch.app/Contents/MacOS/Sketch"
601 </code>
602
603 <p>The frame variable command will also perform "object printing" operations on
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]604 variables (currently we only support ObjC printing, using the object's "description" method.
605 Turn this on by passing the -o flag to frame variable:</p>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]606
607 <code>
608 (lldb) frame variable -o self
609 (SKTGraphicView *) self = 0x0000000100208b40 &lt;SKTGraphicView: 0x100208b40&gt;
610 </code>
611
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]612 <p>You can select another frame to view with the "<code>frame select</code>" command</p>
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]613
614 <code>
615 (lldb) frame select 9
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]616 <br>frame #9: 0x0000000100015ae3, where = Sketch`function1 + 33 at /Projects/Sketch/SKTFunctions.m:11
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]617 </code>
618
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]619 <p>You can also move up and down the stack by passing the &quot;<code>--relative</code>&quot; (&quot;<code>-r</code>&quot;)
620 option. And we have built-in aliases &quot;<code>u</code>&quot; and &quot;<code>d</code>&quot; which
621 behave like their gdb equivalents.
622
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]623 <p>If you need to view more complex data or change program data, you can
624 use the general "expression" command. It takes an expression and
625 evaluates it in the scope of the currently selected frame. For instance:</p>
626
627 <code>
628 (lldb) expr self
629 <br>$0 = (SKTGraphicView *) 0x0000000100135430
630 <br>(lldb) expr self = 0x00
631 <br>$1 = (SKTGraphicView *) 0x0000000000000000
632 <br>(lldb) frame var self
633 <br>(SKTGraphicView *) self = 0x0000000000000000
634 </code>
635
636 <p>You can also call functions:</p>
637
638 <code>
639 (lldb) expr (int) printf ("I have a pointer 0x%llx.\n", self)
640 <br>$2 = (int) 22
641 <br>I have a pointer 0x0.
642 </code>
643
Jim Ingham8d8e3ed2011-03-31 21:56:13 +0000[diff] [blame]644 <p>As I said above, &quot;expression&quot; is one of the &quot;raw&quot; commands. So
Greg Claytonb01a6542011-03-30 01:02:37 +0000[diff] [blame]645 you don't have to quote your whole expression, nor backslash protect quotes,
646 etc...</p>
647
648 <p>Finally, the results of the expressions are stored in persistent variables
649 (of the form $[0-9]+) that you can use in further expressions, like:</p>
650
651 <code>
652 (lldb) expr self = $0
653 <br>$4 = (SKTGraphicView *) 0x0000000100135430
654 </code>
655 <p>
656 </div>
657 <div class="postfooter"></div>
658
659 </div>
660 </div>
661 </div>
662</div>
663</body>
664</html>