diff options
Diffstat (limited to 'contrib/llvm-project/lldb/docs/man')
| -rw-r--r-- | contrib/llvm-project/lldb/docs/man/lldb-server.rst | 209 | ||||
| -rw-r--r-- | contrib/llvm-project/lldb/docs/man/lldb.rst | 345 |
2 files changed, 554 insertions, 0 deletions
diff --git a/contrib/llvm-project/lldb/docs/man/lldb-server.rst b/contrib/llvm-project/lldb/docs/man/lldb-server.rst new file mode 100644 index 000000000000..a67c00b305f6 --- /dev/null +++ b/contrib/llvm-project/lldb/docs/man/lldb-server.rst @@ -0,0 +1,209 @@ +:orphan: + +lldb-server -- Server for LLDB Debugging Sessions +================================================= + +.. program:: lldb-server + +SYNOPSIS +-------- + +| :program:`lldb-server` v[ersion] +| :program:`lldb-server` g[dbserver] [*options*] +| :program:`lldb-server` p[latform] [*options*] + +DESCRIPTION +----------- + +:program:`lldb-server` provides the server counterpart of the LLVM debugger. +The server runs and monitors the debugged program, while the user interfaces +with it via a client, either running locally or connecting remotely. + +All of the code in the LLDB project is available under the Apache 2.0 License +with LLVM exceptions. + +COMMANDS +-------- + +The first argument to lldb-server specifies a command to run. + +.. option:: v[ersion] + + Prints lldb-server version and exits. + +.. option:: g[dbserver] + + Runs the server using the gdb-remote protocol. LLDB can afterwards + connect to the server using *gdb-remote* command. + +.. option:: p[latform] + + Runs the platform server. LLDB can afterwards connect to the server using + *platform select*, followed by *platform connect*. + +GDBSERVER COMMAND +----------------- + +| :program:`lldb-server` g[dbserver] [*options*] [[*host*]:*port*] [[--] *program* *args*...] + +CONNECTION +~~~~~~~~~~ + +.. option:: host:port + + Specifies the hostname and TCP port to listen on. Obligatory unless another + listening option is used. If host is empty, *localhost* will be used. If port + is zero, a random port will be selected, and written as specified by --pipe + or --named-pipe options. + +.. option:: --fd <fd> + + Communicate over the given file descriptor instead of sockets. + +.. option:: --named-pipe <name> + + Write the listening port number to the specified named pipe. + +.. option:: --pipe <fd> + + Write the listening port number to the specified pipe (fd). + +.. option:: --reverse-connect + + Connect to the client instead of passively waiting for a connection. In this + case, [host]:port denotes the remote address to connect to. + +GENERAL OPTIONS +~~~~~~~~~~~~~~~ + +.. option:: --help + + Prints out the usage information and exits. + +.. option:: --log-channels <channel1 categories...:channel2 categories...> + + Channels to log. A colon-separated list of entries. Each entry starts with + a channel followed by a space-separated list of categories. + +.. option:: --log-file <file> + + Destination file to log to. If empty, log to stderr. + +.. option:: --setsid + + Run lldb-server in a new session. + +TARGET SELECTION +~~~~~~~~~~~~~~~~ + +.. option:: --attach <pid-or-name> + + Attach to the process given by a (numeric) process id or a name. + +.. option:: -- program args + + Launch a program for debugging. + +If neither of target options are used, :program:`lldb-server` is started +without a specific target. It can be afterwards instructed by the client +to launch or attach. + +PLATFORM COMMAND +---------------- + +| :program:`lldb-server` p[latform] [*options*] --server --listen [[*host*]:*port*] + +CONNECTION +~~~~~~~~~~ + +.. option:: --server + + Run in server mode, handling multiple connections. If this is not specified, + lldb-server will accept only one connection and exit when it is finished. + +.. option:: --listen <host>:<port> + + Hostname and port to listen on. Obligatory. If *port* is zero, a random port + will be used. + +.. option:: --socket-file <path> + + Write the listening socket port number to the specified file. + +GENERAL OPTIONS +~~~~~~~~~~~~~~~ + +.. option:: --log-channels <channel1 categories...:channel2 categories...> + + Channels to log. A colon-separated list of entries. Each entry starts with + a channel followed by a space-separated list of categories. + +.. option:: --log-file <file> + + Destination file to log to. If empty, log to stderr. + +GDB-SERVER CONNECTIONS +~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: --gdbserver-port <port> + + Define a port to be used for gdb-server connections. Can be specified multiple + times to allow multiple ports. Has no effect if --min-gdbserver-port + and --max-gdbserver-port are specified. + +.. option:: --min-gdbserver-port <port> +.. option:: --max-gdbserver-port <port> + + Specify the range of ports that can be used for gdb-server connections. Both + options need to be specified simultaneously. Overrides --gdbserver-port. + +.. option:: --port-offset <offset> + + Add the specified offset to port numbers returned by server. This is useful + if the server is running behind a firewall, and a range of ports is redirected + to it with an offset. + +EXAMPLES +-------- + +The server can be started in several modes. + +In order to launch a new process inside the debugger, pass the path to it +and the arguments to the debugged executable as positional arguments. +To disambiguate between arguments passed to lldb and arguments passed +to the debugged executable, arguments starting with a - must be passed after +--. The server will launch the new executable and stop it immediately, waiting +for the client to connect. + + lldb-server g :1234 /path/to/program program-argument -- --program-option + +For convenience, passing the executable after -- is also supported. + + lldb-server g :1234 -- /path/to/program program-argument --program-option + +In order to attach to a running process, pass --attach along with the process +identifier or name. The process will be stopped immediately after starting +the server. Note that terminating the server will usually cause the process +to be detached and continue execution. + + lldb-server g :1234 --attach 12345 + lldb-server g :1234 --attach program-name + +Use *gdb-remote* command to connect to the server: + + (lldb) gdb-remote 1234 + +lldb-server can also be started without an inferior. In this case, the client +can select the target after connecting to the server. Note that some commands +(e.g. *target create*) will disconnect and launch a local lldb-server instead. + + lldb-server g :1234 + + (lldb) gdb-remote 1234 + (lldb) process launch a.out + +SEE ALSO +-------- + +The LLDB project page https://lldb.llvm.org has many different resources +for :program:`lldb-server` users. diff --git a/contrib/llvm-project/lldb/docs/man/lldb.rst b/contrib/llvm-project/lldb/docs/man/lldb.rst new file mode 100644 index 000000000000..10b143cd0de8 --- /dev/null +++ b/contrib/llvm-project/lldb/docs/man/lldb.rst @@ -0,0 +1,345 @@ +: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 not to echo commands while sourcing files or one-line commands provided on the command line. + +.. 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:: --print-script-interpreter-info + + Prints out a json dictionary with information about the scripting language interpreter. + +.. 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 armv7 + +For convenience, passing the executable after -- is also supported. + + lldb --arch x86_64 -- /path/to/program program argument --arch armv7 + +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. |