The LLDB Debugger

GOALSANDSTATUS
About
Blog
Goals
Features

GDBTOLLDBCOMMANDMAP

Below is a table of GDB commands with the LLDB counterparts. The built in GDB-compatibility
aliases in LLDB are also listed. The full lldb command names are often long, but any unique short
form can be used. Instead of "breakpoint set", "br se" is also acceptable.
EXECUTIONCOMMANDS

Status
GDB

USEANDEXTENSION
Tutorial
GDBandLLDBcommand
examples
FrameandThreadFormatting

LLDB

Launchaprocessnoarguments.
(gdb)run
(gdb)r

(lldb)processlaunch
(lldb)run
(lldb)r

Launchaprocesswitharguments<args>.
(gdb)run<args>
(gdb)r<args>

(lldb)processlaunch<args>
(lldb)r<args>

Symbolication
VariableFormatting
PythonReference
PythonExample

Launchaprocessforwithargumentsa.out 1 2 3withouthavingtosupplytheargseverytime.
%gdbargsa.out123
(gdb)run
...
(gdb)run
...

SymbolsonMacOSX

Or:

Remotedebugging

(gdb)setargs123
(gdb)run
...
(gdb)run
...

Troubleshooting
Architecture

%lldba.out123
(lldb)run
...
(lldb)run
...

(lldb)settingssettarget.runargs123
(lldb)run
...
(lldb)run
...

Launchaprocesswithargumentsinnewterminalwindow(MacOSXonly).

MAILINGLISTS

(lldb)processlaunchtty<args>
(lldb)prolat<args>

lldbdev
lldbcommits

Launchaprocesswithargumentsinexistingterminal/dev/ttys006(MacOSXonly).
(lldb)processlaunchtty=/dev/ttys006<args>
(lldb)prolat/dev/ttys006<args>

RESOURCES
Download
PythonAPIDocumentation
C++APIDocumentation
Source

Setenvironmentvariablesforprocessbeforelaunching.
(gdb)setenvDEBUG1

Unsetenvironmentvariablesforprocessbeforelaunching.
(gdb)unsetenvDEBUG

Build
Test
CodingConventions
SBAPICodingRules
BugReports

(lldb)settingssettarget.envvarsDEBUG=1
(lldb)setsetarget.envvarsDEBUG=1
(lldb)envDEBUG=1

(lldb)settingsremovetarget.envvarsDEBUG
(lldb)setremtarget.envvarsDEBUG

Showtheargumentsthatwillbeorwerepassedtotheprogramwhenrun.
(gdb)showargs
Argumentlisttogiveprogrambeingdebuggedwhen
itisstartedis"123".

(lldb)settingsshowtarget.runargs
target.runargs(arrayofstrings)=
[0]:"1"
[1]:"2"
[2]:"3"

Setenvironmentvariablesforprocessandlaunchprocessinonecommand.

BrowseSVN

(lldb)processlaunchvDEBUG=1

BrowseViewVC
AttachtoaprocesswithprocessID123.
(gdb)attach123

(lldb)processattachpid123
(lldb)attachp123

Attachtoaprocessnamed"a.out".
(gdb)attacha.out

(lldb)processattachnamea.out
(lldb)proatna.out

Waitforaprocessnamed"a.out"tolaunchandattach.
(gdb)attachwaitfora.out

(lldb)processattachnamea.outwaitfor
(lldb)proatna.outw

Attachtoaremotegdbprotocolserverrunningonsystem"eorgadd",port8000.
(gdb)targetremoteeorgadd:8000

(lldb)gdbremoteeorgadd:8000

Attachtoaremotegdbprotocolserverrunningonthelocalsystem,port8000.
(gdb)targetremotelocalhost:8000

(lldb)gdbremote8000

AttachtoaDarwinkernelinkdpmodeonsystem"eorgadd".
(gdb)kdpreattacheorgadd

(lldb)kdpremoteeorgadd

Doasourcelevelsinglestepinthecurrentlyselectedthread.
(gdb)step
(gdb)s

(lldb)threadstepin
(lldb)step
(lldb)s

Doasourcelevelsinglestepoverinthecurrentlyselectedthread.
(gdb)next
(gdb)n

(lldb)threadstepover
(lldb)next
(lldb)n

Doaninstructionlevelsinglestepinthecurrentlyselectedthread.
(gdb)stepi
(gdb)si

(lldb)threadstepinst
(lldb)si

Doaninstructionlevelsinglestepoverinthecurrentlyselectedthread.
(gdb)nexti
(gdb)ni

(lldb)threadstepinstover
(lldb)ni

Stepoutofthecurrentlyselectedframe.
(gdb)finish

(lldb)threadstepout
(lldb)finish

Returnimmediatelyfromthecurrentlyselectedframe,withanoptionalreturnvalue.
(gdb)return<RETURNEXPRESSION>

(lldb)threadreturn<RETURNEXPRESSION>

Backtraceanddisassembleeverytimeyoustop.
(lldb)targetstophookadd
Enteryourstophookcommand(s).Type'DONE'to
end.
>bt
>disassemblepc
>DONE
Stophook#1added.

BREAKPOINTCOMMANDS
GDB

LLDB

Setabreakpointatallfunctionsnamedmain.
(gdb)breakmain

(lldb)breakpointsetnamemain
(lldb)brsnmain
(lldb)bmain

Setabreakpointinfiletest.catline12.
(gdb)breaktest.c:12

(lldb)breakpointsetfiletest.cline12
(lldb)brsftest.cl12
(lldb)btest.c:12

SetabreakpointatallC++methodswhosebasenameismain.
(gdb)breakmain
(HopethattherearenoCfunctionsnamedmain).

(lldb)breakpointsetmethodmain
(lldb)brsMmain

SetabreakpointatandobjectCfunction:[NSStringstringWithFormat:].
(gdb)break[NSStringstringWithFormat:]

(lldb)breakpointsetname"[NSString
stringWithFormat:]"
(lldb)b[NSStringstringWithFormat:]

SetabreakpointatallObjectiveCmethodswhoseselectoriscount.
(gdb)breakcount
(HopethattherearenoCorC++functionsnamed
count).

(lldb)breakpointsetselectorcount
(lldb)brsScount

Setabreakpointbyregularexpressiononfunctionname.
(gdb)rbreakregularexpression

(lldb)breakpointsetfuncregexregularexpression
(lldb)brsrregularexpression

Ensurethatbreakpointsbyfileandlineworkfor#included.c/.cpp/.mfiles.
(gdb)bfoo.c:12

(lldb)settingssettarget.inlinebreakpointstrategy
always
(lldb)brsffoo.cl12

Setabreakpointbyregularexpressiononsourcefilecontents.
(gdb)shellgrepenpatternsourcefile
(gdb)breaksourcefile:CopyLineNumbers

(lldb)breakpointsetsourcepatternregular
expressionfileSourceFile
(lldb)brspregularexpressionffile

Setaconditionalbreakpoint
(gdb)breakfooifstrcmp(y,"hello")==0

(lldb)breakpointsetnamefoocondition
'(int)strcmp(y,"hello")==0'
(lldb)brsnfooc'(int)strcmp(y,"hello")==0'

Listallbreakpoints.
(gdb)infobreak

(lldb)breakpointlist
(lldb)brl

Deleteabreakpoint.
(gdb)delete1

(lldb)breakpointdelete1
(lldb)brdel1

WATCHPOINTCOMMANDS
GDB

LLDB

Setawatchpointonavariablewhenitiswrittento.
(gdb)watchglobal_var

(lldb)watchpointsetvariableglobal_var
(lldb)wasvglobal_var

Setawatchpointonamemorylocationwhenitiswritteninto.Thesizeoftheregiontowatchfordefaultsto
thepointersizeifno'xbyte_size'isspecified.Thiscommandtakesrawinput,evaluatedasanexpression
returninganunsignedintegerpointingtothestartoftheregion,afterthe''optionterminator.
(gdb)watchlocationg_char_ptr

(lldb)watchpointsetexpressionmy_ptr
(lldb)wasemy_ptr

Setaconditiononawatchpoint.
(lldb)watchsetvarglobal
(lldb)watchpointmodifyc'(global==5)'
(lldb)c
...
(lldb)bt
*thread#1:tid=0x1c03,0x0000000100000ef5
a.out`modify+21atmain.cpp:16,stopreason=
watchpoint1
frame#0:0x0000000100000ef5a.out`modify+21
atmain.cpp:16
frame#1:0x0000000100000eaca.out`main+108
atmain.cpp:25
frame#2:0x00007fff8ac9c7e1libdyld.dylib`start+
1
(lldb)framevarglobal
(int32_t)global=5
Listallwatchpoints.
(gdb)infobreak

(lldb)watchpointlist
(lldb)watchl

Deleteawatchpoint.
(gdb)delete1

(lldb)watchpointdelete1
(lldb)watchdel1

EXAMININGVARIABLES
GDB

LLDB

Showtheargumentsandlocalvariablesforthecurrentframe.
(gdb)infoargs
and
(gdb)infolocals

(lldb)framevariable
(lldb)frv

Showthelocalvariablesforthecurrentframe.
(gdb)infolocals

(lldb)framevariablenoargs
(lldb)frva

Showthecontentsoflocalvariable"bar".
(gdb)pbar

(lldb)framevariablebar

(lldb)frvbar
(lldb)pbar
Showthecontentsoflocalvariable"bar"formattedashex.
(gdb)p/xbar

(lldb)framevariableformatxbar
(lldb)frvfxbar

Showthecontentsofglobalvariable"baz".
(gdb)pbaz

(lldb)targetvariablebaz
(lldb)tavbaz

Showtheglobal/staticvariablesdefinedinthecurrentsourcefile.
n/a

(lldb)targetvariable
(lldb)tav

Displaythevariables"argc"and"argv"everytimeyoustop.
(gdb)displayargc
(gdb)displayargv

(lldb)targetstophookaddoneliner"frame
variableargcargv"
(lldb)tastao"frvargcargv"
(lldb)displayargc
(lldb)displayargv

Displaythevariables"argc"and"argv"onlywhenyoustopinthefunctionnamedmain.
(lldb)targetstophookaddnamemainoneliner
"framevariableargcargv"
(lldb)tastanmaino"frvargcargv"
Displaythevariable"*this"onlywhenyoustopincclassnamedMyClass.
(lldb)targetstophookaddclassnameMyClass
oneliner"framevariable*this"
(lldb)tastacMyClasso"frv*this"

EVALUATINGEXPRESSIONS
GDB

LLDB

Evaluatingageneralizedexpressioninthecurrentframe.
(gdb)print(int)printf("Printnine:%d.",4+5)
orifyoudon'twanttoseevoidreturns:
(gdb)call(int)printf("Printnine:%d.",4+5)

(lldb)expr(int)printf("Printnine:%d.",4+5)
orusingtheprintalias:
(lldb)print(int)printf("Printnine:%d.",4+5)

Creatingandassigningavaluetoaconveniencevariable.
(gdb)set$foo=5
(gdb)setvariable$foo=5
orusingtheprintcommand
(gdb)print$foo=5
orusingthecallcommand
(gdb)call$foo=5
andifyouwanttospecifythetypeofthevariable:
(gdb)set$foo=(unsignedint)5

Inlldbyouevaluateavariabledeclarationexpression
asyouwouldwriteitinC:
(lldb)exprunsignedint$foo=5

PrintingtheObjC"description"ofanobject.
(gdb)po[SomeClassreturnAnObject]

(lldb)expro[SomeClassreturnAnObject]
orusingthepoalias:
(lldb)po[SomeClassreturnAnObject]

Printthedynamictypeoftheresultofanexpression.
(gdb)setprintobject1
(gdb)psomeCPPObjectPtrOrReference
onlyworksforC++objects.

(lldb)exprd1[SomeClassreturnAnObject]
(lldb)exprd1someCPPObjectPtrOrReference
orsetdynamictypeprintingtobethedefault:(lldb)
settingssettarget.preferdynamicruntarget

Callingafunctionsoyoucanstopatabreakpointinthefunction.
(gdb)setunwindonsignal0
(gdb)pfunction_with_a_breakpoint()

(lldb)expri0function_with_a_breakpoint()

Callingafunctionthatcrashes,andstoppingwhenthefunctioncrashes.
(gdb)setunwindonsignal0
(gdb)pfunction_which_crashes()

(lldb)expru0function_which_crashes()

EXAMININGTHREADSTATE
GDB

LLDB

Showthestackbacktraceforthecurrentthread.
(gdb)bt

(lldb)threadbacktrace
(lldb)bt

Showthestackbacktracesforallthreads.
(gdb)threadapplyallbt

(lldb)threadbacktraceall

(lldb)btall
Backtracethefirstfiveframesofthecurrentthread.
(gdb)bt5

(lldb)threadbacktracec5
(lldb)bt5(lldb169andlater)
(lldb)btc5(lldb168andearlier)

Selectadifferentstackframebyindexforthecurrentthread.
(gdb)frame12

(lldb)frameselect12
(lldb)frs12
(lldb)f12

Listinformationaboutthecurrentlyselectedframeinthecurrentthread.
(lldb)frameinfo

Selectthestackframethatcalledthecurrentstackframe.
(gdb)up

(lldb)up
(lldb)frameselectrelative=1

Selectthestackframethatiscalledbythecurrentstackframe.
(gdb)down

(lldb)down
(lldb)frameselectrelative=1
(lldb)frsr1

Selectadifferentstackframeusingarelativeoffset.
(gdb)up2
(gdb)down3

(lldb)frameselectrelative2
(lldb)frsr2
(lldb)frameselectrelative3
(lldb)frsr3

Showthegeneralpurposeregistersforthecurrentthread.
(gdb)inforegisters

(lldb)registerread

Writeanewdecimalvalue'123'tothecurrentthreadregister'rax'.
(gdb)p$rax=123

(lldb)registerwriterax123

Skip8bytesaheadofthecurrentprogramcounter(instructionpointer).Notethatweusebackticksto
evaluateanexpressionandinsertthescalarresultinLLDB.
(gdb)jump*$pc+8

(lldb)registerwritepc`$pc+8`

Showthegeneralpurposeregistersforthecurrentthreadformattedassigneddecimal.LLDBtriestouse
thesameformatcharactersasprintf(3)whenpossible.Type"helpformat"toseethefulllistofformat
specifiers.
(lldb)registerreadformati
(lldb)rerfi
LLDBnowsupportstheGDBshorthandformatsyntax
buttherecan'tbespaceafterthecommand:
(lldb)registerread/d
Showallregistersinallregistersetsforthecurrentthread.
(gdb)infoallregisters

(lldb)registerreadall
(lldb)rera

Showthevaluesfortheregistersnamed"rax","rsp"and"rbp"inthecurrentthread.
(gdb)infoallregistersraxrsprbp

(lldb)registerreadraxrsprbp

Showthevaluesfortheregisternamed"rax"inthecurrentthreadformattedasbinary.
(gdb)p/t$rax

(lldb)registerreadformatbinaryrax
(lldb)rerfbrax
LLDBnowsupportstheGDBshorthandformatsyntax
buttherecan'tbespaceafterthecommand:
(lldb)registerread/trax
(lldb)p/t$rax

Readmemoryfromaddress0xbffff3c0andshow4hexuint32_tvalues.
(gdb)x/4xw0xbffff3c0

(lldb)memoryreadsize4formatxcount4
0xbffff3c0
(lldb)mers4fxc40xbffff3c0
(lldb)xs4fxc40xbffff3c0
LLDBnowsupportstheGDBshorthandformatsyntax
buttherecan'tbespaceafterthecommand:
(lldb)memoryread/4xw0xbffff3c0
(lldb)x/4xw0xbffff3c0
(lldb)memoryreadgdbformat4xw0xbffff3c0

Readmemorystartingattheexpression"argv[0]".
(gdb)xargv[0]

(lldb)memoryread`argv[0]`
NOTE:anycommandcaninlineascalarexpression
result(aslongasthetargetisstopped)using
backticksaroundanyexpression:
(lldb)memoryreadsize`sizeof(int)``argv[0]`

Read512bytesofmemoryfromaddress0xbffff3c0andsaveresultstoalocalfileastext.
(gdb)setloggingon
(gdb)setloggingfile/tmp/mem.txt
(gdb)x/512bx0xbffff3c0
(gdb)setloggingoff

(lldb)memoryreadoutfile/tmp/mem.txtcount
5120xbffff3c0
(lldb)mero/tmp/mem.txtc5120xbffff3c0
(lldb)x/512bxo/tmp/mem.txt0xbffff3c0

Savebinarymemorydatastartingat0x1000andendingat0x2000toafile.
(gdb)dumpmemory/tmp/mem.bin0x10000x2000

(lldb)memoryreadoutfile/tmp/mem.binbinary
0x10000x2000
(lldb)mero/tmp/mem.binb0x10000x2000

Getinformationaboutaspecificheapallocation(availableonMacOSXonly).
(gdb)infomalloc0x10010d680

(lldb)commandscriptimportlldb.macosx.heap
(lldb)processlaunchenvironment
MallocStackLogging=1[ARGS]
(lldb)malloc_infostackhistory0x10010d680

Getinformationaboutaspecificheapallocationandcasttheresulttoanydynamictypethatcanbededuced
(availableonMacOSXonly)
(lldb)commandscriptimportlldb.macosx.heap
(lldb)malloc_infotype0x10010d680
FindallheapblocksthatcontainapointerspecifiedbyanexpressionEXPR(availableonMacOSXonly).
(lldb)commandscriptimportlldb.macosx.heap
(lldb)ptr_refsEXPR
FindallheapblocksthatcontainaCstringanywhereintheblock(availableonMacOSXonly).
(lldb)commandscriptimportlldb.macosx.heap
(lldb)cstr_refsCSTRING
Disassemblethecurrentfunctionforthecurrentframe.
(gdb)disassemble

(lldb)disassembleframe
(lldb)dif

Disassembleanyfunctionsnamedmain.
(gdb)disassemblemain

(lldb)disassemblenamemain
(lldb)dinmain

Disassembleanaddressrange.
(gdb)disassemble0x1eb80x1ec3

(lldb)disassemblestartaddress0x1eb8end
address0x1ec3
(lldb)dis0x1eb8e0x1ec3

Disassemble20instructionsfromagivenaddress.
(gdb)x/20i0x1eb8

(lldb)disassemblestartaddress0x1eb8count
20
(lldb)dis0x1eb8c20

Showmixedsourceanddisassemblyforthecurrentfunctionforthecurrentframe.
n/a

(lldb)disassembleframemixed
(lldb)difm

Disassemblethecurrentfunctionforthecurrentframeandshowtheopcodebytes.
n/a

(lldb)disassembleframebytes
(lldb)difb

Disassemblethecurrentsourcelineforthecurrentframe.
n/a

(lldb)disassembleline
(lldb)dil

EXECUTABLEANDSHAREDLIBRARYQUERYCOMMANDS
GDB

LLDB

Listthemainexecutableandalldependentsharedlibraries.
(gdb)infoshared

(lldb)imagelist

Lookupinformationforarawaddressintheexecutableoranysharedlibraries.
(gdb)infosymbol0x1ec4

(lldb)imagelookupaddress0x1ec4
(lldb)imlooa0x1ec4

Lookupfunctionsmatchingaregularexpressioninabinary.
(gdb)infofunction<FUNC_REGEX>

Thisonefindsdebugsymbols:
(lldb)imagelookuprn<FUNC_REGEX>
Thisonefindsnondebugsymbols:
(lldb)imagelookuprs<FUNC_REGEX>
Providealistofbinariesasargumentstolimitthe
search.

Findfullsourcelineinformation.
(gdb)infoline0x1ec4

Thisoneisabitmessyatpresent.Do:
(lldb)imagelookupvaddress0x1ec4
andlookfortheLineEntryline,whichwillhavethe
fullsourcepathandlinerangeinformation.

Lookupinformationforanaddressina.outonly.
(lldb)imagelookupaddress0x1ec4a.out
(lldb)imlooa0x1ec4a.out
LookupinformationforforatypePointbyname.
(gdb)ptypePoint

(lldb)imagelookuptypePoint
(lldb)imlootPoint

Dumpallsectionsfromthemainexecutableandanysharedlibraries.
(gdb)maintenanceinfosections

(lldb)imagedumpsections

Dumpallsectionsinthea.outmodule.
(lldb)imagedumpsectionsa.out

Dumpallsymbolsfromthemainexecutableandanysharedlibraries.
(lldb)imagedumpsymtab

Dumpallsymbolsina.outandliba.so.
(lldb)imagedumpsymtaba.outliba.so

MISCELLANEOUS
GDB

LLDB

Echotexttothescreen.
(gdb)echoHereissometext\n

(lldb)scriptprint"Hereissometext"

Remapsourcefilepathnamesforthedebugsession.Ifyoursourcefilesarenolongerlocatedinthesame
locationaswhentheprogramwasbuiltmaybetheprogramwasbuiltonadifferentcomputeryou
needtotellthedebuggerhowtofindthesourcesattheirlocalfilepathinsteadofthebuildsystem'sfile
path.
(gdb)setpathnamesubstitutions/buildbot/path
/my/path

(lldb)settingssettarget.sourcemap/buildbot/path
/my/path

Supplyacatchalldirectorytosearchforsourcefilesin.
(gdb)directory/my/path

(Noequivalentcommandusethesourcemap
instead.)