1:orphan:
2
3lldb-server -- Server for LLDB Debugging Sessions
4=================================================
5
6.. program:: lldb-server
7
8SYNOPSIS
9--------
10
11| :program:`lldb-server` v[ersion]
12| :program:`lldb-server` g[dbserver] [*options*]
13| :program:`lldb-server` p[latform] [*options*]
14
15DESCRIPTION
16-----------
17
18:program:`lldb-server` provides the server counterpart of the LLVM debugger.
19The server runs and monitors the debugged program, while the user interfaces
20with it via a client, either running locally or connecting remotely.
21
22All of the code in the LLDB project is available under the Apache 2.0 License
23with LLVM exceptions.
24
25COMMANDS
26--------
27
28The 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
44GDBSERVER COMMAND
45-----------------
46
47| :program:`lldb-server` g[dbserver] [*options*] [[*host*]:*port*] [[--] *program* *args*...]
48
49CONNECTION
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
76GENERAL 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
96TARGET 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
107If neither of target options are used, :program:`lldb-server` is started
108without a specific target. It can be afterwards instructed by the client
109to launch or attach.
110
111PLATFORM COMMAND
112----------------
113
114| :program:`lldb-server` p[latform] [*options*] --server --listen [[*host*]:*port*]
115
116CONNECTION
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
133GENERAL 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
145GDB-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
166EXAMPLES
167--------
168
169The server can be started in several modes.
170
171In order to launch a new process inside the debugger, pass the path to it
172and the arguments to the debugged executable as positional arguments.
173To disambiguate between arguments passed to lldb and arguments passed
174to the debugged executable, arguments starting with a - must be passed after
175--. The server will launch the new executable and stop it immediately, waiting
176for the client to connect.
177
178  lldb-server g :1234 /path/to/program program-argument -- --program-option
179
180For convenience, passing the executable after -- is also supported.
181
182  lldb-server g :1234 -- /path/to/program program-argument --program-option
183
184In order to attach to a running process, pass --attach along with the process
185identifier or name. The process will be stopped immediately after starting
186the server. Note that terminating the server will usually cause the process
187to be detached and continue execution.
188
189  lldb-server g :1234 --attach 12345
190  lldb-server g :1234 --attach program-name
191
192Use *gdb-remote* command to connect to the server:
193
194  (lldb) gdb-remote 1234
195
196lldb-server can also be started without an inferior. In this case, the client
197can 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
205SEE ALSO
206--------
207
208The LLDB project page https://lldb.llvm.org has many different resources
209for :program:`lldb-server` users.
210