1:orphan: 2 3lldb -- The Debugger 4==================== 5 6.. program:: lldb 7 8SYNOPSIS 9-------- 10 11| :program:`lldb` [*options*] *executable* 12 13DESCRIPTION 14----------- 15 16:program:`lldb` is a next generation, high-performance debugger. It is built as 17a set of reusable components which highly leverage existing libraries in the 18larger LLVM Project, such as the Clang expression parser and LLVM disassembler. 19 20:program:`lldb` is the default debugger in Xcode on macOS and supports 21debugging C, Objective-C and C++ on the desktop and iOS devices and simulator. 22 23All of the code in the LLDB project is available under the Apache 2.0 License 24with LLVM exceptions. 25 26ATTACHING 27--------- 28 29.. option:: --attach-name <name> 30 31 Tells the debugger to attach to a process with the given name. 32 33.. option:: --attach-pid <pid> 34 35 Tells the debugger to attach to a process with the given pid. 36 37.. option:: -n <value> 38 39 Alias for --attach-name 40 41.. option:: -p <value> 42 43 Alias for --attach-pid 44 45.. option:: --wait-for 46 47 Tells the debugger to wait for a process with the given pid or name to launch before attaching. 48 49.. option:: -w 50 51 Alias for --wait-for 52 53COMMANDS 54-------- 55 56.. option:: --batch 57 58 Tells the debugger to run the commands from -s, -S, -o & -O, and then quit. 59 60.. option:: -b 61 62 Alias for --batch 63 64.. option:: -K <value> 65 66 Alias for --source-on-crash 67 68.. option:: -k <value> 69 70 Alias for --one-line-on-crash 71 72.. option:: --local-lldbinit 73 74 Allow the debugger to parse the .lldbinit files in the current working directory, unless --no-lldbinit is passed. 75 76.. option:: --no-lldbinit 77 78 Do not automatically parse any '.lldbinit' files. 79 80.. option:: --one-line-before-file <command> 81 82 Tells the debugger to execute this one-line lldb command before any file provided on the command line has been loaded. 83 84.. option:: --one-line-on-crash <command> 85 86 When in batch mode, tells the debugger to run this one-line lldb command if the target crashes. 87 88.. option:: --one-line <command> 89 90 Tells the debugger to execute this one-line lldb command after any file provided on the command line has been loaded. 91 92.. option:: -O <value> 93 94 Alias for --one-line-before-file 95 96.. option:: -o <value> 97 98 Alias for --one-line 99 100.. option:: -Q 101 102 Alias for --source-quietly 103 104.. option:: --source-before-file <file> 105 106 Tells the debugger to read in and execute the lldb commands in the given file, before any file has been loaded. 107 108.. option:: --source-on-crash <file> 109 110 When in batch mode, tells the debugger to source this file of lldb commands if the target crashes. 111 112.. option:: --source-quietly 113 114 Tells the debugger to execute this one-line lldb command before any file has been loaded. 115 116.. option:: --source <file> 117 118 Tells the debugger to read in and execute the lldb commands in the given file, after any file has been loaded. 119 120.. option:: -S <value> 121 122 Alias for --source-before-file 123 124.. option:: -s <value> 125 126 Alias for --source 127 128.. option:: -x 129 130 Alias for --no-lldbinit 131 132OPTIONS 133------- 134 135.. option:: --arch <architecture> 136 137 Tells the debugger to use the specified architecture when starting and running the program. 138 139.. option:: -a <value> 140 141 Alias for --arch 142 143.. option:: --capture-path <filename> 144 145 Tells the debugger to use the given filename for the reproducer. 146 147.. option:: --capture 148 149 Tells the debugger to capture a reproducer. 150 151.. option:: --core <filename> 152 153 Tells the debugger to use the full path to <filename> as the core file. 154 155.. option:: -c <value> 156 157 Alias for --core 158 159.. option:: --debug 160 161 Tells the debugger to print out extra information for debugging itself. 162 163.. option:: -d 164 165 Alias for --debug 166 167.. option:: --editor 168 169 Tells the debugger to open source files using the host's "external editor" mechanism. 170 171.. option:: -e 172 173 Alias for --editor 174 175.. option:: --file <filename> 176 177 Tells the debugger to use the file <filename> as the program to be debugged. 178 179.. option:: -f <value> 180 181 Alias for --file 182 183.. option:: --help 184 185 Prints out the usage information for the LLDB debugger. 186 187.. option:: -h 188 189 Alias for --help 190 191.. option:: --no-use-colors 192 193 Do not use colors. 194 195.. option:: --replay <filename> 196 197 Tells the debugger to replay a reproducer from <filename>. 198 199.. option:: --version 200 201 Prints out the current version number of the LLDB debugger. 202 203.. option:: -v 204 205 Alias for --version 206 207.. option:: -X 208 209 Alias for --no-use-color 210 211REPL 212---- 213 214.. option:: -r=<flags> 215 216 Alias for --repl=<flags> 217 218.. option:: --repl-language <language> 219 220 Chooses the language for the REPL. 221 222.. option:: --repl=<flags> 223 224 Runs lldb in REPL mode with a stub process with the given flags. 225 226.. option:: -R <value> 227 228 Alias for --repl-language 229 230SCRIPTING 231--------- 232 233.. option:: -l <value> 234 235 Alias for --script-language 236 237.. option:: --python-path 238 239 Prints out the path to the lldb.py file for this version of lldb. 240 241.. option:: -P 242 243 Alias for --python-path 244 245.. option:: --script-language <language> 246 247 Tells the debugger to use the specified scripting language for user-defined scripts. 248 249EXAMPLES 250-------- 251 252The debugger can be started in several modes. 253 254Passing an executable as a positional argument prepares lldb to debug the given 255executable. To disambiguate between arguments passed to lldb and arguments 256passed to the debugged executable, arguments starting with a - must be passed 257after --. 258 259 lldb --arch x86_64 /path/to/program program argument -- --arch armv7 260 261For convenience, passing the executable after -- is also supported. 262 263 lldb --arch x86_64 -- /path/to/program program argument --arch armv7 264 265Passing one of the attach options causes :program:`lldb` to immediately attach 266to the given process. 267 268 lldb -p <pid> 269 lldb -n <process-name> 270 271Passing --repl starts :program:`lldb` in REPL mode. 272 273 lldb -r 274 275Passing --core causes :program:`lldb` to debug the core file. 276 277 lldb -c /path/to/core 278 279Command options can be combined with these modes and cause :program:`lldb` to 280run the specified commands before or after events, like loading the file or 281crashing, in the order provided on the command line. 282 283 lldb -O 'settings set stop-disassembly-count 20' -o 'run' -o 'bt' 284 lldb -S /source/before/file -s /source/after/file 285 lldb -K /source/before/crash -k /source/after/crash 286 287Note: In REPL mode no file is loaded, so commands specified to run after 288loading the file (via -o or -s) will be ignored. 289 290USING LLDB 291---------- 292 293In :program:`lldb` there is a help command which can be used to find 294descriptions and examples of all :program:`lldb` commands. To get help on 295"breakpoint set" you would type "help breakpoint set". 296 297There is also an apropos command which will search the help text of all 298commands for a given term ‐‐ this is useful for locating a command by topic. 299For instance, "apropos breakpoint" will list any command that has the word 300"breakpoint" in its help text. 301 302CONFIGURATION FILES 303------------------- 304 305:program:`lldb` reads things like settings, aliases and commands from the 306.lldbinit file. 307 308First, :program:`lldb` will try to read the application specific init file 309whose name is ~/.lldbinit followed by a "-" and the name of the current 310program. This would be ~/.lldbinit-lldb for the command line :program:`lldb` 311and ~/.lldbinit-Xcode for Xcode. If there is no application specific init 312file, :program:`lldb` will look for an init file in the home directory. 313If launched with a `REPL`_ option, it will first look for a REPL configuration 314file, specific to the REPL language. The init file should be named as follow: 315``.lldbinit-<language>-repl`` (i.e. ``.lldbinit-swift-repl``). If this file doesn't 316exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither 317a REPL init file nor an application specific init file, ``lldb`` will fallback to 318the global ~/.lldbinit. 319 320Secondly, it will look for an .lldbinit file in the current working directory. 321For security reasons, :program:`lldb` will print a warning and not source this 322file by default. This behavior can be changed by changing the 323target.load-cwd-lldbinit setting. 324 325To always load the .lldbinit file in the current working directory, add the 326following command to ~/.lldbinit: 327 328 settings set target.load-cwd-lldbinit true 329 330To never load the .lldbinit file in the current working directory and silence 331the warning, add the following command to ~/.lldbinit: 332 333 settings set target.load-cwd-lldbinit false 334 335SEE ALSO 336-------- 337 338The LLDB project page https://lldb.llvm.org has many different resources 339for :program:`lldb` users ‐‐ the gdb/lldb command equivalence page 340https://lldb.llvm.org/use/map.html can be especially helpful for users 341coming from gdb. 342