|
|
:orphan:
|
|
|
|
|
|
lldb -- The Debugger
|
|
|
====================
|
|
|
|
|
|
.. program:: lldb
|
|
|
|
|
|
SYNOPSIS
|
|
|
--------
|
|
|
|
|
|
| :program:`lldb` [*options*] *executable*
|
|
|
|
|
|
DESCRIPTION
|
|
|
-----------
|
|
|
|
|
|
:program:`lldb` is a next generation, high-performance debugger. It is built as
|
|
|
a set of reusable components which highly leverage existing libraries in the
|
|
|
larger LLVM Project, such as the Clang expression parser and LLVM disassembler.
|
|
|
|
|
|
:program:`lldb` is the default debugger in Xcode on macOS and supports
|
|
|
debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
|
|
|
|
|
|
All of the code in the LLDB project is available under the Apache 2.0 License
|
|
|
with LLVM exceptions.
|
|
|
|
|
|
ATTACHING
|
|
|
---------
|
|
|
|
|
|
.. option:: --attach-name <name>
|
|
|
|
|
|
Tells the debugger to attach to a process with the given name.
|
|
|
|
|
|
.. option:: --attach-pid <pid>
|
|
|
|
|
|
Tells the debugger to attach to a process with the given pid.
|
|
|
|
|
|
.. option:: -n <value>
|
|
|
|
|
|
Alias for --attach-name
|
|
|
|
|
|
.. option:: -p <value>
|
|
|
|
|
|
Alias for --attach-pid
|
|
|
|
|
|
.. option:: --wait-for
|
|
|
|
|
|
Tells the debugger to wait for a process with the given pid or name to launch before attaching.
|
|
|
|
|
|
.. option:: -w
|
|
|
|
|
|
Alias for --wait-for
|
|
|
|
|
|
COMMANDS
|
|
|
--------
|
|
|
|
|
|
.. option:: --batch
|
|
|
|
|
|
Tells the debugger to run the commands from -s, -S, -o & -O, and then quit.
|
|
|
|
|
|
.. option:: -b
|
|
|
|
|
|
Alias for --batch
|
|
|
|
|
|
.. option:: -K <value>
|
|
|
|
|
|
Alias for --source-on-crash
|
|
|
|
|
|
.. option:: -k <value>
|
|
|
|
|
|
Alias for --one-line-on-crash
|
|
|
|
|
|
.. option:: --local-lldbinit
|
|
|
|
|
|
Allow the debugger to parse the .lldbinit files in the current working directory, unless --no-lldbinit is passed.
|
|
|
|
|
|
.. option:: --no-lldbinit
|
|
|
|
|
|
Do not automatically parse any '.lldbinit' files.
|
|
|
|
|
|
.. option:: --one-line-before-file <command>
|
|
|
|
|
|
Tells the debugger to execute this one-line lldb command before any file provided on the command line has been loaded.
|
|
|
|
|
|
.. option:: --one-line-on-crash <command>
|
|
|
|
|
|
When in batch mode, tells the debugger to run this one-line lldb command if the target crashes.
|
|
|
|
|
|
.. option:: --one-line <command>
|
|
|
|
|
|
Tells the debugger to execute this one-line lldb command after any file provided on the command line has been loaded.
|
|
|
|
|
|
.. option:: -O <value>
|
|
|
|
|
|
Alias for --one-line-before-file
|
|
|
|
|
|
.. option:: -o <value>
|
|
|
|
|
|
Alias for --one-line
|
|
|
|
|
|
.. option:: -Q
|
|
|
|
|
|
Alias for --source-quietly
|
|
|
|
|
|
.. option:: --source-before-file <file>
|
|
|
|
|
|
Tells the debugger to read in and execute the lldb commands in the given file, before any file has been loaded.
|
|
|
|
|
|
.. option:: --source-on-crash <file>
|
|
|
|
|
|
When in batch mode, tells the debugger to source this file of lldb commands if the target crashes.
|
|
|
|
|
|
.. option:: --source-quietly
|
|
|
|
|
|
Tells the debugger to execute this one-line lldb command before any file has been loaded.
|
|
|
|
|
|
.. option:: --source <file>
|
|
|
|
|
|
Tells the debugger to read in and execute the lldb commands in the given file, after any file has been loaded.
|
|
|
|
|
|
.. option:: -S <value>
|
|
|
|
|
|
Alias for --source-before-file
|
|
|
|
|
|
.. option:: -s <value>
|
|
|
|
|
|
Alias for --source
|
|
|
|
|
|
.. option:: -x
|
|
|
|
|
|
Alias for --no-lldbinit
|
|
|
|
|
|
OPTIONS
|
|
|
-------
|
|
|
|
|
|
.. option:: --arch <architecture>
|
|
|
|
|
|
Tells the debugger to use the specified architecture when starting and running the program.
|
|
|
|
|
|
.. option:: -a <value>
|
|
|
|
|
|
Alias for --arch
|
|
|
|
|
|
.. option:: --capture-path <filename>
|
|
|
|
|
|
Tells the debugger to use the given filename for the reproducer.
|
|
|
|
|
|
.. option:: --capture
|
|
|
|
|
|
Tells the debugger to capture a reproducer.
|
|
|
|
|
|
.. option:: --core <filename>
|
|
|
|
|
|
Tells the debugger to use the full path to <filename> as the core file.
|
|
|
|
|
|
.. option:: -c <value>
|
|
|
|
|
|
Alias for --core
|
|
|
|
|
|
.. option:: --debug
|
|
|
|
|
|
Tells the debugger to print out extra information for debugging itself.
|
|
|
|
|
|
.. option:: -d
|
|
|
|
|
|
Alias for --debug
|
|
|
|
|
|
.. option:: --editor
|
|
|
|
|
|
Tells the debugger to open source files using the host's "external editor" mechanism.
|
|
|
|
|
|
.. option:: -e
|
|
|
|
|
|
Alias for --editor
|
|
|
|
|
|
.. option:: --file <filename>
|
|
|
|
|
|
Tells the debugger to use the file <filename> as the program to be debugged.
|
|
|
|
|
|
.. option:: -f <value>
|
|
|
|
|
|
Alias for --file
|
|
|
|
|
|
.. option:: --help
|
|
|
|
|
|
Prints out the usage information for the LLDB debugger.
|
|
|
|
|
|
.. option:: -h
|
|
|
|
|
|
Alias for --help
|
|
|
|
|
|
.. option:: --no-use-colors
|
|
|
|
|
|
Do not use colors.
|
|
|
|
|
|
.. option:: --replay <filename>
|
|
|
|
|
|
Tells the debugger to replay a reproducer from <filename>.
|
|
|
|
|
|
.. option:: --version
|
|
|
|
|
|
Prints out the current version number of the LLDB debugger.
|
|
|
|
|
|
.. option:: -v
|
|
|
|
|
|
Alias for --version
|
|
|
|
|
|
.. option:: -X
|
|
|
|
|
|
Alias for --no-use-color
|
|
|
|
|
|
REPL
|
|
|
----
|
|
|
|
|
|
.. option:: -r=<flags>
|
|
|
|
|
|
Alias for --repl=<flags>
|
|
|
|
|
|
.. option:: --repl-language <language>
|
|
|
|
|
|
Chooses the language for the REPL.
|
|
|
|
|
|
.. option:: --repl=<flags>
|
|
|
|
|
|
Runs lldb in REPL mode with a stub process with the given flags.
|
|
|
|
|
|
.. option:: -R <value>
|
|
|
|
|
|
Alias for --repl-language
|
|
|
|
|
|
SCRIPTING
|
|
|
---------
|
|
|
|
|
|
.. option:: -l <value>
|
|
|
|
|
|
Alias for --script-language
|
|
|
|
|
|
.. option:: --python-path
|
|
|
|
|
|
Prints out the path to the lldb.py file for this version of lldb.
|
|
|
|
|
|
.. option:: -P
|
|
|
|
|
|
Alias for --python-path
|
|
|
|
|
|
.. option:: --script-language <language>
|
|
|
|
|
|
Tells the debugger to use the specified scripting language for user-defined scripts.
|
|
|
|
|
|
EXAMPLES
|
|
|
--------
|
|
|
|
|
|
The debugger can be started in several modes.
|
|
|
|
|
|
Passing an executable as a positional argument prepares lldb to debug the given
|
|
|
executable. To disambiguate between arguments passed to lldb and arguments
|
|
|
passed to the debugged executable, arguments starting with a - must be passed
|
|
|
after --.
|
|
|
|
|
|
lldb --arch x86_64 /path/to/program program argument -- --arch arvm7
|
|
|
|
|
|
For convenience, passing the executable after -- is also supported.
|
|
|
|
|
|
lldb --arch x86_64 -- /path/to/program program argument --arch arvm7
|
|
|
|
|
|
Passing one of the attach options causes :program:`lldb` to immediately attach
|
|
|
to the given process.
|
|
|
|
|
|
lldb -p <pid>
|
|
|
lldb -n <process-name>
|
|
|
|
|
|
Passing --repl starts :program:`lldb` in REPL mode.
|
|
|
|
|
|
lldb -r
|
|
|
|
|
|
Passing --core causes :program:`lldb` to debug the core file.
|
|
|
|
|
|
lldb -c /path/to/core
|
|
|
|
|
|
Command options can be combined with these modes and cause :program:`lldb` to
|
|
|
run the specified commands before or after events, like loading the file or
|
|
|
crashing, in the order provided on the command line.
|
|
|
|
|
|
lldb -O 'settings set stop-disassembly-count 20' -o 'run' -o 'bt'
|
|
|
lldb -S /source/before/file -s /source/after/file
|
|
|
lldb -K /source/before/crash -k /source/after/crash
|
|
|
|
|
|
Note: In REPL mode no file is loaded, so commands specified to run after
|
|
|
loading the file (via -o or -s) will be ignored.
|
|
|
|
|
|
USING LLDB
|
|
|
----------
|
|
|
|
|
|
In :program:`lldb` there is a help command which can be used to find
|
|
|
descriptions and examples of all :program:`lldb` commands. To get help on
|
|
|
"breakpoint set" you would type "help breakpoint set".
|
|
|
|
|
|
There is also an apropos command which will search the help text of all
|
|
|
commands for a given term ‐‐ this is useful for locating a command by topic.
|
|
|
For instance, "apropos breakpoint" will list any command that has the word
|
|
|
"breakpoint" in its help text.
|
|
|
|
|
|
CONFIGURATION FILES
|
|
|
-------------------
|
|
|
|
|
|
:program:`lldb` reads things like settings, aliases and commands from the
|
|
|
.lldbinit file.
|
|
|
|
|
|
First, :program:`lldb` will try to read the application specific init file
|
|
|
whose name is ~/.lldbinit followed by a "-" and the name of the current
|
|
|
program. This would be ~/.lldbinit-lldb for the command line :program:`lldb`
|
|
|
and ~/.lldbinit-Xcode for Xcode. If there is no application specific init
|
|
|
file, :program:`lldb` will look for an init file in the home directory.
|
|
|
If launched with a `REPL`_ option, it will first look for a REPL configuration
|
|
|
file, specific to the REPL language. The init file should be named as follow:
|
|
|
`.lldbinit-<language>-repl` (i.e. `.lldbinit-swift-repl`). If this file doesn't
|
|
|
exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither
|
|
|
a REPL init file nor an application specific init file, `lldb` will fallback to
|
|
|
the global ~/.lldbinit.
|
|
|
|
|
|
Secondly, it will look for an .lldbinit file in the current working directory.
|
|
|
For security reasons, :program:`lldb` will print a warning and not source this
|
|
|
file by default. This behavior can be changed by changing the
|
|
|
target.load-cwd-lldbinit setting.
|
|
|
|
|
|
To always load the .lldbinit file in the current working directory, add the
|
|
|
following command to ~/.lldbinit:
|
|
|
|
|
|
settings set target.load-cwd-lldbinit true
|
|
|
|
|
|
To never load the .lldbinit file in the current working directory and silence
|
|
|
the warning, add the following command to ~/.lldbinit:
|
|
|
|
|
|
settings set target.load-cwd-lldbinit false
|
|
|
|
|
|
SEE ALSO
|
|
|
--------
|
|
|
|
|
|
The LLDB project page https://lldb.llvm.org has many different resources
|
|
|
for :program:`lldb` users ‐‐ the gdb/lldb command equivalence page
|
|
|
https://lldb.llvm.org/use/map.html can be especially helpful for users
|
|
|
coming from gdb.
|
