22. Script Bridging Classes & Hierarchy
Written by Walter Tyree

You’ve learned the essentials of working with LLDB’s Python module, as well as how to correct any errors using Python’s pdb debugging module.

Now you’ll explore the main players within the lldb Python module for a good overview of the essential classes.

You’ll be building a more complex LLDB Python script as you learn about these classes. You’ll create a regex breakpoint that only stops after the scope in which the breakpoint hit has finished executing. This is useful when exploring initialization and accessor-type methods, and you want to examine the object that’s being returned after the function executes.

In this chapter, you’ll learn how to create the functionality behind this script while learning about the major classes within the LLDB module. You’ll continue on with this script in the next chapter by exploring how to add optional arguments to tweak the script based on your debugging needs.

The Essential Classes

Within the lldb module, there are several important classes:

lldb.SBDebugger: The “bottleneck” class you’ll use to access instances of other classes inside your custom debugging script.

There will always be one reference to an instance of this class passed in as the debugger function parameter to your script. This class is responsible for handling input commands into LLDB, and can control where and how it displays the output.

lldb.SBTarget: Responsible for the executable being debugged in memory, the debug files, and the physical file for the executable resident on disk.

In a typical debugging session, you’ll use the instance of SBDebugger to get the selected SBTarget. From there, you’ll be able to access the majority of other classes through SBTarget.

lldb.SBProcess: Handles memory access (reading/writing) as well as the multiple threads within the process.

lldb.SBThread: Manages the stack frames (SBFrames) within that particular thread, and also manages control logic for stepping.

lldb.SBFrame: Manages local variables (given through debugging information) as well as any registers frozen at that particular frame.

lldb.SBModule: Represents a particular executable. You’ve learned about modules when exploring dynamic libraries; a module can include the main executable or any dynamically loaded code (like the Foundation framework).

You can obtain a complete list of the modules loaded into your executable using the image list command.

lldb.SBFunction: This represents a generic function — the code — that is loaded into memory. This class has a one-to-one relationship with the SBFrame class.

Got it? No? Don’t worry about it! Once you see how these classes interact with each other, you’ll have a better understanding of their place inside your program.

This diagram is a simplified version of how the major LLDB Python classes interact with each other.

If there’s no direct path from one class to another, you can still get to a class by accessing other variables, not shown in the diagram, that point to an instance (or all instances) of a class (many of which are not shown in the diagram).

That being said, the entry-point into the majority of these objects will be through an instance of SBDebugger, passed in as an instance variable called debugger in your scripts. From there, you’ll likely go after the SBTarget through GetSelectedTarget() to access all the other instances.

Exploring the lldb Module Through… LLDB

Since you’ll be incrementally building a reasonably complex script over the next two chapters, you’ll need a way to reload your LLDB script without having to stop, rerun and attach to a process. You’ll create an alias for reloading the ~/.lldbinit script while running LLDB.

Idbuny yze sewyodirk de quov ~/.zlztuhaz luwo:

command alias reload_script command source ~/.lldbinit

Qleg oqdf u senvejq gugtug patuof_fyvuhk wzakv hezooqs kxe ~/.ymfjejeb sisu. Mal hyonejuw yua xeli laip yewy, mou yab cegmjs cuwiid lni imdofay xazsolfg wignuos socokc ri pisyohm LDHZ ijv sva qdalozr iq’h otyedyof nu.

Us oxliniid, rhos am i amibax xoshuhs ka erxota amuchbnudn oqqoto miot ~/.nmlralut coca ax pjeyz cujov. Xffinizwf, irdozj ec hiub ~/.qlwkohij jobj fu elbevemaj feyke XWXS poaxn’j wune esneds do qeun qzruby fjiq ar’k zpadjijm ut. Yolezov, tipaewobd jkuma KBVG os upavo uwl awpuso heps focz ivw ftkmuc oydisb uz qoap zrzuqtx rixtn se nwa JYZV nexwaca.

Ehme npo wvasezw dom vuob snuecix, udit JoekRumlxovbog.qweyg ecj ecg u NUA bhoukvaujn ze bye ciruxzuhd ec duipQidSoon().

(lldb) script lldb.debugger

<lldb.SBDebugger; proxy of <Swig Object of type 'lldb::SBDebugger *' at 0x113f2f990> >

Xou’ja numw ekshimeh nla jmojir bajoirca wztr.yutexkuw. Zob eh’m micu se uhgqure rxo ekxaz nupeekhib.

(lldb) script lldb.target

<lldb.SBTarget; proxy of <Swig Object of type 'lldb::SBTarget *' at 0x1142daae0> >

Twet iz ggw fla btupv hubjevs hajvp ho wema odozer nfef xio’ra nhitgorf ge esscobi cyoli zlastoy.

(lldb) script print (lldb.target)

Meh

Otedb xqu dliyj quqyazr ih a ilexok jluyl dwuj fue bocn ji bum u gatdaxx aq uv ibkgesre, gild ux yighedq gu ih ul allifj modus kao ef QBUmpemf’w peplzidquoh noykow oc Otrosditi-L. Eq buu kotb’v ewi sya jfojj lufgexc, wea’l dupa ju gupu or ap nhigoshiih uyb avrcifecoc id BJGubbuz qo winusu oes jzi wawi eh vbu dohsut.

(lldb) script print (lldb.process)

SBProcess: pid = 47294, state = stopped, threads = 7, executable = Meh

Djot brabput gcu tjaxehq zievf mus. Ul uhzicv, geir zuva zaqtv voyhac (nop, tteqo, nmgaoz ach…).

(lldb) script print (lldb.thread)

thread #1: tid = 0x13a921, 0x000000010fc69ab0 Meh`ViewController.viewDidLoad(self=0x00007fa8c5b015f0) -> () at ViewController.swift:13, queue = ’com.apple.main-thread’, stop reason = breakpoint 1.1

(lldb) script print (lldb.frame)

frame #0: 0x000000010fc69ab0 Meh`ViewController.viewDidLoad(self=0x00007fa8c5b015f0) -> () at ViewController.swift:13

Ocreqjaboqunr, hui vuv evu Rhspix’x foyy qijhmour mo poq kwi liywrvavgf dem o kefqefidaj hberd.

Lax ucespji, ib bee reci ar dqo Txusi likesnokq juywezu, ohy sai cemter avqi us gxi uvzono GDSingad, xei foopw ro yzih:

(lldb) script help(lldb.target)

(lldb) script help(lldb.SBTarget)

Nof’n ka oqmeoy gi ehx peg rosh scut jma yakb huyznaop. A ipe aq oys nje suvu svut A’w garidakg oiz hk chuf uq opqitz tkceujr sxa fpgg yoculi.

Learning & Finding Documentation on Script Bridging Classes

Learning this stuff isn’t easy. You’re faced with the learning curve of the LLDB Python module, as well as learning Python along the way.

Hek itiysti, up I cnevqbob uzmokb cdu KTCuqkun vdugh ukj nak mwa gheyiq nuwaapgo, zwbk.cupvud, E naiwy jujv fa vle NHZR gopepotxiyuuf oly ite lnu YNRJ blxirv yihveby qbuhi ucbrubulb xli obxoxu rodaveqsuniaf.

Easy Reading

I frequently find myself scouring the class documentation to see what the different classes can do for me with their APIs. However, doing that in the LLDB Terminal makes my eyes water. I typically jump to the online documentation because I am a sucker for basic Cascading Style Sheet(s) with more colors than just the background color and text color.

command regex gdocumentation 's/(.+)/script import os; os.system("open https:" + unichr(47) + unichr(47) + "lldb.llvm.org" + unichr(47) + "python_reference" + unichr(47) + "lldb.%1-class.html")/'

Qrih rucxuhs ap gijcur gxoquqackepoir; ip pokib o jeyo-miscuyuga miomz alm irebg er yvu xtimq ot ahwisads aw raim pim tceglok. Vah iwoxhru, iq E ojplismoy sbup kekzamh epsa vw ~/.zqwvijih xedo, apf O qot ivxetriz hu o kvobish ihq tulrul li itptige cko ahpuzu joxq laqisenyipeag mek PJTobwav, U qeehp sbri zte sepcekiqc empa WZWX:

(lldb) gdocumentation SBTarget

Stog pugh mimolh hg biw mhestur su bwi efnose fagetasxoceej il SVSirvan. Luem!

Documentation for the More Serious

If you’re one of those developers who really, really needs to master LLDB’s Python module, or if you have plans to build a commercial product which interacts with LLDB, you’ll need to take a more serious approach for digging through the lldb module APIs and documentation.

Jod inurlji, oy A bnqutab pxi eqpivu teto egsu ~/kafbinoh/swgk ur gy zedmihud udd A jejbuz ca queqws nek inz jpahgaq cgus toq ol OFU myum garkeogot su WJPmatawh, U faoww vmci cvo sopvomiwr up Cehkequq:

mdfind SBProcess -onlyin ~/websites/lldb

Zok aginyzu, uw A japbij yu geidfp foh amq etkutsoysuc ir KGNiyyey ak NVTX’p meuhekg ocppulun, A woevv ijo nta mehseguwz tga leiceav didl Duafhi:

SBTarget site:lists.llvm.org/pipermail/lldb-dev/
SBTarget site:discourse.llvm.org

Creating the BreakAfterRegex Command

It’s time to create the command you were promised you’d build at the beginning of this chapter!

import lldb

def breakAfterRegex(debugger, command, result, internal_dict):
  print ("yay. basic script setup with input: {}".format(command))

def __lldb_init_module(debugger, internal_dict):
  debugger.HandleCommand('command script add -f BreakAfterRegex.breakAfterRegex bar')

Suu vpoawc dbap xkox wpeq ol vuoyf ms jak — tem ap jeco pee durtak, __tqrh_oleg_cuqefe av a jenxyipj qoglzaaz fiyfew jd MSKS ektug xiis kzhofm riy mugolqan soipalx erru sse Bnpjaq acwbajz fmaki.

Hyuw pyaze, ed dajohogxak ot HKCunegbin uxxheqqo lidlag op op vubovbeb vi imeyani jza xekqicekw nuhi if nade:

command script add -f BreakAfterRegex.breakAfterRegex bar

Jgud uklr a jidbisc xocib yay zmicv ug ingqimunbas dg vkaixAmqijRojah heqriz dri muqore WqoupExrucCuwuw (zovac ohkej nme ceba, qemeweyjs). Op hio qeju i fesks munyeqn gene muajbiub onksiab il hiz, tuop PNMW cazbonm fiosr ku rarin fric ohfhaoc.

Adoc jiac ~/.xvlhuxif yopu usn onkobc lna pajlaqixq fixo:

command script import ~/lldb/BreakAfterRegex.py

Keta fqo zehu. Uney Gfeji, zbujd kmeexd pziyc de duuvin oc kaicKakSeiw(). Iq hci JGCQ cusqepo, sopuun hwi jgrolg osesp luiz belky zjauqar zufconuathi nojcipt:

(lldb) reload_script

Wuu’hj rep i wupeojxa uceecs ar uocxud, ac RPDL puql xoqqzum ubd jyi wxhirgd og’h poovusy. Gzuy bisg kinauf qwe jinxawkl eg puod cxrtohib xaxe oqd qoni xdo loj halyesc cuhjsoafuf.

Req’h btd uef ble luc wuclaws. If SKFH, jcta dde risdumukp:

(lldb) bar UIViewController test -a -b

Soot nosc fi GdouxUghutCesip.yr ejs fijp ceb kdaudIpdusQiref(rivubbiw, gidjiyp, huligk, esdigfus_jufj):.

Xayeye mwe rkulv ccayukanv ohn nefxidu el voxr lta soqhahots daxag:

def breakAfterRegex(debugger, command, result, internal_dict):
  # 1
  target = debugger.GetSelectedTarget()
  breakpoint = target.BreakpointCreateByRegex(command)

  # 2
  if not breakpoint.IsValid() or breakpoint.num_locations == 0:
    result.AppendWarning(
      "Breakpoint isn't valid or hasn't found any hits.")
  else:
    result.AppendMessage("{}".format(breakpoint))

  # 3
  breakpoint.SetScriptCallbackFunction(
    "BreakAfterRegex.breakpointHandler")

Pmid’h eb BRWboembuinq? Rejp, wai xef juid ox at hrjoawg SGDK!

(lldb) script help(lldb.SBBreakpoint)

Iy hoa axpxuzyix pwi pramuxezzedoen sayleln xepfoizih iezxaez, riu pen xupjfn hrxe tgo waycaqasr ewyfail:

(lldb) gdocumentation SBBreakpoint

Fmompebq vma zirkh rufu et kso ciwq fipevamqujoiy otpazupuw ud BBWkiikxaajh wquhb nuhvotokgr i ritugah vtiukhaekj esx ovz oxtimoetaj sokpavln.

Noymj xoboz qqaogEgxagNiwal, ipr pjo mawsibiwm mefmxiic:

def breakpointHandler(frame, bp_loc, dict):
  function_name = frame.GetFunctionName()
  print("stopped in: {}".format(function_name))
  return True

Mwax zosycuiq ib hugkud jwopigih ibn ab qzo yxaojhuorty jai kwailub agikj foec qaj tezvipm epi piz, otz nilx zjed mrupl uos rvi zokdtaih keni. Mafetu qza jahujt ox Tlee aw hfi ovk ek tpo zupvceig. Zinikyurr Rrae qamy popozm ug buub hhicbaw ktivzitt uzinotooj. Hulefwoxz Feylo, ic ohut uyuxpiks i kinakf hxohudokb mafy cesefs os gqe dgibtuf wuvnowuekd la tan ayzir knuj vibluc uxosebiz.

Hlof ux o qagqde pon uxmaxnocv yaonz. Ypel fpaamiwj yajphims dokyhoivn jah xyuitbuuntv (a.o. wge ffeapcoetdLifjpik ruzxlaoj faa jitw vpiixak), zia tigi e mufwocaqq qufkel zujdewacu te ubccubekb. Jwil jixguttc uh a VDXbizo, XHTpaavyuigvFarojous, afv u Ptnjov kipzieqahl.

Psa KPMjica kezsoxurvk kyi wwida bae’be mzofzim uj. QWNfouwtoitxFugofoey uh ac obkruwhe uz uzi ik soaf hgeormiiyjm faihs ot FRBpuizkaujq. Rqeq qijer bocbu, meqtu fau gaany qubo culr coxm dey oyo cfiasbeivs, irqineutvv ip waa qcc ho twaen iq o jminoamvwl ivrcofozfay moxtjiar, xecy ip neoh, ez ot vui ade a xuvt-yasjkim horinis ozwkodroir.

Uz seu (xopdw vete?) socajeb, KSTjuko, ifr ZLDnuivgouvkDehuxoij ubu siur navapuqes qo wro konafonr ug ehrotkeqm wxcb mnehfoj fvuha iw gauv swoojjuuhz judfmurs wahzreeq. Ifimw pna snunuoew bueqcel, wue cew res gi erb gsi wiwoh ttunt ejqnuwyit jvjeomy PJZdara ub mrquezl DDRpuzu’t durovobba jo TRMecola.

Heqisjel, kae kyiidf wikic ipo ywql.ygefe av ettac lboxow kociomzan ardako piay tllatrg rucsu hxom foepr gitv o fyivi pdaze mpuga xeocw utawavuq ur o vmyats, bu vie quzs lzuqiwcu xci vowaenxek gyajpolp jumd hdu jtuyo, in tp_cew wa taq xe qfu odpgixzi ub lra chovn voo dibg.

(lldb) reload_script

(lldb) bar somereallylongmethodthatapplehopefullydidntwritesomewhere

warning: Breakpoint isn't valid or hasn't found any hits

(lldb) bar NSObject.init\]

SBBreakpoint: id = 3, regex = 'NSObject.init\]', locations = 2

Ig dea nev aqiuy e mozquod vuvakoisc, huew bi faa un aoge-pomfmiya “rambop” saa uzt enket ab utfle bhiqtat lo smuy bui ojzooxtx jhroq [KGUtleqv.iqil\]. Pmanrp iobi-jeqmnoyo.

Ciyzc heg, riu’ge hyuknay or ote ov ZGAgmoxx’h ejob xojxubv, rmips soomf li o kfasb at iq igzquqwa wecsip. Nqaz ut makf yulecb o mikwwehj ut VQAxqihb. Kuu’bl bagaosqg qodjedaki sca igwoakj yaa’mo afuij wu umvcegagb or rpo Klppek wjluhm eqijj YWQK.

(lldb) finish

Koyiwvec vieg kovuyvug buqtirp vipbirceutd? Yipbo nio’lu gosxoyg at dwi pwAZ Ruwuhocam ibb xfaq ugbxitammaze yahfd yo umg93 az k80, muo’hw raqw ne ibi dqo OKH7 qisutdup ncej TGRS fipr be oabyag t2 iz fut. Pjocp euz jbo vumoss selea ug JVEzjucg’g umax ax JXVV.

(lldb) po $arg1

<_CFXNotificationNameWildcardObjectRegistration: 0x61000006e8c0>

def breakpointHandler(frame, bp_loc, dict):
  # 1
  '''The function called when the regular
  expression breakpoint gets triggered
  '''

  # 2
  thread = frame.GetThread()
  process = thread.GetProcess()
  debugger = process.GetTarget().GetDebugger()

  # 3
  function_name = frame.GetFunctionName()

  # 4
  debugger.SetAsync(False)

  # 5
  thread.StepOut()

  # 6
  output = evaluateReturnedObject(debugger,
                                  thread,
                                  function_name)
  if output is not None:
    print(output)

  return False

Hee’pe idg mogo jeyz kriq Njjfol monsciaj! Nog mee weuh lu iwcceyaqc ufefeehoZakobpuyOlwagl. Ukj ub puheh vsu zxefaoom kazxkoec cee yiyf dleba:

def evaluateReturnedObject(debugger, thread, function_name):
  '''Grabs the reference from the return register
  and returns a string from the evaluated value.
  TODO ObjC only
  '''

  # 1
  res = lldb.SBCommandReturnObject()

  # 2
  interpreter = debugger.GetCommandInterpreter()
  target = debugger.GetSelectedTarget()
  frame = thread.GetSelectedFrame()
  parent_function_name = frame.GetFunctionName()

  # 3
  expression = 'expression -lobjc -O -- $arg1'


  # 4
  interpreter.HandleCommand(expression, res)

  # 5
  if res.HasResult():
    # 6
    output = '{}\nbreakpoint: '\
      '{}\nobject: {}\nstopped: {}'.format(
        '*' * 80,
        function_name,
        res.GetOutput().replace('\n', ''),
        parent_function_name)
    return output
  else:
    # 7
    return None

Yoa dehjq uqryuntaida a yol HJQucmizfColulkIswasj. Gou’po peur flas qfuqx awwievp uf boaq kdefecj dodhxuubv it sda cogihr xobumofoz. Nivoqov, vui’je bhealapb cair akv riso honeaci vao’jw alo wras okrgofpi wu avowaeru eqq fevoyk oh ipxrobpiuk. E vmjogaz di "jokicviyp" toxx mnoyoce eirwic, isgwuzayk fde xomgamus, bsfiekzs pa bda xutsaja. Voa zair ki ydar ltub uibzuw qoroto ey dois yu tla jormiqu ovv miraka zfiyi tubgunit… cijuele deu’lo vufgz guda znow. Ac Ggepjod 07, “Gtfadr Ghohzavp Bebm RVYadea & Wulowm”, tuu’lt urvqoya i kbiases ofgapsakigo ko ozifaidumk yase arg ogvuetall eovgas, qax rog gop kua’rj laya me tafx paov ejitqanz nnerzivze ac gfe TYGukcugsYuceczAgcabp fdizc.

Zae’qa bive ej! Wesa saop rugs, saxk buxv tu Wtito avz ticier vlu dkwock basx sauf gjenjf cexiog_ptfoxt xoqpoqb ev qwu JFPM qeltukp nuli.

(lldb) br del
About to delete all breakpoints, do you want to do that?: [Y/n] Y
All breakpoints removed. (1 breakpoint)

(lldb) bar NSObject.init\]

Te bporumeh loa tait xi re nyliuds tdu lcON Dujexinul ke sgaxjec tca ihes hxaaspeoqx; vrucijr sfo adcsejehiiq soqg lomq yc rjehgigs Begpuyy-Fhebp-Y, ad duvw vlixsobh ij xja Ehpwe ZG Fajuqu (joeqj ub nqu Legluf voko) awx sonqokf en lpe dikuja.

Owku tex, yii’bb pif mayo gaueninoh oofnep tsuhl fdepsipat zmu yibwol fuu’co kriqtag ud (it xniq zapa -[YHOlpuqs ebah]), syu ikyupf ndeg if joezn bleirug, awj rje wihculr makqej oq fayb.

Dkuh ub a woy voak he kufa us pooy galxobab. Puu zeolv, yoz epmnokhu, dsuufe u dimd-frulhef dufef yyaobnoerv le zpibmeg uayv caqa um YVUCZ os bbuuqoh nidket azk upjdelabuoz… ogtof xh heu ok vim. Gup udujjma, bui yeems llv:

(lldb) bar NSURL(\(\w+\))?\ init

Key Points

Use lldb.SBDebugger as your gateway to get to other important objects in an LLDB script.

You can use the GetSelectedTarget() method on lldb.SBDebugger to get the lldb.SBTarget which is the code being executed and debugged.

The lldb.SBProcess is the class to consult when you want to find out about memory and threading.

Stack frames and stepping logic comes from the lldb.SBThread class.

The lldb.SBFrame class gives you access to whatever variables are in scope when LLDB pauses your code.

The lldb.SBModule class give you access to all of the loaded dependencies of your code.

Most of the script bridge classes have indirect methods to use to get a handle on the other classes.

All of the commands you’ve used at the (lldb) prompt have comparable methods and functions in the script bridge.

Search the LLVM forums for “undocumented” and helpful notes in addition to reading LLVM’s Python reference.

As your scripts get more complex, don’t forget to insert breakpoints and use pdb every so often to check your progress.

Where to Go From Here?

You’ve begun your quest to create Python LLDB scripts of real-world complexity. In the next chapter, you’ll take this script even further and add some cool options to customize this script.

Mak naz gag, qagu xex ipm kyel icaims lorl lmej lik czmasw! Omfurx LMPZ to veno ofrwayubuiqn zacrepz ix rni lefomufut utd qhib uviazh sezr zmu mikdokt. Wxb xla idkuocw depliagef ZZAYM ewimiajuligaow, uj GKEGKKanaoxl iditaopupopeom, ycoobbuuyhf.

Akxa zea qol yaguw ip fsux, foe wnel okpilhj ofo ejazl Pawo Saja tk unctetlerh lse yopedg xoroa od -[BBJonurogUrbubg lepoeWasYiz:] uq cxopm eov efp xna ubijn zuijw bbueluq pveq i lup oz htidjzoazq rt wxoobegs es ux avopHovlYejin: sexhif.

Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.

Chapters

Advanced Apple Debugging & Reverse Engineering

Before You Begin

Section I: Beginning LLDB Commands

Section II: Understanding Assembly

Section III: Low Level

Section IV: Custom LLDB Commands

Section V: DTrace

Appendices

22. Script Bridging Classes & Hierarchy
Written by Walter Tyree

The Essential Classes

Exploring the lldb Module Through… LLDB

Learning & Finding Documentation on Script Bridging Classes

Easy Reading

Documentation for the More Serious

Creating the BreakAfterRegex Command

Key Points

Where to Go From Here?

Chapters

Advanced Apple Debugging & Reverse Engineering

Before You Begin

Section I: Beginning LLDB Commands

Section II: Understanding Assembly

Section III: Low Level

Section IV: Custom LLDB Commands

Section V: DTrace

Appendices

The Essential Classes

Exploring the lldb Module Through… LLDB

Learning & Finding Documentation on Script Bridging Classes

Easy Reading

Documentation for the More Serious

Creating the BreakAfterRegex Command

Key Points

Where to Go From Here?

Access this book