Greg Clayton | b01a654 | 2011-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 Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 6 | <title>LLDB Tutorial</title>
|
Greg Clayton | b01a654 | 2011-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 Ingham | 8d8e3ed | 2011-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 Clayton | b01a654 | 2011-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 Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 37 | <noun> <verb> [-options [option-value]] [argument [argument...]]
|
Greg Clayton | b01a654 | 2011-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 Ingham | 8d8e3ed | 2011-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 Clayton | b01a654 | 2011-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 Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 65 | might enter</p>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 66 |
|
| 67 | <code>
|
| 68 | (gdb) break foo.c:12
|
Jim Ingham | 8d8e3ed | 2011-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 Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 73 | </code>
|
| 74 |
|
Jim Ingham | 8d8e3ed | 2011-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 Clayton | b01a654 | 2011-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 Ingham | 0772b53 | 2013-02-14 19:17:49 +0000 | [diff] [blame] | 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 commmon 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 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 103 | <p>Setting breakpoints by name is even more specialized in LLDB as you can specify
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 104 | that you want to set a breakpoint at a function by method name. To set a breakpoint
|
Johnny Chen | 9faf327 | 2011-08-04 21:01:04 +0000 | [diff] [blame] | 105 | on all C++ methods named <code>foo</code> you can enter either of:</p>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 106 |
|
| 107 | <code>
|
| 108 | (lldb) breakpoint set --method foo
|
| 109 | <br>(lldb) breakpoint set -M foo
|
| 110 | </code>
|
| 111 |
|
Johnny Chen | 9faf327 | 2011-08-04 21:01:04 +0000 | [diff] [blame] | 112 | <p>To set a breakpoint Objective C selectors named <code>alignLeftEdges:</code> you can enter either of:</p>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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 <path></code>" ("<code>-s <path></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 |
|
Jim Ingham | 0772b53 | 2013-02-14 19:17:49 +0000 | [diff] [blame] | 127 | <p>The <code>--shlib</code> option can also be repeated to specify several shared libraries.</p>
|
| 128 |
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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:]"
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 137 | <br>(lldb) br s -n "-[SKTGraphicView alignLeftEdges:]"
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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 <path></code>" option in "breakpoint" completes to source files, the
|
| 144 | "<code>--shlib <path></code>" option to currently loaded shared libraries, etc. We can even do
|
| 145 | things like if you specify "<code>--shlib <path></code>", and are completing on "<code>--file <path></code>", we will only
|
| 146 | list source files in the shared library specified by "<code>--shlib <path></code>".</p>
|
| 147 |
|
Sean Callanan | 24592a3 | 2012-12-12 18:02:47 +0000 | [diff] [blame] | 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>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 173 | to fill the namespace with lots of aliases, and then have to type them
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 182 | <p> One alias of note that we do include by popular demand is a weak emulator
|
| 183 | of gdb's "break" 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 |
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 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 |
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 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
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 278 | id within their parent breakpoint (the two are joined by a ".",
|
| 279 | e.g. 1.1 in the example above.) </p>
|
| 280 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 281 | <p>Also the logical breakpoints remain <i>live</i> so that if another shared library
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 300 | <p>That is, lldb will always make a breakpoint from your specification, even
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 314 | locations generated by your logical breakpoint, or on any one of the particular locations
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 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>
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 319 | (lldb) breakpoint command add 1.1
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 320 | <br>Enter your debugger command(s). Type 'DONE' to end.
|
| 321 | <br>> bt
|
| 322 | <br>> DONE
|
| 323 | </code>
|
| 324 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 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>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 328 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 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 <cmd-options> <breakpt-id>
|
| 336 | <br> etc...
|
| 337 | </code>
|
| 338 |
|
| 339 | <p>When you see arguments to commands specified in the Syntax in angle
|
| 340 | brackets like <code><breakpt-id></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 <breakpt-id>
|
| 346 | <br><breakpt-id> -- Breakpoint ID's consist major and minor numbers; the major
|
| 347 | <br> etc...
|
| 348 | </code>
|
| 349 |
|
Johnny Chen | 48e8dde | 2012-03-16 00:44:02 +0000 | [diff] [blame] | 350 | </div>
|
| 351 | <div class="postfooter"></div>
|
| 352 |
|
| 353 | <div class="post">
|
| 354 | <h1 class ="postheader">Setting watchpoints</h1>
|
| 355 | <div class="postcontent">
|
| 356 |
|
| 357 | <p>In addition to breakpoints, you can use <code>help watchpoint</code>
|
| 358 | to see all the commands for watchpoint manipulations. For instance, we might do the following to watch
|
| 359 | a variable called 'global' for write operation, but only stop if the condition '(global==5)' is true:</p>
|
| 360 |
|
Jason Molenda | ee7a663 | 2012-10-19 19:52:12 +0000 | [diff] [blame] | 361 | <pre><tt>(lldb) watch set var global
|
Johnny Chen | 48e8dde | 2012-03-16 00:44:02 +0000 | [diff] [blame] | 362 | Watchpoint created: Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
|
| 363 | declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
|
| 364 | (lldb) watch modify -c '(global==5)'
|
| 365 | (lldb) watch list
|
| 366 | Current watchpoints:
|
| 367 | Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
|
| 368 | declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
|
| 369 | condition = '(global==5)'
|
| 370 | (lldb) c
|
| 371 | Process 15562 resuming
|
| 372 | (lldb) about to write to 'global'...
|
| 373 | Process 15562 stopped and was programmatically restarted.
|
| 374 | Process 15562 stopped and was programmatically restarted.
|
| 375 | Process 15562 stopped and was programmatically restarted.
|
| 376 | Process 15562 stopped and was programmatically restarted.
|
| 377 | Process 15562 stopped
|
| 378 | * thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1
|
| 379 | frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16
|
| 380 | 13
|
| 381 | 14 static void modify(int32_t &var) {
|
| 382 | 15 ++var;
|
| 383 | -> 16 }
|
| 384 | 17
|
| 385 | 18 int main(int argc, char** argv) {
|
| 386 | 19 int local = 0;
|
| 387 | (lldb) bt
|
| 388 | * thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1
|
| 389 | frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16
|
| 390 | frame #1: 0x0000000100000eac a.out`main + 108 at main.cpp:25
|
| 391 | frame #2: 0x00007fff8ac9c7e1 libdyld.dylib`start + 1
|
| 392 | (lldb) frame var global
|
| 393 | (int32_t) global = 5
|
| 394 | (lldb) watch list -v
|
| 395 | Current watchpoints:
|
| 396 | Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
|
| 397 | declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
|
| 398 | condition = '(global==5)'
|
| 399 | hw_index = 0 hit_count = 5 ignore_count = 0
|
| 400 | (lldb) </tt></pre>
|
| 401 | </div>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 402 | <div class="postfooter"></div>
|
| 403 |
|
| 404 | <div class="post">
|
| 405 | <h1 class ="postheader">Starting or attaching to your Program</h1>
|
| 406 | <div class="postcontent">
|
| 407 |
|
| 408 | <p>To launch a program in lldb we use the "<code>process launch</code>" command or
|
| 409 | one of its built in aliases:</p>
|
| 410 |
|
| 411 | <code>
|
| 412 | (lldb) process launch
|
| 413 | <br>(lldb) run
|
| 414 | <br>(lldb) r
|
| 415 | </code>
|
| 416 |
|
| 417 | <p>You can also attach to a process by process ID or process name.
|
| 418 | When attaching to a process by name, lldb also supports the "<code>--waitfor</code>" option which waits for the
|
| 419 | next process that has that name to show up, and attaches to it</p>
|
| 420 |
|
| 421 | <code>
|
| 422 | (lldb) process attach --pid 123
|
| 423 | <br>(lldb) process attach --name Sketch
|
| 424 | <br>(lldb) process attach --name Sketch --waitfor
|
| 425 | </code>
|
| 426 |
|
| 427 | <p>After you launch or attach to a process, your process might stop
|
| 428 | somewhere:</p>
|
| 429 | <code>
|
| 430 | (lldb) process attach -p 12345
|
| 431 | <br>Process 46915 Attaching
|
| 432 | <br>Process 46915 Stopped
|
| 433 | <br>1 of 3 threads stopped with reasons:
|
| 434 | <br>* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread
|
| 435 | </code>
|
| 436 |
|
| 437 |
|
| 438 | <p>Note the line that says "<code>1 of 3 threads stopped with reasons:</code>" and the
|
| 439 | lines that follow it. In a multi-threaded environment it is very
|
| 440 | common for more than one thread to hit your breakpoint(s) before the
|
| 441 | kernel actually returns control to the debugger. In that case, you
|
| 442 | will see all the threads that stopped for some interesting reason
|
| 443 | listed in the stop message.</p>
|
| 444 |
|
| 445 | </div>
|
| 446 | <div class="postfooter"></div>
|
| 447 |
|
| 448 | <div class="post">
|
| 449 | <h1 class ="postheader">Controlling your Program</h1>
|
| 450 | <div class="postcontent">
|
| 451 |
|
| 452 |
|
| 453 | <p>After launching, we can continue until we hit our breakpoint. The primitive
|
| 454 | commands for process control all exist under the "thread" command:</p>
|
| 455 |
|
| 456 | <code>
|
| 457 | (lldb) thread continue
|
| 458 | <br>Resuming thread 0x2c03 in process 46915
|
| 459 | <br>Resuming process 46915
|
| 460 | <br>(lldb)
|
| 461 | </code>
|
| 462 |
|
| 463 | <p>At present you can only operate on one thread at a time, but the
|
| 464 | design will ultimately support saying "step over the function in
|
| 465 | Thread 1, and step into the function in Thread 2, and continue Thread
|
| 466 | 3" etc. When we eventually support keeping some threads running while
|
| 467 | others are stopped this will be particularly important. For
|
| 468 | convenience, however, all the stepping commands have easy aliases.
|
| 469 | So "thread continue" is just "c", etc.</p>
|
| 470 |
|
| 471 | <p>The other program stepping commands are pretty much the same as in gdb.
|
| 472 | You've got:</p>
|
| 473 |
|
| 474 | <pre><tt>(lldb) thread step-in // The same as gdb's "step" or "s"
|
| 475 | (lldb) thread step-over // The same as gdb's "next" or "n"
|
| 476 | (lldb) thread step-out // The same as gdb's "finish" or "f"
|
| 477 | </tt></pre>
|
| 478 |
|
| 479 | <p>By default, lldb does defined aliases to all common gdb process control
|
| 480 | commands ("<code>s</code>", "<code>step</code>", "<code>n</code>", "<code>next</code>", "<code>finish</code>").
|
| 481 | If we have missed any, please add them to your <code>~/.lldbinit</code> file
|
| 482 | using the "<code>command alias</code>" command.
|
| 483 |
|
| 484 | <p>lldb also supported the <i>step by instruction</i> versions:</p>
|
| 485 | <pre><tt>(lldb) thread step-inst // The same as gdb's "stepi" / "si"
|
| 486 | (lldb) thread step-over-inst // The same as gdb's "nexti" / "ni"
|
| 487 | </tt></pre>
|
| 488 |
|
| 489 | <p>Finally, lldb has a <i>run until line or frame exit</i> stepping mode:</p>
|
| 490 |
|
| 491 | <code>
|
| 492 | (lldb) thread until 100
|
| 493 | </code>
|
| 494 |
|
| 495 | <p>This command will run the thread in the current frame till it reaches line 100 in
|
| 496 | this frame or stops if it leaves the current frame. This is a pretty
|
| 497 | close equivalent to gdb's "<code>until</code>" command.</p>
|
| 498 |
|
| 499 | <p>A process, by default, will shared the lldb terminal with the inferior
|
| 500 | process. When in this mode, much like when debugging with gdb, when
|
| 501 | the process is running anything you type will go to the STDIN of the
|
| 502 | inferior process. To interrupt your inferior program, type CTRL+C.</p>
|
| 503 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 504 | <p>If you attach to a process, or launch a process with the "<code>--no-stdin</code>"
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 505 | option, the command interpreter is always available to enter commands. This
|
| 506 | might be a little disconcerting to gdb users when always have an <code>(lldb)</code>
|
| 507 | prompt. This allows you to set a breakpoint, etc without having to explicitly interrupt
|
| 508 | the program you are debugging:</p>
|
| 509 |
|
| 510 | <code>
|
| 511 | (lldb) process continue
|
| 512 | <br>(lldb) breakpoint set --name stop_here
|
| 513 | </code>
|
| 514 |
|
| 515 | <p>There are many commands that won't work while running, and the command
|
| 516 | interpreter should do a good job of letting you know when this is the
|
| 517 | case. If you find any instances where the command interpreter isn't
|
| 518 | doing its job, please file a bug. This way of operation will set us
|
| 519 | up for a future debugging mode called <i>thread centric debugging</i>.
|
| 520 | This mode will allow us to run all threads and only stop the threads
|
| 521 | that are at breakpoints or have exceptions or signals.</p>
|
| 522 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 523 | <p>The commands that currently work while running include
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 524 | interrupting the process to halt execution ("<code>process interrupt</code>"),
|
| 525 | getting the process status ("<code>process status</code>"),
|
| 526 | breakpoint setting and clearing ("<code> breakpoint [set|clear|enable|disable|list] ...</code>"),
|
| 527 | and memory reading and writing ("<code> memory [read|write] ...</code>").
|
| 528 | </p>
|
| 529 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 530 | <p>The question of disabling stdio when running brings up a good opportunity to
|
| 531 | show how to set debugger properties in general.
|
| 532 | If you always want to run in the <code>--no-stdin</code> mode, you can set this
|
| 533 | as a generic process property using the lldb "<code>settings</code>&qout; command,
|
| 534 | which is equivalent to gdb's "<code>set</code>" command. For instance,
|
| 535 | in this case you would say:</p>
|
| 536 |
|
| 537 | <code>
|
| 538 | (lldb) settings set target.process.disable-stdio true
|
| 539 | </code>
|
| 540 |
|
| 541 | <p>Over time, gdb's "<code>set</code> command became a wilderness of disordered options,
|
| 542 | so that there were useful options that even experienced gdb users didn't know about
|
| 543 | because they were too hard to find. We tried to organize the settings hierarchically
|
| 544 | using the structure of the basic entities in the debugger. For the most part anywhere
|
| 545 | you can specify a setting on a generic entity (threads, for example) you can also apply
|
| 546 | the option to a particular instance, which can also be convenient at times.
|
| 547 | You can view the available settings with "<code>settings list</code>" and
|
| 548 | there is help on the settings command explaining how it works more generally.</p>
|
| 549 |
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 550 | </div>
|
| 551 | <div class="postfooter"></div>
|
| 552 |
|
| 553 | <div class="post">
|
| 554 | <h1 class ="postheader">Examining Thread State</h1>
|
| 555 | <div class="postcontent">
|
| 556 |
|
| 557 | <p>Once you've stopped, lldb will choose a current thread, usually the
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 558 | one that stopped "for a reason", and a current frame in that thread (on stop this is always the bottom-most frame).
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 559 | Many the commands for inspecting state work on this current
|
| 560 | thread/frame.</p>
|
| 561 |
|
| 562 | <p>To inspect the current state of your process, you can start with the
|
| 563 | threads:</p>
|
| 564 |
|
| 565 | <pre><tt>(lldb) thread list
|
| 566 | Process 46915 state is Stopped
|
| 567 | * thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread
|
| 568 | thread #2: tid = 0x2e03, 0x00007fff85cbb08a, where = libSystem.B.dylib`kevent + 10, queue = com.apple.libdispatch-manager
|
| 569 | thread #3: tid = 0x2f03, 0x00007fff85cbbeaa, where = libSystem.B.dylib`__workq_kernreturn + 10
|
| 570 | </tt></pre>
|
| 571 |
|
| 572 | <p>The * indicates that Thread 1 is the current thread. To get a
|
| 573 | backtrace for that thread, do:</p>
|
| 574 |
|
| 575 | <pre><tt>(lldb) thread backtrace
|
| 576 | thread #1: tid = 0x2c03, stop reason = breakpoint 1.1, queue = com.apple.main-thread
|
| 577 | frame #0: 0x0000000100010d5b, where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405
|
| 578 | frame #1: 0x00007fff8602d152, where = AppKit`-[NSApplication sendAction:to:from:] + 95
|
| 579 | frame #2: 0x00007fff860516be, where = AppKit`-[NSMenuItem _corePerformAction] + 365
|
| 580 | frame #3: 0x00007fff86051428, where = AppKit`-[NSCarbonMenuImpl performActionWithHighlightingForItemAtIndex:] + 121
|
| 581 | frame #4: 0x00007fff860370c1, where = AppKit`-[NSMenu performKeyEquivalent:] + 272
|
| 582 | frame #5: 0x00007fff86035e69, where = AppKit`-[NSApplication _handleKeyEquivalent:] + 559
|
| 583 | frame #6: 0x00007fff85f06aa1, where = AppKit`-[NSApplication sendEvent:] + 3630
|
| 584 | frame #7: 0x00007fff85e9d922, where = AppKit`-[NSApplication run] + 474
|
| 585 | frame #8: 0x00007fff85e965f8, where = AppKit`NSApplicationMain + 364
|
| 586 | frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11
|
| 587 | frame #10: 0x0000000100000f20, where = Sketch`start + 52
|
| 588 | </tt></pre>
|
| 589 |
|
| 590 | <p>You can also provide a list of threads to backtrace, or the keyword
|
| 591 | "all" to see all threads:</p>
|
| 592 |
|
| 593 | <code>
|
| 594 | (lldb) thread backtrace all
|
| 595 | </code>
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 596 |
|
| 597 | <p>You can select the current thread, which will be used by default in all the commands in
|
| 598 | the next section, with the "thread select" command:</p>
|
| 599 |
|
| 600 | <code>
|
| 601 | (lldb) thread select 2
|
| 602 | </code>
|
| 603 |
|
| 604 | <p>where the thread index is just the one shown in the "<code>thread list</code>" listing.
|
| 605 |
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 606 | </div>
|
| 607 | <div class="postfooter"></div>
|
| 608 |
|
| 609 | <div class="post">
|
| 610 | <h1 class ="postheader">Examining Stack Frame State</h1>
|
| 611 | <div class="postcontent">
|
| 612 |
|
| 613 |
|
| 614 | <p>The most convenient way to inspect a frame's arguments and local variables is to use the "<code>frame variable</code>" command:</p>
|
| 615 |
|
| 616 | <code>
|
| 617 | (lldb) frame variable
|
| 618 | <br>self = (SKTGraphicView *) 0x0000000100208b40
|
| 619 | <br>_cmd = (struct objc_selector *) 0x000000010001bae1
|
| 620 | <br>sender = (id) 0x00000001001264e0
|
| 621 | <br>selection = (NSArray *) 0x00000001001264e0
|
| 622 | <br>i = (NSUInteger) 0x00000001001264e0
|
| 623 | <br>c = (NSUInteger) 0x00000001001253b0
|
| 624 | </code>
|
| 625 |
|
| 626 | <p>As you see above, if you don't specify any variable names, all arguments
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 627 | and locals will be shown. If you call "<code>frame variable</code>"
|
| 628 | passing in the names of a particular local(s), only those variables
|
| 629 | will be printed. For instance:
|
| 630 | </p>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 631 |
|
| 632 | <code>
|
| 633 | (lldb) frame variable self
|
| 634 | <br>(SKTGraphicView *) self = 0x0000000100208b40
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 635 | </code>
|
| 636 |
|
| 637 | <p>You can also pass in a path to some subelement of one of the available locals,
|
| 638 | and that sub-element will be printed. For instance:
|
| 639 | </p>
|
| 640 |
|
| 641 | <code>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 642 | <br>(lldb) frame variable self.isa
|
| 643 | <br>(struct objc_class *) self.isa = 0x0000000100023730
|
| 644 | </code>
|
| 645 |
|
| 646 | <p>The "<code>frame variable</code>" command is not a full expression
|
| 647 | parser but it does support a few simple operations like &, *, ->, [] (no overloaded
|
| 648 | operators). The array brackets can be used on pointers to treat pointers
|
| 649 | as arrays:</p>
|
| 650 |
|
| 651 | <code>
|
| 652 | (lldb) frame variable *self
|
| 653 | <br>(SKTGraphicView *) self = 0x0000000100208b40
|
| 654 | <br>(NSView) NSView = {
|
| 655 | <br>(NSResponder) NSResponder = {
|
| 656 | <br>...
|
| 657 | <br>
|
| 658 | <br>(lldb) frame variable &self
|
| 659 | <br>(SKTGraphicView **) &self = 0x0000000100304ab
|
| 660 | <br>
|
| 661 | <br>(lldb) frame variable argv[0]
|
| 662 | <br>(char const *) argv[0] = 0x00007fff5fbffaf8 "/Projects/Sketch/build/Debug/Sketch.app/Contents/MacOS/Sketch"
|
| 663 | </code>
|
| 664 |
|
| 665 | <p>The frame variable command will also perform "object printing" operations on
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 666 | variables (currently we only support ObjC printing, using the object's "description" method.
|
| 667 | Turn this on by passing the -o flag to frame variable:</p>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 668 |
|
| 669 | <code>
|
| 670 | (lldb) frame variable -o self
|
| 671 | (SKTGraphicView *) self = 0x0000000100208b40 <SKTGraphicView: 0x100208b40>
|
| 672 | </code>
|
| 673 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 674 | <p>You can select another frame to view with the "<code>frame select</code>" command</p>
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 675 |
|
| 676 | <code>
|
| 677 | (lldb) frame select 9
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 678 | <br>frame #9: 0x0000000100015ae3, where = Sketch`function1 + 33 at /Projects/Sketch/SKTFunctions.m:11
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 679 | </code>
|
| 680 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 681 | <p>You can also move up and down the stack by passing the "<code>--relative</code>" ("<code>-r</code>")
|
| 682 | option. And we have built-in aliases "<code>u</code>" and "<code>d</code>" which
|
| 683 | behave like their gdb equivalents.
|
| 684 |
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 685 | <p>If you need to view more complex data or change program data, you can
|
| 686 | use the general "expression" command. It takes an expression and
|
| 687 | evaluates it in the scope of the currently selected frame. For instance:</p>
|
| 688 |
|
| 689 | <code>
|
| 690 | (lldb) expr self
|
| 691 | <br>$0 = (SKTGraphicView *) 0x0000000100135430
|
| 692 | <br>(lldb) expr self = 0x00
|
| 693 | <br>$1 = (SKTGraphicView *) 0x0000000000000000
|
| 694 | <br>(lldb) frame var self
|
| 695 | <br>(SKTGraphicView *) self = 0x0000000000000000
|
| 696 | </code>
|
| 697 |
|
| 698 | <p>You can also call functions:</p>
|
| 699 |
|
| 700 | <code>
|
| 701 | (lldb) expr (int) printf ("I have a pointer 0x%llx.\n", self)
|
| 702 | <br>$2 = (int) 22
|
| 703 | <br>I have a pointer 0x0.
|
| 704 | </code>
|
| 705 |
|
Jim Ingham | 8d8e3ed | 2011-03-31 21:56:13 +0000 | [diff] [blame] | 706 | <p>As I said above, "expression" is one of the "raw" commands. So
|
Greg Clayton | b01a654 | 2011-03-30 01:02:37 +0000 | [diff] [blame] | 707 | you don't have to quote your whole expression, nor backslash protect quotes,
|
| 708 | etc...</p>
|
| 709 |
|
| 710 | <p>Finally, the results of the expressions are stored in persistent variables
|
| 711 | (of the form $[0-9]+) that you can use in further expressions, like:</p>
|
| 712 |
|
| 713 | <code>
|
| 714 | (lldb) expr self = $0
|
| 715 | <br>$4 = (SKTGraphicView *) 0x0000000100135430
|
| 716 | </code>
|
| 717 | <p>
|
| 718 | </div>
|
| 719 | <div class="postfooter"></div>
|
| 720 |
|
| 721 | </div>
|
| 722 | </div>
|
| 723 | </div>
|
| 724 | </div>
|
| 725 | </body>
|
| 726 | </html>
|