lldb/docs/man/lldb.rst

   1 :orphan:
   2
   3 lldb -- The Debugger
   4 ====================
   5
   6 .. program:: lldb
   7
   8 SYNOPSIS
   9 --------
  10
  11 | :program:`lldb` [*options*] *executable*
  12
  13 DESCRIPTION
  14 -----------
  15
  16 :program:`lldb` is a next generation, high-performance debugger. It is built as
  17 a set of reusable components which highly leverage existing libraries in the
  18 larger 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
  21 debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
  22
  23 All of the code in the LLDB project is available under the Apache 2.0 License
  24 with LLVM exceptions.
  25
  26 ATTACHING
  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
  53 COMMANDS
  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
 132 OPTIONS
 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
 211 REPL
 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
 230 SCRIPTING
 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
 253 EXAMPLES
 254 --------
 255
 256 The debugger can be started in several modes.
 257
 258 Passing an executable as a positional argument prepares lldb to debug the given
 259 executable. To disambiguate between arguments passed to lldb and arguments
 260 passed to the debugged executable, arguments starting with a - must be passed
 261 after --.
 262
 263   lldb --arch x86_64 /path/to/program program argument -- --arch armv7
 264
 265 For convenience, passing the executable after -- is also supported.
 266
 267   lldb --arch x86_64 -- /path/to/program program argument --arch armv7
 268
 269 Passing one of the attach options causes :program:`lldb` to immediately attach
 270 to the given process.
 271
 272   lldb -p <pid>
 273   lldb -n <process-name>
 274
 275 Passing --repl starts :program:`lldb` in REPL mode.
 276
 277   lldb -r
 278
 279 Passing --core causes :program:`lldb` to debug the core file.
 280
 281   lldb -c /path/to/core
 282
 283 Command options can be combined with these modes and cause :program:`lldb` to
 284 run the specified commands before or after events, like loading the file or
 285 crashing, 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
 291 Note: In REPL mode no file is loaded, so commands specified to run after
 292 loading the file (via -o or -s) will be ignored.
 293
 294 USING LLDB
 295 ----------
 296
 297 In :program:`lldb` there is a help command which can be used to find
 298 descriptions and examples of all :program:`lldb` commands.  To get help on
 299 "breakpoint set" you would type "help breakpoint set".
 300
 301 There is also an apropos command which will search the help text of all
 302 commands for a given term ‐‐ this is useful for locating a command by topic.
 303 For instance, "apropos breakpoint" will list any command that has the word
 304 "breakpoint" in its help text.
 305
 306 CONFIGURATION FILES
 307 -------------------
 308
 309 :program:`lldb` reads things like settings, aliases and commands from the
 310 .lldbinit file.
 311
 312 First, :program:`lldb` will try to read the application specific init file
 313 whose name is ~/.lldbinit followed by a "-" and the name of the current
 314 program. This would be ~/.lldbinit-lldb for the command line :program:`lldb`
 315 and ~/.lldbinit-Xcode for Xcode. If there is no application specific init
 316 file, :program:`lldb` will look for an init file in the home directory.
 317 If launched with a `REPL`_ option, it will first look for a REPL configuration
 318 file, 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
 320 exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither
 321 a REPL init file nor an application specific init file, ``lldb`` will fallback to
 322 the global ~/.lldbinit.
 323
 324 Secondly, it will look for an .lldbinit file in the current working directory.
 325 For security reasons, :program:`lldb` will print a warning and not source this
 326 file by default. This behavior can be changed by changing the
 327 target.load-cwd-lldbinit setting.
 328
 329 To always load the .lldbinit file in the current working directory, add the
 330 following command to ~/.lldbinit:
 331
 332   settings set target.load-cwd-lldbinit true
 333
 334 To never load the .lldbinit file in the current working directory and silence
 335 the warning, add the following command to ~/.lldbinit:
 336
 337   settings set target.load-cwd-lldbinit false
 338
 339 SEE ALSO
 340 --------
 341
 342 The LLDB project page https://lldb.llvm.org has many different resources
 343 for :program:`lldb` users ‐‐ the gdb/lldb command equivalence page
 344 https://lldb.llvm.org/use/map.html can be especially helpful for users
 345 coming from gdb.