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 not to echo commands while sourcing files or one-line commands provided on the command line. 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:: --print-script-interpreter-info 238 239 Prints out a json dictionary with information about the scripting language interpreter. 240 241.. option:: --python-path 242 243 Prints out the path to the lldb.py file for this version of lldb. 244 245.. option:: -P 246 247 Alias for --python-path 248 249.. option:: --script-language <language> 250 251 Tells the debugger to use the specified scripting language for user-defined scripts. 252 253EXAMPLES 254-------- 255 256The debugger can be started in several modes. 257 258Passing an executable as a positional argument prepares lldb to debug the given 259executable. To disambiguate between arguments passed to lldb and arguments 260passed to the debugged executable, arguments starting with a - must be passed 261after --. 262 263 lldb --arch x86_64 /path/to/program program argument -- --arch armv7 264 265For convenience, passing the executable after -- is also supported. 266 267 lldb --arch x86_64 -- /path/to/program program argument --arch armv7 268 269Passing one of the attach options causes :program:`lldb` to immediately attach 270to the given process. 271 272 lldb -p <pid> 273 lldb -n <process-name> 274 275Passing --repl starts :program:`lldb` in REPL mode. 276 277 lldb -r 278 279Passing --core causes :program:`lldb` to debug the core file. 280 281 lldb -c /path/to/core 282 283Command options can be combined with these modes and cause :program:`lldb` to 284run the specified commands before or after events, like loading the file or 285crashing, in the order provided on the command line. 286 287 lldb -O 'settings set stop-disassembly-count 20' -o 'run' -o 'bt' 288 lldb -S /source/before/file -s /source/after/file 289 lldb -K /source/before/crash -k /source/after/crash 290 291Note: In REPL mode no file is loaded, so commands specified to run after 292loading the file (via -o or -s) will be ignored. 293 294USING LLDB 295---------- 296 297In :program:`lldb` there is a help command which can be used to find 298descriptions and examples of all :program:`lldb` commands. To get help on 299"breakpoint set" you would type "help breakpoint set". 300 301There is also an apropos command which will search the help text of all 302commands for a given term ‐‐ this is useful for locating a command by topic. 303For instance, "apropos breakpoint" will list any command that has the word 304"breakpoint" in its help text. 305 306CONFIGURATION FILES 307------------------- 308 309:program:`lldb` reads things like settings, aliases and commands from the 310.lldbinit file. 311 312First, :program:`lldb` will try to read the application specific init file 313whose name is ~/.lldbinit followed by a "-" and the name of the current 314program. This would be ~/.lldbinit-lldb for the command line :program:`lldb` 315and ~/.lldbinit-Xcode for Xcode. If there is no application specific init 316file, :program:`lldb` will look for an init file in the home directory. 317If launched with a `REPL`_ option, it will first look for a REPL configuration 318file, specific to the REPL language. The init file should be named as follow: 319``.lldbinit-<language>-repl`` (i.e. ``.lldbinit-swift-repl``). If this file doesn't 320exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither 321a REPL init file nor an application specific init file, ``lldb`` will fallback to 322the global ~/.lldbinit. 323 324Secondly, it will look for an .lldbinit file in the current working directory. 325For security reasons, :program:`lldb` will print a warning and not source this 326file by default. This behavior can be changed by changing the 327target.load-cwd-lldbinit setting. 328 329To always load the .lldbinit file in the current working directory, add the 330following command to ~/.lldbinit: 331 332 settings set target.load-cwd-lldbinit true 333 334To never load the .lldbinit file in the current working directory and silence 335the warning, add the following command to ~/.lldbinit: 336 337 settings set target.load-cwd-lldbinit false 338 339SEE ALSO 340-------- 341 342The LLDB project page https://lldb.llvm.org has many different resources 343for :program:`lldb` users ‐‐ the gdb/lldb command equivalence page 344https://lldb.llvm.org/use/map.html can be especially helpful for users 345coming from gdb. 346