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 not to echo commands while sourcing files or one-line commands provided on the command line.
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:: --print-script-interpreter-info
238
239  Prints out a json dictionary with information about the scripting language interpreter.
240
241.. option:: --python-path
242
243 Prints out the path to the lldb.py file for this version of lldb.
244
245.. option:: -P
246
247 Alias for --python-path
248
249.. option:: --script-language <language>
250
251 Tells the debugger to use the specified scripting language for user-defined scripts.
252
253EXAMPLES
254--------
255
256The debugger can be started in several modes.
257
258Passing an executable as a positional argument prepares lldb to debug the given
259executable. To disambiguate between arguments passed to lldb and arguments
260passed to the debugged executable, arguments starting with a - must be passed
261after --.
262
263  lldb --arch x86_64 /path/to/program program argument -- --arch armv7
264
265For convenience, passing the executable after -- is also supported.
266
267  lldb --arch x86_64 -- /path/to/program program argument --arch armv7
268
269Passing one of the attach options causes :program:`lldb` to immediately attach
270to the given process.
271
272  lldb -p <pid>
273  lldb -n <process-name>
274
275Passing --repl starts :program:`lldb` in REPL mode.
276
277  lldb -r
278
279Passing --core causes :program:`lldb` to debug the core file.
280
281  lldb -c /path/to/core
282
283Command options can be combined with these modes and cause :program:`lldb` to
284run the specified commands before or after events, like loading the file or
285crashing, in the order provided on the command line.
286
287  lldb -O 'settings set stop-disassembly-count 20' -o 'run' -o 'bt'
288  lldb -S /source/before/file -s /source/after/file
289  lldb -K /source/before/crash -k /source/after/crash
290
291Note: In REPL mode no file is loaded, so commands specified to run after
292loading the file (via -o or -s) will be ignored.
293
294USING LLDB
295----------
296
297In :program:`lldb` there is a help command which can be used to find
298descriptions and examples of all :program:`lldb` commands.  To get help on
299"breakpoint set" you would type "help breakpoint set".
300
301There is also an apropos command which will search the help text of all
302commands for a given term ‐‐ this is useful for locating a command by topic.
303For instance, "apropos breakpoint" will list any command that has the word
304"breakpoint" in its help text.
305
306CONFIGURATION FILES
307-------------------
308
309:program:`lldb` reads things like settings, aliases and commands from the
310.lldbinit file.
311
312First, :program:`lldb` will try to read the application specific init file
313whose name is ~/.lldbinit followed by a "-" and the name of the current
314program. This would be ~/.lldbinit-lldb for the command line :program:`lldb`
315and ~/.lldbinit-Xcode for Xcode. If there is no application specific init
316file, :program:`lldb` will look for an init file in the home directory.
317If launched with a `REPL`_ option, it will first look for a REPL configuration
318file, specific to the REPL language. The init file should be named as follow:
319``.lldbinit-<language>-repl`` (i.e. ``.lldbinit-swift-repl``). If this file doesn't
320exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither
321a REPL init file nor an application specific init file, ``lldb`` will fallback to
322the global ~/.lldbinit.
323
324Secondly, it will look for an .lldbinit file in the current working directory.
325For security reasons, :program:`lldb` will print a warning and not source this
326file by default. This behavior can be changed by changing the
327target.load-cwd-lldbinit setting.
328
329To always load the .lldbinit file in the current working directory, add the
330following command to ~/.lldbinit:
331
332  settings set target.load-cwd-lldbinit true
333
334To never load the .lldbinit file in the current working directory and silence
335the warning, add the following command to ~/.lldbinit:
336
337  settings set target.load-cwd-lldbinit false
338
339SEE ALSO
340--------
341
342The LLDB project page https://lldb.llvm.org has many different resources
343for :program:`lldb` users ‐‐ the gdb/lldb command equivalence page
344https://lldb.llvm.org/use/map.html can be especially helpful for users
345coming from gdb.
346