xref: /freebsd-10-stable/contrib/llvm/tools/lldb/docs/lldb.1

.Dd 7 June, 2012     \" DATE
.Dt LLDB 1           \" Program name and manual section number
.Os Darwin           \" Operating System
.Sh NAME             \" Section Header - required - don't modify 
.Nm lldb
.Nd The debugger
.Sh SYNOPSIS         \" Section Header - required - don't modify
.Nm lldb
.Op Fl hvdexw
.Op Fl a Ar arch
.Op Fl l Ar script-language
.Op Fl s Ar lldb-commands
.Op Fl n Ar process-name
.Op Fl p Ar pid
.Ar [[--] <PROGRAM-ARG1> <PROGRAM-ARG2> ...]
.Sh DESCRIPTION      \" Section Header - required - don't modify
.Nm
is the command line interface for the LLDB debugger library. 
.Nm
can debug C, C++, Objective-C, and Objective-C++ programs.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl h, -help 
Prints out the usage information for the 
.Nm
debugger.  The \fB\-\-help\fR text may be more up-to-date and
authoritative than the command line options described in this man
page.
.It Fl v, -version 
Prints out the version number of the 
.Nm 
debugger.
.It Fl a, -arch Ar arch
Specifies which architecture 
.Nm
will use when launching the specified program (assuming the provided
executable is built for multiple architectures.)
.It Fl f, -file Ar filename
Specifies the executable file that
.nm
will be launching / attaching to.
.It Fl n, -attach-name Ar process-name
Specifies the name of a currently-running process to attach to.
(or the name of a process to wait for if \fB\-w\fR is used.)
.It Fl w, -wait-for
When used in concert with \&\fB\-n process-name\-E\fR, indicates that
.Nm
should wait for a new process of that name to be started -- and attach
to it as early in the process-launch as possible.
.It Fl p, -attach-pid Ar pid
Specifies a currently running process that
.Nm
should attach to.
.It Fl l, -script-language Ar language
Tells the debugger to use the specified scripting language for
user-defined scripts, rather than the default.  Valid scripting
languages that can be specified include Python, Perl, Ruby and Tcl.
Currently only the Python extensions have been implemented.
.It Fl d, -debug
Tells the debugger to print out extra information for debugging itself.
.It Fl s, -source Ar filename
Tells 
.Nm
to read in and execute the file "\fBfilename\fR", which
should contain 
.Nm
commands.
.It Fl e, -editor
Instructs
.Nm
to open source files using the host's "external editor" mechanism.
.It Fl x, -no-lldbinit
Do not automatically parse any '.lldbinit' files.
.Pp
(If you don't provide -f then the first argument will be the file to be debugged
so 'lldb -- <filename> [<ARG1> [<ARG2>]]' also works.
Remember to end the options with "--" if any of your arguments have a "-" in them.)
.El
.Sh USING LLDB
In
.Nm
there is a \fBhelp\fR command which can be used to find descriptions and examples of
all 
.Nm
commands.  To get help on "\fBbreakpoint set\fR" you would type "\fBhelp breakpoint set\fR".
.Pp
There is also an \fBapropos\fR 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, "\fBapropos breakpoint\fR"
will list any command that has the word \fBbreakpoint\fR in its help text.
.Sh FILES
.Nm
will read settings/aliases/commands from three files at startup, if they exist.
.Pp
First, it will read a \fB~/.lldbinit-\fIdebugger\fR command file.  If you are using the
.Nm
command line interface, this is \fB~/.lldbinit-lldb\fR.  If you are using 
.Nm
inside a GUI debugger like
.Nm Xcode
this will be \fB~/.lldbinit-Xcode\fR.  This is a useful place to put settings that you
want to apply only when a given 
.Nm
command interpreter is used.
.Pp
Second, \fB~/.lldbinit\fR is read.
.Pp
Third, an \fR.lldbinit\fR file in the current working directory (where 
.Nm
is started) will be read.
.Sh SEE ALSO
The LLDB project page http://lldb.llvm.org/ has many different resources for
.Nm
users -- the gdb/lldb command equivalence page http://lldb.llvm.org/lldb-gdb.html can
be especially helpful for users coming from gdb.
.Sh BUGS
To report bugs, please visit http://llvm.org/bugs/
.Sh AUTHOR
Maintained by the LLDB Team, http://lldb.llvm.org/