xref: /freebsd/contrib/llvm-project/lldb/docs/man/lldb.rst (revision 9e5787d2284e187abb5b654d924394a65772e004)
1:orphan:
2
3lldb -- The Debugger
4====================
5
6.. program:: lldb
7
8SYNOPSIS
9--------
10
11| :program:`lldb` [*options*] *executable*
12
13DESCRIPTION
14-----------
15
16:program:`lldb` is a next generation, high-performance debugger. It is built as
17a set of reusable components which highly leverage existing libraries in the
18larger 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
21debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
22
23All of the code in the LLDB project is available under the Apache 2.0 License
24with LLVM exceptions.
25
26ATTACHING
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
53COMMANDS
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 to execute this one-line lldb command before any file has been loaded.
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
132OPTIONS
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
211REPL
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
230SCRIPTING
231---------
232
233.. option:: -l <value>
234
235 Alias for --script-language
236
237.. option:: --python-path
238
239 Prints out the path to the lldb.py file for this version of lldb.
240
241.. option:: -P
242
243 Alias for --python-path
244
245.. option:: --script-language <language>
246
247 Tells the debugger to use the specified scripting language for user-defined scripts.
248
249EXAMPLES
250--------
251
252The debugger can be started in several modes.
253
254Passing an executable as a positional argument prepares lldb to debug the given
255executable. To disambiguate between arguments passed to lldb and arguments
256passed to the debugged executable, arguments starting with a - must be passed
257after --.
258
259  lldb --arch x86_64 /path/to/program program argument -- --arch arvm7
260
261For convenience, passing the executable after -- is also supported.
262
263  lldb --arch x86_64 -- /path/to/program program argument --arch arvm7
264
265Passing one of the attach options causes :program:`lldb` to immediately attach
266to the given process.
267
268  lldb -p <pid>
269  lldb -n <process-name>
270
271Passing --repl starts :program:`lldb` in REPL mode.
272
273  lldb -r
274
275Passing --core causes :program:`lldb` to debug the core file.
276
277  lldb -c /path/to/core
278
279Command options can be combined with these modes and cause :program:`lldb` to
280run the specified commands before or after events, like loading the file or
281crashing, in the order provided on the command line.
282
283  lldb -O 'settings set stop-disassembly-count 20' -o 'run' -o 'bt'
284  lldb -S /source/before/file -s /source/after/file
285  lldb -K /source/before/crash -k /source/after/crash
286
287Note: In REPL mode no file is loaded, so commands specified to run after
288loading the file (via -o or -s) will be ignored.
289
290USING LLDB
291----------
292
293In :program:`lldb` there is a help command which can be used to find
294descriptions and examples of all :program:`lldb` commands.  To get help on
295"breakpoint set" you would type "help breakpoint set".
296
297There is also an apropos command which will search the help text of all
298commands for a given term ‐‐ this is useful for locating a command by topic.
299For instance, "apropos breakpoint" will list any command that has the word
300"breakpoint" in its help text.
301
302CONFIGURATION FILES
303-------------------
304
305:program:`lldb` reads things like settings, aliases and commands from the
306.lldbinit file.
307
308First, it will read the application specific init file whose name is
309~/.lldbinit followed by a "-" and the name of the current program. This would
310be ~/.lldbinit-lldb for the command line :program:`lldb` and ~/.lldbinit-Xcode
311for Xcode. If there is no application specific init file, the global
312~/.lldbinit is read.
313
314Secondly, it will look for an .lldbinit file in the current working directory.
315For security reasons, :program:`lldb` will print a warning and not source this
316file by default. This behavior can be changed by changing the
317target.load-cwd-lldbinit setting.
318
319To always load the .lldbinit file in the current working directory, add the
320following command to ~/.lldbinit:
321
322  settings set target.load-cwd-lldbinit true
323
324To never load the .lldbinit file in the current working directory and silence
325the warning, add the following command to ~/.lldbinit:
326
327  settings set target.load-cwd-lldbinit false
328
329SEE ALSO
330--------
331
332The LLDB project page https://lldb.llvm.org has many different resources
333for :program:`lldb` users ‐‐ the gdb/lldb command equivalence page
334https://lldb.llvm.org/use/map.html can be especially helpful for users
335coming from gdb.
336