346 lines · plain
1:orphan:2 3lldb -- The Debugger4====================5 6.. program:: lldb7 8SYNOPSIS9--------10 11| :program:`lldb` [*options*] *executable*12 13DESCRIPTION14-----------15 16:program:`lldb` is a next generation, high-performance debugger. It is built as17a set of reusable components which highly leverage existing libraries in the18larger LLVM Project, such as the Clang expression parser and LLVM disassembler.19 20:program:`lldb` is the default debugger in Xcode on macOS and supports21debugging 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 License24with LLVM exceptions.25 26ATTACHING27---------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-name40 41.. option:: -p <value>42 43 Alias for --attach-pid44 45.. option:: --wait-for46 47 Tells the debugger to wait for a process with the given pid or name to launch before attaching.48 49.. option:: -w50 51 Alias for --wait-for52 53COMMANDS54--------55 56.. option:: --batch57 58 Tells the debugger to run the commands from -s, -S, -o & -O, and then quit.59 60.. option:: -b61 62 Alias for --batch63 64.. option:: -K <value>65 66 Alias for --source-on-crash67 68.. option:: -k <value>69 70 Alias for --one-line-on-crash71 72.. option:: --local-lldbinit73 74 Allow the debugger to parse the .lldbinit files in the current working directory, unless --no-lldbinit is passed.75 76.. option:: --no-lldbinit77 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-file95 96.. option:: -o <value>97 98 Alias for --one-line99 100.. option:: -Q101 102 Alias for --source-quietly103 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-quietly113 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-file123 124.. option:: -s <value>125 126 Alias for --source127 128.. option:: -x129 130 Alias for --no-lldbinit131 132OPTIONS133-------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 --arch142 143.. option:: --capture-path <filename>144 145 Tells the debugger to use the given filename for the reproducer.146 147.. option:: --capture148 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 --core158 159.. option:: --debug160 161 Tells the debugger to print out extra information for debugging itself.162 163.. option:: -d164 165 Alias for --debug166 167.. option:: --editor168 169 Tells the debugger to open source files using the host's "external editor" mechanism.170 171.. option:: -e172 173 Alias for --editor174 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 --file182 183.. option:: --help184 185 Prints out the usage information for the LLDB debugger.186 187.. option:: -h188 189 Alias for --help190 191.. option:: --no-use-colors192 193 Do not use colors.194 195.. option:: --replay <filename>196 197 Tells the debugger to replay a reproducer from <filename>.198 199.. option:: --version200 201 Prints out the current version number of the LLDB debugger.202 203.. option:: -v204 205 Alias for --version206 207.. option:: -X208 209 Alias for --no-use-color210 211REPL212----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-language229 230SCRIPTING231---------232 233.. option:: -l <value>234 235 Alias for --script-language236 237.. option:: --print-script-interpreter-info238 239 Prints out a json dictionary with information about the scripting language interpreter.240 241.. option:: --python-path242 243 Prints out the path to the lldb.py file for this version of lldb.244 245.. option:: -P246 247 Alias for --python-path248 249.. option:: --script-language <language>250 251 Tells the debugger to use the specified scripting language for user-defined scripts.252 253EXAMPLES254--------255 256The debugger can be started in several modes.257 258Passing an executable as a positional argument prepares lldb to debug the given259executable. To disambiguate between arguments passed to lldb and arguments260passed to the debugged executable, arguments starting with a - must be passed261after --.262 263 lldb --arch x86_64 /path/to/program program argument -- --arch armv7264 265For convenience, passing the executable after -- is also supported.266 267 lldb --arch x86_64 -- /path/to/program program argument --arch armv7268 269Passing one of the attach options causes :program:`lldb` to immediately attach270to 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 -r278 279Passing --core causes :program:`lldb` to debug the core file.280 281 lldb -c /path/to/core282 283Command options can be combined with these modes and cause :program:`lldb` to284run the specified commands before or after events, like loading the file or285crashing, 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/file289 lldb -K /source/before/crash -k /source/after/crash290 291Note: In REPL mode no file is loaded, so commands specified to run after292loading the file (via -o or -s) will be ignored.293 294USING LLDB295----------296 297In :program:`lldb` there is a help command which can be used to find298descriptions and examples of all :program:`lldb` commands. To get help on299"breakpoint set" you would type "help breakpoint set".300 301There is also an apropos command which will search the help text of all302commands for a given term ‐‐ this is useful for locating a command by topic.303For instance, "apropos breakpoint" will list any command that has the word304"breakpoint" in its help text.305 306CONFIGURATION FILES307-------------------308 309:program:`lldb` reads things like settings, aliases and commands from the310.lldbinit file.311 312First, :program:`lldb` will try to read the application specific init file313whose name is ~/.lldbinit followed by a "-" and the name of the current314program. This would be ~/.lldbinit-lldb for the command line :program:`lldb`315and ~/.lldbinit-Xcode for Xcode. If there is no application specific init316file, :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 configuration318file, 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't320exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither321a REPL init file nor an application specific init file, ``lldb`` will fallback to322the 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 this326file by default. This behavior can be changed by changing the327target.load-cwd-lldbinit setting.328 329To always load the .lldbinit file in the current working directory, add the330following command to ~/.lldbinit:331 332 settings set target.load-cwd-lldbinit true333 334To never load the .lldbinit file in the current working directory and silence335the warning, add the following command to ~/.lldbinit:336 337 settings set target.load-cwd-lldbinit false338 339SEE ALSO340--------341 342The LLDB project page https://lldb.llvm.org has many different resources343for :program:`lldb` users ‐‐ the gdb/lldb command equivalence page344https://lldb.llvm.org/use/map.html can be especially helpful for users345coming from gdb.346