Fix/unify the spelling of Objective-C.
[lldb.git] / lldb / www / tutorial.html
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" />
6 <title>LLDB Tutorial</title>
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.
23                         We will start with some details on lldb command structure and syntax to help orient you.</p>
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>
37                    &lt;noun&gt; &lt;verb&gt; [-options [option-value]] [argument [argument...]]
38                    </code>
39
40                    <p>The command line parsing is done before command execution, so it is
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
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
65                    might enter</p>
66
67                    <code>
68                        (gdb) break foo.c:12
69                    </code>
70                    <p>to break at line 12 of foo.c, and:</p>
71                    <code>
72                        (gdb) break foo
73                    </code>
74
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
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 intelligent 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
96                    <p>You can use the --name option multiple times to make a breakpoint on a set of functions as well.  This is convenient
97                       since it allows you to set common conditions or commands without having to specify them multiple times:</p>
98
99                     <code>
100                         (lldb) breakpoint set --name foo --name bar
101                     </code>
102
103                    <p>Setting breakpoints by name is even more specialized in LLDB as you can specify
104                        that you want to set a breakpoint at a function by method name. To set a breakpoint
105                        on all C++ methods named <code>foo</code> you can enter either of:</p>
106
107                    <code>
108                        (lldb) breakpoint set --method foo
109                        <br>(lldb) breakpoint set -M foo
110                   </code>
111
112                    <p>To set a breakpoint Objective-C selectors named <code>alignLeftEdges:</code> you can enter either of:</p>
113
114                    <code>
115                        (lldb) breakpoint set --selector alignLeftEdges:
116                        <br>(lldb) breakpoint set -S alignLeftEdges:
117                   </code>
118
119                    <p>You can limit any breakpoints to a specific executable image by using
120                        the "<code>--shlib &lt;path&gt;</code>" ("<code>-s &lt;path&gt;</code>" for short):</p>
121
122                    <code>
123                       (lldb) breakpoint set --shlib foo.dylib --name foo
124                       <br>(lldb) breakpoint set -s foo.dylib -n foo
125                   </code>
126
127                    <p>The <code>--shlib</code> option can also be repeated to specify several shared libraries.</p>
128
129                    <p>Suggestions on more interesting primitives of this sort are also very welcome.</p>
130
131                    <p>Just like gdb, the lldb command interpreter does a shortest unique
132                    string match on command names, so the following two commands will
133                    both execute the same command:</p>
134
135                    <code>
136                        (lldb) breakpoint set -n "-[SKTGraphicView alignLeftEdges:]"
137                        <br>(lldb) br s -n "-[SKTGraphicView alignLeftEdges:]"
138                   </code>
139
140                    <p>lldb also supports command completion for source file names, symbol
141                    names, file names, etc. Completion is initiated by a hitting a <b>TAB</b>.
142                    Individual options in a command can have different completers, so for
143                    instance the "<code>--file &lt;path&gt;</code>" option in "breakpoint" completes to source files, the
144                    "<code>--shlib &lt;path&gt;</code>" option to currently loaded shared libraries, etc.  We can even do 
145                    things like if you specify "<code>--shlib &lt;path&gt;</code>", and are completing on "<code>--file &lt;path&gt;</code>", we will only
146                    list source files in the shared library specified by "<code>--shlib &lt;path&gt;</code>".</p>
147
148                    <p>The individual commands are pretty extensively documented.  You can
149                    use the <code>help</code> command to get an overview of which commands are
150                    available or to obtain details about specific commands.  There is also an
151                    <code>apropos</code> command that will search the help text for all commands
152                    for a particular word and dump a summary help string for each matching
153                    command.</p>
154
155                    <p>Finally, there is a mechanism to construct aliases for commonly used
156                    commands.  So for instance if you get annoyed typing:</p>
157
158                    <code>
159                        (lldb) breakpoint set --file foo.c --line 12
160                    </code>
161
162                    <p>you can do:</p>
163
164                    <code>
165                        (lldb) command alias bfl breakpoint set -f %1 -l %2
166                        <br>(lldb) bfl foo.c 12
167                    </code>
168
169                    <p>We have added a few aliases for commonly used commands (e.g. "step",
170                    "next" and "continue") but we haven't tried to be exhaustive because
171                    in our experience it is more convenient to make the basic commands
172                    unique down to a letter or two, and then learn these sequences than
173                    to fill the namespace with lots of aliases, and then have to type them
174                    all the way out.</p>
175
176                    <p>However, users are free to customize lldb's command set however they
177                    like, and since lldb reads the file ~/.lldbinit at startup, you can
178                    store all your aliases there and they will be generally available to
179                    you.  Your aliases are also documented in the help command so you can
180                    remind yourself of what you've set up.</p>
181
182                    <p> One alias of note that we do include by popular demand is a weak emulator
183                    of gdb's &quot;break&quot; command.  It doesn't try to do everything that gdb's
184                    break command does (for instance, it doesn't handle <code>foo.c::bar</code>.  But
185                    it mostly works, and makes the transition easier.  Also by popular demand, it
186                    is aliased to <code>b</code>.  If you actually want to learn the lldb command
187                    set natively, that means it will get in the way of the rest of the breakpoint
188                    commands.  Fortunately, if you don't like one of our aliases, you an easily
189                    get rid of it by running (for example):</p>
190
191                    <code>
192                     (lldb) command unalias b
193                    </code>
194
195                    <p>I actually also do:</p>
196
197                    <code>
198                      (lldb) command alias b breakpoint
199                    </code>
200
201                    <p>so I can run the native lldb breakpoint command with just <code>b</code></p>
202                      
203                    <p>The lldb command parser also supports "raw" commands, where, after command options
204                    are stripped off, the rest of the command string is passed uninterpreted to the command.
205                    This is convenient for commands whose arguments might be some complex expression that would
206                    be painful to backslash protect.
207                    For instance the "expression" command is a "raw" command for obvious reasons.  The
208                    "help" output for a command will tell you if it is "raw" or not, so you know what to expect.
209                    The one thing you have to watch out for is that since raw commands still can have options,
210                    if your command string has dashes in it, you'll have to indicate these are not option
211                    markers by putting "--" after the command name, but before your command string.  
212
213                    <p>lldb also has a built-in Python interpreter, which is accessible by
214                    the "script" command.  All the functionality of the debugger is
215                    available as classes in the Python interpreter, so the more complex
216                    commands that in gdb you would introduce with the "define" command can
217                    be done by writing Python functions using the lldb-Python library,
218                    then loading the scripts into your running session and accessing them
219                    with the "script" command.</p>
220
221                    <p>Having given an overview of lldb's command syntax, we proceed to lay out the stages
222                    of a standard debug session.</p>
223
224                                 </div>
225                                 <div class="postfooter"></div>
226
227
228                         <div class="post">
229                                 <h1 class ="postheader">Loading a program into lldb</h1>
230                                 <div class="postcontent">
231
232                     <p>First we need to set the program to debug. As with gdb, you
233                          can start lldb and specify the file you wish to debug on the command line:</p>
234
235                     <code>
236                         $ lldb /Projects/Sketch/build/Debug/Sketch.app
237                         <br>Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).
238                     </code>
239
240                     <p>or you can specify it after the fact with the "file" command:</p>
241
242                     <code>
243                         $ lldb
244                         <br>(lldb) file /Projects/Sketch/build/Debug/Sketch.app
245                         <br>Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).
246                     </code>
247                 <p>
248                                 </div>
249                                 <div class="postfooter"></div>
250
251                                 <div class="post">
252                                   <h1 class ="postheader">Setting breakpoints</h1>
253                                   <div class="postcontent">
254
255                     <p>We've discussed how to set breakpoints above.  You can use <code>help breakpoint set</code>
256                     to see all the options for breakpoint setting.  For instance, we might do:</p>
257
258                     <code>
259                         (lldb) breakpoint set --selector alignLeftEdges:
260                         <br>Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1
261                     </code>
262
263                     <p>You can find out about the breakpoints you've set with:</p>
264
265                     <pre><tt>(lldb) breakpoint list
266 Current breakpoints:
267 1: name = 'alignLeftEdges:', locations = 1, resolved = 1
268   1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x0000000100010d5b, resolved, hit count = 0 
269 </tt></pre>
270
271                     <p>Note that setting a breakpoint creates a <i>logical</i> breakpoint, which could
272                     resolve to one or more <i>locations</i>.  For instance, break by selector would
273                     set a breakpoint on all the methods that implement that selector in the classes in
274                     your program.  Similarly, a file and line breakpoint might result in multiple
275                     locations if that file and line were inlined in different places in your code.</p>
276
277                     <p>The logical breakpoint has an integer id, and it's locations have an
278                     id within their parent breakpoint (the two are joined by a ".",
279                     e.g. 1.1 in the example above.)  </p>
280
281                     <p>Also the logical breakpoints remain <i>live</i> so that if another shared library
282                     were to be loaded that had another implementation of the
283                     "<code>alignLeftEdges:</code>" selector, the new location would be added to
284                     breakpoint 1 (e.g. a "1.2" breakpoint would be set on the newly loaded
285                     selector).</p>
286
287                     <p>The other piece of information in the breakpoint listing is whether the
288                     breakpoint location was <i>resolved</i> or not.  A location gets resolved when
289                     the file address it corresponds to gets loaded into the program you are
290                     debugging.  For instance if you set a breakpoint in a shared library that 
291                     then gets unloaded, that breakpoint location will remain, but it will no 
292                     longer be <i>resolved</i>.</p>
293
294                     <p>One other thing to note for gdb users is that lldb acts like gdb with:</p>
295
296                     <code>
297                         (gdb) set breakpoint pending on
298                     </code>
299
300                     <p>That is, lldb will always make a breakpoint from your specification, even
301                     if it couldn't find any locations that match the specification.  You can tell
302                     whether the expression was resolved or not by checking the locations field
303                     in "breakpoint list", and we report the breakpoint as "pending" when you
304                     set it so you can tell you've made a typo more easily, if that was indeed 
305                     the reason no locations were found:</p>
306
307                     <code>
308                         (lldb) breakpoint set --file foo.c --line 12
309                         <br>Breakpoint created: 2: file ='foo.c', line = 12, locations = 0 (pending)
310                         <br>WARNING:  Unable to resolve breakpoint to any actual locations.
311                     </code>
312
313                     <p>You can delete, disable, set conditions and ignore counts either on all the
314                     locations generated by your logical breakpoint, or on any one of the particular locations
315                     your specification resolved to.  For instance if we wanted to add a command
316                     to print a backtrace when we hit this breakpoint we could do:</p>
317
318                     <code>
319                         (lldb) breakpoint command add 1.1
320                         <br>Enter your debugger command(s).  Type 'DONE' to end.
321                         <br>&gt; bt
322                         <br>&gt; DONE
323                     </code>
324
325                     <p>By default, the <code> breakpoint command add</code> command takes lldb command line commands.
326                     You can also specify this explicitly by passing the "<code>--command</code>" option.
327                     Use "<code>--script</code>" if you want to implement your breakpoint command using the Python script instead.</p>
328
329                     <p>This is an convenient point to bring up another feature of the lldb command help.  Do:</p>
330
331                     <code>
332                     (lldb) help break command add
333                      <br>Add a set of commands to a breakpoint, to be executed whenever the breakpoint is hit.
334                      <br>
335                      <br>Syntax: breakpoint command add &lt;cmd-options&gt; &lt;breakpt-id&gt;
336                      <br> etc...
337                     </code>
338                      
339                      <p>When you see arguments to commands specified in the Syntax in angle 
340                      brackets like <code>&lt;breakpt-id&gt;</code>, that indicates that
341                      that is some common argument type that you can get further help on from the command system.  
342                      So in this case you could do:</p>
343
344                      <code>
345                     (lldb) help &lt;breakpt-id&gt;
346                     <br>&lt;breakpt-id&gt; -- Breakpoint ID's consist major and minor numbers;  the major
347                     <br> etc...
348                      </code>
349
350                             </div>
351                                 <div class="postfooter"></div>
352
353
354                                 <div class="post">
355                                   <h1 class ="postheader">Breakpoint Names</h1>
356                                   <div class="postcontent">
357
358                     <p>Breakpoints carry two orthognal sets of information: one specifies where to
359                        set the breakpoint, and the other how to react when the breakpoint is hit.
360                        The latter set of information (e.g. commands, conditions, hit-count, auto-continue...)
361                        we call breakpoint options.</p>
362                        <p>It is fairly common to want to apply one set of options to a number of breakpoints.
363                        For instance, you might want to check that <code>self == nil</code> and if it is, 
364                        print a backtrace and continue, on a number of methods.  
365                        One convenient way to do that would be to make all
366                        the breakpoints, then configure the options with:</p>
367
368                     <code>
369                         (lldb) breakpoint modify -c "self == nil" -C bt --auto-continue 1 2 3
370                     </code>
371
372                     <p>That's not too bad, but you have to repeat this for every new breakpoint you 
373                       make, and if you wanted to change the options, you have to remember all the ones you 
374                       are using this way.</p>
375
376                     <p> Breakpoint names provide a convenient solution to this problem.  The simple solution would
377                       be to use the name to gather the breakpoints you want to affect this way into a group.  So
378                       when you make the breakpoint you would do:</p>
379
380                     <code>
381                         (lldb) breakpoint set <SPECIFICATION> -N SelfNil
382                     </code>
383
384                     <p>Then when you've made all your breakpoints, you can set up or modify the options using
385                        the name to collect all the relevant breakpoints.</p>
386
387                     <code>
388                         (lldb) breakpoint modify -c "self == nil" -C bt --auto-continue SelfNil
389                     </code>
390
391                     <p> That is better, but suffers from the problem that when new breakpoints get added, they
392                       don't pick up these modifications, and the options only exist in the context of actual
393                       breakpoints, so they are hard to store & reuse.  </p>
394                      <p>A even better solution is to make a
395                       fully configured breakpoint name:</p>
396                     <code>
397                         (lldb) breakpoint name configure -c "self == nil" -C bt --auto-continue SelfNil
398                     </code>
399                     <p>Then you can apply the name to your breakpoints, and they will all pick up these
400                     options.  The connection from name to breakpoints remains live, so when you change the
401                     options configured on the name, all the breakpoints pick up those changes.  This makes
402                     it easy to use configured names to experiment with your options.</p>
403                     <p>You can make breakpoint names in your .lldbinit file, so you can use them to
404                     can behaviors that you have found useful and reapply them in future sessions.</p>
405
406                     <p>You can also make a breakpoint name from the options set on a breakpoint:</p>
407                     <code>
408                         (lldb) breakpoint name configure -B 1 SelfNil
409                     </code>
410                     <p>which makes it easy to copy behavior from one breakpoint to a set of others.</p>
411
412                                 <div class="postfooter"></div>
413
414                 <div class="post">
415                                 <h1 class ="postheader">Setting watchpoints</h1>
416                                 <div class="postcontent">
417
418                     <p>In addition to breakpoints, you can use <code>help watchpoint</code>
419                     to see all the commands for watchpoint manipulations.  For instance, we might do the following to watch
420                     a variable called 'global' for write operation, but only stop if the condition '(global==5)' is true:</p>
421
422                    <pre><tt>(lldb) watch set var global
423 Watchpoint created: Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
424     declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
425 (lldb) watch modify -c '(global==5)'
426 (lldb) watch list
427 Current watchpoints:
428 Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
429     declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
430     condition = '(global==5)'
431 (lldb) c
432 Process 15562 resuming
433 (lldb) about to write to 'global'...
434 Process 15562 stopped and was programmatically restarted.
435 Process 15562 stopped and was programmatically restarted.
436 Process 15562 stopped and was programmatically restarted.
437 Process 15562 stopped and was programmatically restarted.
438 Process 15562 stopped
439 * thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1
440     frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16
441    13   
442    14   static void modify(int32_t &var) {
443    15       ++var;
444 -> 16   }
445    17   
446    18   int main(int argc, char** argv) {
447    19       int local = 0;
448 (lldb) bt
449 * thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1
450     frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16
451     frame #1: 0x0000000100000eac a.out`main + 108 at main.cpp:25
452     frame #2: 0x00007fff8ac9c7e1 libdyld.dylib`start + 1
453 (lldb) frame var global
454 (int32_t) global = 5
455 (lldb) watch list -v
456 Current watchpoints:
457 Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
458     declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
459     condition = '(global==5)'
460     hw_index = 0  hit_count = 5     ignore_count = 0   
461 (lldb) </tt></pre>
462                             </div>
463                                 <div class="postfooter"></div>
464
465                         <div class="post">
466                                 <h1 class ="postheader">Starting or attaching to your Program</h1>
467                                 <div class="postcontent">
468
469                     <p>To launch a program in lldb we use the "<code>process launch</code>" command or 
470                         one of its built in aliases:</p>
471
472                     <code>
473                         (lldb) process launch
474                         <br>(lldb) run
475                         <br>(lldb) r
476                     </code>
477
478                     <p>You can also attach to a process by process ID or process name.
479                         When attaching to a process by name, lldb also supports the "<code>--waitfor</code>" option which waits for the
480                     next process that has that name to show up, and attaches to it</p>
481
482                     <code>
483                         (lldb) process attach --pid 123
484                         <br>(lldb) process attach --name Sketch
485                         <br>(lldb) process attach --name Sketch --waitfor
486                     </code>
487
488                     <p>After you launch or attach to a process, your process might stop
489                         somewhere:</p>
490                         <code>
491                             (lldb) process attach -p 12345
492                             <br>Process 46915 Attaching
493                             <br>Process 46915 Stopped
494                             <br>1 of 3 threads stopped with reasons:
495                             <br>* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread
496                         </code>
497                         
498                         
499                     <p>Note the line that says "<code>1 of 3 threads stopped with reasons:</code>" and the
500                     lines that follow it. In a multi-threaded environment it is very
501                     common for more than one thread to hit your breakpoint(s) before the
502                     kernel actually returns control to the debugger.  In that case, you
503                     will see all the threads that stopped for some interesting reason
504                     listed in the stop message.</p>
505
506                                 </div>
507                                 <div class="postfooter"></div>
508
509                         <div class="post">
510                                 <h1 class ="postheader">Controlling your Program</h1>
511                                 <div class="postcontent">
512
513
514                     <p>After launching, we can continue until we hit our breakpoint.  The primitive
515                     commands for process control all exist under the "thread" command:</p>
516
517                     <code>
518                         (lldb) thread continue
519                         <br>Resuming thread 0x2c03 in process 46915
520                         <br>Resuming process 46915
521                         <br>(lldb)
522                     </code>
523
524                     <p>At present you can only operate on one thread at a time, but the
525                     design will ultimately support saying "step over the function in
526                     Thread 1, and step into the function in Thread 2, and continue Thread
527                     3" etc.  When we eventually support keeping some threads running while
528                     others are stopped this will be particularly important.  For
529                     convenience, however, all the stepping commands have easy aliases.  
530                     So "thread continue" is just "c", etc.</p>
531
532                     <p>The other program stepping commands are pretty much the same as in gdb.  
533                     You've got:</p>
534
535                     <pre><tt>(lldb) thread step-in    // The same as gdb's "step" or "s" 
536 (lldb) thread step-over  // The same as gdb's "next" or "n"
537 (lldb) thread step-out   // The same as gdb's "finish" or "f"
538 </tt></pre>
539
540                     <p>By default, lldb does defined aliases to all common gdb process control 
541                         commands ("<code>s</code>", "<code>step</code>", "<code>n</code>", "<code>next</code>", "<code>finish</code>").
542                         If we have missed any, please add them to your <code>~/.lldbinit</code> file
543                         using the "<code>command alias</code>" command.
544
545                     <p>lldb also supported the <i>step by instruction</i> versions:</p>
546                     <pre><tt>(lldb) thread step-inst       // The same as gdb's "stepi" / "si"
547 (lldb) thread step-over-inst  // The same as gdb's "nexti" / "ni"
548 </tt></pre>
549
550                     <p>Finally, lldb has a <i>run until line or frame exit</i> stepping mode:</p>
551
552                     <code>
553                         (lldb) thread until 100
554                     </code>
555
556                     <p>This command will run the thread in the current frame till it reaches line 100 in
557                     this frame or stops if it leaves the current frame.  This is a pretty 
558                     close equivalent to gdb's "<code>until</code>" command.</p>
559
560                     <p>A process, by default, will share the lldb terminal with the inferior
561                         process. When in this mode, much like when debugging with gdb, when
562                         the process is running anything you type will go to the STDIN of the
563                         inferior process. To interrupt your inferior program, type CTRL+C.</p>
564                         
565                     <p>If you attach to a process, or launch a process with the &quot;<code>--no-stdin</code>&quot;
566                         option, the command interpreter is always available to enter commands. This 
567                         might be a little disconcerting to gdb users when always have an <code>(lldb)</code>
568                         prompt. This allows you to set a breakpoint, etc without having to explicitly interrupt
569                         the program you are debugging:</p>
570
571                         <code>
572                             (lldb) process continue
573                             <br>(lldb) breakpoint set --name stop_here
574                         </code>
575                         
576                     <p>There are many commands that won't work while running, and the command
577                         interpreter should do a good job of letting you know when this is the
578                         case. If you find any instances where the command interpreter isn't
579                         doing its job, please file a bug. This way of operation will set us
580                         up for a future debugging mode called <i>thread centric debugging</i>.
581                         This mode will allow us to run all threads and only stop the threads
582                         that are at breakpoints or have exceptions or signals.</p>
583
584                     <p>The commands that currently work while running include
585                         interrupting the process to halt execution ("<code>process interrupt</code>"),
586                         getting the process status ("<code>process status</code>"),
587                         breakpoint setting and clearing ("<code> breakpoint [set|clear|enable|disable|list] ...</code>"),
588                         and memory reading and writing  ("<code> memory [read|write] ...</code>").
589                         </p>
590
591                     <p>The question of disabling stdio when running brings up a good opportunity to 
592                         show how to set debugger properties in general.  
593                         If you always want to run in the <code>--no-stdin</code> mode, you can set this
594                         as a generic process property using the lldb &quot;<code>settings</code>&quot; command, 
595                         which is equivalent to gdb's &quot;<code>set</code>&quot; command.  For instance, 
596                         in this case you would say:</p>
597                     
598                     <code>
599                     (lldb) settings set target.process.disable-stdio true
600                     </code>
601
602                     <p>Over time, gdb's &quot;<code>set</code> command became a wilderness of disordered options, 
603                         so that there were useful options that even experienced gdb users didn't know about
604                         because they were too hard to find.  We tried to organize the settings hierarchically
605                         using the structure of the basic entities in the debugger.  For the most part anywhere
606                         you can specify a setting on a generic entity (threads, for example) you can also apply
607                         the option to a particular instance, which can also be convenient at times.
608                         You can view the available settings with &quot;<code>settings list</code>&quot; and
609                         there is help on the settings command explaining how it works more generally.</p>
610
611                                 </div>
612                                 <div class="postfooter"></div>
613
614                                 <div class="post">
615                                         <h1 class ="postheader">Examining Thread State</h1>
616                                         <div class="postcontent">
617
618                     <p>Once you've stopped, lldb will choose a current thread, usually the
619                     one that stopped "for a reason", and a current frame in that thread (on stop this is always the bottom-most frame).
620                     Many the commands for inspecting state work on this current
621                     thread/frame.</p>
622
623                     <p>To inspect the current state of your process, you can start with the
624                     threads:</p>
625
626                     <pre><tt>(lldb) thread list
627 Process 46915 state is Stopped
628 * thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread
629   thread #2: tid = 0x2e03, 0x00007fff85cbb08a, where = libSystem.B.dylib`kevent + 10, queue = com.apple.libdispatch-manager
630   thread #3: tid = 0x2f03, 0x00007fff85cbbeaa, where = libSystem.B.dylib`__workq_kernreturn + 10
631 </tt></pre>
632
633                     <p>The * indicates that Thread 1 is the current thread.  To get a
634                     backtrace for that thread, do:</p>
635
636                     <pre><tt>(lldb) thread backtrace
637 thread #1: tid = 0x2c03, stop reason = breakpoint 1.1, queue = com.apple.main-thread
638  frame #0: 0x0000000100010d5b, where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405
639  frame #1: 0x00007fff8602d152, where = AppKit`-[NSApplication sendAction:to:from:] + 95
640  frame #2: 0x00007fff860516be, where = AppKit`-[NSMenuItem _corePerformAction] + 365
641  frame #3: 0x00007fff86051428, where = AppKit`-[NSCarbonMenuImpl performActionWithHighlightingForItemAtIndex:] + 121
642  frame #4: 0x00007fff860370c1, where = AppKit`-[NSMenu performKeyEquivalent:] + 272
643  frame #5: 0x00007fff86035e69, where = AppKit`-[NSApplication _handleKeyEquivalent:] + 559
644  frame #6: 0x00007fff85f06aa1, where = AppKit`-[NSApplication sendEvent:] + 3630
645  frame #7: 0x00007fff85e9d922, where = AppKit`-[NSApplication run] + 474
646  frame #8: 0x00007fff85e965f8, where = AppKit`NSApplicationMain + 364
647  frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11
648  frame #10: 0x0000000100000f20, where = Sketch`start + 52
649 </tt></pre>
650
651                     <p>You can also provide a list of threads to backtrace, or the keyword
652                     "all" to see all threads:</p>
653
654                     <code>
655                         (lldb) thread backtrace all
656                     </code>
657
658                     <p>You can select the current thread, which will be used by default in all the commands in 
659                     the next section, with the "thread select" command:</p>
660
661                     <code>
662                       (lldb) thread select 2
663                     </code>
664
665                     <p>where the thread index is just the one shown in the &quot;<code>thread list</code>&quot listing.
666                     
667                                 </div>
668                                 <div class="postfooter"></div>
669
670                         <div class="post">
671                                 <h1 class ="postheader">Examining Stack Frame State</h1>
672                                 <div class="postcontent">
673
674
675                     <p>The most convenient way to inspect a frame's arguments and local variables is to use the "<code>frame variable</code>" command:</p>
676
677                     <code>
678                         (lldb) frame variable 
679                         <br>self = (SKTGraphicView *) 0x0000000100208b40
680                         <br>_cmd = (struct objc_selector *) 0x000000010001bae1
681                         <br>sender = (id) 0x00000001001264e0
682                         <br>selection = (NSArray *) 0x00000001001264e0
683                         <br>i = (NSUInteger) 0x00000001001264e0
684                         <br>c = (NSUInteger) 0x00000001001253b0
685                     </code>
686
687                     <p>As you see above, if you don't specify any variable names, all arguments 
688                         and locals will be shown. If you call "<code>frame variable</code>" 
689                         passing in the names of a particular local(s), only those variables
690                         will be printed.  For instance:
691                         </p>
692
693                     <code>
694                         (lldb) frame variable self
695                         <br>(SKTGraphicView *) self = 0x0000000100208b40
696                     </code>
697
698                     <p>You can also pass in a path to some subelement of one of the available locals,
699                       and that sub-element will be printed. For instance:
700                       </p>
701
702                     <code>
703                         <br>(lldb) frame variable self.isa
704                         <br>(struct objc_class *) self.isa = 0x0000000100023730
705                     </code>
706
707                     <p>The "<code>frame variable</code>" command is not a full expression 
708                         parser but it does support a few simple operations like &amp;, *, ->, [] (no overloaded
709                     operators). The array brackets can be used on pointers to treat pointers
710                     as arrays:</p>
711
712                     <code>
713                         (lldb) frame variable *self
714                         <br>(SKTGraphicView *) self = 0x0000000100208b40
715                         <br>(NSView) NSView = {
716                         <br>(NSResponder) NSResponder = {
717                         <br>...
718                         <br>
719                         <br>(lldb) frame variable &amp;self
720                         <br>(SKTGraphicView **) &amp;self = 0x0000000100304ab
721                         <br>
722                         <br>(lldb) frame variable argv[0]
723                         <br>(char const *) argv[0] = 0x00007fff5fbffaf8 "/Projects/Sketch/build/Debug/Sketch.app/Contents/MacOS/Sketch"
724                     </code>
725
726                     <p>The frame variable command will also perform "object printing" operations on
727                     variables (currently we only support ObjC printing, using the object's "description" method.
728                     Turn this on by passing the -o flag to frame variable:</p>
729
730                     <code>
731                         (lldb) frame variable -o self
732                         (SKTGraphicView *) self = 0x0000000100208b40 &lt;SKTGraphicView: 0x100208b40&gt;
733                     </code>
734
735                     <p>You can select another frame to view with the "<code>frame select</code>" command</p>
736
737                     <code>
738                         (lldb) frame select 9
739                         <br>frame #9: 0x0000000100015ae3, where = Sketch`function1 + 33 at /Projects/Sketch/SKTFunctions.m:11
740                     </code>
741
742                     <p>You can also move up and down the stack by passing the &quot;<code>--relative</code>&quot; (&quot;<code>-r</code>&quot;)
743                       option.  And we have built-in aliases &quot;<code>u</code>&quot; and &quot;<code>d</code>&quot; which
744                       behave like their gdb equivalents.
745
746                     <p>If you need to view more complex data or change program data, you can
747                     use the general "expression" command.  It takes an expression and
748                     evaluates it in the scope of the currently selected frame.  For instance:</p>
749
750                     <code>
751                         (lldb) expr self
752                         <br>$0 = (SKTGraphicView *) 0x0000000100135430
753                         <br>(lldb) expr self = 0x00
754                         <br>$1 = (SKTGraphicView *) 0x0000000000000000
755                         <br>(lldb) frame var self
756                         <br>(SKTGraphicView *) self = 0x0000000000000000
757                     </code>
758
759                     <p>You can also call functions:</p>
760
761                     <code>
762                         (lldb) expr (int) printf ("I have a pointer 0x%llx.\n", self)
763                         <br>$2 = (int) 22
764                         <br>I have a pointer 0x0.
765                     </code>
766
767                     <p>As I said above, &quot;expression&quot; is one of the &quot;raw&quot; commands.  So
768                     you don't have to quote your whole expression, nor backslash protect quotes,
769                     etc...</p>
770
771                     <p>Finally, the results of the expressions are stored in persistent variables
772                     (of the form $[0-9]+) that you can use in further expressions, like:</p>
773
774                     <code>
775                         (lldb) expr self = $0
776                         <br>$4 = (SKTGraphicView *) 0x0000000100135430
777                                     </code>
778                     <p>
779                 </div>
780                     <div class="postfooter"></div>
781                         
782             </div>
783         </div>
784         </div>
785 </div>
786 </body>
787 </html>