lldb/docs/man/lldb-server.rst

   1 :orphan:
   2
   3 lldb-server -- Server for LLDB Debugging Sessions
   4 =================================================
   5
   6 .. program:: lldb-server
   7
   8 SYNOPSIS
   9 --------
  10
  11 | :program:`lldb-server` v[ersion]
  12 | :program:`lldb-server` g[dbserver] [*options*]
  13 | :program:`lldb-server` p[latform] [*options*]
  14
  15 DESCRIPTION
  16 -----------
  17
  18 :program:`lldb-server` provides the server counterpart of the LLVM debugger.
  19 The server runs and monitors the debugged program, while the user interfaces
  20 with it via a client, either running locally or connecting remotely.
  21
  22 All of the code in the LLDB project is available under the Apache 2.0 License
  23 with LLVM exceptions.
  24
  25 COMMANDS
  26 --------
  27
  28 The first argument to lldb-server specifies a command to run.
  29
  30 .. option:: v[ersion]
  31
  32  Prints lldb-server version and exits.
  33
  34 .. option:: g[dbserver]
  35
  36  Runs the server using the gdb-remote protocol. LLDB can afterwards
  37  connect to the server using *gdb-remote* command.
  38
  39 .. option:: p[latform]
  40
  41  Runs the platform server. LLDB can afterwards connect to the server using
  42  *platform select*, followed by *platform connect*.
  43
  44 GDBSERVER COMMAND
  45 -----------------
  46
  47 | :program:`lldb-server` g[dbserver] [*options*] [[*host*]:*port*] [[--] *program* *args*...]
  48
  49 CONNECTION
  50 ~~~~~~~~~~
  51
  52 .. option:: host:port
  53
  54  Specifies the hostname and TCP port to listen on. Obligatory unless another
  55  listening option is used. If host is empty, *localhost* will be used.  If port
  56  is zero, a random port will be selected, and written as specified by --pipe
  57  or --named-pipe options.
  58
  59 .. option:: --fd <fd>
  60
  61  Communicate over the given file descriptor instead of sockets.
  62
  63 .. option:: --named-pipe <name>
  64
  65  Write the listening port number to the specified named pipe.
  66
  67 .. option:: --pipe <fd>
  68
  69  Write the listening port number to the specified pipe (fd).
  70
  71 .. option:: --reverse-connect
  72
  73  Connect to the client instead of passively waiting for a connection. In this
  74  case, [host]:port denotes the remote address to connect to.
  75
  76 GENERAL OPTIONS
  77 ~~~~~~~~~~~~~~~
  78
  79 .. option:: --help
  80
  81  Prints out the usage information and exits.
  82
  83 .. option:: --log-channels <channel1 categories...:channel2 categories...>
  84
  85  Channels to log. A colon-separated list of entries. Each entry starts with
  86  a channel followed by a space-separated list of categories.
  87
  88 .. option:: --log-file <file>
  89
  90  Destination file to log to. If empty, log to stderr.
  91
  92 .. option:: --setsid
  93
  94  Run lldb-server in a new session.
  95
  96 TARGET SELECTION
  97 ~~~~~~~~~~~~~~~~
  98
  99 .. option:: --attach <pid-or-name>
 100
 101  Attach to the process given by a (numeric) process id or a name.
 102
 103 .. option:: -- program args
 104
 105  Launch a program for debugging.
 106
 107 If neither of target options are used, :program:`lldb-server` is started
 108 without a specific target. It can be afterwards instructed by the client
 109 to launch or attach.
 110
 111 PLATFORM COMMAND
 112 ----------------
 113
 114 | :program:`lldb-server` p[latform] [*options*] --server --listen [[*host*]:*port*]
 115
 116 CONNECTION
 117 ~~~~~~~~~~
 118
 119 .. option:: --server
 120
 121  Run in server mode, handling multiple connections. If this is not specified,
 122  lldb-server will accept only one connection and exit when it is finished.
 123
 124 .. option:: --listen <host>:<port>
 125
 126  Hostname and port to listen on. Obligatory. If *port* is zero, a random port
 127  will be used.
 128
 129 .. option:: --socket-file <path>
 130
 131  Write the listening socket port number to the specified file.
 132
 133 GENERAL OPTIONS
 134 ~~~~~~~~~~~~~~~
 135
 136 .. option:: --log-channels <channel1 categories...:channel2 categories...>
 137
 138  Channels to log. A colon-separated list of entries. Each entry starts with
 139  a channel followed by a space-separated list of categories.
 140
 141 .. option:: --log-file <file>
 142
 143  Destination file to log to. If empty, log to stderr.
 144
 145 GDB-SERVER CONNECTIONS
 146 ~~~~~~~~~~~~~~~~~~~~~~
 147
 148 .. option:: --gdbserver-port <port>
 149
 150  Define a port to be used for gdb-server connections. Can be specified multiple
 151  times to allow multiple ports. Has no effect if --min-gdbserver-port
 152  and --max-gdbserver-port are specified.
 153
 154 .. option:: --min-gdbserver-port <port>
 155 .. option:: --max-gdbserver-port <port>
 156
 157  Specify the range of ports that can be used for gdb-server connections. Both
 158  options need to be specified simultaneously. Overrides --gdbserver-port.
 159
 160 .. option:: --port-offset <offset>
 161
 162  Add the specified offset to port numbers returned by server. This is useful
 163  if the server is running behind a firewall, and a range of ports is redirected
 164  to it with an offset.
 165
 166 EXAMPLES
 167 --------
 168
 169 The server can be started in several modes.
 170
 171 In order to launch a new process inside the debugger, pass the path to it
 172 and the arguments to the debugged executable as positional arguments.
 173 To disambiguate between arguments passed to lldb and arguments passed
 174 to the debugged executable, arguments starting with a - must be passed after
 175 --. The server will launch the new executable and stop it immediately, waiting
 176 for the client to connect.
 177
 178   lldb-server g :1234 /path/to/program program-argument -- --program-option
 179
 180 For convenience, passing the executable after -- is also supported.
 181
 182   lldb-server g :1234 -- /path/to/program program-argument --program-option
 183
 184 In order to attach to a running process, pass --attach along with the process
 185 identifier or name. The process will be stopped immediately after starting
 186 the server. Note that terminating the server will usually cause the process
 187 to be detached and continue execution.
 188
 189   lldb-server g :1234 --attach 12345
 190   lldb-server g :1234 --attach program-name
 191
 192 Use *gdb-remote* command to connect to the server:
 193
 194   (lldb) gdb-remote 1234
 195
 196 lldb-server can also be started without an inferior. In this case, the client
 197 can select the target after connecting to the server. Note that some commands
 198 (e.g. *target create*) will disconnect and launch a local lldb-server instead.
 199
 200   lldb-server g :1234
 201
 202   (lldb) gdb-remote 1234
 203   (lldb) process launch a.out
 204
 205 SEE ALSO
 206 --------
 207
 208 The LLDB project page https://lldb.llvm.org has many different resources
 209 for :program:`lldb-server` users.