1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916691769186919692069216922692369246925692669276928692969306931693269336934693569366937693869396940694169426943694469456946694769486949695069516952695369546955695669576958695969606961696269636964696569666967696869696970697169726973697469756976697769786979698069816982698369846985698669876988698969906991699269936994699569966997699869997000700170027003700470057006700770087009701070117012701370147015701670177018701970207021702270237024702570267027702870297030703170327033703470357036703770387039704070417042704370447045704670477048704970507051705270537054705570567057705870597060706170627063706470657066706770687069707070717072707370747075707670777078707970807081708270837084708570867087708870897090709170927093709470957096709770987099710071017102710371047105710671077108710971107111711271137114711571167117711871197120712171227123712471257126712771287129713071317132713371347135713671377138713971407141714271437144714571467147714871497150715171527153715471557156715771587159716071617162716371647165716671677168716971707171717271737174717571767177717871797180718171827183718471857186718771887189719071917192719371947195719671977198719972007201720272037204720572067207720872097210721172127213721472157216721772187219722072217222722372247225722672277228722972307231723272337234723572367237723872397240724172427243724472457246724772487249725072517252725372547255725672577258725972607261726272637264726572667267726872697270727172727273727472757276727772787279728072817282728372847285728672877288728972907291729272937294729572967297729872997300730173027303730473057306730773087309731073117312731373147315731673177318731973207321732273237324732573267327732873297330733173327333733473357336733773387339734073417342734373447345734673477348734973507351735273537354735573567357735873597360736173627363736473657366736773687369737073717372737373747375737673777378737973807381738273837384738573867387738873897390739173927393739473957396739773987399740074017402740374047405740674077408740974107411741274137414741574167417741874197420742174227423742474257426742774287429743074317432743374347435743674377438743974407441744274437444744574467447744874497450745174527453745474557456745774587459746074617462746374647465746674677468746974707471747274737474747574767477747874797480748174827483748474857486748774887489749074917492749374947495749674977498749975007501750275037504750575067507750875097510751175127513751475157516751775187519752075217522752375247525752675277528752975307531753275337534753575367537753875397540754175427543754475457546754775487549755075517552755375547555755675577558755975607561756275637564756575667567756875697570757175727573757475757576757775787579758075817582758375847585758675877588758975907591759275937594759575967597759875997600760176027603760476057606760776087609761076117612761376147615761676177618761976207621762276237624762576267627762876297630763176327633763476357636763776387639764076417642764376447645764676477648764976507651765276537654765576567657765876597660766176627663766476657666766776687669767076717672767376747675767676777678767976807681768276837684768576867687768876897690769176927693769476957696769776987699770077017702770377047705770677077708770977107711771277137714771577167717771877197720772177227723772477257726772777287729773077317732773377347735773677377738773977407741774277437744774577467747774877497750775177527753775477557756775777587759776077617762776377647765776677677768776977707771777277737774777577767777777877797780778177827783778477857786778777887789779077917792779377947795779677977798779978007801780278037804780578067807780878097810781178127813781478157816781778187819782078217822782378247825782678277828782978307831783278337834783578367837783878397840784178427843784478457846784778487849785078517852785378547855785678577858785978607861786278637864786578667867786878697870787178727873787478757876787778787879788078817882788378847885788678877888788978907891789278937894789578967897789878997900790179027903790479057906790779087909791079117912791379147915791679177918791979207921792279237924792579267927792879297930793179327933793479357936793779387939794079417942794379447945794679477948794979507951795279537954795579567957795879597960796179627963796479657966796779687969797079717972797379747975797679777978797979807981798279837984798579867987798879897990799179927993799479957996799779987999800080018002800380048005800680078008800980108011801280138014801580168017801880198020802180228023802480258026802780288029803080318032803380348035803680378038803980408041804280438044804580468047804880498050805180528053805480558056805780588059806080618062806380648065806680678068806980708071807280738074807580768077807880798080808180828083808480858086808780888089809080918092809380948095809680978098809981008101810281038104810581068107810881098110811181128113811481158116811781188119812081218122812381248125812681278128812981308131813281338134813581368137813881398140814181428143814481458146814781488149815081518152815381548155815681578158815981608161816281638164816581668167816881698170817181728173817481758176817781788179818081818182818381848185818681878188818981908191819281938194819581968197819881998200820182028203820482058206820782088209821082118212821382148215821682178218821982208221822282238224822582268227822882298230823182328233823482358236823782388239824082418242824382448245824682478248824982508251825282538254825582568257825882598260826182628263826482658266826782688269827082718272827382748275827682778278827982808281828282838284828582868287828882898290829182928293829482958296829782988299830083018302830383048305830683078308830983108311831283138314831583168317831883198320832183228323832483258326832783288329833083318332833383348335833683378338833983408341834283438344834583468347834883498350835183528353835483558356835783588359836083618362836383648365836683678368836983708371837283738374837583768377837883798380838183828383838483858386838783888389839083918392839383948395839683978398839984008401840284038404840584068407840884098410841184128413841484158416841784188419842084218422842384248425842684278428842984308431843284338434843584368437843884398440844184428443844484458446844784488449845084518452845384548455845684578458845984608461846284638464846584668467846884698470847184728473847484758476847784788479848084818482848384848485848684878488848984908491849284938494849584968497849884998500850185028503850485058506850785088509851085118512851385148515851685178518851985208521852285238524852585268527852885298530853185328533853485358536853785388539854085418542854385448545854685478548854985508551855285538554855585568557855885598560856185628563856485658566856785688569857085718572857385748575857685778578857985808581858285838584858585868587858885898590859185928593859485958596859785988599860086018602860386048605860686078608860986108611861286138614861586168617861886198620862186228623862486258626862786288629863086318632863386348635863686378638863986408641864286438644864586468647864886498650865186528653865486558656865786588659866086618662866386648665866686678668866986708671867286738674867586768677867886798680868186828683868486858686868786888689869086918692869386948695869686978698869987008701870287038704870587068707870887098710871187128713871487158716871787188719872087218722872387248725872687278728872987308731873287338734873587368737873887398740874187428743874487458746874787488749875087518752875387548755875687578758875987608761876287638764876587668767876887698770877187728773877487758776877787788779878087818782878387848785878687878788878987908791879287938794879587968797879887998800880188028803880488058806880788088809881088118812881388148815881688178818881988208821882288238824882588268827882888298830883188328833883488358836883788388839884088418842884388448845884688478848884988508851885288538854885588568857885888598860886188628863886488658866886788688869887088718872887388748875887688778878887988808881888288838884888588868887888888898890889188928893889488958896889788988899890089018902890389048905890689078908890989108911891289138914891589168917891889198920892189228923892489258926892789288929893089318932893389348935893689378938893989408941894289438944894589468947894889498950895189528953895489558956895789588959896089618962896389648965896689678968896989708971897289738974897589768977897889798980898189828983898489858986898789888989899089918992899389948995899689978998899990009001900290039004900590069007900890099010901190129013901490159016901790189019902090219022902390249025902690279028902990309031903290339034903590369037903890399040904190429043904490459046904790489049905090519052905390549055905690579058905990609061906290639064906590669067906890699070907190729073907490759076907790789079908090819082908390849085908690879088908990909091909290939094909590969097909890999100910191029103910491059106910791089109911091119112911391149115911691179118911991209121912291239124912591269127912891299130913191329133913491359136913791389139914091419142914391449145914691479148914991509151915291539154915591569157915891599160916191629163916491659166916791689169917091719172917391749175917691779178917991809181918291839184918591869187918891899190919191929193919491959196919791989199920092019202920392049205920692079208920992109211921292139214921592169217921892199220922192229223922492259226922792289229923092319232923392349235923692379238923992409241924292439244924592469247924892499250925192529253925492559256925792589259926092619262926392649265926692679268926992709271927292739274927592769277927892799280928192829283928492859286928792889289929092919292929392949295929692979298929993009301930293039304930593069307930893099310931193129313931493159316931793189319932093219322932393249325932693279328932993309331933293339334933593369337933893399340934193429343934493459346934793489349935093519352935393549355935693579358935993609361936293639364936593669367936893699370937193729373937493759376937793789379938093819382938393849385938693879388938993909391939293939394939593969397939893999400940194029403940494059406940794089409941094119412941394149415941694179418941994209421942294239424942594269427942894299430943194329433943494359436943794389439944094419442944394449445944694479448944994509451945294539454945594569457945894599460946194629463946494659466946794689469947094719472947394749475947694779478947994809481948294839484948594869487948894899490949194929493949494959496949794989499950095019502950395049505950695079508950995109511951295139514951595169517951895199520952195229523952495259526952795289529953095319532953395349535953695379538953995409541954295439544954595469547954895499550955195529553955495559556955795589559956095619562956395649565956695679568956995709571957295739574957595769577957895799580958195829583958495859586958795889589959095919592959395949595959695979598959996009601960296039604960596069607960896099610961196129613961496159616961796189619962096219622962396249625962696279628962996309631963296339634963596369637963896399640964196429643964496459646964796489649965096519652965396549655965696579658965996609661966296639664966596669667966896699670967196729673967496759676967796789679968096819682968396849685968696879688968996909691969296939694969596969697969896999700970197029703970497059706970797089709971097119712971397149715971697179718971997209721972297239724972597269727972897299730973197329733973497359736973797389739974097419742974397449745974697479748974997509751975297539754975597569757975897599760976197629763976497659766976797689769977097719772977397749775977697779778977997809781978297839784978597869787978897899790979197929793979497959796979797989799980098019802980398049805980698079808980998109811981298139814981598169817981898199820982198229823982498259826982798289829983098319832983398349835983698379838983998409841984298439844984598469847984898499850985198529853985498559856985798589859986098619862986398649865986698679868986998709871987298739874987598769877987898799880988198829883988498859886988798889889989098919892989398949895989698979898989999009901990299039904990599069907990899099910991199129913991499159916991799189919992099219922992399249925992699279928992999309931993299339934993599369937993899399940994199429943994499459946994799489949995099519952995399549955995699579958995999609961996299639964996599669967996899699970997199729973997499759976997799789979998099819982998399849985998699879988998999909991999299939994999599969997999899991000010001100021000310004100051000610007100081000910010100111001210013100141001510016100171001810019100201002110022100231002410025100261002710028100291003010031100321003310034100351003610037100381003910040100411004210043100441004510046100471004810049100501005110052100531005410055100561005710058100591006010061100621006310064100651006610067100681006910070100711007210073100741007510076100771007810079100801008110082100831008410085100861008710088100891009010091100921009310094100951009610097100981009910100101011010210103101041010510106101071010810109101101011110112101131011410115101161011710118101191012010121101221012310124101251012610127101281012910130101311013210133101341013510136101371013810139101401014110142101431014410145101461014710148101491015010151101521015310154101551015610157101581015910160101611016210163101641016510166101671016810169101701017110172101731017410175101761017710178101791018010181101821018310184101851018610187101881018910190101911019210193101941019510196101971019810199102001020110202102031020410205102061020710208102091021010211102121021310214102151021610217102181021910220102211022210223102241022510226102271022810229102301023110232102331023410235102361023710238102391024010241102421024310244102451024610247102481024910250102511025210253102541025510256102571025810259102601026110262102631026410265102661026710268102691027010271102721027310274102751027610277102781027910280102811028210283102841028510286102871028810289102901029110292102931029410295102961029710298102991030010301103021030310304103051030610307103081030910310103111031210313103141031510316103171031810319103201032110322103231032410325103261032710328103291033010331103321033310334103351033610337103381033910340103411034210343103441034510346103471034810349103501035110352103531035410355103561035710358103591036010361103621036310364103651036610367103681036910370103711037210373103741037510376103771037810379103801038110382103831038410385103861038710388103891039010391103921039310394103951039610397103981039910400104011040210403104041040510406104071040810409104101041110412104131041410415104161041710418104191042010421104221042310424104251042610427104281042910430104311043210433104341043510436104371043810439104401044110442104431044410445104461044710448104491045010451104521045310454104551045610457104581045910460104611046210463104641046510466104671046810469104701047110472104731047410475104761047710478104791048010481104821048310484104851048610487104881048910490104911049210493104941049510496104971049810499105001050110502105031050410505105061050710508105091051010511105121051310514105151051610517105181051910520105211052210523105241052510526105271052810529105301053110532105331053410535105361053710538105391054010541105421054310544105451054610547105481054910550105511055210553105541055510556105571055810559105601056110562105631056410565105661056710568105691057010571105721057310574105751057610577105781057910580105811058210583105841058510586105871058810589105901059110592105931059410595105961059710598105991060010601106021060310604106051060610607106081060910610106111061210613106141061510616106171061810619106201062110622106231062410625106261062710628106291063010631106321063310634106351063610637106381063910640106411064210643106441064510646106471064810649106501065110652106531065410655106561065710658106591066010661106621066310664106651066610667106681066910670106711067210673106741067510676106771067810679106801068110682106831068410685106861068710688106891069010691106921069310694106951069610697106981069910700107011070210703107041070510706107071070810709107101071110712107131071410715107161071710718107191072010721107221072310724107251072610727107281072910730107311073210733107341073510736107371073810739107401074110742107431074410745107461074710748107491075010751107521075310754107551075610757107581075910760107611076210763107641076510766107671076810769107701077110772107731077410775107761077710778107791078010781107821078310784107851078610787107881078910790107911079210793107941079510796107971079810799108001080110802108031080410805108061080710808108091081010811108121081310814108151081610817108181081910820108211082210823108241082510826108271082810829108301083110832108331083410835108361083710838108391084010841108421084310844108451084610847108481084910850108511085210853108541085510856108571085810859108601086110862108631086410865108661086710868108691087010871108721087310874108751087610877108781087910880108811088210883108841088510886108871088810889108901089110892108931089410895108961089710898108991090010901109021090310904109051090610907109081090910910109111091210913109141091510916109171091810919109201092110922109231092410925109261092710928109291093010931109321093310934109351093610937109381093910940109411094210943109441094510946109471094810949109501095110952109531095410955109561095710958109591096010961109621096310964109651096610967109681096910970109711097210973109741097510976109771097810979109801098110982109831098410985109861098710988109891099010991109921099310994109951099610997109981099911000110011100211003110041100511006110071100811009110101101111012110131101411015110161101711018110191102011021110221102311024110251102611027110281102911030110311103211033110341103511036110371103811039110401104111042110431104411045110461104711048110491105011051110521105311054110551105611057110581105911060110611106211063110641106511066110671106811069110701107111072110731107411075110761107711078110791108011081110821108311084110851108611087110881108911090110911109211093110941109511096110971109811099111001110111102111031110411105111061110711108111091111011111111121111311114111151111611117111181111911120111211112211123111241112511126111271112811129111301113111132111331113411135111361113711138111391114011141111421114311144111451114611147111481114911150111511115211153111541115511156111571115811159111601116111162111631116411165111661116711168111691117011171111721117311174111751117611177111781117911180111811118211183111841118511186111871118811189111901119111192111931119411195111961119711198111991120011201112021120311204112051120611207112081120911210112111121211213112141121511216112171121811219112201122111222112231122411225112261122711228112291123011231112321123311234112351123611237112381123911240112411124211243112441124511246112471124811249112501125111252112531125411255112561125711258112591126011261112621126311264112651126611267112681126911270112711127211273112741127511276112771127811279112801128111282112831128411285112861128711288112891129011291112921129311294112951129611297112981129911300113011130211303113041130511306113071130811309113101131111312113131131411315113161131711318113191132011321113221132311324113251132611327113281132911330113311133211333113341133511336113371133811339113401134111342113431134411345113461134711348113491135011351113521135311354113551135611357113581135911360113611136211363113641136511366113671136811369113701137111372113731137411375113761137711378113791138011381113821138311384113851138611387113881138911390113911139211393113941139511396113971139811399114001140111402114031140411405114061140711408114091141011411114121141311414114151141611417114181141911420114211142211423114241142511426114271142811429114301143111432114331143411435114361143711438114391144011441114421144311444114451144611447114481144911450114511145211453114541145511456114571145811459114601146111462114631146411465114661146711468114691147011471114721147311474114751147611477114781147911480114811148211483114841148511486114871148811489114901149111492114931149411495114961149711498114991150011501115021150311504115051150611507115081150911510115111151211513115141151511516115171151811519115201152111522115231152411525115261152711528115291153011531115321153311534115351153611537115381153911540115411154211543115441154511546115471154811549115501155111552115531155411555115561155711558115591156011561115621156311564115651156611567115681156911570115711157211573115741157511576115771157811579115801158111582115831158411585115861158711588115891159011591115921159311594115951159611597115981159911600116011160211603116041160511606116071160811609116101161111612116131161411615116161161711618116191162011621116221162311624116251162611627116281162911630116311163211633116341163511636116371163811639116401164111642116431164411645116461164711648116491165011651116521165311654116551165611657116581165911660116611166211663116641166511666116671166811669116701167111672116731167411675116761167711678116791168011681116821168311684116851168611687116881168911690116911169211693116941169511696116971169811699117001170111702117031170411705117061170711708117091171011711117121171311714117151171611717117181171911720117211172211723117241172511726117271172811729117301173111732117331173411735117361173711738117391174011741117421174311744117451174611747117481174911750117511175211753117541175511756117571175811759117601176111762117631176411765117661176711768117691177011771117721177311774117751177611777117781177911780117811178211783117841178511786117871178811789117901179111792117931179411795117961179711798117991180011801118021180311804118051180611807118081180911810118111181211813118141181511816118171181811819118201182111822118231182411825118261182711828118291183011831118321183311834118351183611837118381183911840118411184211843118441184511846118471184811849118501185111852118531185411855118561185711858118591186011861118621186311864118651186611867118681186911870118711187211873118741187511876118771187811879118801188111882118831188411885118861188711888118891189011891118921189311894118951189611897118981189911900119011190211903119041190511906119071190811909119101191111912119131191411915119161191711918119191192011921119221192311924119251192611927119281192911930119311193211933119341193511936119371193811939119401194111942119431194411945119461194711948119491195011951119521195311954119551195611957119581195911960119611196211963119641196511966119671196811969119701197111972119731197411975119761197711978119791198011981119821198311984119851198611987119881198911990119911199211993119941199511996119971199811999120001200112002120031200412005120061200712008120091201012011120121201312014120151201612017120181201912020120211202212023120241202512026120271202812029120301203112032120331203412035120361203712038120391204012041120421204312044120451204612047120481204912050120511205212053120541205512056120571205812059120601206112062120631206412065120661206712068120691207012071120721207312074120751207612077120781207912080120811208212083120841208512086120871208812089120901209112092120931209412095120961209712098120991210012101121021210312104121051210612107121081210912110121111211212113121141211512116121171211812119121201212112122121231212412125121261212712128121291213012131121321213312134121351213612137121381213912140121411214212143121441214512146121471214812149121501215112152121531215412155121561215712158121591216012161121621216312164121651216612167121681216912170121711217212173121741217512176121771217812179121801218112182121831218412185121861218712188121891219012191121921219312194121951219612197121981219912200122011220212203122041220512206122071220812209122101221112212122131221412215122161221712218122191222012221122221222312224122251222612227122281222912230122311223212233122341223512236122371223812239122401224112242122431224412245122461224712248122491225012251122521225312254122551225612257122581225912260122611226212263122641226512266122671226812269122701227112272122731227412275122761227712278122791228012281122821228312284122851228612287122881228912290122911229212293122941229512296122971229812299123001230112302123031230412305123061230712308123091231012311123121231312314123151231612317123181231912320123211232212323123241232512326123271232812329123301233112332123331233412335123361233712338123391234012341123421234312344123451234612347123481234912350123511235212353123541235512356123571235812359123601236112362123631236412365123661236712368123691237012371123721237312374123751237612377123781237912380123811238212383123841238512386123871238812389123901239112392123931239412395123961239712398123991240012401124021240312404124051240612407124081240912410124111241212413124141241512416124171241812419124201242112422124231242412425124261242712428124291243012431124321243312434124351243612437124381243912440124411244212443124441244512446124471244812449124501245112452124531245412455124561245712458124591246012461124621246312464124651246612467124681246912470124711247212473124741247512476124771247812479124801248112482124831248412485124861248712488124891249012491124921249312494124951249612497124981249912500125011250212503125041250512506125071250812509125101251112512125131251412515125161251712518125191252012521125221252312524125251252612527125281252912530125311253212533125341253512536125371253812539125401254112542125431254412545125461254712548125491255012551125521255312554125551255612557125581255912560125611256212563125641256512566125671256812569125701257112572125731257412575125761257712578125791258012581125821258312584125851258612587125881258912590125911259212593125941259512596125971259812599126001260112602126031260412605126061260712608126091261012611126121261312614126151261612617126181261912620126211262212623126241262512626126271262812629126301263112632126331263412635126361263712638126391264012641126421264312644126451264612647126481264912650126511265212653126541265512656126571265812659126601266112662126631266412665126661266712668126691267012671126721267312674126751267612677126781267912680126811268212683126841268512686126871268812689126901269112692126931269412695126961269712698126991270012701127021270312704127051270612707127081270912710127111271212713127141271512716127171271812719127201272112722127231272412725127261272712728127291273012731127321273312734127351273612737127381273912740127411274212743127441274512746127471274812749127501275112752127531275412755127561275712758127591276012761127621276312764127651276612767127681276912770127711277212773127741277512776127771277812779127801278112782127831278412785127861278712788127891279012791127921279312794127951279612797127981279912800128011280212803128041280512806128071280812809128101281112812128131281412815128161281712818128191282012821128221282312824128251282612827128281282912830128311283212833128341283512836128371283812839128401284112842128431284412845128461284712848128491285012851128521285312854128551285612857128581285912860128611286212863128641286512866128671286812869128701287112872128731287412875128761287712878128791288012881128821288312884128851288612887128881288912890128911289212893128941289512896128971289812899129001290112902129031290412905129061290712908129091291012911129121291312914129151291612917129181291912920129211292212923129241292512926129271292812929129301293112932129331293412935129361293712938129391294012941129421294312944129451294612947129481294912950129511295212953129541295512956129571295812959129601296112962129631296412965129661296712968129691297012971129721297312974129751297612977129781297912980129811298212983129841298512986129871298812989129901299112992129931299412995129961299712998129991300013001130021300313004130051300613007130081300913010130111301213013130141301513016130171301813019130201302113022130231302413025130261302713028130291303013031130321303313034130351303613037130381303913040130411304213043130441304513046130471304813049130501305113052130531305413055130561305713058130591306013061130621306313064130651306613067130681306913070130711307213073130741307513076130771307813079130801308113082130831308413085130861308713088130891309013091130921309313094130951309613097130981309913100131011310213103131041310513106131071310813109131101311113112131131311413115131161311713118131191312013121131221312313124131251312613127131281312913130131311313213133131341313513136131371313813139131401314113142131431314413145131461314713148131491315013151131521315313154131551315613157131581315913160131611316213163131641316513166131671316813169131701317113172131731317413175131761317713178131791318013181131821318313184131851318613187131881318913190131911319213193131941319513196131971319813199132001320113202132031320413205132061320713208132091321013211132121321313214132151321613217132181321913220132211322213223132241322513226132271322813229132301323113232132331323413235132361323713238132391324013241132421324313244132451324613247132481324913250132511325213253132541325513256132571325813259132601326113262132631326413265132661326713268132691327013271132721327313274132751327613277132781327913280132811328213283132841328513286132871328813289132901329113292132931329413295132961329713298132991330013301133021330313304133051330613307133081330913310133111331213313133141331513316133171331813319133201332113322133231332413325133261332713328133291333013331133321333313334133351333613337133381333913340133411334213343133441334513346133471334813349133501335113352133531335413355133561335713358133591336013361133621336313364133651336613367133681336913370133711337213373133741337513376133771337813379133801338113382133831338413385133861338713388133891339013391133921339313394133951339613397133981339913400134011340213403134041340513406134071340813409134101341113412134131341413415134161341713418134191342013421134221342313424134251342613427134281342913430134311343213433134341343513436134371343813439134401344113442134431344413445134461344713448134491345013451134521345313454134551345613457134581345913460134611346213463134641346513466134671346813469134701347113472134731347413475134761347713478134791348013481134821348313484134851348613487134881348913490134911349213493134941349513496134971349813499135001350113502135031350413505135061350713508135091351013511135121351313514135151351613517135181351913520135211352213523135241352513526135271352813529135301353113532135331353413535135361353713538135391354013541135421354313544135451354613547135481354913550135511355213553135541355513556135571355813559135601356113562135631356413565135661356713568135691357013571135721357313574135751357613577135781357913580135811358213583135841358513586135871358813589135901359113592135931359413595135961359713598135991360013601136021360313604136051360613607136081360913610136111361213613136141361513616136171361813619136201362113622136231362413625136261362713628136291363013631136321363313634136351363613637136381363913640136411364213643136441364513646136471364813649136501365113652136531365413655136561365713658136591366013661136621366313664136651366613667136681366913670136711367213673136741367513676136771367813679136801368113682136831368413685136861368713688136891369013691136921369313694136951369613697136981369913700137011370213703137041370513706137071370813709137101371113712137131371413715137161371713718137191372013721137221372313724137251372613727137281372913730137311373213733137341373513736137371373813739137401374113742137431374413745137461374713748137491375013751137521375313754137551375613757137581375913760137611376213763137641376513766137671376813769137701377113772137731377413775137761377713778137791378013781137821378313784137851378613787137881378913790137911379213793137941379513796137971379813799138001380113802138031380413805138061380713808138091381013811138121381313814138151381613817138181381913820138211382213823138241382513826138271382813829138301383113832138331383413835138361383713838138391384013841138421384313844138451384613847138481384913850138511385213853138541385513856138571385813859138601386113862138631386413865138661386713868138691387013871138721387313874138751387613877138781387913880138811388213883138841388513886138871388813889138901389113892138931389413895138961389713898138991390013901139021390313904139051390613907139081390913910139111391213913139141391513916139171391813919139201392113922139231392413925139261392713928139291393013931139321393313934139351393613937139381393913940139411394213943139441394513946139471394813949139501395113952139531395413955139561395713958139591396013961139621396313964139651396613967139681396913970139711397213973139741397513976139771397813979139801398113982139831398413985139861398713988139891399013991139921399313994139951399613997139981399914000140011400214003140041400514006140071400814009140101401114012140131401414015140161401714018140191402014021140221402314024140251402614027140281402914030140311403214033140341403514036140371403814039140401404114042140431404414045140461404714048140491405014051140521405314054140551405614057140581405914060140611406214063140641406514066140671406814069140701407114072140731407414075140761407714078140791408014081140821408314084140851408614087140881408914090140911409214093140941409514096140971409814099141001410114102141031410414105141061410714108141091411014111141121411314114141151411614117141181411914120141211412214123141241412514126141271412814129141301413114132141331413414135141361413714138141391414014141141421414314144141451414614147141481414914150141511415214153141541415514156141571415814159141601416114162141631416414165141661416714168141691417014171141721417314174141751417614177141781417914180141811418214183141841418514186141871418814189141901419114192141931419414195141961419714198141991420014201142021420314204142051420614207142081420914210142111421214213142141421514216142171421814219142201422114222142231422414225142261422714228142291423014231142321423314234142351423614237142381423914240142411424214243142441424514246142471424814249142501425114252142531425414255142561425714258142591426014261142621426314264142651426614267142681426914270142711427214273142741427514276142771427814279142801428114282142831428414285142861428714288142891429014291142921429314294142951429614297142981429914300143011430214303143041430514306143071430814309143101431114312143131431414315143161431714318143191432014321143221432314324143251432614327143281432914330143311433214333143341433514336143371433814339143401434114342143431434414345143461434714348143491435014351143521435314354143551435614357143581435914360143611436214363143641436514366143671436814369143701437114372143731437414375143761437714378143791438014381143821438314384143851438614387143881438914390143911439214393143941439514396143971439814399144001440114402144031440414405144061440714408144091441014411144121441314414144151441614417144181441914420144211442214423144241442514426144271442814429144301443114432144331443414435144361443714438144391444014441144421444314444144451444614447144481444914450144511445214453144541445514456144571445814459144601446114462144631446414465144661446714468144691447014471144721447314474144751447614477144781447914480144811448214483144841448514486144871448814489144901449114492144931449414495144961449714498144991450014501145021450314504145051450614507145081450914510145111451214513145141451514516145171451814519145201452114522145231452414525145261452714528145291453014531145321453314534145351453614537145381453914540145411454214543145441454514546145471454814549145501455114552145531455414555145561455714558145591456014561145621456314564145651456614567145681456914570145711457214573145741457514576145771457814579145801458114582145831458414585145861458714588145891459014591145921459314594145951459614597145981459914600146011460214603146041460514606146071460814609146101461114612146131461414615146161461714618146191462014621146221462314624146251462614627146281462914630146311463214633146341463514636146371463814639146401464114642146431464414645146461464714648146491465014651146521465314654146551465614657146581465914660146611466214663146641466514666146671466814669146701467114672146731467414675146761467714678146791468014681146821468314684146851468614687146881468914690146911469214693146941469514696146971469814699147001470114702147031470414705147061470714708147091471014711147121471314714147151471614717147181471914720147211472214723147241472514726147271472814729147301473114732147331473414735147361473714738147391474014741147421474314744147451474614747147481474914750147511475214753147541475514756147571475814759147601476114762147631476414765147661476714768147691477014771147721477314774147751477614777147781477914780147811478214783147841478514786147871478814789147901479114792147931479414795147961479714798147991480014801148021480314804148051480614807148081480914810148111481214813148141481514816148171481814819148201482114822148231482414825148261482714828148291483014831148321483314834148351483614837148381483914840148411484214843148441484514846148471484814849148501485114852148531485414855148561485714858148591486014861148621486314864148651486614867148681486914870148711487214873148741487514876148771487814879148801488114882148831488414885148861488714888148891489014891148921489314894148951489614897148981489914900149011490214903149041490514906149071490814909149101491114912149131491414915149161491714918149191492014921149221492314924149251492614927149281492914930149311493214933149341493514936149371493814939149401494114942149431494414945149461494714948149491495014951149521495314954149551495614957149581495914960149611496214963149641496514966149671496814969149701497114972149731497414975149761497714978149791498014981149821498314984149851498614987149881498914990149911499214993149941499514996149971499814999150001500115002150031500415005150061500715008150091501015011150121501315014150151501615017150181501915020150211502215023150241502515026150271502815029150301503115032150331503415035150361503715038150391504015041150421504315044150451504615047150481504915050150511505215053150541505515056150571505815059150601506115062150631506415065150661506715068150691507015071150721507315074150751507615077150781507915080150811508215083150841508515086150871508815089150901509115092150931509415095150961509715098150991510015101151021510315104151051510615107151081510915110151111511215113151141511515116151171511815119151201512115122151231512415125151261512715128151291513015131151321513315134151351513615137151381513915140151411514215143151441514515146151471514815149151501515115152151531515415155151561515715158151591516015161151621516315164151651516615167151681516915170151711517215173151741517515176151771517815179151801518115182151831518415185151861518715188151891519015191151921519315194151951519615197151981519915200152011520215203152041520515206152071520815209152101521115212152131521415215152161521715218152191522015221152221522315224152251522615227152281522915230152311523215233152341523515236152371523815239152401524115242152431524415245152461524715248152491525015251152521525315254152551525615257152581525915260152611526215263152641526515266152671526815269152701527115272152731527415275152761527715278152791528015281152821528315284152851528615287152881528915290152911529215293152941529515296152971529815299153001530115302153031530415305153061530715308153091531015311153121531315314153151531615317153181531915320153211532215323153241532515326153271532815329153301533115332153331533415335153361533715338153391534015341153421534315344153451534615347153481534915350153511535215353153541535515356153571535815359153601536115362153631536415365153661536715368153691537015371153721537315374153751537615377153781537915380153811538215383153841538515386153871538815389153901539115392153931539415395153961539715398153991540015401154021540315404154051540615407154081540915410154111541215413154141541515416154171541815419154201542115422154231542415425154261542715428154291543015431154321543315434154351543615437154381543915440154411544215443154441544515446154471544815449154501545115452154531545415455154561545715458154591546015461154621546315464154651546615467154681546915470154711547215473154741547515476154771547815479154801548115482154831548415485154861548715488154891549015491154921549315494154951549615497154981549915500155011550215503155041550515506155071550815509155101551115512155131551415515155161551715518155191552015521155221552315524155251552615527155281552915530155311553215533155341553515536155371553815539155401554115542155431554415545155461554715548155491555015551155521555315554155551555615557155581555915560155611556215563155641556515566155671556815569155701557115572155731557415575155761557715578155791558015581155821558315584155851558615587155881558915590155911559215593155941559515596155971559815599156001560115602156031560415605156061560715608156091561015611156121561315614156151561615617156181561915620156211562215623156241562515626156271562815629156301563115632156331563415635156361563715638156391564015641156421564315644156451564615647156481564915650156511565215653156541565515656156571565815659156601566115662156631566415665156661566715668156691567015671156721567315674156751567615677156781567915680156811568215683156841568515686156871568815689156901569115692156931569415695156961569715698156991570015701157021570315704157051570615707157081570915710157111571215713157141571515716157171571815719157201572115722157231572415725157261572715728157291573015731157321573315734157351573615737157381573915740157411574215743157441574515746157471574815749157501575115752157531575415755157561575715758157591576015761157621576315764157651576615767157681576915770157711577215773157741577515776157771577815779157801578115782157831578415785157861578715788157891579015791157921579315794157951579615797157981579915800158011580215803158041580515806158071580815809158101581115812158131581415815158161581715818158191582015821158221582315824158251582615827158281582915830158311583215833158341583515836158371583815839158401584115842158431584415845158461584715848158491585015851158521585315854158551585615857158581585915860158611586215863158641586515866158671586815869158701587115872158731587415875158761587715878158791588015881158821588315884158851588615887158881588915890158911589215893158941589515896158971589815899159001590115902159031590415905159061590715908159091591015911159121591315914159151591615917159181591915920159211592215923159241592515926159271592815929159301593115932159331593415935159361593715938159391594015941159421594315944159451594615947159481594915950159511595215953159541595515956159571595815959159601596115962159631596415965159661596715968159691597015971159721597315974159751597615977159781597915980159811598215983159841598515986159871598815989159901599115992159931599415995159961599715998159991600016001160021600316004160051600616007160081600916010160111601216013160141601516016160171601816019160201602116022160231602416025160261602716028160291603016031160321603316034160351603616037160381603916040160411604216043160441604516046160471604816049160501605116052160531605416055160561605716058160591606016061160621606316064160651606616067160681606916070160711607216073160741607516076160771607816079160801608116082160831608416085160861608716088160891609016091160921609316094160951609616097160981609916100161011610216103161041610516106161071610816109161101611116112161131611416115161161611716118161191612016121161221612316124161251612616127161281612916130161311613216133161341613516136161371613816139161401614116142161431614416145161461614716148161491615016151161521615316154161551615616157161581615916160161611616216163161641616516166161671616816169161701617116172161731617416175161761617716178161791618016181161821618316184161851618616187161881618916190161911619216193161941619516196161971619816199162001620116202162031620416205162061620716208162091621016211162121621316214162151621616217162181621916220162211622216223162241622516226162271622816229162301623116232162331623416235162361623716238162391624016241162421624316244162451624616247162481624916250162511625216253162541625516256162571625816259162601626116262162631626416265162661626716268162691627016271162721627316274162751627616277162781627916280162811628216283162841628516286162871628816289162901629116292162931629416295162961629716298162991630016301163021630316304163051630616307163081630916310163111631216313163141631516316163171631816319163201632116322163231632416325163261632716328163291633016331163321633316334163351633616337163381633916340163411634216343163441634516346163471634816349163501635116352163531635416355163561635716358163591636016361163621636316364163651636616367163681636916370163711637216373163741637516376163771637816379163801638116382163831638416385163861638716388163891639016391163921639316394163951639616397163981639916400164011640216403164041640516406164071640816409164101641116412164131641416415164161641716418164191642016421164221642316424164251642616427164281642916430164311643216433164341643516436164371643816439164401644116442164431644416445164461644716448164491645016451164521645316454164551645616457164581645916460164611646216463164641646516466164671646816469164701647116472164731647416475164761647716478164791648016481164821648316484164851648616487164881648916490164911649216493164941649516496164971649816499165001650116502165031650416505165061650716508165091651016511165121651316514165151651616517165181651916520165211652216523165241652516526165271652816529165301653116532165331653416535165361653716538165391654016541165421654316544165451654616547165481654916550165511655216553165541655516556165571655816559165601656116562165631656416565165661656716568165691657016571165721657316574165751657616577165781657916580165811658216583165841658516586165871658816589165901659116592165931659416595165961659716598165991660016601166021660316604166051660616607166081660916610166111661216613166141661516616166171661816619166201662116622166231662416625166261662716628166291663016631166321663316634166351663616637166381663916640166411664216643166441664516646166471664816649166501665116652166531665416655166561665716658166591666016661166621666316664166651666616667166681666916670166711667216673166741667516676166771667816679166801668116682166831668416685166861668716688166891669016691166921669316694166951669616697166981669916700167011670216703167041670516706167071670816709167101671116712167131671416715167161671716718167191672016721167221672316724167251672616727167281672916730167311673216733167341673516736167371673816739167401674116742167431674416745167461674716748167491675016751167521675316754167551675616757167581675916760167611676216763167641676516766167671676816769167701677116772167731677416775167761677716778167791678016781167821678316784167851678616787167881678916790167911679216793167941679516796167971679816799168001680116802168031680416805168061680716808168091681016811168121681316814168151681616817168181681916820168211682216823168241682516826168271682816829168301683116832168331683416835168361683716838168391684016841168421684316844168451684616847168481684916850168511685216853168541685516856168571685816859168601686116862168631686416865168661686716868168691687016871168721687316874168751687616877168781687916880168811688216883168841688516886168871688816889168901689116892168931689416895168961689716898168991690016901169021690316904169051690616907169081690916910169111691216913169141691516916169171691816919169201692116922169231692416925169261692716928169291693016931169321693316934169351693616937169381693916940169411694216943169441694516946169471694816949169501695116952169531695416955169561695716958169591696016961169621696316964169651696616967169681696916970169711697216973169741697516976169771697816979169801698116982169831698416985169861698716988169891699016991169921699316994169951699616997169981699917000170011700217003170041700517006170071700817009170101701117012170131701417015170161701717018170191702017021170221702317024170251702617027170281702917030170311703217033170341703517036170371703817039170401704117042170431704417045170461704717048170491705017051170521705317054170551705617057170581705917060170611706217063170641706517066170671706817069170701707117072170731707417075170761707717078170791708017081170821708317084170851708617087170881708917090170911709217093170941709517096170971709817099171001710117102171031710417105171061710717108171091711017111171121711317114171151711617117171181711917120171211712217123171241712517126171271712817129171301713117132171331713417135171361713717138171391714017141171421714317144171451714617147171481714917150171511715217153171541715517156171571715817159171601716117162171631716417165171661716717168171691717017171171721717317174171751717617177171781717917180171811718217183171841718517186171871718817189171901719117192171931719417195171961719717198171991720017201172021720317204172051720617207172081720917210172111721217213172141721517216172171721817219172201722117222172231722417225172261722717228172291723017231172321723317234172351723617237172381723917240172411724217243172441724517246172471724817249172501725117252172531725417255172561725717258172591726017261172621726317264172651726617267172681726917270172711727217273172741727517276172771727817279172801728117282172831728417285172861728717288172891729017291172921729317294172951729617297172981729917300173011730217303173041730517306173071730817309173101731117312173131731417315173161731717318173191732017321173221732317324173251732617327173281732917330173311733217333173341733517336173371733817339173401734117342173431734417345173461734717348173491735017351173521735317354173551735617357173581735917360173611736217363173641736517366173671736817369173701737117372173731737417375173761737717378173791738017381173821738317384173851738617387173881738917390173911739217393173941739517396173971739817399174001740117402174031740417405174061740717408174091741017411174121741317414174151741617417174181741917420174211742217423174241742517426174271742817429174301743117432174331743417435174361743717438174391744017441174421744317444174451744617447174481744917450174511745217453174541745517456174571745817459174601746117462174631746417465174661746717468174691747017471174721747317474174751747617477174781747917480174811748217483174841748517486174871748817489174901749117492174931749417495174961749717498174991750017501175021750317504175051750617507175081750917510175111751217513175141751517516175171751817519175201752117522175231752417525175261752717528175291753017531175321753317534175351753617537175381753917540175411754217543175441754517546175471754817549175501755117552175531755417555175561755717558175591756017561175621756317564175651756617567175681756917570175711757217573175741757517576175771757817579175801758117582175831758417585175861758717588175891759017591175921759317594175951759617597175981759917600176011760217603176041760517606176071760817609176101761117612176131761417615176161761717618176191762017621176221762317624176251762617627176281762917630176311763217633176341763517636176371763817639176401764117642176431764417645176461764717648176491765017651176521765317654176551765617657176581765917660176611766217663176641766517666176671766817669176701767117672176731767417675176761767717678176791768017681176821768317684176851768617687176881768917690176911769217693176941769517696176971769817699177001770117702177031770417705177061770717708177091771017711177121771317714177151771617717177181771917720177211772217723177241772517726177271772817729177301773117732177331773417735177361773717738177391774017741177421774317744177451774617747177481774917750177511775217753177541775517756177571775817759177601776117762177631776417765177661776717768177691777017771177721777317774177751777617777177781777917780177811778217783177841778517786177871778817789177901779117792177931779417795177961779717798177991780017801178021780317804178051780617807178081780917810178111781217813178141781517816178171781817819178201782117822178231782417825178261782717828178291783017831178321783317834178351783617837178381783917840178411784217843178441784517846178471784817849178501785117852178531785417855178561785717858178591786017861178621786317864178651786617867178681786917870178711787217873178741787517876178771787817879178801788117882178831788417885178861788717888178891789017891178921789317894178951789617897178981789917900179011790217903179041790517906179071790817909179101791117912179131791417915179161791717918179191792017921179221792317924179251792617927179281792917930179311793217933179341793517936179371793817939179401794117942179431794417945179461794717948179491795017951179521795317954179551795617957179581795917960179611796217963179641796517966179671796817969179701797117972179731797417975179761797717978179791798017981179821798317984179851798617987179881798917990179911799217993179941799517996179971799817999180001800118002180031800418005180061800718008180091801018011180121801318014180151801618017180181801918020180211802218023180241802518026180271802818029180301803118032180331803418035180361803718038180391804018041180421804318044180451804618047180481804918050180511805218053180541805518056180571805818059180601806118062180631806418065180661806718068180691807018071180721807318074180751807618077180781807918080180811808218083180841808518086180871808818089180901809118092180931809418095180961809718098180991810018101181021810318104181051810618107181081810918110181111811218113181141811518116181171811818119181201812118122181231812418125181261812718128181291813018131181321813318134181351813618137181381813918140181411814218143181441814518146181471814818149181501815118152181531815418155181561815718158181591816018161181621816318164181651816618167181681816918170181711817218173181741817518176181771817818179181801818118182181831818418185181861818718188181891819018191181921819318194181951819618197181981819918200182011820218203182041820518206182071820818209182101821118212182131821418215182161821718218182191822018221182221822318224182251822618227182281822918230182311823218233182341823518236182371823818239182401824118242182431824418245182461824718248182491825018251182521825318254182551825618257182581825918260182611826218263182641826518266182671826818269182701827118272182731827418275182761827718278182791828018281182821828318284182851828618287182881828918290182911829218293182941829518296182971829818299183001830118302183031830418305183061830718308183091831018311183121831318314183151831618317183181831918320183211832218323183241832518326183271832818329183301833118332183331833418335183361833718338183391834018341183421834318344183451834618347183481834918350183511835218353183541835518356183571835818359183601836118362183631836418365183661836718368183691837018371183721837318374183751837618377183781837918380183811838218383183841838518386183871838818389183901839118392183931839418395183961839718398183991840018401184021840318404184051840618407184081840918410184111841218413184141841518416184171841818419184201842118422184231842418425184261842718428184291843018431184321843318434184351843618437184381843918440184411844218443184441844518446184471844818449184501845118452184531845418455184561845718458184591846018461184621846318464184651846618467184681846918470184711847218473184741847518476184771847818479184801848118482184831848418485184861848718488184891849018491184921849318494184951849618497184981849918500185011850218503185041850518506185071850818509185101851118512185131851418515185161851718518185191852018521185221852318524185251852618527185281852918530185311853218533185341853518536185371853818539185401854118542185431854418545185461854718548185491855018551185521855318554185551855618557185581855918560185611856218563185641856518566185671856818569185701857118572185731857418575185761857718578185791858018581185821858318584185851858618587185881858918590185911859218593185941859518596185971859818599186001860118602186031860418605186061860718608186091861018611186121861318614186151861618617186181861918620186211862218623186241862518626186271862818629186301863118632186331863418635186361863718638186391864018641186421864318644186451864618647186481864918650186511865218653186541865518656186571865818659186601866118662186631866418665186661866718668186691867018671186721867318674186751867618677186781867918680186811868218683186841868518686186871868818689186901869118692186931869418695186961869718698186991870018701187021870318704187051870618707187081870918710187111871218713187141871518716187171871818719187201872118722187231872418725187261872718728187291873018731187321873318734187351873618737187381873918740187411874218743187441874518746187471874818749187501875118752187531875418755187561875718758187591876018761187621876318764187651876618767187681876918770187711877218773187741877518776187771877818779187801878118782187831878418785187861878718788187891879018791187921879318794187951879618797187981879918800188011880218803188041880518806188071880818809188101881118812188131881418815188161881718818188191882018821188221882318824188251882618827188281882918830188311883218833188341883518836188371883818839188401884118842188431884418845188461884718848188491885018851188521885318854188551885618857188581885918860188611886218863188641886518866188671886818869188701887118872188731887418875188761887718878188791888018881188821888318884188851888618887188881888918890188911889218893188941889518896188971889818899189001890118902189031890418905189061890718908189091891018911189121891318914189151891618917189181891918920189211892218923189241892518926189271892818929189301893118932189331893418935189361893718938189391894018941189421894318944189451894618947189481894918950189511895218953189541895518956189571895818959189601896118962189631896418965189661896718968189691897018971189721897318974189751897618977189781897918980189811898218983189841898518986189871898818989189901899118992189931899418995189961899718998189991900019001190021900319004190051900619007190081900919010190111901219013190141901519016190171901819019190201902119022190231902419025190261902719028190291903019031190321903319034190351903619037190381903919040190411904219043190441904519046190471904819049190501905119052190531905419055190561905719058190591906019061190621906319064190651906619067190681906919070190711907219073190741907519076190771907819079190801908119082190831908419085190861908719088190891909019091190921909319094190951909619097190981909919100191011910219103191041910519106191071910819109191101911119112191131911419115191161911719118191191912019121191221912319124191251912619127191281912919130191311913219133191341913519136191371913819139191401914119142191431914419145191461914719148191491915019151191521915319154191551915619157191581915919160191611916219163191641916519166191671916819169191701917119172191731917419175191761917719178191791918019181191821918319184191851918619187191881918919190191911919219193191941919519196191971919819199192001920119202192031920419205192061920719208192091921019211192121921319214192151921619217192181921919220192211922219223192241922519226192271922819229192301923119232192331923419235192361923719238192391924019241192421924319244192451924619247192481924919250192511925219253192541925519256192571925819259192601926119262192631926419265192661926719268192691927019271192721927319274192751927619277192781927919280192811928219283192841928519286192871928819289192901929119292192931929419295192961929719298192991930019301193021930319304193051930619307193081930919310193111931219313193141931519316193171931819319193201932119322193231932419325193261932719328193291933019331193321933319334193351933619337193381933919340193411934219343193441934519346193471934819349193501935119352193531935419355193561935719358193591936019361193621936319364193651936619367193681936919370193711937219373193741937519376193771937819379193801938119382193831938419385193861938719388193891939019391193921939319394193951939619397193981939919400194011940219403194041940519406194071940819409194101941119412194131941419415194161941719418194191942019421194221942319424194251942619427194281942919430194311943219433194341943519436194371943819439194401944119442194431944419445194461944719448194491945019451194521945319454194551945619457194581945919460194611946219463194641946519466194671946819469194701947119472194731947419475194761947719478194791948019481194821948319484194851948619487194881948919490194911949219493194941949519496194971949819499195001950119502195031950419505195061950719508195091951019511195121951319514195151951619517195181951919520195211952219523195241952519526195271952819529195301953119532195331953419535195361953719538195391954019541195421954319544195451954619547195481954919550195511955219553195541955519556195571955819559195601956119562195631956419565195661956719568195691957019571195721957319574195751957619577195781957919580195811958219583195841958519586195871958819589195901959119592195931959419595195961959719598195991960019601196021960319604196051960619607196081960919610196111961219613196141961519616196171961819619196201962119622196231962419625196261962719628196291963019631196321963319634196351963619637196381963919640196411964219643196441964519646196471964819649196501965119652196531965419655196561965719658196591966019661196621966319664196651966619667196681966919670196711967219673196741967519676196771967819679196801968119682196831968419685196861968719688196891969019691196921969319694196951969619697196981969919700197011970219703197041970519706197071970819709197101971119712197131971419715197161971719718197191972019721197221972319724197251972619727197281972919730197311973219733197341973519736197371973819739197401974119742197431974419745197461974719748197491975019751197521975319754197551975619757197581975919760197611976219763197641976519766197671976819769197701977119772197731977419775197761977719778197791978019781197821978319784197851978619787197881978919790197911979219793197941979519796197971979819799198001980119802198031980419805198061980719808198091981019811198121981319814198151981619817198181981919820198211982219823198241982519826198271982819829198301983119832198331983419835198361983719838198391984019841198421984319844198451984619847198481984919850198511985219853198541985519856198571985819859198601986119862198631986419865198661986719868198691987019871198721987319874198751987619877198781987919880198811988219883198841988519886198871988819889198901989119892198931989419895198961989719898198991990019901199021990319904199051990619907199081990919910199111991219913199141991519916199171991819919199201992119922199231992419925199261992719928199291993019931199321993319934199351993619937199381993919940199411994219943199441994519946199471994819949199501995119952199531995419955199561995719958199591996019961199621996319964199651996619967199681996919970199711997219973199741997519976199771997819979199801998119982199831998419985199861998719988199891999019991199921999319994199951999619997199981999920000200012000220003200042000520006200072000820009200102001120012200132001420015200162001720018200192002020021200222002320024200252002620027200282002920030200312003220033200342003520036200372003820039200402004120042200432004420045200462004720048200492005020051200522005320054200552005620057200582005920060200612006220063200642006520066200672006820069200702007120072200732007420075200762007720078200792008020081200822008320084200852008620087200882008920090200912009220093200942009520096200972009820099201002010120102201032010420105201062010720108201092011020111201122011320114201152011620117201182011920120201212012220123201242012520126201272012820129201302013120132201332013420135201362013720138201392014020141201422014320144201452014620147201482014920150201512015220153201542015520156201572015820159201602016120162201632016420165201662016720168201692017020171201722017320174201752017620177201782017920180201812018220183201842018520186201872018820189201902019120192201932019420195201962019720198201992020020201202022020320204202052020620207202082020920210202112021220213202142021520216202172021820219202202022120222202232022420225202262022720228202292023020231202322023320234202352023620237202382023920240202412024220243202442024520246202472024820249202502025120252202532025420255202562025720258202592026020261202622026320264202652026620267202682026920270202712027220273202742027520276202772027820279202802028120282202832028420285202862028720288202892029020291202922029320294202952029620297202982029920300203012030220303203042030520306203072030820309203102031120312203132031420315203162031720318203192032020321203222032320324203252032620327203282032920330203312033220333203342033520336203372033820339203402034120342203432034420345203462034720348203492035020351203522035320354203552035620357203582035920360203612036220363203642036520366203672036820369203702037120372203732037420375203762037720378203792038020381203822038320384203852038620387203882038920390203912039220393203942039520396203972039820399204002040120402204032040420405204062040720408204092041020411204122041320414204152041620417204182041920420204212042220423204242042520426204272042820429204302043120432204332043420435204362043720438204392044020441204422044320444204452044620447204482044920450204512045220453204542045520456204572045820459204602046120462204632046420465204662046720468204692047020471204722047320474204752047620477204782047920480204812048220483204842048520486204872048820489204902049120492204932049420495204962049720498204992050020501205022050320504205052050620507205082050920510205112051220513205142051520516205172051820519205202052120522205232052420525205262052720528205292053020531205322053320534205352053620537205382053920540205412054220543205442054520546205472054820549205502055120552205532055420555205562055720558205592056020561205622056320564205652056620567205682056920570205712057220573205742057520576205772057820579205802058120582205832058420585205862058720588205892059020591205922059320594205952059620597205982059920600206012060220603206042060520606206072060820609206102061120612206132061420615206162061720618206192062020621206222062320624206252062620627206282062920630206312063220633206342063520636206372063820639206402064120642206432064420645206462064720648206492065020651206522065320654206552065620657206582065920660206612066220663206642066520666206672066820669206702067120672206732067420675206762067720678206792068020681206822068320684206852068620687206882068920690206912069220693206942069520696206972069820699207002070120702207032070420705207062070720708207092071020711207122071320714207152071620717207182071920720207212072220723207242072520726207272072820729207302073120732207332073420735207362073720738207392074020741207422074320744207452074620747207482074920750207512075220753207542075520756207572075820759207602076120762207632076420765207662076720768207692077020771207722077320774207752077620777207782077920780207812078220783207842078520786207872078820789207902079120792207932079420795207962079720798207992080020801208022080320804208052080620807208082080920810208112081220813208142081520816208172081820819208202082120822208232082420825208262082720828208292083020831208322083320834208352083620837208382083920840208412084220843208442084520846208472084820849208502085120852208532085420855208562085720858208592086020861208622086320864208652086620867208682086920870208712087220873208742087520876208772087820879208802088120882208832088420885208862088720888208892089020891208922089320894208952089620897208982089920900209012090220903209042090520906209072090820909209102091120912209132091420915209162091720918209192092020921209222092320924209252092620927209282092920930209312093220933209342093520936209372093820939209402094120942209432094420945209462094720948209492095020951209522095320954209552095620957209582095920960209612096220963209642096520966209672096820969209702097120972209732097420975209762097720978209792098020981209822098320984209852098620987209882098920990209912099220993209942099520996209972099820999210002100121002210032100421005210062100721008210092101021011210122101321014210152101621017210182101921020210212102221023210242102521026210272102821029210302103121032210332103421035210362103721038210392104021041210422104321044210452104621047210482104921050210512105221053210542105521056210572105821059210602106121062210632106421065210662106721068210692107021071210722107321074210752107621077210782107921080210812108221083210842108521086210872108821089210902109121092210932109421095210962109721098210992110021101211022110321104211052110621107211082110921110211112111221113211142111521116211172111821119211202112121122211232112421125211262112721128211292113021131211322113321134211352113621137211382113921140211412114221143211442114521146211472114821149211502115121152211532115421155211562115721158211592116021161211622116321164211652116621167211682116921170211712117221173211742117521176211772117821179211802118121182211832118421185211862118721188211892119021191211922119321194211952119621197211982119921200212012120221203212042120521206212072120821209212102121121212212132121421215212162121721218212192122021221212222122321224212252122621227212282122921230212312123221233212342123521236212372123821239212402124121242212432124421245212462124721248212492125021251212522125321254212552125621257212582125921260212612126221263212642126521266212672126821269212702127121272212732127421275212762127721278212792128021281212822128321284212852128621287212882128921290212912129221293212942129521296212972129821299213002130121302213032130421305213062130721308213092131021311213122131321314213152131621317213182131921320213212132221323213242132521326213272132821329213302133121332213332133421335213362133721338213392134021341213422134321344213452134621347213482134921350213512135221353213542135521356213572135821359213602136121362213632136421365213662136721368213692137021371213722137321374213752137621377213782137921380213812138221383213842138521386213872138821389213902139121392213932139421395213962139721398213992140021401214022140321404214052140621407214082140921410214112141221413214142141521416214172141821419214202142121422214232142421425214262142721428214292143021431214322143321434214352143621437214382143921440214412144221443214442144521446214472144821449214502145121452214532145421455214562145721458214592146021461214622146321464214652146621467214682146921470214712147221473214742147521476214772147821479214802148121482214832148421485214862148721488214892149021491214922149321494214952149621497214982149921500215012150221503215042150521506215072150821509215102151121512215132151421515215162151721518215192152021521215222152321524215252152621527215282152921530215312153221533215342153521536215372153821539215402154121542215432154421545215462154721548215492155021551215522155321554215552155621557215582155921560215612156221563215642156521566215672156821569215702157121572215732157421575215762157721578215792158021581215822158321584215852158621587215882158921590215912159221593215942159521596215972159821599216002160121602216032160421605216062160721608216092161021611216122161321614216152161621617216182161921620216212162221623216242162521626216272162821629216302163121632216332163421635216362163721638216392164021641216422164321644216452164621647216482164921650216512165221653216542165521656216572165821659216602166121662216632166421665216662166721668216692167021671216722167321674216752167621677216782167921680216812168221683216842168521686216872168821689216902169121692216932169421695216962169721698216992170021701217022170321704217052170621707217082170921710217112171221713217142171521716217172171821719217202172121722217232172421725217262172721728217292173021731217322173321734217352173621737217382173921740217412174221743217442174521746217472174821749217502175121752217532175421755217562175721758217592176021761217622176321764217652176621767217682176921770217712177221773217742177521776217772177821779217802178121782217832178421785217862178721788217892179021791217922179321794217952179621797217982179921800218012180221803218042180521806218072180821809218102181121812218132181421815218162181721818218192182021821218222182321824218252182621827218282182921830218312183221833218342183521836218372183821839218402184121842218432184421845218462184721848218492185021851218522185321854218552185621857218582185921860218612186221863218642186521866218672186821869218702187121872218732187421875218762187721878218792188021881218822188321884218852188621887218882188921890218912189221893218942189521896218972189821899219002190121902219032190421905219062190721908219092191021911219122191321914219152191621917219182191921920219212192221923219242192521926219272192821929219302193121932219332193421935219362193721938219392194021941219422194321944219452194621947219482194921950219512195221953219542195521956219572195821959219602196121962219632196421965219662196721968219692197021971219722197321974219752197621977219782197921980219812198221983219842198521986219872198821989219902199121992219932199421995219962199721998219992200022001220022200322004220052200622007220082200922010220112201222013220142201522016220172201822019220202202122022220232202422025220262202722028220292203022031220322203322034220352203622037220382203922040220412204222043220442204522046220472204822049220502205122052220532205422055220562205722058220592206022061220622206322064220652206622067220682206922070220712207222073220742207522076220772207822079220802208122082220832208422085220862208722088220892209022091220922209322094220952209622097220982209922100221012210222103221042210522106221072210822109221102211122112221132211422115221162211722118221192212022121221222212322124221252212622127221282212922130221312213222133221342213522136221372213822139221402214122142221432214422145221462214722148221492215022151221522215322154221552215622157221582215922160221612216222163221642216522166221672216822169221702217122172221732217422175221762217722178221792218022181221822218322184221852218622187221882218922190221912219222193221942219522196221972219822199222002220122202222032220422205222062220722208222092221022211222122221322214222152221622217222182221922220222212222222223222242222522226222272222822229222302223122232222332223422235222362223722238222392224022241222422224322244222452224622247222482224922250222512225222253222542225522256222572225822259222602226122262222632226422265222662226722268222692227022271222722227322274222752227622277222782227922280222812228222283222842228522286222872228822289222902229122292222932229422295222962229722298222992230022301223022230322304223052230622307223082230922310223112231222313223142231522316223172231822319223202232122322223232232422325223262232722328223292233022331223322233322334223352233622337223382233922340223412234222343223442234522346223472234822349223502235122352223532235422355223562235722358223592236022361223622236322364223652236622367223682236922370223712237222373223742237522376223772237822379223802238122382223832238422385223862238722388223892239022391223922239322394223952239622397223982239922400224012240222403224042240522406224072240822409224102241122412224132241422415224162241722418224192242022421224222242322424224252242622427224282242922430224312243222433224342243522436224372243822439224402244122442224432244422445224462244722448224492245022451224522245322454224552245622457224582245922460224612246222463224642246522466224672246822469224702247122472224732247422475224762247722478224792248022481224822248322484224852248622487224882248922490224912249222493224942249522496224972249822499225002250122502225032250422505225062250722508225092251022511225122251322514225152251622517225182251922520225212252222523225242252522526225272252822529225302253122532225332253422535225362253722538225392254022541225422254322544225452254622547225482254922550225512255222553225542255522556225572255822559225602256122562225632256422565225662256722568225692257022571225722257322574225752257622577225782257922580225812258222583225842258522586225872258822589225902259122592225932259422595225962259722598225992260022601226022260322604226052260622607226082260922610226112261222613226142261522616226172261822619226202262122622226232262422625226262262722628226292263022631226322263322634226352263622637226382263922640226412264222643226442264522646226472264822649226502265122652226532265422655226562265722658226592266022661226622266322664226652266622667226682266922670226712267222673226742267522676226772267822679226802268122682226832268422685226862268722688226892269022691226922269322694226952269622697226982269922700227012270222703227042270522706227072270822709227102271122712227132271422715227162271722718227192272022721227222272322724227252272622727227282272922730227312273222733227342273522736227372273822739227402274122742227432274422745227462274722748227492275022751227522275322754227552275622757227582275922760227612276222763227642276522766227672276822769227702277122772227732277422775227762277722778227792278022781227822278322784227852278622787227882278922790227912279222793227942279522796227972279822799228002280122802228032280422805228062280722808228092281022811228122281322814228152281622817228182281922820228212282222823228242282522826228272282822829228302283122832228332283422835228362283722838228392284022841228422284322844228452284622847228482284922850228512285222853228542285522856228572285822859228602286122862228632286422865228662286722868228692287022871228722287322874228752287622877228782287922880228812288222883228842288522886228872288822889228902289122892228932289422895228962289722898228992290022901229022290322904229052290622907229082290922910229112291222913229142291522916229172291822919229202292122922229232292422925229262292722928229292293022931229322293322934229352293622937229382293922940229412294222943229442294522946229472294822949229502295122952229532295422955229562295722958229592296022961229622296322964229652296622967229682296922970229712297222973229742297522976229772297822979229802298122982229832298422985229862298722988229892299022991229922299322994229952299622997229982299923000230012300223003230042300523006230072300823009230102301123012230132301423015230162301723018230192302023021230222302323024230252302623027230282302923030230312303223033230342303523036230372303823039230402304123042230432304423045230462304723048230492305023051230522305323054230552305623057230582305923060230612306223063230642306523066230672306823069230702307123072230732307423075230762307723078230792308023081230822308323084230852308623087230882308923090230912309223093230942309523096230972309823099231002310123102231032310423105231062310723108231092311023111231122311323114231152311623117231182311923120231212312223123231242312523126231272312823129231302313123132231332313423135231362313723138231392314023141231422314323144231452314623147231482314923150231512315223153231542315523156231572315823159231602316123162231632316423165231662316723168231692317023171231722317323174231752317623177231782317923180231812318223183231842318523186231872318823189231902319123192231932319423195231962319723198231992320023201232022320323204232052320623207232082320923210232112321223213232142321523216232172321823219232202322123222232232322423225232262322723228232292323023231232322323323234232352323623237232382323923240232412324223243232442324523246232472324823249232502325123252232532325423255232562325723258232592326023261232622326323264232652326623267232682326923270232712327223273232742327523276232772327823279232802328123282232832328423285232862328723288232892329023291232922329323294232952329623297232982329923300233012330223303233042330523306233072330823309233102331123312233132331423315233162331723318233192332023321233222332323324233252332623327233282332923330233312333223333233342333523336233372333823339233402334123342233432334423345233462334723348233492335023351233522335323354233552335623357233582335923360233612336223363233642336523366233672336823369233702337123372233732337423375233762337723378233792338023381233822338323384233852338623387233882338923390233912339223393233942339523396233972339823399234002340123402234032340423405234062340723408234092341023411234122341323414234152341623417234182341923420234212342223423234242342523426234272342823429234302343123432234332343423435234362343723438234392344023441234422344323444234452344623447234482344923450234512345223453234542345523456234572345823459234602346123462234632346423465234662346723468234692347023471234722347323474234752347623477234782347923480234812348223483234842348523486234872348823489234902349123492234932349423495234962349723498234992350023501235022350323504235052350623507235082350923510235112351223513235142351523516235172351823519235202352123522235232352423525235262352723528235292353023531235322353323534235352353623537235382353923540235412354223543235442354523546235472354823549235502355123552235532355423555235562355723558235592356023561235622356323564235652356623567235682356923570235712357223573235742357523576235772357823579235802358123582235832358423585235862358723588235892359023591235922359323594235952359623597235982359923600236012360223603236042360523606236072360823609236102361123612236132361423615236162361723618236192362023621236222362323624236252362623627236282362923630236312363223633236342363523636236372363823639236402364123642236432364423645236462364723648236492365023651236522365323654236552365623657236582365923660236612366223663236642366523666236672366823669236702367123672236732367423675236762367723678236792368023681236822368323684236852368623687236882368923690236912369223693236942369523696236972369823699237002370123702237032370423705237062370723708237092371023711237122371323714237152371623717237182371923720237212372223723237242372523726237272372823729237302373123732237332373423735237362373723738237392374023741237422374323744237452374623747237482374923750237512375223753237542375523756237572375823759237602376123762237632376423765237662376723768237692377023771237722377323774237752377623777237782377923780237812378223783237842378523786237872378823789237902379123792237932379423795237962379723798237992380023801238022380323804238052380623807238082380923810238112381223813238142381523816238172381823819238202382123822238232382423825238262382723828238292383023831238322383323834238352383623837238382383923840238412384223843238442384523846238472384823849238502385123852238532385423855238562385723858238592386023861238622386323864238652386623867238682386923870238712387223873238742387523876238772387823879238802388123882238832388423885238862388723888238892389023891238922389323894238952389623897238982389923900239012390223903239042390523906239072390823909239102391123912239132391423915239162391723918239192392023921239222392323924239252392623927239282392923930239312393223933239342393523936239372393823939239402394123942239432394423945239462394723948239492395023951239522395323954239552395623957239582395923960239612396223963239642396523966239672396823969239702397123972239732397423975239762397723978239792398023981239822398323984239852398623987239882398923990239912399223993239942399523996239972399823999240002400124002240032400424005240062400724008240092401024011240122401324014240152401624017240182401924020240212402224023240242402524026240272402824029240302403124032240332403424035240362403724038240392404024041240422404324044240452404624047240482404924050240512405224053240542405524056240572405824059240602406124062240632406424065240662406724068240692407024071240722407324074240752407624077240782407924080240812408224083240842408524086240872408824089240902409124092240932409424095240962409724098240992410024101241022410324104241052410624107241082410924110241112411224113241142411524116241172411824119241202412124122241232412424125241262412724128241292413024131241322413324134241352413624137241382413924140241412414224143241442414524146241472414824149241502415124152241532415424155241562415724158241592416024161241622416324164241652416624167241682416924170241712417224173241742417524176241772417824179241802418124182241832418424185241862418724188241892419024191241922419324194241952419624197241982419924200242012420224203242042420524206242072420824209242102421124212242132421424215242162421724218242192422024221242222422324224242252422624227242282422924230242312423224233242342423524236242372423824239242402424124242242432424424245242462424724248242492425024251242522425324254242552425624257242582425924260242612426224263242642426524266242672426824269242702427124272242732427424275242762427724278242792428024281242822428324284242852428624287242882428924290242912429224293242942429524296242972429824299243002430124302243032430424305243062430724308243092431024311243122431324314243152431624317243182431924320243212432224323243242432524326243272432824329243302433124332243332433424335243362433724338243392434024341243422434324344243452434624347243482434924350243512435224353243542435524356243572435824359243602436124362243632436424365243662436724368243692437024371243722437324374243752437624377243782437924380243812438224383243842438524386243872438824389243902439124392243932439424395243962439724398243992440024401244022440324404244052440624407244082440924410244112441224413244142441524416244172441824419244202442124422244232442424425244262442724428244292443024431244322443324434244352443624437244382443924440244412444224443244442444524446244472444824449244502445124452244532445424455244562445724458244592446024461244622446324464244652446624467244682446924470244712447224473244742447524476244772447824479244802448124482244832448424485244862448724488244892449024491244922449324494244952449624497244982449924500245012450224503245042450524506245072450824509245102451124512245132451424515245162451724518245192452024521245222452324524245252452624527245282452924530245312453224533245342453524536245372453824539245402454124542245432454424545245462454724548245492455024551245522455324554245552455624557245582455924560245612456224563245642456524566245672456824569245702457124572245732457424575245762457724578245792458024581245822458324584245852458624587245882458924590245912459224593245942459524596245972459824599246002460124602246032460424605246062460724608246092461024611246122461324614246152461624617246182461924620246212462224623246242462524626246272462824629246302463124632246332463424635246362463724638246392464024641246422464324644246452464624647246482464924650246512465224653246542465524656246572465824659246602466124662246632466424665246662466724668246692467024671246722467324674246752467624677246782467924680246812468224683246842468524686246872468824689246902469124692246932469424695246962469724698246992470024701247022470324704247052470624707247082470924710247112471224713247142471524716247172471824719247202472124722247232472424725247262472724728247292473024731247322473324734247352473624737247382473924740247412474224743247442474524746247472474824749247502475124752247532475424755247562475724758247592476024761247622476324764247652476624767247682476924770247712477224773247742477524776247772477824779247802478124782247832478424785247862478724788247892479024791247922479324794247952479624797247982479924800248012480224803248042480524806248072480824809248102481124812248132481424815248162481724818248192482024821248222482324824248252482624827248282482924830248312483224833248342483524836248372483824839248402484124842248432484424845248462484724848248492485024851248522485324854248552485624857248582485924860248612486224863248642486524866248672486824869248702487124872248732487424875248762487724878248792488024881248822488324884248852488624887248882488924890248912489224893248942489524896248972489824899249002490124902249032490424905249062490724908249092491024911249122491324914249152491624917249182491924920249212492224923249242492524926249272492824929249302493124932249332493424935249362493724938249392494024941249422494324944249452494624947249482494924950249512495224953249542495524956249572495824959249602496124962249632496424965249662496724968249692497024971249722497324974249752497624977249782497924980249812498224983249842498524986249872498824989249902499124992249932499424995249962499724998249992500025001250022500325004250052500625007250082500925010250112501225013250142501525016250172501825019250202502125022250232502425025250262502725028250292503025031250322503325034250352503625037250382503925040250412504225043250442504525046250472504825049250502505125052250532505425055250562505725058250592506025061250622506325064250652506625067250682506925070250712507225073250742507525076250772507825079250802508125082250832508425085250862508725088250892509025091250922509325094250952509625097250982509925100251012510225103251042510525106251072510825109251102511125112251132511425115251162511725118251192512025121251222512325124251252512625127251282512925130251312513225133251342513525136251372513825139251402514125142251432514425145251462514725148251492515025151251522515325154251552515625157251582515925160251612516225163251642516525166251672516825169251702517125172251732517425175251762517725178251792518025181251822518325184251852518625187251882518925190251912519225193251942519525196251972519825199252002520125202252032520425205252062520725208252092521025211252122521325214252152521625217252182521925220252212522225223252242522525226252272522825229252302523125232252332523425235252362523725238252392524025241252422524325244252452524625247252482524925250252512525225253252542525525256252572525825259252602526125262252632526425265252662526725268252692527025271252722527325274252752527625277252782527925280252812528225283252842528525286252872528825289252902529125292252932529425295252962529725298252992530025301253022530325304253052530625307253082530925310253112531225313253142531525316253172531825319253202532125322253232532425325253262532725328253292533025331253322533325334253352533625337253382533925340253412534225343253442534525346253472534825349253502535125352253532535425355253562535725358253592536025361253622536325364253652536625367253682536925370253712537225373253742537525376253772537825379253802538125382253832538425385253862538725388253892539025391253922539325394253952539625397253982539925400254012540225403254042540525406254072540825409254102541125412254132541425415254162541725418254192542025421254222542325424254252542625427254282542925430254312543225433254342543525436254372543825439254402544125442254432544425445254462544725448254492545025451254522545325454254552545625457254582545925460254612546225463254642546525466254672546825469254702547125472254732547425475254762547725478254792548025481254822548325484254852548625487254882548925490254912549225493254942549525496254972549825499255002550125502255032550425505255062550725508255092551025511255122551325514255152551625517255182551925520255212552225523255242552525526255272552825529255302553125532255332553425535255362553725538255392554025541255422554325544255452554625547255482554925550255512555225553255542555525556255572555825559255602556125562255632556425565255662556725568255692557025571255722557325574255752557625577255782557925580255812558225583255842558525586255872558825589255902559125592255932559425595255962559725598255992560025601256022560325604256052560625607256082560925610256112561225613256142561525616256172561825619256202562125622256232562425625256262562725628256292563025631256322563325634256352563625637256382563925640256412564225643256442564525646256472564825649256502565125652256532565425655256562565725658256592566025661256622566325664256652566625667256682566925670256712567225673256742567525676256772567825679256802568125682256832568425685256862568725688256892569025691256922569325694256952569625697256982569925700257012570225703257042570525706257072570825709257102571125712257132571425715257162571725718257192572025721257222572325724257252572625727257282572925730257312573225733257342573525736257372573825739257402574125742257432574425745257462574725748257492575025751257522575325754257552575625757257582575925760257612576225763257642576525766257672576825769257702577125772257732577425775257762577725778257792578025781257822578325784257852578625787257882578925790257912579225793257942579525796257972579825799258002580125802258032580425805258062580725808258092581025811258122581325814258152581625817258182581925820258212582225823258242582525826258272582825829258302583125832258332583425835258362583725838258392584025841258422584325844258452584625847258482584925850258512585225853258542585525856258572585825859258602586125862258632586425865258662586725868258692587025871258722587325874258752587625877258782587925880258812588225883258842588525886258872588825889258902589125892258932589425895258962589725898258992590025901259022590325904259052590625907259082590925910259112591225913259142591525916259172591825919259202592125922259232592425925259262592725928259292593025931259322593325934259352593625937259382593925940259412594225943259442594525946259472594825949259502595125952259532595425955259562595725958259592596025961259622596325964259652596625967259682596925970259712597225973259742597525976259772597825979259802598125982259832598425985259862598725988259892599025991259922599325994259952599625997259982599926000260012600226003260042600526006260072600826009260102601126012260132601426015260162601726018260192602026021260222602326024260252602626027260282602926030260312603226033260342603526036260372603826039260402604126042260432604426045260462604726048260492605026051260522605326054260552605626057260582605926060260612606226063260642606526066260672606826069260702607126072260732607426075260762607726078260792608026081260822608326084260852608626087260882608926090260912609226093260942609526096260972609826099261002610126102261032610426105261062610726108261092611026111261122611326114261152611626117261182611926120261212612226123261242612526126261272612826129261302613126132261332613426135261362613726138261392614026141261422614326144261452614626147261482614926150261512615226153261542615526156261572615826159261602616126162261632616426165261662616726168261692617026171261722617326174261752617626177261782617926180261812618226183261842618526186261872618826189261902619126192261932619426195261962619726198261992620026201262022620326204262052620626207262082620926210262112621226213262142621526216262172621826219262202622126222262232622426225262262622726228262292623026231262322623326234262352623626237262382623926240262412624226243262442624526246262472624826249262502625126252262532625426255262562625726258262592626026261262622626326264262652626626267262682626926270262712627226273262742627526276262772627826279262802628126282262832628426285262862628726288262892629026291262922629326294262952629626297262982629926300263012630226303263042630526306263072630826309263102631126312263132631426315263162631726318263192632026321263222632326324263252632626327263282632926330263312633226333263342633526336263372633826339263402634126342263432634426345263462634726348263492635026351263522635326354263552635626357263582635926360263612636226363263642636526366263672636826369263702637126372263732637426375263762637726378263792638026381263822638326384263852638626387263882638926390263912639226393263942639526396263972639826399264002640126402264032640426405264062640726408264092641026411264122641326414264152641626417264182641926420264212642226423264242642526426264272642826429264302643126432264332643426435264362643726438264392644026441264422644326444264452644626447264482644926450264512645226453264542645526456264572645826459264602646126462264632646426465264662646726468264692647026471264722647326474264752647626477264782647926480264812648226483264842648526486264872648826489264902649126492264932649426495264962649726498264992650026501265022650326504265052650626507265082650926510265112651226513265142651526516265172651826519265202652126522265232652426525265262652726528265292653026531265322653326534265352653626537265382653926540265412654226543265442654526546265472654826549265502655126552265532655426555265562655726558265592656026561265622656326564265652656626567265682656926570265712657226573265742657526576265772657826579265802658126582265832658426585265862658726588265892659026591265922659326594265952659626597265982659926600266012660226603266042660526606266072660826609266102661126612266132661426615266162661726618266192662026621266222662326624266252662626627266282662926630266312663226633266342663526636266372663826639266402664126642266432664426645266462664726648266492665026651266522665326654266552665626657266582665926660266612666226663266642666526666266672666826669266702667126672266732667426675266762667726678266792668026681266822668326684266852668626687266882668926690266912669226693266942669526696266972669826699267002670126702267032670426705267062670726708267092671026711267122671326714267152671626717267182671926720267212672226723267242672526726267272672826729267302673126732267332673426735267362673726738267392674026741267422674326744267452674626747267482674926750267512675226753267542675526756267572675826759267602676126762267632676426765267662676726768267692677026771267722677326774267752677626777267782677926780267812678226783267842678526786267872678826789267902679126792267932679426795267962679726798267992680026801268022680326804268052680626807268082680926810268112681226813268142681526816268172681826819268202682126822268232682426825268262682726828268292683026831268322683326834268352683626837268382683926840268412684226843268442684526846268472684826849268502685126852268532685426855268562685726858268592686026861268622686326864268652686626867268682686926870268712687226873268742687526876268772687826879268802688126882268832688426885268862688726888268892689026891268922689326894268952689626897268982689926900269012690226903269042690526906269072690826909269102691126912269132691426915269162691726918269192692026921269222692326924269252692626927269282692926930269312693226933269342693526936269372693826939269402694126942269432694426945269462694726948269492695026951269522695326954269552695626957269582695926960269612696226963269642696526966269672696826969269702697126972269732697426975269762697726978269792698026981269822698326984269852698626987269882698926990269912699226993269942699526996269972699826999270002700127002270032700427005270062700727008270092701027011270122701327014270152701627017270182701927020270212702227023270242702527026270272702827029270302703127032270332703427035270362703727038270392704027041270422704327044270452704627047270482704927050270512705227053270542705527056270572705827059270602706127062270632706427065270662706727068270692707027071270722707327074270752707627077270782707927080270812708227083270842708527086270872708827089270902709127092270932709427095270962709727098270992710027101271022710327104271052710627107271082710927110271112711227113271142711527116271172711827119271202712127122271232712427125271262712727128271292713027131271322713327134271352713627137271382713927140271412714227143271442714527146271472714827149271502715127152271532715427155271562715727158271592716027161271622716327164271652716627167271682716927170271712717227173271742717527176271772717827179271802718127182271832718427185271862718727188271892719027191271922719327194271952719627197271982719927200272012720227203272042720527206272072720827209272102721127212272132721427215272162721727218272192722027221272222722327224272252722627227272282722927230272312723227233272342723527236272372723827239272402724127242272432724427245272462724727248272492725027251272522725327254272552725627257272582725927260272612726227263272642726527266272672726827269272702727127272272732727427275272762727727278272792728027281272822728327284272852728627287272882728927290272912729227293272942729527296272972729827299273002730127302273032730427305273062730727308273092731027311273122731327314273152731627317273182731927320273212732227323273242732527326273272732827329273302733127332273332733427335273362733727338273392734027341273422734327344273452734627347273482734927350273512735227353273542735527356273572735827359273602736127362273632736427365273662736727368273692737027371273722737327374273752737627377273782737927380273812738227383273842738527386273872738827389273902739127392273932739427395273962739727398273992740027401274022740327404274052740627407274082740927410274112741227413274142741527416274172741827419274202742127422274232742427425274262742727428274292743027431274322743327434274352743627437274382743927440274412744227443274442744527446274472744827449274502745127452274532745427455274562745727458274592746027461274622746327464274652746627467274682746927470274712747227473274742747527476274772747827479274802748127482274832748427485274862748727488274892749027491274922749327494274952749627497274982749927500275012750227503275042750527506275072750827509275102751127512275132751427515275162751727518275192752027521275222752327524275252752627527275282752927530275312753227533275342753527536275372753827539275402754127542275432754427545275462754727548275492755027551275522755327554275552755627557275582755927560275612756227563275642756527566275672756827569275702757127572275732757427575275762757727578275792758027581275822758327584275852758627587275882758927590275912759227593275942759527596275972759827599276002760127602276032760427605276062760727608276092761027611276122761327614276152761627617276182761927620276212762227623276242762527626276272762827629276302763127632276332763427635276362763727638276392764027641276422764327644276452764627647276482764927650276512765227653276542765527656276572765827659276602766127662276632766427665276662766727668276692767027671276722767327674276752767627677276782767927680276812768227683276842768527686276872768827689276902769127692276932769427695276962769727698276992770027701277022770327704277052770627707277082770927710277112771227713277142771527716277172771827719277202772127722277232772427725277262772727728277292773027731277322773327734277352773627737277382773927740277412774227743277442774527746277472774827749277502775127752277532775427755277562775727758277592776027761277622776327764277652776627767277682776927770277712777227773277742777527776277772777827779277802778127782277832778427785277862778727788277892779027791277922779327794277952779627797277982779927800278012780227803278042780527806278072780827809278102781127812278132781427815278162781727818278192782027821278222782327824278252782627827278282782927830278312783227833278342783527836278372783827839278402784127842278432784427845278462784727848278492785027851278522785327854278552785627857278582785927860278612786227863278642786527866278672786827869278702787127872278732787427875278762787727878278792788027881278822788327884278852788627887278882788927890278912789227893278942789527896278972789827899279002790127902279032790427905279062790727908279092791027911279122791327914279152791627917279182791927920279212792227923279242792527926279272792827929279302793127932279332793427935279362793727938279392794027941279422794327944279452794627947279482794927950279512795227953279542795527956279572795827959279602796127962279632796427965279662796727968279692797027971279722797327974279752797627977279782797927980279812798227983279842798527986279872798827989279902799127992279932799427995279962799727998279992800028001280022800328004280052800628007280082800928010280112801228013280142801528016280172801828019280202802128022280232802428025280262802728028280292803028031280322803328034280352803628037280382803928040280412804228043280442804528046280472804828049280502805128052280532805428055280562805728058280592806028061280622806328064280652806628067280682806928070280712807228073280742807528076280772807828079280802808128082280832808428085280862808728088280892809028091280922809328094280952809628097280982809928100281012810228103281042810528106281072810828109281102811128112281132811428115281162811728118281192812028121281222812328124281252812628127281282812928130281312813228133281342813528136281372813828139281402814128142281432814428145281462814728148281492815028151281522815328154281552815628157281582815928160281612816228163281642816528166281672816828169281702817128172281732817428175281762817728178281792818028181281822818328184281852818628187281882818928190281912819228193281942819528196281972819828199282002820128202282032820428205282062820728208282092821028211282122821328214282152821628217282182821928220282212822228223282242822528226282272822828229282302823128232282332823428235282362823728238282392824028241282422824328244282452824628247282482824928250282512825228253282542825528256282572825828259282602826128262282632826428265282662826728268282692827028271282722827328274282752827628277282782827928280282812828228283282842828528286282872828828289282902829128292282932829428295282962829728298282992830028301283022830328304283052830628307283082830928310283112831228313283142831528316283172831828319283202832128322283232832428325283262832728328283292833028331283322833328334283352833628337283382833928340283412834228343283442834528346283472834828349283502835128352283532835428355283562835728358283592836028361283622836328364283652836628367283682836928370283712837228373283742837528376283772837828379283802838128382283832838428385283862838728388283892839028391283922839328394283952839628397283982839928400284012840228403284042840528406284072840828409284102841128412284132841428415284162841728418284192842028421284222842328424284252842628427284282842928430284312843228433284342843528436284372843828439284402844128442284432844428445284462844728448284492845028451284522845328454284552845628457284582845928460284612846228463284642846528466284672846828469284702847128472284732847428475284762847728478284792848028481284822848328484284852848628487284882848928490284912849228493284942849528496284972849828499285002850128502285032850428505285062850728508285092851028511285122851328514285152851628517285182851928520285212852228523285242852528526285272852828529285302853128532285332853428535285362853728538285392854028541285422854328544285452854628547285482854928550285512855228553285542855528556285572855828559285602856128562285632856428565285662856728568285692857028571285722857328574285752857628577285782857928580285812858228583285842858528586285872858828589285902859128592285932859428595285962859728598285992860028601286022860328604286052860628607286082860928610286112861228613286142861528616286172861828619286202862128622286232862428625286262862728628286292863028631286322863328634286352863628637286382863928640286412864228643286442864528646286472864828649286502865128652286532865428655286562865728658286592866028661286622866328664286652866628667286682866928670286712867228673286742867528676286772867828679286802868128682286832868428685286862868728688286892869028691286922869328694286952869628697286982869928700287012870228703287042870528706287072870828709287102871128712287132871428715287162871728718287192872028721287222872328724287252872628727287282872928730287312873228733287342873528736287372873828739287402874128742287432874428745287462874728748287492875028751287522875328754287552875628757287582875928760287612876228763287642876528766287672876828769287702877128772287732877428775287762877728778287792878028781287822878328784287852878628787287882878928790287912879228793287942879528796287972879828799288002880128802288032880428805288062880728808288092881028811288122881328814288152881628817288182881928820288212882228823288242882528826288272882828829288302883128832288332883428835288362883728838288392884028841288422884328844288452884628847288482884928850288512885228853288542885528856288572885828859288602886128862288632886428865288662886728868288692887028871288722887328874288752887628877288782887928880288812888228883288842888528886288872888828889288902889128892288932889428895288962889728898288992890028901289022890328904289052890628907289082890928910289112891228913289142891528916289172891828919289202892128922289232892428925289262892728928289292893028931289322893328934289352893628937289382893928940289412894228943289442894528946289472894828949289502895128952289532895428955289562895728958289592896028961289622896328964289652896628967289682896928970289712897228973289742897528976289772897828979289802898128982289832898428985289862898728988289892899028991289922899328994289952899628997289982899929000290012900229003290042900529006290072900829009290102901129012290132901429015290162901729018290192902029021290222902329024290252902629027290282902929030290312903229033290342903529036290372903829039290402904129042290432904429045290462904729048290492905029051290522905329054290552905629057290582905929060290612906229063290642906529066290672906829069290702907129072290732907429075290762907729078290792908029081290822908329084290852908629087290882908929090290912909229093290942909529096290972909829099291002910129102291032910429105291062910729108291092911029111291122911329114291152911629117291182911929120291212912229123291242912529126291272912829129291302913129132291332913429135291362913729138291392914029141291422914329144291452914629147291482914929150291512915229153291542915529156291572915829159291602916129162291632916429165291662916729168291692917029171291722917329174291752917629177291782917929180291812918229183291842918529186291872918829189291902919129192291932919429195291962919729198291992920029201292022920329204292052920629207292082920929210292112921229213292142921529216292172921829219292202922129222292232922429225292262922729228292292923029231292322923329234292352923629237292382923929240292412924229243292442924529246292472924829249292502925129252292532925429255292562925729258292592926029261292622926329264292652926629267292682926929270292712927229273292742927529276292772927829279292802928129282292832928429285292862928729288292892929029291292922929329294292952929629297292982929929300293012930229303293042930529306293072930829309293102931129312293132931429315293162931729318293192932029321293222932329324293252932629327293282932929330293312933229333293342933529336293372933829339293402934129342293432934429345293462934729348293492935029351293522935329354293552935629357293582935929360293612936229363293642936529366293672936829369293702937129372293732937429375293762937729378293792938029381293822938329384293852938629387293882938929390293912939229393293942939529396293972939829399294002940129402294032940429405294062940729408294092941029411294122941329414294152941629417294182941929420294212942229423294242942529426294272942829429294302943129432294332943429435294362943729438294392944029441294422944329444294452944629447294482944929450294512945229453294542945529456294572945829459294602946129462294632946429465294662946729468294692947029471294722947329474294752947629477294782947929480294812948229483294842948529486294872948829489294902949129492294932949429495294962949729498294992950029501295022950329504295052950629507295082950929510295112951229513295142951529516295172951829519295202952129522295232952429525295262952729528295292953029531295322953329534295352953629537295382953929540295412954229543295442954529546295472954829549295502955129552295532955429555295562955729558295592956029561295622956329564295652956629567295682956929570295712957229573295742957529576295772957829579295802958129582295832958429585295862958729588295892959029591295922959329594295952959629597295982959929600296012960229603296042960529606296072960829609296102961129612296132961429615296162961729618296192962029621296222962329624296252962629627296282962929630296312963229633296342963529636296372963829639296402964129642296432964429645296462964729648296492965029651296522965329654296552965629657296582965929660296612966229663296642966529666296672966829669296702967129672296732967429675296762967729678296792968029681296822968329684296852968629687296882968929690296912969229693296942969529696296972969829699297002970129702297032970429705297062970729708297092971029711297122971329714297152971629717297182971929720297212972229723297242972529726297272972829729297302973129732297332973429735297362973729738297392974029741297422974329744297452974629747297482974929750297512975229753297542975529756297572975829759297602976129762297632976429765297662976729768297692977029771297722977329774297752977629777297782977929780297812978229783297842978529786297872978829789297902979129792297932979429795297962979729798297992980029801298022980329804298052980629807298082980929810298112981229813298142981529816298172981829819298202982129822298232982429825298262982729828298292983029831298322983329834298352983629837298382983929840298412984229843298442984529846298472984829849298502985129852298532985429855298562985729858298592986029861298622986329864298652986629867298682986929870298712987229873298742987529876298772987829879298802988129882298832988429885298862988729888298892989029891298922989329894298952989629897298982989929900299012990229903299042990529906299072990829909299102991129912299132991429915299162991729918299192992029921299222992329924299252992629927299282992929930299312993229933299342993529936299372993829939299402994129942299432994429945299462994729948299492995029951299522995329954299552995629957299582995929960299612996229963299642996529966299672996829969299702997129972299732997429975299762997729978299792998029981299822998329984299852998629987299882998929990299912999229993299942999529996299972999829999300003000130002300033000430005300063000730008300093001030011300123001330014300153001630017300183001930020300213002230023300243002530026300273002830029300303003130032300333003430035300363003730038300393004030041300423004330044300453004630047300483004930050300513005230053300543005530056300573005830059300603006130062300633006430065300663006730068300693007030071300723007330074300753007630077300783007930080300813008230083300843008530086300873008830089300903009130092300933009430095300963009730098300993010030101301023010330104301053010630107301083010930110301113011230113301143011530116301173011830119301203012130122301233012430125301263012730128301293013030131301323013330134301353013630137301383013930140301413014230143301443014530146301473014830149301503015130152301533015430155301563015730158301593016030161301623016330164301653016630167301683016930170301713017230173301743017530176301773017830179301803018130182301833018430185301863018730188301893019030191301923019330194301953019630197301983019930200302013020230203302043020530206302073020830209302103021130212302133021430215302163021730218302193022030221302223022330224302253022630227302283022930230302313023230233302343023530236302373023830239302403024130242302433024430245302463024730248302493025030251302523025330254302553025630257302583025930260302613026230263302643026530266302673026830269302703027130272302733027430275302763027730278302793028030281302823028330284302853028630287302883028930290302913029230293302943029530296302973029830299303003030130302303033030430305303063030730308303093031030311303123031330314303153031630317303183031930320303213032230323303243032530326303273032830329303303033130332303333033430335303363033730338303393034030341303423034330344303453034630347303483034930350303513035230353303543035530356303573035830359303603036130362303633036430365303663036730368303693037030371303723037330374303753037630377303783037930380303813038230383303843038530386303873038830389303903039130392303933039430395303963039730398303993040030401304023040330404304053040630407304083040930410304113041230413304143041530416304173041830419304203042130422304233042430425304263042730428304293043030431304323043330434304353043630437304383043930440304413044230443304443044530446304473044830449304503045130452304533045430455304563045730458304593046030461304623046330464304653046630467304683046930470304713047230473304743047530476304773047830479304803048130482304833048430485304863048730488304893049030491304923049330494304953049630497304983049930500305013050230503305043050530506305073050830509305103051130512305133051430515305163051730518305193052030521305223052330524305253052630527305283052930530305313053230533305343053530536305373053830539305403054130542305433054430545305463054730548305493055030551305523055330554305553055630557305583055930560305613056230563305643056530566305673056830569305703057130572305733057430575305763057730578305793058030581305823058330584305853058630587305883058930590305913059230593305943059530596305973059830599306003060130602306033060430605306063060730608306093061030611306123061330614306153061630617306183061930620306213062230623306243062530626306273062830629306303063130632306333063430635306363063730638306393064030641306423064330644306453064630647306483064930650306513065230653306543065530656306573065830659306603066130662306633066430665306663066730668306693067030671306723067330674306753067630677306783067930680306813068230683306843068530686306873068830689306903069130692306933069430695306963069730698306993070030701307023070330704307053070630707307083070930710307113071230713307143071530716307173071830719307203072130722307233072430725307263072730728307293073030731307323073330734307353073630737307383073930740307413074230743307443074530746307473074830749307503075130752307533075430755307563075730758307593076030761307623076330764307653076630767307683076930770307713077230773307743077530776307773077830779307803078130782307833078430785307863078730788307893079030791307923079330794307953079630797307983079930800308013080230803308043080530806308073080830809308103081130812308133081430815308163081730818308193082030821308223082330824308253082630827308283082930830308313083230833308343083530836308373083830839308403084130842308433084430845308463084730848308493085030851308523085330854308553085630857308583085930860308613086230863308643086530866308673086830869308703087130872308733087430875308763087730878308793088030881308823088330884308853088630887308883088930890308913089230893308943089530896308973089830899309003090130902309033090430905309063090730908309093091030911309123091330914309153091630917309183091930920309213092230923309243092530926309273092830929309303093130932309333093430935309363093730938309393094030941309423094330944309453094630947309483094930950309513095230953309543095530956309573095830959309603096130962309633096430965309663096730968309693097030971309723097330974309753097630977309783097930980309813098230983309843098530986309873098830989309903099130992309933099430995309963099730998309993100031001310023100331004310053100631007310083100931010310113101231013310143101531016310173101831019310203102131022310233102431025310263102731028310293103031031310323103331034310353103631037310383103931040310413104231043310443104531046310473104831049310503105131052310533105431055310563105731058310593106031061310623106331064310653106631067310683106931070310713107231073310743107531076310773107831079310803108131082310833108431085310863108731088310893109031091310923109331094310953109631097310983109931100311013110231103311043110531106311073110831109311103111131112311133111431115311163111731118311193112031121311223112331124311253112631127311283112931130311313113231133311343113531136311373113831139311403114131142311433114431145311463114731148311493115031151311523115331154311553115631157311583115931160311613116231163311643116531166311673116831169311703117131172311733117431175311763117731178311793118031181311823118331184311853118631187311883118931190311913119231193311943119531196311973119831199312003120131202312033120431205312063120731208312093121031211312123121331214312153121631217312183121931220312213122231223312243122531226312273122831229312303123131232312333123431235312363123731238312393124031241312423124331244312453124631247312483124931250312513125231253312543125531256312573125831259312603126131262312633126431265312663126731268312693127031271312723127331274312753127631277312783127931280312813128231283312843128531286312873128831289312903129131292312933129431295312963129731298312993130031301313023130331304313053130631307313083130931310313113131231313313143131531316313173131831319313203132131322313233132431325313263132731328313293133031331313323133331334313353133631337313383133931340313413134231343313443134531346313473134831349313503135131352313533135431355313563135731358313593136031361313623136331364313653136631367313683136931370313713137231373313743137531376313773137831379313803138131382313833138431385313863138731388313893139031391313923139331394313953139631397313983139931400314013140231403314043140531406314073140831409314103141131412314133141431415314163141731418314193142031421314223142331424314253142631427314283142931430314313143231433314343143531436314373143831439314403144131442314433144431445314463144731448314493145031451314523145331454314553145631457314583145931460314613146231463314643146531466314673146831469314703147131472314733147431475314763147731478314793148031481314823148331484314853148631487314883148931490314913149231493314943149531496314973149831499315003150131502315033150431505315063150731508315093151031511315123151331514315153151631517315183151931520315213152231523315243152531526315273152831529315303153131532315333153431535315363153731538315393154031541315423154331544315453154631547315483154931550315513155231553315543155531556315573155831559315603156131562315633156431565315663156731568315693157031571315723157331574315753157631577315783157931580315813158231583315843158531586315873158831589315903159131592315933159431595315963159731598315993160031601316023160331604316053160631607316083160931610316113161231613316143161531616316173161831619316203162131622316233162431625316263162731628316293163031631316323163331634316353163631637316383163931640316413164231643316443164531646316473164831649316503165131652316533165431655316563165731658316593166031661316623166331664316653166631667316683166931670316713167231673316743167531676316773167831679316803168131682316833168431685316863168731688316893169031691316923169331694316953169631697316983169931700317013170231703317043170531706317073170831709317103171131712317133171431715317163171731718317193172031721317223172331724317253172631727317283172931730317313173231733317343173531736317373173831739317403174131742317433174431745317463174731748317493175031751317523175331754317553175631757317583175931760317613176231763317643176531766317673176831769317703177131772317733177431775317763177731778317793178031781317823178331784317853178631787317883178931790317913179231793317943179531796317973179831799318003180131802318033180431805318063180731808318093181031811318123181331814318153181631817318183181931820318213182231823318243182531826318273182831829318303183131832318333183431835318363183731838318393184031841318423184331844318453184631847318483184931850318513185231853318543185531856318573185831859318603186131862318633186431865318663186731868318693187031871318723187331874318753187631877318783187931880318813188231883318843188531886318873188831889318903189131892318933189431895318963189731898318993190031901319023190331904319053190631907319083190931910319113191231913319143191531916319173191831919319203192131922319233192431925319263192731928319293193031931319323193331934319353193631937319383193931940319413194231943319443194531946319473194831949319503195131952319533195431955319563195731958319593196031961319623196331964319653196631967319683196931970319713197231973319743197531976319773197831979319803198131982319833198431985319863198731988319893199031991319923199331994319953199631997319983199932000320013200232003320043200532006320073200832009320103201132012320133201432015320163201732018320193202032021320223202332024320253202632027320283202932030320313203232033320343203532036320373203832039320403204132042320433204432045320463204732048320493205032051320523205332054320553205632057320583205932060320613206232063320643206532066320673206832069320703207132072320733207432075320763207732078320793208032081320823208332084320853208632087320883208932090320913209232093320943209532096320973209832099321003210132102321033210432105321063210732108321093211032111321123211332114321153211632117321183211932120321213212232123321243212532126321273212832129321303213132132321333213432135321363213732138321393214032141321423214332144321453214632147321483214932150321513215232153321543215532156321573215832159321603216132162321633216432165321663216732168321693217032171321723217332174321753217632177321783217932180321813218232183321843218532186321873218832189321903219132192321933219432195321963219732198321993220032201322023220332204322053220632207322083220932210322113221232213322143221532216322173221832219322203222132222322233222432225322263222732228322293223032231322323223332234322353223632237322383223932240322413224232243322443224532246322473224832249322503225132252322533225432255322563225732258322593226032261322623226332264322653226632267322683226932270322713227232273322743227532276322773227832279322803228132282322833228432285322863228732288322893229032291322923229332294322953229632297322983229932300323013230232303323043230532306323073230832309323103231132312323133231432315323163231732318323193232032321323223232332324323253232632327323283232932330323313233232333323343233532336323373233832339323403234132342323433234432345323463234732348323493235032351323523235332354323553235632357323583235932360323613236232363323643236532366323673236832369323703237132372323733237432375323763237732378323793238032381323823238332384323853238632387323883238932390323913239232393323943239532396323973239832399324003240132402324033240432405324063240732408324093241032411324123241332414324153241632417324183241932420324213242232423324243242532426324273242832429324303243132432324333243432435324363243732438324393244032441324423244332444324453244632447324483244932450324513245232453324543245532456324573245832459324603246132462324633246432465324663246732468324693247032471324723247332474324753247632477324783247932480324813248232483324843248532486324873248832489324903249132492324933249432495324963249732498324993250032501325023250332504325053250632507325083250932510325113251232513325143251532516325173251832519325203252132522325233252432525325263252732528325293253032531325323253332534325353253632537325383253932540325413254232543325443254532546325473254832549325503255132552325533255432555325563255732558325593256032561325623256332564325653256632567325683256932570325713257232573325743257532576325773257832579325803258132582325833258432585325863258732588325893259032591325923259332594325953259632597325983259932600326013260232603326043260532606326073260832609326103261132612326133261432615326163261732618326193262032621326223262332624326253262632627326283262932630326313263232633326343263532636326373263832639326403264132642326433264432645326463264732648326493265032651326523265332654326553265632657326583265932660326613266232663326643266532666326673266832669326703267132672326733267432675326763267732678326793268032681326823268332684326853268632687326883268932690326913269232693326943269532696326973269832699327003270132702327033270432705327063270732708327093271032711327123271332714327153271632717327183271932720327213272232723327243272532726327273272832729327303273132732327333273432735327363273732738327393274032741327423274332744327453274632747327483274932750327513275232753327543275532756327573275832759327603276132762327633276432765327663276732768327693277032771327723277332774327753277632777327783277932780327813278232783327843278532786327873278832789327903279132792327933279432795327963279732798327993280032801328023280332804328053280632807328083280932810328113281232813328143281532816328173281832819328203282132822328233282432825328263282732828328293283032831328323283332834328353283632837328383283932840328413284232843328443284532846328473284832849328503285132852328533285432855328563285732858328593286032861328623286332864328653286632867328683286932870328713287232873328743287532876328773287832879328803288132882328833288432885328863288732888328893289032891328923289332894328953289632897328983289932900329013290232903329043290532906329073290832909329103291132912329133291432915329163291732918329193292032921329223292332924329253292632927329283292932930329313293232933329343293532936329373293832939329403294132942329433294432945329463294732948329493295032951329523295332954329553295632957329583295932960329613296232963329643296532966329673296832969329703297132972329733297432975329763297732978329793298032981329823298332984329853298632987329883298932990329913299232993329943299532996329973299832999330003300133002330033300433005330063300733008330093301033011330123301333014330153301633017330183301933020330213302233023330243302533026330273302833029330303303133032330333303433035330363303733038330393304033041330423304333044330453304633047330483304933050330513305233053330543305533056330573305833059330603306133062330633306433065330663306733068330693307033071330723307333074330753307633077330783307933080330813308233083330843308533086330873308833089330903309133092330933309433095330963309733098330993310033101331023310333104331053310633107331083310933110331113311233113331143311533116331173311833119331203312133122331233312433125331263312733128331293313033131331323313333134331353313633137331383313933140331413314233143331443314533146331473314833149331503315133152331533315433155331563315733158331593316033161331623316333164331653316633167331683316933170331713317233173331743317533176331773317833179331803318133182331833318433185331863318733188331893319033191331923319333194331953319633197331983319933200332013320233203332043320533206332073320833209332103321133212332133321433215332163321733218332193322033221332223322333224332253322633227332283322933230332313323233233332343323533236332373323833239332403324133242332433324433245332463324733248332493325033251332523325333254332553325633257332583325933260332613326233263332643326533266332673326833269332703327133272332733327433275332763327733278332793328033281332823328333284332853328633287332883328933290332913329233293332943329533296332973329833299333003330133302333033330433305333063330733308333093331033311333123331333314333153331633317333183331933320333213332233323333243332533326333273332833329333303333133332333333333433335333363333733338333393334033341333423334333344333453334633347333483334933350333513335233353333543335533356333573335833359333603336133362333633336433365333663336733368333693337033371333723337333374333753337633377333783337933380333813338233383333843338533386333873338833389333903339133392333933339433395333963339733398333993340033401334023340333404334053340633407334083340933410334113341233413334143341533416334173341833419334203342133422334233342433425334263342733428334293343033431334323343333434334353343633437334383343933440334413344233443334443344533446334473344833449334503345133452334533345433455334563345733458334593346033461334623346333464334653346633467334683346933470334713347233473334743347533476334773347833479334803348133482334833348433485334863348733488334893349033491334923349333494334953349633497334983349933500335013350233503335043350533506335073350833509335103351133512335133351433515335163351733518335193352033521335223352333524335253352633527335283352933530335313353233533335343353533536335373353833539335403354133542335433354433545335463354733548335493355033551335523355333554335553355633557335583355933560335613356233563335643356533566335673356833569335703357133572335733357433575335763357733578335793358033581335823358333584335853358633587335883358933590335913359233593335943359533596335973359833599336003360133602336033360433605336063360733608336093361033611336123361333614336153361633617336183361933620336213362233623336243362533626336273362833629336303363133632336333363433635336363363733638336393364033641336423364333644336453364633647336483364933650336513365233653336543365533656336573365833659336603366133662336633366433665336663366733668336693367033671336723367333674336753367633677336783367933680336813368233683336843368533686336873368833689336903369133692336933369433695336963369733698336993370033701337023370333704337053370633707337083370933710337113371233713337143371533716337173371833719337203372133722337233372433725337263372733728337293373033731337323373333734337353373633737337383373933740337413374233743337443374533746337473374833749337503375133752337533375433755337563375733758337593376033761337623376333764337653376633767337683376933770337713377233773337743377533776337773377833779337803378133782337833378433785337863378733788337893379033791337923379333794337953379633797337983379933800338013380233803338043380533806338073380833809338103381133812338133381433815338163381733818338193382033821338223382333824338253382633827338283382933830338313383233833338343383533836338373383833839338403384133842338433384433845338463384733848338493385033851338523385333854338553385633857338583385933860338613386233863338643386533866338673386833869338703387133872338733387433875338763387733878338793388033881338823388333884338853388633887338883388933890338913389233893338943389533896338973389833899339003390133902339033390433905339063390733908339093391033911339123391333914339153391633917339183391933920339213392233923339243392533926339273392833929339303393133932339333393433935339363393733938339393394033941339423394333944339453394633947339483394933950339513395233953339543395533956339573395833959339603396133962339633396433965339663396733968339693397033971339723397333974339753397633977339783397933980339813398233983339843398533986339873398833989339903399133992339933399433995339963399733998339993400034001340023400334004340053400634007340083400934010340113401234013340143401534016340173401834019340203402134022340233402434025340263402734028340293403034031340323403334034340353403634037340383403934040340413404234043340443404534046340473404834049340503405134052340533405434055340563405734058340593406034061340623406334064340653406634067340683406934070340713407234073340743407534076340773407834079340803408134082340833408434085340863408734088340893409034091340923409334094340953409634097340983409934100341013410234103341043410534106341073410834109341103411134112341133411434115341163411734118341193412034121341223412334124341253412634127341283412934130341313413234133341343413534136341373413834139341403414134142341433414434145341463414734148341493415034151341523415334154341553415634157341583415934160341613416234163341643416534166341673416834169341703417134172341733417434175341763417734178341793418034181341823418334184341853418634187341883418934190341913419234193341943419534196341973419834199342003420134202342033420434205342063420734208342093421034211342123421334214342153421634217342183421934220342213422234223342243422534226342273422834229342303423134232342333423434235342363423734238342393424034241342423424334244342453424634247342483424934250342513425234253342543425534256342573425834259342603426134262342633426434265342663426734268342693427034271342723427334274342753427634277342783427934280342813428234283342843428534286342873428834289342903429134292342933429434295342963429734298342993430034301343023430334304343053430634307343083430934310343113431234313343143431534316343173431834319343203432134322343233432434325343263432734328343293433034331343323433334334343353433634337343383433934340343413434234343343443434534346343473434834349343503435134352343533435434355343563435734358343593436034361343623436334364343653436634367343683436934370343713437234373343743437534376343773437834379343803438134382343833438434385343863438734388343893439034391343923439334394343953439634397343983439934400344013440234403344043440534406344073440834409344103441134412344133441434415344163441734418344193442034421344223442334424344253442634427344283442934430344313443234433344343443534436344373443834439344403444134442344433444434445344463444734448344493445034451344523445334454344553445634457344583445934460344613446234463344643446534466344673446834469344703447134472344733447434475344763447734478344793448034481344823448334484344853448634487344883448934490344913449234493344943449534496344973449834499345003450134502345033450434505345063450734508345093451034511345123451334514345153451634517345183451934520345213452234523345243452534526345273452834529345303453134532345333453434535345363453734538345393454034541345423454334544345453454634547345483454934550345513455234553345543455534556345573455834559345603456134562345633456434565345663456734568345693457034571345723457334574345753457634577345783457934580345813458234583345843458534586345873458834589345903459134592345933459434595345963459734598345993460034601346023460334604346053460634607346083460934610346113461234613346143461534616346173461834619346203462134622346233462434625346263462734628346293463034631346323463334634346353463634637346383463934640346413464234643346443464534646346473464834649346503465134652346533465434655346563465734658346593466034661346623466334664346653466634667346683466934670346713467234673346743467534676346773467834679346803468134682346833468434685346863468734688346893469034691346923469334694346953469634697346983469934700347013470234703347043470534706347073470834709347103471134712347133471434715347163471734718347193472034721347223472334724347253472634727347283472934730347313473234733347343473534736347373473834739347403474134742347433474434745347463474734748347493475034751347523475334754347553475634757347583475934760347613476234763347643476534766347673476834769347703477134772347733477434775347763477734778347793478034781347823478334784347853478634787347883478934790347913479234793347943479534796347973479834799348003480134802348033480434805348063480734808348093481034811348123481334814348153481634817348183481934820348213482234823348243482534826348273482834829348303483134832348333483434835348363483734838348393484034841348423484334844348453484634847348483484934850348513485234853348543485534856348573485834859348603486134862348633486434865348663486734868348693487034871348723487334874348753487634877348783487934880348813488234883348843488534886348873488834889348903489134892348933489434895348963489734898348993490034901349023490334904349053490634907349083490934910349113491234913349143491534916349173491834919349203492134922349233492434925349263492734928349293493034931349323493334934349353493634937349383493934940349413494234943349443494534946349473494834949349503495134952349533495434955349563495734958349593496034961349623496334964349653496634967349683496934970349713497234973349743497534976349773497834979349803498134982349833498434985349863498734988349893499034991349923499334994349953499634997349983499935000350013500235003350043500535006350073500835009350103501135012350133501435015350163501735018350193502035021350223502335024350253502635027350283502935030350313503235033350343503535036350373503835039350403504135042350433504435045350463504735048350493505035051350523505335054350553505635057350583505935060350613506235063350643506535066350673506835069350703507135072350733507435075350763507735078350793508035081350823508335084350853508635087350883508935090350913509235093350943509535096350973509835099351003510135102351033510435105351063510735108351093511035111351123511335114351153511635117351183511935120351213512235123351243512535126351273512835129351303513135132351333513435135351363513735138351393514035141351423514335144351453514635147351483514935150351513515235153351543515535156351573515835159351603516135162351633516435165351663516735168351693517035171351723517335174351753517635177351783517935180351813518235183351843518535186351873518835189351903519135192351933519435195351963519735198351993520035201352023520335204352053520635207352083520935210352113521235213352143521535216352173521835219352203522135222352233522435225352263522735228352293523035231352323523335234352353523635237352383523935240352413524235243352443524535246352473524835249352503525135252352533525435255352563525735258352593526035261352623526335264352653526635267352683526935270352713527235273352743527535276352773527835279352803528135282352833528435285352863528735288352893529035291352923529335294352953529635297352983529935300353013530235303353043530535306353073530835309353103531135312353133531435315353163531735318353193532035321353223532335324353253532635327353283532935330353313533235333353343533535336353373533835339353403534135342353433534435345353463534735348353493535035351353523535335354353553535635357353583535935360353613536235363353643536535366353673536835369353703537135372353733537435375353763537735378353793538035381353823538335384353853538635387353883538935390353913539235393353943539535396353973539835399354003540135402354033540435405354063540735408354093541035411354123541335414354153541635417354183541935420354213542235423354243542535426354273542835429354303543135432354333543435435354363543735438354393544035441354423544335444354453544635447354483544935450354513545235453354543545535456354573545835459354603546135462354633546435465354663546735468354693547035471354723547335474354753547635477354783547935480354813548235483354843548535486354873548835489354903549135492354933549435495354963549735498354993550035501355023550335504355053550635507355083550935510355113551235513355143551535516355173551835519355203552135522355233552435525355263552735528355293553035531355323553335534355353553635537355383553935540355413554235543355443554535546355473554835549355503555135552355533555435555355563555735558355593556035561355623556335564355653556635567355683556935570355713557235573355743557535576355773557835579355803558135582355833558435585355863558735588355893559035591355923559335594355953559635597355983559935600356013560235603356043560535606356073560835609356103561135612356133561435615356163561735618356193562035621356223562335624356253562635627356283562935630356313563235633356343563535636356373563835639356403564135642356433564435645356463564735648356493565035651356523565335654356553565635657356583565935660356613566235663356643566535666356673566835669356703567135672356733567435675356763567735678356793568035681356823568335684356853568635687356883568935690356913569235693356943569535696356973569835699357003570135702357033570435705357063570735708357093571035711357123571335714357153571635717357183571935720357213572235723357243572535726357273572835729357303573135732357333573435735357363573735738357393574035741357423574335744357453574635747357483574935750357513575235753357543575535756357573575835759357603576135762357633576435765357663576735768357693577035771357723577335774357753577635777357783577935780357813578235783357843578535786357873578835789357903579135792357933579435795357963579735798357993580035801358023580335804358053580635807358083580935810358113581235813358143581535816358173581835819358203582135822358233582435825358263582735828358293583035831358323583335834358353583635837358383583935840358413584235843358443584535846358473584835849358503585135852358533585435855358563585735858358593586035861358623586335864358653586635867358683586935870358713587235873358743587535876358773587835879358803588135882358833588435885358863588735888358893589035891358923589335894358953589635897358983589935900359013590235903359043590535906359073590835909359103591135912359133591435915359163591735918359193592035921359223592335924359253592635927359283592935930359313593235933359343593535936359373593835939359403594135942359433594435945359463594735948359493595035951359523595335954359553595635957359583595935960359613596235963359643596535966359673596835969359703597135972359733597435975359763597735978359793598035981359823598335984359853598635987359883598935990359913599235993359943599535996359973599835999360003600136002360033600436005360063600736008360093601036011360123601336014360153601636017360183601936020360213602236023360243602536026360273602836029360303603136032360333603436035360363603736038360393604036041360423604336044360453604636047360483604936050360513605236053360543605536056360573605836059360603606136062360633606436065360663606736068360693607036071360723607336074360753607636077360783607936080360813608236083360843608536086360873608836089360903609136092360933609436095360963609736098360993610036101361023610336104361053610636107361083610936110361113611236113361143611536116361173611836119361203612136122361233612436125361263612736128361293613036131361323613336134361353613636137361383613936140361413614236143361443614536146361473614836149361503615136152361533615436155361563615736158361593616036161361623616336164361653616636167361683616936170361713617236173361743617536176361773617836179361803618136182361833618436185361863618736188361893619036191361923619336194361953619636197361983619936200362013620236203362043620536206362073620836209362103621136212362133621436215362163621736218362193622036221362223622336224362253622636227362283622936230362313623236233362343623536236362373623836239362403624136242362433624436245362463624736248362493625036251362523625336254362553625636257362583625936260362613626236263362643626536266362673626836269362703627136272362733627436275362763627736278362793628036281362823628336284362853628636287362883628936290362913629236293362943629536296362973629836299363003630136302363033630436305363063630736308363093631036311363123631336314363153631636317363183631936320363213632236323363243632536326363273632836329363303633136332363333633436335363363633736338363393634036341363423634336344363453634636347363483634936350363513635236353363543635536356363573635836359363603636136362363633636436365363663636736368363693637036371363723637336374363753637636377363783637936380363813638236383363843638536386363873638836389363903639136392363933639436395363963639736398363993640036401364023640336404364053640636407364083640936410364113641236413364143641536416364173641836419364203642136422364233642436425364263642736428364293643036431364323643336434364353643636437364383643936440364413644236443364443644536446364473644836449364503645136452364533645436455364563645736458364593646036461364623646336464364653646636467364683646936470364713647236473364743647536476364773647836479364803648136482364833648436485364863648736488364893649036491364923649336494364953649636497364983649936500365013650236503365043650536506365073650836509365103651136512365133651436515365163651736518365193652036521365223652336524365253652636527365283652936530365313653236533365343653536536365373653836539365403654136542365433654436545365463654736548365493655036551365523655336554365553655636557365583655936560365613656236563365643656536566365673656836569365703657136572365733657436575365763657736578365793658036581365823658336584365853658636587365883658936590365913659236593365943659536596365973659836599366003660136602366033660436605366063660736608366093661036611366123661336614366153661636617366183661936620366213662236623366243662536626366273662836629366303663136632366333663436635366363663736638366393664036641366423664336644366453664636647366483664936650366513665236653366543665536656366573665836659366603666136662366633666436665366663666736668366693667036671366723667336674366753667636677366783667936680366813668236683366843668536686366873668836689366903669136692366933669436695366963669736698366993670036701367023670336704367053670636707367083670936710367113671236713367143671536716367173671836719367203672136722367233672436725367263672736728367293673036731367323673336734367353673636737367383673936740367413674236743367443674536746367473674836749367503675136752367533675436755367563675736758367593676036761367623676336764367653676636767367683676936770367713677236773367743677536776367773677836779367803678136782367833678436785367863678736788367893679036791367923679336794367953679636797367983679936800368013680236803368043680536806368073680836809368103681136812368133681436815368163681736818368193682036821368223682336824368253682636827368283682936830368313683236833368343683536836368373683836839368403684136842368433684436845368463684736848368493685036851368523685336854368553685636857368583685936860368613686236863368643686536866368673686836869368703687136872368733687436875368763687736878368793688036881368823688336884368853688636887368883688936890368913689236893368943689536896368973689836899369003690136902369033690436905369063690736908369093691036911369123691336914369153691636917369183691936920369213692236923369243692536926369273692836929369303693136932369333693436935369363693736938369393694036941369423694336944369453694636947369483694936950369513695236953369543695536956369573695836959369603696136962369633696436965369663696736968369693697036971369723697336974369753697636977369783697936980369813698236983369843698536986369873698836989369903699136992369933699436995369963699736998369993700037001370023700337004370053700637007370083700937010370113701237013370143701537016370173701837019370203702137022370233702437025370263702737028370293703037031370323703337034370353703637037370383703937040370413704237043370443704537046370473704837049370503705137052370533705437055370563705737058370593706037061370623706337064370653706637067370683706937070370713707237073370743707537076370773707837079370803708137082370833708437085370863708737088370893709037091370923709337094370953709637097370983709937100371013710237103371043710537106371073710837109371103711137112371133711437115371163711737118371193712037121371223712337124371253712637127371283712937130371313713237133371343713537136371373713837139371403714137142371433714437145371463714737148371493715037151371523715337154371553715637157371583715937160371613716237163371643716537166371673716837169371703717137172371733717437175371763717737178371793718037181371823718337184371853718637187371883718937190371913719237193371943719537196371973719837199372003720137202372033720437205372063720737208372093721037211372123721337214372153721637217372183721937220372213722237223372243722537226372273722837229372303723137232372333723437235372363723737238372393724037241372423724337244372453724637247372483724937250372513725237253372543725537256372573725837259372603726137262372633726437265372663726737268372693727037271372723727337274372753727637277372783727937280372813728237283372843728537286372873728837289372903729137292372933729437295372963729737298372993730037301373023730337304373053730637307373083730937310373113731237313373143731537316373173731837319373203732137322373233732437325373263732737328373293733037331373323733337334373353733637337373383733937340373413734237343373443734537346373473734837349373503735137352373533735437355373563735737358373593736037361373623736337364373653736637367373683736937370373713737237373373743737537376373773737837379373803738137382373833738437385373863738737388373893739037391373923739337394373953739637397373983739937400374013740237403374043740537406374073740837409374103741137412374133741437415374163741737418374193742037421374223742337424374253742637427374283742937430374313743237433374343743537436374373743837439374403744137442374433744437445374463744737448374493745037451374523745337454374553745637457374583745937460374613746237463374643746537466374673746837469374703747137472374733747437475374763747737478374793748037481374823748337484374853748637487374883748937490374913749237493374943749537496374973749837499375003750137502375033750437505375063750737508375093751037511375123751337514375153751637517375183751937520375213752237523375243752537526375273752837529375303753137532375333753437535375363753737538375393754037541375423754337544375453754637547375483754937550375513755237553375543755537556375573755837559375603756137562375633756437565375663756737568375693757037571375723757337574375753757637577375783757937580375813758237583375843758537586375873758837589375903759137592375933759437595375963759737598375993760037601376023760337604376053760637607376083760937610376113761237613376143761537616376173761837619376203762137622376233762437625376263762737628376293763037631376323763337634376353763637637376383763937640376413764237643376443764537646376473764837649376503765137652376533765437655376563765737658376593766037661376623766337664376653766637667376683766937670376713767237673376743767537676376773767837679376803768137682376833768437685376863768737688376893769037691376923769337694376953769637697376983769937700377013770237703377043770537706377073770837709377103771137712377133771437715377163771737718377193772037721377223772337724377253772637727377283772937730377313773237733377343773537736377373773837739377403774137742377433774437745377463774737748377493775037751377523775337754377553775637757377583775937760377613776237763377643776537766377673776837769377703777137772377733777437775377763777737778377793778037781377823778337784377853778637787377883778937790377913779237793377943779537796377973779837799378003780137802378033780437805378063780737808378093781037811378123781337814378153781637817378183781937820378213782237823378243782537826378273782837829378303783137832378333783437835378363783737838378393784037841378423784337844378453784637847378483784937850378513785237853378543785537856378573785837859378603786137862378633786437865378663786737868378693787037871378723787337874378753787637877378783787937880378813788237883378843788537886378873788837889378903789137892378933789437895378963789737898378993790037901379023790337904379053790637907379083790937910379113791237913379143791537916379173791837919379203792137922379233792437925379263792737928379293793037931379323793337934379353793637937379383793937940379413794237943379443794537946379473794837949379503795137952379533795437955379563795737958379593796037961379623796337964379653796637967379683796937970379713797237973379743797537976379773797837979379803798137982379833798437985379863798737988379893799037991379923799337994379953799637997379983799938000380013800238003380043800538006380073800838009380103801138012380133801438015380163801738018380193802038021380223802338024380253802638027380283802938030380313803238033380343803538036380373803838039380403804138042380433804438045380463804738048380493805038051380523805338054380553805638057380583805938060380613806238063380643806538066380673806838069380703807138072380733807438075380763807738078380793808038081380823808338084380853808638087380883808938090380913809238093380943809538096380973809838099381003810138102381033810438105381063810738108381093811038111381123811338114381153811638117381183811938120381213812238123381243812538126381273812838129381303813138132381333813438135381363813738138381393814038141381423814338144381453814638147381483814938150381513815238153381543815538156381573815838159381603816138162381633816438165381663816738168381693817038171381723817338174381753817638177381783817938180381813818238183381843818538186381873818838189381903819138192381933819438195381963819738198381993820038201382023820338204382053820638207382083820938210382113821238213382143821538216382173821838219382203822138222382233822438225382263822738228382293823038231382323823338234382353823638237382383823938240382413824238243382443824538246382473824838249382503825138252382533825438255382563825738258382593826038261382623826338264382653826638267382683826938270382713827238273382743827538276382773827838279382803828138282382833828438285382863828738288382893829038291382923829338294382953829638297382983829938300383013830238303383043830538306383073830838309383103831138312383133831438315383163831738318383193832038321383223832338324383253832638327383283832938330383313833238333383343833538336383373833838339383403834138342383433834438345383463834738348383493835038351383523835338354383553835638357383583835938360383613836238363383643836538366383673836838369383703837138372383733837438375383763837738378383793838038381383823838338384383853838638387383883838938390383913839238393383943839538396383973839838399384003840138402384033840438405384063840738408384093841038411384123841338414384153841638417384183841938420384213842238423384243842538426384273842838429384303843138432384333843438435384363843738438384393844038441384423844338444384453844638447384483844938450384513845238453384543845538456384573845838459384603846138462384633846438465384663846738468384693847038471384723847338474384753847638477384783847938480384813848238483384843848538486384873848838489384903849138492384933849438495384963849738498384993850038501385023850338504385053850638507385083850938510385113851238513385143851538516385173851838519385203852138522385233852438525385263852738528385293853038531385323853338534385353853638537385383853938540385413854238543385443854538546385473854838549385503855138552385533855438555385563855738558385593856038561385623856338564385653856638567385683856938570385713857238573385743857538576385773857838579385803858138582385833858438585385863858738588385893859038591385923859338594385953859638597385983859938600386013860238603386043860538606386073860838609386103861138612386133861438615386163861738618386193862038621386223862338624386253862638627386283862938630386313863238633386343863538636386373863838639386403864138642386433864438645386463864738648386493865038651386523865338654386553865638657386583865938660386613866238663386643866538666386673866838669386703867138672386733867438675386763867738678386793868038681386823868338684386853868638687386883868938690386913869238693386943869538696386973869838699387003870138702387033870438705387063870738708387093871038711387123871338714387153871638717387183871938720387213872238723387243872538726387273872838729387303873138732387333873438735387363873738738387393874038741387423874338744387453874638747387483874938750387513875238753387543875538756387573875838759387603876138762387633876438765387663876738768387693877038771387723877338774387753877638777387783877938780387813878238783387843878538786387873878838789387903879138792387933879438795387963879738798387993880038801388023880338804388053880638807388083880938810388113881238813388143881538816388173881838819388203882138822388233882438825388263882738828388293883038831388323883338834388353883638837388383883938840388413884238843388443884538846388473884838849388503885138852388533885438855388563885738858388593886038861388623886338864388653886638867388683886938870388713887238873388743887538876388773887838879388803888138882388833888438885388863888738888388893889038891388923889338894388953889638897388983889938900389013890238903389043890538906389073890838909389103891138912389133891438915389163891738918389193892038921389223892338924389253892638927389283892938930389313893238933389343893538936389373893838939389403894138942389433894438945389463894738948389493895038951389523895338954389553895638957389583895938960389613896238963389643896538966389673896838969389703897138972389733897438975389763897738978389793898038981389823898338984389853898638987389883898938990389913899238993389943899538996389973899838999390003900139002390033900439005390063900739008390093901039011390123901339014390153901639017390183901939020390213902239023390243902539026390273902839029390303903139032390333903439035390363903739038390393904039041390423904339044390453904639047390483904939050390513905239053390543905539056390573905839059390603906139062390633906439065390663906739068390693907039071390723907339074390753907639077390783907939080390813908239083390843908539086390873908839089390903909139092390933909439095390963909739098390993910039101391023910339104391053910639107391083910939110391113911239113391143911539116391173911839119391203912139122391233912439125391263912739128391293913039131391323913339134391353913639137391383913939140391413914239143391443914539146391473914839149391503915139152391533915439155391563915739158391593916039161391623916339164391653916639167391683916939170391713917239173391743917539176391773917839179391803918139182391833918439185391863918739188391893919039191391923919339194391953919639197391983919939200392013920239203392043920539206392073920839209392103921139212392133921439215392163921739218392193922039221392223922339224392253922639227392283922939230392313923239233392343923539236392373923839239392403924139242392433924439245392463924739248392493925039251392523925339254392553925639257392583925939260392613926239263392643926539266392673926839269392703927139272392733927439275392763927739278392793928039281392823928339284392853928639287392883928939290392913929239293392943929539296392973929839299393003930139302393033930439305393063930739308393093931039311393123931339314393153931639317393183931939320393213932239323393243932539326393273932839329393303933139332393333933439335393363933739338393393934039341393423934339344393453934639347393483934939350393513935239353393543935539356393573935839359393603936139362393633936439365393663936739368393693937039371393723937339374393753937639377393783937939380393813938239383393843938539386393873938839389393903939139392393933939439395393963939739398393993940039401394023940339404394053940639407394083940939410394113941239413394143941539416394173941839419394203942139422394233942439425394263942739428394293943039431394323943339434394353943639437394383943939440394413944239443394443944539446394473944839449394503945139452394533945439455394563945739458394593946039461394623946339464394653946639467394683946939470394713947239473394743947539476394773947839479394803948139482394833948439485394863948739488394893949039491394923949339494394953949639497394983949939500395013950239503395043950539506395073950839509395103951139512395133951439515395163951739518395193952039521395223952339524395253952639527395283952939530395313953239533395343953539536395373953839539395403954139542395433954439545395463954739548395493955039551395523955339554395553955639557395583955939560395613956239563395643956539566395673956839569395703957139572395733957439575395763957739578395793958039581395823958339584395853958639587395883958939590395913959239593395943959539596395973959839599396003960139602396033960439605396063960739608396093961039611396123961339614396153961639617396183961939620396213962239623396243962539626396273962839629396303963139632396333963439635396363963739638396393964039641396423964339644396453964639647396483964939650396513965239653396543965539656396573965839659396603966139662396633966439665396663966739668396693967039671396723967339674396753967639677396783967939680396813968239683396843968539686396873968839689396903969139692396933969439695396963969739698396993970039701397023970339704397053970639707397083970939710397113971239713397143971539716397173971839719397203972139722397233972439725397263972739728397293973039731397323973339734397353973639737397383973939740397413974239743397443974539746397473974839749397503975139752397533975439755397563975739758397593976039761397623976339764397653976639767397683976939770397713977239773397743977539776397773977839779397803978139782397833978439785397863978739788397893979039791397923979339794397953979639797397983979939800398013980239803398043980539806398073980839809398103981139812398133981439815398163981739818398193982039821398223982339824398253982639827398283982939830398313983239833398343983539836398373983839839398403984139842398433984439845398463984739848398493985039851398523985339854398553985639857398583985939860398613986239863398643986539866398673986839869398703987139872398733987439875398763987739878398793988039881398823988339884398853988639887398883988939890398913989239893398943989539896398973989839899399003990139902399033990439905399063990739908399093991039911399123991339914399153991639917399183991939920399213992239923399243992539926399273992839929399303993139932399333993439935399363993739938399393994039941399423994339944399453994639947399483994939950399513995239953399543995539956399573995839959399603996139962399633996439965399663996739968399693997039971399723997339974399753997639977399783997939980399813998239983399843998539986399873998839989399903999139992399933999439995399963999739998399994000040001400024000340004400054000640007400084000940010400114001240013400144001540016400174001840019400204002140022400234002440025400264002740028400294003040031400324003340034400354003640037400384003940040400414004240043400444004540046400474004840049400504005140052400534005440055400564005740058400594006040061400624006340064400654006640067400684006940070400714007240073400744007540076400774007840079400804008140082400834008440085400864008740088400894009040091400924009340094400954009640097400984009940100401014010240103401044010540106401074010840109401104011140112401134011440115401164011740118401194012040121401224012340124401254012640127401284012940130401314013240133401344013540136401374013840139401404014140142401434014440145401464014740148401494015040151401524015340154401554015640157401584015940160401614016240163401644016540166401674016840169401704017140172401734017440175401764017740178401794018040181401824018340184401854018640187401884018940190401914019240193401944019540196401974019840199402004020140202402034020440205402064020740208402094021040211402124021340214402154021640217402184021940220402214022240223402244022540226402274022840229402304023140232402334023440235402364023740238402394024040241402424024340244402454024640247402484024940250402514025240253402544025540256402574025840259402604026140262402634026440265402664026740268402694027040271402724027340274402754027640277402784027940280402814028240283402844028540286402874028840289402904029140292402934029440295402964029740298402994030040301403024030340304403054030640307403084030940310403114031240313403144031540316403174031840319403204032140322403234032440325403264032740328403294033040331403324033340334403354033640337403384033940340403414034240343403444034540346403474034840349403504035140352403534035440355403564035740358403594036040361403624036340364403654036640367403684036940370403714037240373403744037540376403774037840379403804038140382403834038440385403864038740388403894039040391403924039340394403954039640397403984039940400404014040240403404044040540406404074040840409404104041140412404134041440415404164041740418404194042040421404224042340424404254042640427404284042940430404314043240433404344043540436404374043840439404404044140442404434044440445404464044740448404494045040451404524045340454404554045640457404584045940460404614046240463404644046540466404674046840469404704047140472404734047440475404764047740478404794048040481404824048340484404854048640487404884048940490404914049240493404944049540496404974049840499405004050140502405034050440505405064050740508405094051040511405124051340514405154051640517405184051940520405214052240523405244052540526405274052840529405304053140532405334053440535405364053740538405394054040541405424054340544405454054640547405484054940550405514055240553405544055540556405574055840559405604056140562405634056440565405664056740568405694057040571405724057340574405754057640577405784057940580405814058240583405844058540586405874058840589405904059140592405934059440595405964059740598405994060040601406024060340604406054060640607406084060940610406114061240613406144061540616406174061840619406204062140622406234062440625406264062740628406294063040631406324063340634406354063640637406384063940640406414064240643406444064540646406474064840649406504065140652406534065440655406564065740658406594066040661406624066340664406654066640667406684066940670406714067240673406744067540676406774067840679406804068140682406834068440685406864068740688406894069040691406924069340694406954069640697406984069940700407014070240703407044070540706407074070840709407104071140712407134071440715407164071740718407194072040721407224072340724407254072640727407284072940730407314073240733407344073540736407374073840739407404074140742407434074440745407464074740748407494075040751407524075340754407554075640757407584075940760407614076240763407644076540766407674076840769407704077140772407734077440775407764077740778407794078040781407824078340784407854078640787407884078940790407914079240793407944079540796407974079840799408004080140802408034080440805408064080740808408094081040811408124081340814408154081640817408184081940820408214082240823408244082540826408274082840829408304083140832408334083440835408364083740838408394084040841408424084340844408454084640847408484084940850408514085240853408544085540856408574085840859408604086140862408634086440865408664086740868408694087040871408724087340874408754087640877408784087940880408814088240883408844088540886408874088840889408904089140892408934089440895408964089740898408994090040901409024090340904409054090640907409084090940910409114091240913409144091540916409174091840919409204092140922409234092440925409264092740928409294093040931409324093340934409354093640937409384093940940409414094240943409444094540946409474094840949409504095140952409534095440955409564095740958409594096040961409624096340964409654096640967409684096940970409714097240973409744097540976409774097840979409804098140982409834098440985409864098740988409894099040991409924099340994409954099640997409984099941000410014100241003410044100541006410074100841009410104101141012410134101441015410164101741018410194102041021410224102341024410254102641027410284102941030410314103241033410344103541036410374103841039410404104141042410434104441045410464104741048410494105041051410524105341054410554105641057410584105941060410614106241063410644106541066410674106841069410704107141072410734107441075410764107741078410794108041081410824108341084410854108641087410884108941090410914109241093410944109541096410974109841099411004110141102411034110441105411064110741108411094111041111411124111341114411154111641117411184111941120411214112241123411244112541126411274112841129411304113141132411334113441135411364113741138411394114041141411424114341144411454114641147411484114941150411514115241153411544115541156411574115841159411604116141162411634116441165411664116741168411694117041171411724117341174411754117641177411784117941180411814118241183411844118541186411874118841189411904119141192411934119441195411964119741198411994120041201412024120341204412054120641207412084120941210412114121241213412144121541216412174121841219412204122141222412234122441225412264122741228412294123041231412324123341234412354123641237412384123941240412414124241243412444124541246412474124841249412504125141252412534125441255412564125741258412594126041261412624126341264412654126641267412684126941270412714127241273412744127541276412774127841279412804128141282412834128441285412864128741288412894129041291412924129341294412954129641297412984129941300413014130241303413044130541306413074130841309413104131141312413134131441315413164131741318413194132041321413224132341324413254132641327413284132941330413314133241333413344133541336413374133841339413404134141342413434134441345413464134741348413494135041351413524135341354413554135641357413584135941360413614136241363413644136541366413674136841369413704137141372413734137441375413764137741378413794138041381413824138341384413854138641387413884138941390413914139241393413944139541396413974139841399414004140141402414034140441405414064140741408414094141041411414124141341414414154141641417414184141941420414214142241423414244142541426414274142841429414304143141432414334143441435414364143741438414394144041441414424144341444414454144641447414484144941450414514145241453414544145541456414574145841459414604146141462414634146441465414664146741468414694147041471414724147341474414754147641477414784147941480414814148241483414844148541486414874148841489414904149141492414934149441495414964149741498414994150041501415024150341504415054150641507415084150941510415114151241513415144151541516415174151841519415204152141522415234152441525415264152741528415294153041531415324153341534415354153641537415384153941540415414154241543415444154541546415474154841549415504155141552415534155441555415564155741558415594156041561415624156341564415654156641567415684156941570415714157241573415744157541576415774157841579415804158141582415834158441585415864158741588415894159041591415924159341594415954159641597415984159941600416014160241603416044160541606416074160841609416104161141612416134161441615416164161741618416194162041621416224162341624416254162641627416284162941630416314163241633416344163541636416374163841639416404164141642416434164441645416464164741648416494165041651416524165341654416554165641657416584165941660416614166241663416644166541666416674166841669416704167141672416734167441675416764167741678416794168041681416824168341684416854168641687416884168941690416914169241693416944169541696416974169841699417004170141702417034170441705417064170741708417094171041711417124171341714417154171641717417184171941720417214172241723417244172541726417274172841729417304173141732417334173441735417364173741738417394174041741417424174341744417454174641747417484174941750417514175241753417544175541756417574175841759417604176141762417634176441765417664176741768417694177041771417724177341774417754177641777417784177941780417814178241783417844178541786417874178841789417904179141792417934179441795417964179741798417994180041801418024180341804418054180641807418084180941810418114181241813418144181541816418174181841819418204182141822418234182441825418264182741828418294183041831418324183341834418354183641837418384183941840418414184241843418444184541846418474184841849418504185141852418534185441855418564185741858418594186041861418624186341864418654186641867418684186941870418714187241873418744187541876418774187841879418804188141882418834188441885418864188741888418894189041891418924189341894418954189641897418984189941900419014190241903419044190541906419074190841909419104191141912419134191441915419164191741918419194192041921419224192341924419254192641927419284192941930419314193241933419344193541936419374193841939419404194141942419434194441945419464194741948419494195041951419524195341954419554195641957419584195941960419614196241963419644196541966419674196841969419704197141972419734197441975419764197741978419794198041981419824198341984419854198641987419884198941990419914199241993419944199541996419974199841999420004200142002420034200442005420064200742008420094201042011420124201342014420154201642017420184201942020420214202242023420244202542026420274202842029420304203142032420334203442035420364203742038420394204042041420424204342044420454204642047420484204942050420514205242053420544205542056420574205842059420604206142062420634206442065420664206742068420694207042071420724207342074420754207642077420784207942080420814208242083420844208542086420874208842089420904209142092420934209442095420964209742098420994210042101421024210342104421054210642107421084210942110421114211242113421144211542116421174211842119421204212142122421234212442125421264212742128421294213042131421324213342134421354213642137421384213942140421414214242143421444214542146421474214842149421504215142152421534215442155421564215742158421594216042161421624216342164421654216642167421684216942170421714217242173421744217542176421774217842179421804218142182421834218442185421864218742188421894219042191421924219342194421954219642197421984219942200422014220242203422044220542206422074220842209422104221142212422134221442215422164221742218422194222042221422224222342224422254222642227422284222942230422314223242233422344223542236422374223842239422404224142242422434224442245422464224742248422494225042251422524225342254422554225642257422584225942260422614226242263422644226542266422674226842269422704227142272422734227442275422764227742278422794228042281422824228342284422854228642287422884228942290422914229242293422944229542296422974229842299423004230142302423034230442305423064230742308423094231042311423124231342314423154231642317423184231942320423214232242323423244232542326423274232842329423304233142332423334233442335423364233742338423394234042341423424234342344423454234642347423484234942350423514235242353423544235542356423574235842359423604236142362423634236442365423664236742368423694237042371423724237342374423754237642377423784237942380423814238242383423844238542386423874238842389423904239142392423934239442395423964239742398423994240042401424024240342404424054240642407424084240942410424114241242413424144241542416424174241842419424204242142422424234242442425424264242742428424294243042431424324243342434424354243642437424384243942440424414244242443424444244542446424474244842449424504245142452424534245442455424564245742458424594246042461424624246342464424654246642467424684246942470424714247242473424744247542476424774247842479424804248142482424834248442485424864248742488424894249042491424924249342494424954249642497424984249942500425014250242503425044250542506425074250842509425104251142512425134251442515425164251742518425194252042521425224252342524425254252642527425284252942530425314253242533425344253542536425374253842539425404254142542425434254442545425464254742548425494255042551425524255342554425554255642557425584255942560425614256242563425644256542566425674256842569425704257142572425734257442575425764257742578425794258042581425824258342584425854258642587425884258942590425914259242593425944259542596425974259842599426004260142602426034260442605426064260742608426094261042611426124261342614426154261642617426184261942620426214262242623426244262542626426274262842629426304263142632426334263442635426364263742638426394264042641426424264342644426454264642647426484264942650426514265242653426544265542656426574265842659426604266142662426634266442665426664266742668426694267042671426724267342674426754267642677426784267942680426814268242683426844268542686426874268842689426904269142692426934269442695426964269742698426994270042701427024270342704427054270642707427084270942710427114271242713427144271542716427174271842719427204272142722427234272442725427264272742728427294273042731427324273342734427354273642737427384273942740427414274242743427444274542746427474274842749427504275142752427534275442755427564275742758427594276042761427624276342764427654276642767427684276942770427714277242773427744277542776427774277842779427804278142782427834278442785427864278742788427894279042791427924279342794427954279642797427984279942800428014280242803428044280542806428074280842809428104281142812428134281442815428164281742818428194282042821428224282342824428254282642827428284282942830428314283242833428344283542836428374283842839428404284142842428434284442845428464284742848428494285042851428524285342854428554285642857428584285942860428614286242863428644286542866428674286842869428704287142872428734287442875428764287742878428794288042881428824288342884428854288642887428884288942890428914289242893428944289542896428974289842899429004290142902429034290442905429064290742908429094291042911429124291342914429154291642917429184291942920429214292242923429244292542926429274292842929429304293142932429334293442935429364293742938429394294042941429424294342944429454294642947429484294942950429514295242953429544295542956429574295842959429604296142962429634296442965429664296742968429694297042971429724297342974429754297642977429784297942980429814298242983429844298542986429874298842989429904299142992429934299442995429964299742998429994300043001430024300343004430054300643007430084300943010430114301243013430144301543016430174301843019430204302143022430234302443025430264302743028430294303043031430324303343034430354303643037430384303943040430414304243043430444304543046430474304843049430504305143052430534305443055430564305743058430594306043061430624306343064430654306643067430684306943070430714307243073430744307543076430774307843079430804308143082430834308443085430864308743088430894309043091430924309343094430954309643097430984309943100431014310243103431044310543106431074310843109431104311143112431134311443115431164311743118431194312043121431224312343124431254312643127431284312943130431314313243133431344313543136431374313843139431404314143142431434314443145431464314743148431494315043151431524315343154431554315643157431584315943160431614316243163431644316543166431674316843169431704317143172431734317443175431764317743178431794318043181431824318343184431854318643187431884318943190431914319243193431944319543196431974319843199432004320143202432034320443205432064320743208432094321043211432124321343214432154321643217432184321943220432214322243223432244322543226432274322843229432304323143232432334323443235432364323743238432394324043241432424324343244432454324643247432484324943250432514325243253432544325543256432574325843259432604326143262432634326443265432664326743268432694327043271432724327343274432754327643277432784327943280432814328243283432844328543286432874328843289432904329143292432934329443295432964329743298432994330043301433024330343304433054330643307433084330943310433114331243313433144331543316433174331843319433204332143322433234332443325433264332743328433294333043331433324333343334433354333643337433384333943340433414334243343433444334543346433474334843349433504335143352433534335443355433564335743358433594336043361433624336343364433654336643367433684336943370433714337243373433744337543376433774337843379433804338143382433834338443385433864338743388433894339043391433924339343394433954339643397433984339943400434014340243403434044340543406434074340843409434104341143412434134341443415434164341743418434194342043421434224342343424434254342643427434284342943430434314343243433434344343543436434374343843439434404344143442434434344443445434464344743448434494345043451434524345343454434554345643457434584345943460434614346243463434644346543466434674346843469434704347143472434734347443475434764347743478434794348043481434824348343484434854348643487434884348943490434914349243493434944349543496434974349843499435004350143502435034350443505435064350743508435094351043511435124351343514435154351643517435184351943520435214352243523435244352543526435274352843529435304353143532435334353443535435364353743538435394354043541435424354343544435454354643547435484354943550435514355243553435544355543556435574355843559435604356143562435634356443565435664356743568435694357043571435724357343574435754357643577435784357943580435814358243583435844358543586435874358843589435904359143592435934359443595435964359743598435994360043601436024360343604436054360643607436084360943610436114361243613436144361543616436174361843619436204362143622436234362443625436264362743628436294363043631436324363343634436354363643637436384363943640436414364243643436444364543646436474364843649436504365143652436534365443655436564365743658436594366043661436624366343664436654366643667436684366943670436714367243673436744367543676436774367843679436804368143682436834368443685436864368743688436894369043691436924369343694436954369643697436984369943700437014370243703437044370543706437074370843709437104371143712437134371443715437164371743718437194372043721437224372343724437254372643727437284372943730437314373243733437344373543736437374373843739437404374143742437434374443745437464374743748437494375043751437524375343754437554375643757437584375943760437614376243763437644376543766437674376843769437704377143772437734377443775437764377743778437794378043781437824378343784437854378643787437884378943790437914379243793437944379543796437974379843799438004380143802438034380443805438064380743808438094381043811438124381343814438154381643817438184381943820438214382243823438244382543826438274382843829438304383143832438334383443835438364383743838438394384043841438424384343844438454384643847438484384943850438514385243853438544385543856438574385843859438604386143862438634386443865438664386743868438694387043871438724387343874438754387643877438784387943880438814388243883438844388543886438874388843889438904389143892438934389443895438964389743898438994390043901439024390343904439054390643907439084390943910439114391243913439144391543916439174391843919439204392143922439234392443925439264392743928439294393043931439324393343934439354393643937439384393943940439414394243943439444394543946439474394843949439504395143952439534395443955439564395743958439594396043961439624396343964439654396643967439684396943970439714397243973439744397543976439774397843979439804398143982439834398443985439864398743988439894399043991439924399343994439954399643997439984399944000440014400244003440044400544006440074400844009440104401144012440134401444015440164401744018440194402044021440224402344024440254402644027440284402944030440314403244033440344403544036440374403844039440404404144042440434404444045440464404744048440494405044051440524405344054440554405644057440584405944060440614406244063440644406544066440674406844069440704407144072440734407444075440764407744078440794408044081440824408344084440854408644087440884408944090440914409244093440944409544096440974409844099441004410144102441034410444105441064410744108441094411044111441124411344114441154411644117441184411944120441214412244123441244412544126441274412844129441304413144132441334413444135441364413744138441394414044141441424414344144441454414644147441484414944150441514415244153441544415544156441574415844159441604416144162441634416444165441664416744168441694417044171441724417344174441754417644177441784417944180441814418244183441844418544186441874418844189441904419144192441934419444195441964419744198441994420044201442024420344204442054420644207442084420944210442114421244213442144421544216442174421844219442204422144222442234422444225442264422744228442294423044231442324423344234442354423644237442384423944240442414424244243442444424544246442474424844249442504425144252442534425444255442564425744258442594426044261442624426344264442654426644267442684426944270442714427244273442744427544276442774427844279442804428144282442834428444285442864428744288442894429044291442924429344294442954429644297442984429944300443014430244303443044430544306443074430844309443104431144312443134431444315443164431744318443194432044321443224432344324443254432644327443284432944330443314433244333443344433544336443374433844339443404434144342443434434444345443464434744348443494435044351443524435344354443554435644357443584435944360443614436244363443644436544366443674436844369443704437144372443734437444375443764437744378443794438044381443824438344384443854438644387443884438944390443914439244393443944439544396443974439844399444004440144402444034440444405444064440744408444094441044411444124441344414444154441644417444184441944420444214442244423444244442544426444274442844429444304443144432444334443444435444364443744438444394444044441444424444344444444454444644447444484444944450444514445244453444544445544456444574445844459444604446144462444634446444465444664446744468444694447044471444724447344474444754447644477444784447944480444814448244483444844448544486444874448844489444904449144492444934449444495444964449744498444994450044501445024450344504445054450644507445084450944510445114451244513445144451544516445174451844519445204452144522445234452444525445264452744528445294453044531445324453344534445354453644537445384453944540445414454244543445444454544546445474454844549445504455144552445534455444555445564455744558445594456044561445624456344564445654456644567445684456944570445714457244573445744457544576445774457844579445804458144582445834458444585445864458744588445894459044591445924459344594445954459644597445984459944600446014460244603446044460544606446074460844609446104461144612446134461444615446164461744618446194462044621446224462344624446254462644627446284462944630446314463244633446344463544636446374463844639446404464144642446434464444645446464464744648446494465044651446524465344654446554465644657446584465944660446614466244663446644466544666446674466844669446704467144672446734467444675446764467744678446794468044681446824468344684446854468644687446884468944690446914469244693446944469544696446974469844699447004470144702447034470444705447064470744708447094471044711447124471344714447154471644717447184471944720447214472244723447244472544726447274472844729447304473144732447334473444735447364473744738447394474044741447424474344744447454474644747447484474944750447514475244753447544475544756447574475844759447604476144762447634476444765447664476744768447694477044771447724477344774447754477644777447784477944780447814478244783447844478544786447874478844789447904479144792447934479444795447964479744798447994480044801448024480344804448054480644807448084480944810448114481244813448144481544816448174481844819448204482144822448234482444825448264482744828448294483044831448324483344834448354483644837448384483944840448414484244843448444484544846448474484844849448504485144852448534485444855448564485744858448594486044861448624486344864448654486644867448684486944870448714487244873448744487544876448774487844879448804488144882448834488444885448864488744888448894489044891448924489344894448954489644897448984489944900449014490244903449044490544906449074490844909449104491144912449134491444915449164491744918449194492044921449224492344924449254492644927449284492944930449314493244933449344493544936449374493844939449404494144942449434494444945449464494744948449494495044951449524495344954449554495644957449584495944960449614496244963449644496544966449674496844969449704497144972449734497444975449764497744978449794498044981449824498344984449854498644987449884498944990449914499244993449944499544996449974499844999450004500145002450034500445005450064500745008450094501045011450124501345014450154501645017450184501945020450214502245023450244502545026450274502845029450304503145032450334503445035450364503745038450394504045041450424504345044450454504645047450484504945050450514505245053450544505545056450574505845059450604506145062450634506445065450664506745068450694507045071450724507345074450754507645077450784507945080450814508245083450844508545086450874508845089450904509145092450934509445095450964509745098450994510045101451024510345104451054510645107451084510945110451114511245113451144511545116451174511845119451204512145122451234512445125451264512745128451294513045131451324513345134451354513645137451384513945140451414514245143451444514545146451474514845149451504515145152451534515445155451564515745158451594516045161451624516345164451654516645167451684516945170451714517245173451744517545176451774517845179451804518145182451834518445185451864518745188451894519045191451924519345194451954519645197451984519945200452014520245203452044520545206452074520845209452104521145212452134521445215452164521745218452194522045221452224522345224452254522645227452284522945230452314523245233452344523545236452374523845239452404524145242452434524445245452464524745248452494525045251452524525345254452554525645257452584525945260452614526245263452644526545266452674526845269452704527145272452734527445275452764527745278452794528045281452824528345284452854528645287452884528945290452914529245293452944529545296452974529845299453004530145302453034530445305453064530745308453094531045311453124531345314453154531645317453184531945320453214532245323453244532545326453274532845329453304533145332453334533445335453364533745338453394534045341453424534345344453454534645347453484534945350453514535245353453544535545356453574535845359453604536145362453634536445365453664536745368453694537045371453724537345374453754537645377453784537945380453814538245383453844538545386453874538845389453904539145392453934539445395453964539745398453994540045401454024540345404454054540645407454084540945410454114541245413454144541545416454174541845419454204542145422454234542445425454264542745428454294543045431454324543345434454354543645437454384543945440454414544245443454444544545446454474544845449454504545145452454534545445455454564545745458454594546045461454624546345464454654546645467454684546945470454714547245473454744547545476454774547845479454804548145482454834548445485454864548745488454894549045491454924549345494454954549645497454984549945500455014550245503455044550545506455074550845509455104551145512455134551445515455164551745518455194552045521455224552345524455254552645527455284552945530455314553245533455344553545536455374553845539455404554145542455434554445545455464554745548455494555045551455524555345554455554555645557455584555945560455614556245563455644556545566455674556845569455704557145572455734557445575455764557745578455794558045581455824558345584455854558645587455884558945590455914559245593455944559545596455974559845599456004560145602456034560445605456064560745608456094561045611456124561345614456154561645617456184561945620456214562245623456244562545626456274562845629456304563145632456334563445635456364563745638456394564045641456424564345644456454564645647456484564945650456514565245653456544565545656456574565845659456604566145662456634566445665456664566745668456694567045671456724567345674456754567645677456784567945680456814568245683456844568545686456874568845689456904569145692456934569445695456964569745698456994570045701457024570345704457054570645707457084570945710457114571245713457144571545716457174571845719457204572145722457234572445725457264572745728457294573045731457324573345734457354573645737457384573945740457414574245743457444574545746457474574845749457504575145752457534575445755457564575745758457594576045761457624576345764457654576645767457684576945770457714577245773457744577545776457774577845779457804578145782457834578445785457864578745788457894579045791457924579345794457954579645797457984579945800458014580245803458044580545806458074580845809458104581145812458134581445815458164581745818458194582045821458224582345824458254582645827458284582945830458314583245833458344583545836458374583845839458404584145842458434584445845458464584745848458494585045851458524585345854458554585645857458584585945860458614586245863458644586545866458674586845869458704587145872458734587445875458764587745878458794588045881458824588345884458854588645887458884588945890458914589245893458944589545896458974589845899459004590145902459034590445905459064590745908459094591045911459124591345914459154591645917459184591945920459214592245923459244592545926459274592845929459304593145932459334593445935459364593745938459394594045941459424594345944459454594645947459484594945950459514595245953459544595545956459574595845959459604596145962459634596445965459664596745968459694597045971459724597345974459754597645977459784597945980459814598245983459844598545986459874598845989459904599145992459934599445995459964599745998459994600046001460024600346004460054600646007460084600946010460114601246013460144601546016460174601846019460204602146022460234602446025460264602746028460294603046031460324603346034460354603646037460384603946040460414604246043460444604546046460474604846049460504605146052460534605446055460564605746058460594606046061460624606346064460654606646067460684606946070460714607246073460744607546076460774607846079460804608146082460834608446085460864608746088460894609046091460924609346094460954609646097460984609946100461014610246103461044610546106461074610846109461104611146112461134611446115461164611746118461194612046121461224612346124461254612646127461284612946130461314613246133461344613546136461374613846139461404614146142461434614446145461464614746148461494615046151461524615346154461554615646157461584615946160461614616246163461644616546166461674616846169461704617146172461734617446175461764617746178461794618046181461824618346184461854618646187461884618946190461914619246193461944619546196461974619846199462004620146202462034620446205462064620746208462094621046211462124621346214462154621646217462184621946220462214622246223462244622546226462274622846229462304623146232462334623446235462364623746238462394624046241462424624346244462454624646247462484624946250462514625246253462544625546256462574625846259462604626146262462634626446265462664626746268462694627046271462724627346274462754627646277462784627946280462814628246283462844628546286462874628846289462904629146292462934629446295462964629746298462994630046301463024630346304463054630646307463084630946310463114631246313463144631546316463174631846319463204632146322463234632446325463264632746328463294633046331463324633346334463354633646337463384633946340463414634246343463444634546346463474634846349463504635146352463534635446355463564635746358463594636046361463624636346364463654636646367463684636946370463714637246373463744637546376463774637846379463804638146382463834638446385463864638746388463894639046391463924639346394463954639646397463984639946400464014640246403464044640546406464074640846409464104641146412464134641446415464164641746418464194642046421464224642346424464254642646427464284642946430464314643246433464344643546436464374643846439464404644146442464434644446445464464644746448464494645046451464524645346454464554645646457464584645946460464614646246463464644646546466464674646846469464704647146472464734647446475464764647746478464794648046481464824648346484464854648646487464884648946490464914649246493464944649546496464974649846499465004650146502465034650446505465064650746508465094651046511465124651346514465154651646517465184651946520465214652246523465244652546526465274652846529465304653146532465334653446535465364653746538465394654046541465424654346544465454654646547465484654946550465514655246553465544655546556465574655846559465604656146562465634656446565465664656746568465694657046571465724657346574465754657646577465784657946580465814658246583465844658546586465874658846589465904659146592465934659446595465964659746598465994660046601466024660346604466054660646607466084660946610466114661246613466144661546616466174661846619466204662146622466234662446625466264662746628466294663046631466324663346634466354663646637466384663946640466414664246643466444664546646466474664846649466504665146652466534665446655466564665746658466594666046661466624666346664466654666646667466684666946670466714667246673466744667546676466774667846679466804668146682466834668446685466864668746688466894669046691466924669346694466954669646697466984669946700467014670246703467044670546706467074670846709467104671146712467134671446715467164671746718467194672046721467224672346724467254672646727467284672946730467314673246733467344673546736467374673846739467404674146742467434674446745467464674746748467494675046751467524675346754467554675646757467584675946760467614676246763467644676546766467674676846769467704677146772467734677446775467764677746778467794678046781467824678346784467854678646787467884678946790467914679246793467944679546796467974679846799468004680146802468034680446805468064680746808468094681046811468124681346814468154681646817468184681946820468214682246823468244682546826468274682846829468304683146832468334683446835468364683746838468394684046841468424684346844468454684646847468484684946850468514685246853468544685546856468574685846859468604686146862468634686446865468664686746868468694687046871468724687346874468754687646877468784687946880468814688246883468844688546886468874688846889468904689146892468934689446895468964689746898468994690046901469024690346904469054690646907469084690946910469114691246913469144691546916469174691846919469204692146922469234692446925469264692746928469294693046931469324693346934469354693646937469384693946940469414694246943469444694546946469474694846949469504695146952469534695446955469564695746958469594696046961469624696346964469654696646967469684696946970469714697246973469744697546976469774697846979469804698146982469834698446985469864698746988469894699046991469924699346994469954699646997469984699947000470014700247003470044700547006470074700847009470104701147012470134701447015470164701747018470194702047021470224702347024470254702647027470284702947030470314703247033470344703547036470374703847039470404704147042470434704447045470464704747048470494705047051470524705347054470554705647057470584705947060470614706247063470644706547066470674706847069470704707147072470734707447075470764707747078470794708047081470824708347084470854708647087470884708947090470914709247093470944709547096470974709847099471004710147102471034710447105471064710747108471094711047111471124711347114471154711647117471184711947120471214712247123471244712547126471274712847129471304713147132471334713447135471364713747138471394714047141471424714347144471454714647147471484714947150471514715247153471544715547156471574715847159471604716147162471634716447165471664716747168471694717047171471724717347174471754717647177471784717947180471814718247183471844718547186471874718847189471904719147192471934719447195471964719747198471994720047201472024720347204472054720647207472084720947210472114721247213472144721547216472174721847219472204722147222472234722447225472264722747228472294723047231472324723347234472354723647237472384723947240472414724247243472444724547246472474724847249472504725147252472534725447255472564725747258472594726047261472624726347264472654726647267472684726947270472714727247273472744727547276472774727847279472804728147282472834728447285472864728747288472894729047291472924729347294472954729647297472984729947300473014730247303473044730547306473074730847309473104731147312473134731447315473164731747318473194732047321473224732347324473254732647327473284732947330473314733247333473344733547336473374733847339473404734147342473434734447345473464734747348473494735047351473524735347354473554735647357473584735947360473614736247363473644736547366473674736847369473704737147372473734737447375473764737747378473794738047381473824738347384473854738647387473884738947390473914739247393473944739547396473974739847399474004740147402474034740447405474064740747408474094741047411474124741347414474154741647417474184741947420474214742247423474244742547426474274742847429474304743147432474334743447435474364743747438474394744047441474424744347444474454744647447474484744947450474514745247453474544745547456474574745847459474604746147462474634746447465474664746747468474694747047471474724747347474474754747647477474784747947480474814748247483474844748547486474874748847489474904749147492474934749447495474964749747498474994750047501475024750347504475054750647507475084750947510475114751247513475144751547516475174751847519475204752147522475234752447525475264752747528475294753047531475324753347534475354753647537475384753947540475414754247543475444754547546475474754847549475504755147552475534755447555475564755747558475594756047561475624756347564475654756647567475684756947570475714757247573475744757547576475774757847579475804758147582475834758447585475864758747588475894759047591475924759347594475954759647597475984759947600476014760247603476044760547606476074760847609476104761147612476134761447615476164761747618476194762047621476224762347624476254762647627476284762947630476314763247633476344763547636476374763847639476404764147642476434764447645476464764747648476494765047651476524765347654476554765647657476584765947660476614766247663476644766547666476674766847669476704767147672476734767447675476764767747678476794768047681476824768347684476854768647687476884768947690476914769247693476944769547696476974769847699477004770147702477034770447705477064770747708477094771047711477124771347714477154771647717477184771947720477214772247723477244772547726477274772847729477304773147732477334773447735477364773747738477394774047741477424774347744477454774647747477484774947750477514775247753477544775547756477574775847759477604776147762477634776447765477664776747768477694777047771477724777347774477754777647777477784777947780477814778247783477844778547786477874778847789477904779147792477934779447795477964779747798477994780047801478024780347804478054780647807478084780947810478114781247813478144781547816478174781847819478204782147822478234782447825478264782747828478294783047831478324783347834478354783647837478384783947840478414784247843478444784547846478474784847849478504785147852478534785447855478564785747858478594786047861478624786347864478654786647867478684786947870478714787247873478744787547876478774787847879478804788147882478834788447885478864788747888478894789047891478924789347894478954789647897478984789947900479014790247903479044790547906479074790847909479104791147912479134791447915479164791747918479194792047921479224792347924479254792647927479284792947930479314793247933479344793547936479374793847939479404794147942479434794447945479464794747948479494795047951479524795347954479554795647957479584795947960479614796247963479644796547966479674796847969479704797147972479734797447975479764797747978479794798047981479824798347984479854798647987479884798947990479914799247993479944799547996479974799847999480004800148002480034800448005480064800748008480094801048011480124801348014480154801648017480184801948020480214802248023480244802548026480274802848029480304803148032480334803448035480364803748038480394804048041480424804348044480454804648047480484804948050480514805248053480544805548056480574805848059480604806148062480634806448065480664806748068480694807048071480724807348074480754807648077480784807948080480814808248083480844808548086480874808848089480904809148092480934809448095480964809748098480994810048101481024810348104481054810648107481084810948110481114811248113481144811548116481174811848119481204812148122481234812448125481264812748128481294813048131481324813348134481354813648137481384813948140481414814248143481444814548146481474814848149481504815148152481534815448155481564815748158481594816048161481624816348164481654816648167481684816948170481714817248173481744817548176481774817848179481804818148182481834818448185481864818748188481894819048191481924819348194481954819648197481984819948200482014820248203482044820548206482074820848209482104821148212482134821448215482164821748218482194822048221482224822348224482254822648227482284822948230482314823248233482344823548236482374823848239482404824148242482434824448245482464824748248482494825048251482524825348254482554825648257482584825948260482614826248263482644826548266482674826848269482704827148272482734827448275482764827748278482794828048281482824828348284482854828648287482884828948290482914829248293482944829548296482974829848299483004830148302483034830448305483064830748308483094831048311483124831348314483154831648317483184831948320483214832248323483244832548326483274832848329483304833148332483334833448335483364833748338483394834048341483424834348344483454834648347483484834948350483514835248353483544835548356483574835848359483604836148362483634836448365483664836748368483694837048371483724837348374483754837648377483784837948380483814838248383483844838548386483874838848389483904839148392483934839448395483964839748398483994840048401484024840348404 |
- \input texinfo @c -*-texinfo-*-
- @c Copyright (C) 1988--2022 Free Software Foundation, Inc.
- @c
- @c %**start of header
- @c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
- @c of @set vars. However, you can override filename with makeinfo -o.
- @setfilename gdb.info
- @c
- @c man begin INCLUDE
- @include gdb-cfg.texi
- @c man end
- @c
- @settitle Debugging with @value{GDBN}
- @setchapternewpage odd
- @c %**end of header
- @iftex
- @c @smallbook
- @c @cropmarks
- @end iftex
- @finalout
- @c To avoid file-name clashes between index.html and Index.html, when
- @c the manual is produced on a Posix host and then moved to a
- @c case-insensitive filesystem (e.g., MS-Windows), we separate the
- @c indices into two: Concept Index and all the rest.
- @syncodeindex ky fn
- @syncodeindex tp fn
- @c readline appendices use @vindex, @findex and @ftable,
- @c annotate.texi and gdbmi use @findex.
- @syncodeindex vr fn
- @c !!set GDB manual's edition---not the same as GDB version!
- @c This is updated by GNU Press.
- @set EDITION Tenth
- @c !!set GDB edit command default editor
- @set EDITOR /bin/ex
- @c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.
- @c This is a dir.info fragment to support semi-automated addition of
- @c manuals to an info tree.
- @dircategory Software development
- @direntry
- * Gdb: (gdb). The GNU debugger.
- * gdbserver: (gdb) Server. The GNU debugging server.
- @end direntry
- @copying
- @c man begin COPYRIGHT
- Copyright @copyright{} 1988-2022 Free Software Foundation, Inc.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with the
- Invariant Sections being ``Free Software'' and ``Free Software Needs
- Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
- and with the Back-Cover Texts as in (a) below.
- (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
- this GNU Manual. Buying copies from GNU Press supports the FSF in
- developing GNU and promoting software freedom.''
- @c man end
- @end copying
- @ifnottex
- This file documents the @sc{gnu} debugger @value{GDBN}.
- This is the @value{EDITION} Edition, of @cite{Debugging with
- @value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
- @ifset VERSION_PACKAGE
- @value{VERSION_PACKAGE}
- @end ifset
- Version @value{GDBVN}.
- @insertcopying
- @end ifnottex
- @titlepage
- @title Debugging with @value{GDBN}
- @subtitle The @sc{gnu} Source-Level Debugger
- @sp 1
- @subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
- @ifset VERSION_PACKAGE
- @sp 1
- @subtitle @value{VERSION_PACKAGE}
- @end ifset
- @author Richard Stallman, Roland Pesch, Stan Shebs, et al.
- @page
- @tex
- {\parskip=0pt
- \hfill (Send bugs and comments on @value{GDBN} to @value{BUGURL}.)\par
- \hfill {\it Debugging with @value{GDBN}}\par
- \hfill \TeX{}info \texinfoversion\par
- }
- @end tex
- @vskip 0pt plus 1filll
- Published by the Free Software Foundation @*
- 51 Franklin Street, Fifth Floor,
- Boston, MA 02110-1301, USA@*
- ISBN 978-0-9831592-3-0 @*
- @insertcopying
- @end titlepage
- @page
- @ifnottex
- @node Top, Summary
- @top Debugging with @value{GDBN}
- This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
- This is the @value{EDITION} Edition, for @value{GDBN}
- @ifset VERSION_PACKAGE
- @value{VERSION_PACKAGE}
- @end ifset
- Version @value{GDBVN}.
- Copyright (C) 1988-2022 Free Software Foundation, Inc.
- This edition of the GDB manual is dedicated to the memory of Fred
- Fish. Fred was a long-standing contributor to GDB and to Free
- software in general. We will miss him.
- @menu
- * Summary:: Summary of @value{GDBN}
- * Sample Session:: A sample @value{GDBN} session
- * Invocation:: Getting in and out of @value{GDBN}
- * Commands:: @value{GDBN} commands
- * Running:: Running programs under @value{GDBN}
- * Stopping:: Stopping and continuing
- * Reverse Execution:: Running programs backward
- * Process Record and Replay:: Recording inferior's execution and replaying it
- * Stack:: Examining the stack
- * Source:: Examining source files
- * Data:: Examining data
- * Optimized Code:: Debugging optimized code
- * Macros:: Preprocessor Macros
- * Tracepoints:: Debugging remote targets non-intrusively
- * Overlays:: Debugging programs that use overlays
- * Languages:: Using @value{GDBN} with different languages
- * Symbols:: Examining the symbol table
- * Altering:: Altering execution
- * GDB Files:: @value{GDBN} files
- * Targets:: Specifying a debugging target
- * Remote Debugging:: Debugging remote programs
- * Configurations:: Configuration-specific information
- * Controlling GDB:: Controlling @value{GDBN}
- * Extending GDB:: Extending @value{GDBN}
- * Interpreters:: Command Interpreters
- * TUI:: @value{GDBN} Text User Interface
- * Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
- * GDB/MI:: @value{GDBN}'s Machine Interface.
- * Annotations:: @value{GDBN}'s annotation interface.
- * JIT Interface:: Using the JIT debugging interface.
- * In-Process Agent:: In-Process Agent
- * GDB Bugs:: Reporting bugs in @value{GDBN}
- @ifset SYSTEM_READLINE
- * Command Line Editing: (rluserman). Command Line Editing
- * Using History Interactively: (history). Using History Interactively
- @end ifset
- @ifclear SYSTEM_READLINE
- * Command Line Editing:: Command Line Editing
- * Using History Interactively:: Using History Interactively
- @end ifclear
- * In Memoriam:: In Memoriam
- * Formatting Documentation:: How to format and print @value{GDBN} documentation
- * Installing GDB:: Installing GDB
- * Maintenance Commands:: Maintenance Commands
- * Remote Protocol:: GDB Remote Serial Protocol
- * Agent Expressions:: The GDB Agent Expression Mechanism
- * Target Descriptions:: How targets can describe themselves to
- @value{GDBN}
- * Operating System Information:: Getting additional information from
- the operating system
- * Trace File Format:: GDB trace file format
- * Index Section Format:: .gdb_index section format
- * Debuginfod:: Download debugging resources with @code{debuginfod}
- * Man Pages:: Manual pages
- * Copying:: GNU General Public License says
- how you can copy and share GDB
- * GNU Free Documentation License:: The license for this documentation
- * Concept Index:: Index of @value{GDBN} concepts
- * Command and Variable Index:: Index of @value{GDBN} commands, variables,
- functions, and Python data types
- @end menu
- @end ifnottex
- @contents
- @node Summary
- @unnumbered Summary of @value{GDBN}
- The purpose of a debugger such as @value{GDBN} is to allow you to see what is
- going on ``inside'' another program while it executes---or what another
- program was doing at the moment it crashed.
- @value{GDBN} can do four main kinds of things (plus other things in support of
- these) to help you catch bugs in the act:
- @itemize @bullet
- @item
- Start your program, specifying anything that might affect its behavior.
- @item
- Make your program stop on specified conditions.
- @item
- Examine what has happened, when your program has stopped.
- @item
- Change things in your program, so you can experiment with correcting the
- effects of one bug and go on to learn about another.
- @end itemize
- You can use @value{GDBN} to debug programs written in C and C@t{++}.
- For more information, see @ref{Supported Languages,,Supported Languages}.
- For more information, see @ref{C,,C and C++}.
- Support for D is partial. For information on D, see
- @ref{D,,D}.
- @cindex Modula-2
- Support for Modula-2 is partial. For information on Modula-2, see
- @ref{Modula-2,,Modula-2}.
- Support for OpenCL C is partial. For information on OpenCL C, see
- @ref{OpenCL C,,OpenCL C}.
- @cindex Pascal
- Debugging Pascal programs which use sets, subranges, file variables, or
- nested functions does not currently work. @value{GDBN} does not support
- entering expressions, printing values, or similar features using Pascal
- syntax.
- @cindex Fortran
- @value{GDBN} can be used to debug programs written in Fortran, although
- it may be necessary to refer to some variables with a trailing
- underscore.
- @value{GDBN} can be used to debug programs written in Objective-C,
- using either the Apple/NeXT or the GNU Objective-C runtime.
- @menu
- * Free Software:: Freely redistributable software
- * Free Documentation:: Free Software Needs Free Documentation
- * Contributors:: Contributors to GDB
- @end menu
- @node Free Software
- @unnumberedsec Free Software
- @value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
- General Public License
- (GPL). The GPL gives you the freedom to copy or adapt a licensed
- program---but every person getting a copy also gets with it the
- freedom to modify that copy (which means that they must get access to
- the source code), and the freedom to distribute further copies.
- Typical software companies use copyrights to limit your freedoms; the
- Free Software Foundation uses the GPL to preserve these freedoms.
- Fundamentally, the General Public License is a license which says that
- you have these freedoms and that you cannot take these freedoms away
- from anyone else.
- @node Free Documentation
- @unnumberedsec Free Software Needs Free Documentation
- The biggest deficiency in the free software community today is not in
- the software---it is the lack of good free documentation that we can
- include with the free software. Many of our most important
- programs do not come with free reference manuals and free introductory
- texts. Documentation is an essential part of any software package;
- when an important free software package does not come with a free
- manual and a free tutorial, that is a major gap. We have many such
- gaps today.
- Consider Perl, for instance. The tutorial manuals that people
- normally use are non-free. How did this come about? Because the
- authors of those manuals published them with restrictive terms---no
- copying, no modification, source files not available---which exclude
- them from the free software world.
- That wasn't the first time this sort of thing happened, and it was far
- from the last. Many times we have heard a GNU user eagerly describe a
- manual that he is writing, his intended contribution to the community,
- only to learn that he had ruined everything by signing a publication
- contract to make it non-free.
- Free documentation, like free software, is a matter of freedom, not
- price. The problem with the non-free manual is not that publishers
- charge a price for printed copies---that in itself is fine. (The Free
- Software Foundation sells printed copies of manuals, too.) The
- problem is the restrictions on the use of the manual. Free manuals
- are available in source code form, and give you permission to copy and
- modify. Non-free manuals do not allow this.
- The criteria of freedom for a free manual are roughly the same as for
- free software. Redistribution (including the normal kinds of
- commercial redistribution) must be permitted, so that the manual can
- accompany every copy of the program, both on-line and on paper.
- Permission for modification of the technical content is crucial too.
- When people modify the software, adding or changing features, if they
- are conscientious they will change the manual too---so they can
- provide accurate and clear documentation for the modified program. A
- manual that leaves you no choice but to write a new manual to document
- a changed version of the program is not really available to our
- community.
- Some kinds of limits on the way modification is handled are
- acceptable. For example, requirements to preserve the original
- author's copyright notice, the distribution terms, or the list of
- authors, are ok. It is also no problem to require modified versions
- to include notice that they were modified. Even entire sections that
- may not be deleted or changed are acceptable, as long as they deal
- with nontechnical topics (like this one). These kinds of restrictions
- are acceptable because they don't obstruct the community's normal use
- of the manual.
- However, it must be possible to modify all the @emph{technical}
- content of the manual, and then distribute the result in all the usual
- media, through all the usual channels. Otherwise, the restrictions
- obstruct the use of the manual, it is not free, and we need another
- manual to replace it.
- Please spread the word about this issue. Our community continues to
- lose manuals to proprietary publishing. If we spread the word that
- free software needs free reference manuals and free tutorials, perhaps
- the next person who wants to contribute by writing documentation will
- realize, before it is too late, that only free manuals contribute to
- the free software community.
- If you are writing documentation, please insist on publishing it under
- the GNU Free Documentation License or another free documentation
- license. Remember that this decision requires your approval---you
- don't have to let the publisher decide. Some commercial publishers
- will use a free license if you insist, but they will not propose the
- option; it is up to you to raise the issue and say firmly that this is
- what you want. If the publisher you are dealing with refuses, please
- try other publishers. If you're not sure whether a proposed license
- is free, write to @email{licensing@@gnu.org}.
- You can encourage commercial publishers to sell more free, copylefted
- manuals and tutorials by buying them, and particularly by buying
- copies from the publishers that paid for their writing or for major
- improvements. Meanwhile, try to avoid buying non-free documentation
- at all. Check the distribution terms of a manual before you buy it,
- and insist that whoever seeks your business must respect your freedom.
- Check the history of the book, and try to reward the publishers that
- have paid or pay the authors to work on it.
- The Free Software Foundation maintains a list of free documentation
- published by other publishers, at
- @url{http://www.fsf.org/doc/other-free-books.html}.
- @node Contributors
- @unnumberedsec Contributors to @value{GDBN}
- Richard Stallman was the original author of @value{GDBN}, and of many
- other @sc{gnu} programs. Many others have contributed to its
- development. This section attempts to credit major contributors. One
- of the virtues of free software is that everyone is free to contribute
- to it; with regret, we cannot actually acknowledge everyone here. The
- file @file{ChangeLog} in the @value{GDBN} distribution approximates a
- blow-by-blow account.
- Changes much prior to version 2.0 are lost in the mists of time.
- @quotation
- @emph{Plea:} Additions to this section are particularly welcome. If you
- or your friends (or enemies, to be evenhanded) have been unfairly
- omitted from this list, we would like to add your names!
- @end quotation
- So that they may not regard their many labors as thankless, we
- particularly thank those who shepherded @value{GDBN} through major
- releases:
- Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
- Jim Blandy (release 4.18);
- Jason Molenda (release 4.17);
- Stan Shebs (release 4.14);
- Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
- Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
- John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
- Jim Kingdon (releases 3.5, 3.4, and 3.3);
- and Randy Smith (releases 3.2, 3.1, and 3.0).
- Richard Stallman, assisted at various times by Peter TerMaat, Chris
- Hanson, and Richard Mlynarik, handled releases through 2.8.
- Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
- in @value{GDBN}, with significant additional contributions from Per
- Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++}
- demangler. Early work on C@t{++} was by Peter TerMaat (who also did
- much general update work leading to release 3.0).
- @value{GDBN} uses the BFD subroutine library to examine multiple
- object-file formats; BFD was a joint project of David V.
- Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
- David Johnson wrote the original COFF support; Pace Willison did
- the original support for encapsulated COFF.
- Brent Benson of Harris Computer Systems contributed DWARF 2 support.
- Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
- Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
- support.
- Jean-Daniel Fekete contributed Sun 386i support.
- Chris Hanson improved the HP9000 support.
- Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
- David Johnson contributed Encore Umax support.
- Jyrki Kuoppala contributed Altos 3068 support.
- Jeff Law contributed HP PA and SOM support.
- Keith Packard contributed NS32K support.
- Doug Rabson contributed Acorn Risc Machine support.
- Bob Rusk contributed Harris Nighthawk CX-UX support.
- Chris Smith contributed Convex support (and Fortran debugging).
- Jonathan Stone contributed Pyramid support.
- Michael Tiemann contributed SPARC support.
- Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
- Pace Willison contributed Intel 386 support.
- Jay Vosburgh contributed Symmetry support.
- Marko Mlinar contributed OpenRISC 1000 support.
- Andreas Schwab contributed M68K @sc{gnu}/Linux support.
- Rich Schaefer and Peter Schauer helped with support of SunOS shared
- libraries.
- Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
- about several machine instruction sets.
- Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
- remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
- contributed remote debugging modules for the i960, VxWorks, A29K UDI,
- and RDI targets, respectively.
- Brian Fox is the author of the readline libraries providing
- command-line editing and command history.
- Andrew Beers of SUNY Buffalo wrote the language-switching code, the
- Modula-2 support, and contributed the Languages chapter of this manual.
- Fred Fish wrote most of the support for Unix System Vr4.
- He also enhanced the command-completion support to cover C@t{++} overloaded
- symbols.
- Hitachi America (now Renesas America), Ltd. sponsored the support for
- H8/300, H8/500, and Super-H processors.
- NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
- Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D
- processors.
- Toshiba sponsored the support for the TX39 Mips processor.
- Matsushita sponsored the support for the MN10200 and MN10300 processors.
- Fujitsu sponsored the support for SPARClite and FR30 processors.
- Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
- watchpoints.
- Michael Snyder added support for tracepoints.
- Stu Grossman wrote gdbserver.
- Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
- nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
- The following people at the Hewlett-Packard Company contributed
- support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
- (narrow mode), HP's implementation of kernel threads, HP's aC@t{++}
- compiler, and the Text User Interface (nee Terminal User Interface):
- Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
- Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
- provided HP-specific information in this manual.
- DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
- Robert Hoehne made significant contributions to the DJGPP port.
- Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
- development since 1991. Cygnus engineers who have worked on @value{GDBN}
- fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
- Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
- Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
- Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
- Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
- addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
- JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
- Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
- Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
- Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
- Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
- Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
- Zuhn have made contributions both large and small.
- Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
- Cygnus Solutions, implemented the original @sc{gdb/mi} interface.
- Jim Blandy added support for preprocessor macros, while working for Red
- Hat.
- Andrew Cagney designed @value{GDBN}'s architecture vector. Many
- people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
- Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei
- Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason
- Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
- with the migration of old architectures to this new framework.
- Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s
- unwinder framework, this consisting of a fresh new design featuring
- frame IDs, independent frame sniffers, and the sentinel frame. Mark
- Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
- libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
- trad unwinders. The architecture-specific changes, each involving a
- complete rewrite of the architecture's frame code, were carried out by
- Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
- Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
- Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
- Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
- Weigand.
- Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
- Tensilica, Inc.@: contributed support for Xtensa processors. Others
- who have worked on the Xtensa port of @value{GDBN} in the past include
- Steve Tjiang, John Newlin, and Scott Foehner.
- Michael Eager and staff of Xilinx, Inc., contributed support for the
- Xilinx MicroBlaze architecture.
- Initial support for the FreeBSD/mips target and native configuration
- was developed by SRI International and the University of Cambridge
- Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237
- ("CTSRD"), as part of the DARPA CRASH research programme.
- Initial support for the FreeBSD/riscv target and native configuration
- was developed by SRI International and the University of Cambridge
- Computer Laboratory (Department of Computer Science and Technology)
- under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA
- SSITH research programme.
- The original port to the OpenRISC 1000 is believed to be due to
- Alessandro Forin and Per Bothner. More recent ports have been the work
- of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and
- Stafford Horne.
- Weimin Pan, David Faust and Jose E. Marchesi contributed support for
- the Linux kernel BPF virtual architecture. This work was sponsored by
- Oracle.
- @node Sample Session
- @chapter A Sample @value{GDBN} Session
- You can use this manual at your leisure to read all about @value{GDBN}.
- However, a handful of commands are enough to get started using the
- debugger. This chapter illustrates those commands.
- @iftex
- In this sample session, we emphasize user input like this: @b{input},
- to make it easier to pick out from the surrounding output.
- @end iftex
- @c FIXME: this example may not be appropriate for some configs, where
- @c FIXME...primary interest is in remote use.
- One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
- processor) exhibits the following bug: sometimes, when we change its
- quote strings from the default, the commands used to capture one macro
- definition within another stop working. In the following short @code{m4}
- session, we define a macro @code{foo} which expands to @code{0000}; we
- then use the @code{m4} built-in @code{defn} to define @code{bar} as the
- same thing. However, when we change the open quote string to
- @code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
- procedure fails to define a new synonym @code{baz}:
- @smallexample
- $ @b{cd gnu/m4}
- $ @b{./m4}
- @b{define(foo,0000)}
- @b{foo}
- 0000
- @b{define(bar,defn(`foo'))}
- @b{bar}
- 0000
- @b{changequote(<QUOTE>,<UNQUOTE>)}
- @b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
- @b{baz}
- @b{Ctrl-d}
- m4: End of input: 0: fatal error: EOF in string
- @end smallexample
- @noindent
- Let us use @value{GDBN} to try to see what is going on.
- @smallexample
- $ @b{@value{GDBP} m4}
- @c FIXME: this falsifies the exact text played out, to permit smallbook
- @c FIXME... format to come out better.
- @value{GDBN} is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
- the conditions.
- There is absolutely no warranty for @value{GDBN}; type "show warranty"
- for details.
- @value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
- (@value{GDBP})
- @end smallexample
- @noindent
- @value{GDBN} reads only enough symbol data to know where to find the
- rest when needed; as a result, the first prompt comes up very quickly.
- We now tell @value{GDBN} to use a narrower display width than usual, so
- that examples fit in this manual.
- @smallexample
- (@value{GDBP}) @b{set width 70}
- @end smallexample
- @noindent
- We need to see how the @code{m4} built-in @code{changequote} works.
- Having looked at the source, we know the relevant subroutine is
- @code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
- @code{break} command.
- @smallexample
- (@value{GDBP}) @b{break m4_changequote}
- Breakpoint 1 at 0x62f4: file builtin.c, line 879.
- @end smallexample
- @noindent
- Using the @code{run} command, we start @code{m4} running under @value{GDBN}
- control; as long as control does not reach the @code{m4_changequote}
- subroutine, the program runs as usual:
- @smallexample
- (@value{GDBP}) @b{run}
- Starting program: /work/Editorial/gdb/gnu/m4/m4
- @b{define(foo,0000)}
- @b{foo}
- 0000
- @end smallexample
- @noindent
- To trigger the breakpoint, we call @code{changequote}. @value{GDBN}
- suspends execution of @code{m4}, displaying information about the
- context where it stops.
- @smallexample
- @b{changequote(<QUOTE>,<UNQUOTE>)}
- Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
- at builtin.c:879
- 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
- @end smallexample
- @noindent
- Now we use the command @code{n} (@code{next}) to advance execution to
- the next line of the current function.
- @smallexample
- (@value{GDBP}) @b{n}
- 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
- : nil,
- @end smallexample
- @noindent
- @code{set_quotes} looks like a promising subroutine. We can go into it
- by using the command @code{s} (@code{step}) instead of @code{next}.
- @code{step} goes to the next line to be executed in @emph{any}
- subroutine, so it steps into @code{set_quotes}.
- @smallexample
- (@value{GDBP}) @b{s}
- set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
- at input.c:530
- 530 if (lquote != def_lquote)
- @end smallexample
- @noindent
- The display that shows the subroutine where @code{m4} is now
- suspended (and its arguments) is called a stack frame display. It
- shows a summary of the stack. We can use the @code{backtrace}
- command (which can also be spelled @code{bt}), to see where we are
- in the stack as a whole: the @code{backtrace} command displays a
- stack frame for each active subroutine.
- @smallexample
- (@value{GDBP}) @b{bt}
- #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
- at input.c:530
- #1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
- at builtin.c:882
- #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
- #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
- at macro.c:71
- #4 0x79dc in expand_input () at macro.c:40
- #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
- @end smallexample
- @noindent
- We step through a few more lines to see what happens. The first two
- times, we can use @samp{s}; the next two times we use @code{n} to avoid
- falling into the @code{xstrdup} subroutine.
- @smallexample
- (@value{GDBP}) @b{s}
- 0x3b5c 532 if (rquote != def_rquote)
- (@value{GDBP}) @b{s}
- 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
- def_lquote : xstrdup(lq);
- (@value{GDBP}) @b{n}
- 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
- : xstrdup(rq);
- (@value{GDBP}) @b{n}
- 538 len_lquote = strlen(rquote);
- @end smallexample
- @noindent
- The last line displayed looks a little odd; we can examine the variables
- @code{lquote} and @code{rquote} to see if they are in fact the new left
- and right quotes we specified. We use the command @code{p}
- (@code{print}) to see their values.
- @smallexample
- (@value{GDBP}) @b{p lquote}
- $1 = 0x35d40 "<QUOTE>"
- (@value{GDBP}) @b{p rquote}
- $2 = 0x35d50 "<UNQUOTE>"
- @end smallexample
- @noindent
- @code{lquote} and @code{rquote} are indeed the new left and right quotes.
- To look at some context, we can display ten lines of source
- surrounding the current line with the @code{l} (@code{list}) command.
- @smallexample
- (@value{GDBP}) @b{l}
- 533 xfree(rquote);
- 534
- 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
- : xstrdup (lq);
- 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
- : xstrdup (rq);
- 537
- 538 len_lquote = strlen(rquote);
- 539 len_rquote = strlen(lquote);
- 540 @}
- 541
- 542 void
- @end smallexample
- @noindent
- Let us step past the two lines that set @code{len_lquote} and
- @code{len_rquote}, and then examine the values of those variables.
- @smallexample
- (@value{GDBP}) @b{n}
- 539 len_rquote = strlen(lquote);
- (@value{GDBP}) @b{n}
- 540 @}
- (@value{GDBP}) @b{p len_lquote}
- $3 = 9
- (@value{GDBP}) @b{p len_rquote}
- $4 = 7
- @end smallexample
- @noindent
- That certainly looks wrong, assuming @code{len_lquote} and
- @code{len_rquote} are meant to be the lengths of @code{lquote} and
- @code{rquote} respectively. We can set them to better values using
- the @code{p} command, since it can print the value of
- any expression---and that expression can include subroutine calls and
- assignments.
- @smallexample
- (@value{GDBP}) @b{p len_lquote=strlen(lquote)}
- $5 = 7
- (@value{GDBP}) @b{p len_rquote=strlen(rquote)}
- $6 = 9
- @end smallexample
- @noindent
- Is that enough to fix the problem of using the new quotes with the
- @code{m4} built-in @code{defn}? We can allow @code{m4} to continue
- executing with the @code{c} (@code{continue}) command, and then try the
- example that caused trouble initially:
- @smallexample
- (@value{GDBP}) @b{c}
- Continuing.
- @b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
- baz
- 0000
- @end smallexample
- @noindent
- Success! The new quotes now work just as well as the default ones. The
- problem seems to have been just the two typos defining the wrong
- lengths. We allow @code{m4} exit by giving it an EOF as input:
- @smallexample
- @b{Ctrl-d}
- Program exited normally.
- @end smallexample
- @noindent
- The message @samp{Program exited normally.} is from @value{GDBN}; it
- indicates @code{m4} has finished executing. We can end our @value{GDBN}
- session with the @value{GDBN} @code{quit} command.
- @smallexample
- (@value{GDBP}) @b{quit}
- @end smallexample
- @node Invocation
- @chapter Getting In and Out of @value{GDBN}
- This chapter discusses how to start @value{GDBN}, and how to get out of it.
- The essentials are:
- @itemize @bullet
- @item
- type @samp{@value{GDBP}} to start @value{GDBN}.
- @item
- type @kbd{quit}, @kbd{exit} or @kbd{Ctrl-d} to exit.
- @end itemize
- @menu
- * Invoking GDB:: How to start @value{GDBN}
- * Quitting GDB:: How to quit @value{GDBN}
- * Shell Commands:: How to use shell commands inside @value{GDBN}
- * Logging Output:: How to log @value{GDBN}'s output to a file
- @end menu
- @node Invoking GDB
- @section Invoking @value{GDBN}
- Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
- @value{GDBN} reads commands from the terminal until you tell it to exit.
- You can also run @code{@value{GDBP}} with a variety of arguments and options,
- to specify more of your debugging environment at the outset.
- The command-line options described here are designed
- to cover a variety of situations; in some environments, some of these
- options may effectively be unavailable.
- The most usual way to start @value{GDBN} is with one argument,
- specifying an executable program:
- @smallexample
- @value{GDBP} @var{program}
- @end smallexample
- @noindent
- You can also start with both an executable program and a core file
- specified:
- @smallexample
- @value{GDBP} @var{program} @var{core}
- @end smallexample
- You can, instead, specify a process ID as a second argument or use option
- @code{-p}, if you want to debug a running process:
- @smallexample
- @value{GDBP} @var{program} 1234
- @value{GDBP} -p 1234
- @end smallexample
- @noindent
- would attach @value{GDBN} to process @code{1234}. With option @option{-p} you
- can omit the @var{program} filename.
- Taking advantage of the second command-line argument requires a fairly
- complete operating system; when you use @value{GDBN} as a remote
- debugger attached to a bare board, there may not be any notion of
- ``process'', and there is often no way to get a core dump. @value{GDBN}
- will warn you if it is unable to attach or to read core dumps.
- You can optionally have @code{@value{GDBP}} pass any arguments after the
- executable file to the inferior using @code{--args}. This option stops
- option processing.
- @smallexample
- @value{GDBP} --args gcc -O2 -c foo.c
- @end smallexample
- This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
- @code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
- You can run @code{@value{GDBP}} without printing the front material, which describes
- @value{GDBN}'s non-warranty, by specifying @code{--silent}
- (or @code{-q}/@code{--quiet}):
- @smallexample
- @value{GDBP} --silent
- @end smallexample
- @noindent
- You can further control how @value{GDBN} starts up by using command-line
- options. @value{GDBN} itself can remind you of the options available.
- @noindent
- Type
- @smallexample
- @value{GDBP} -help
- @end smallexample
- @noindent
- to display all available options and briefly describe their use
- (@samp{@value{GDBP} -h} is a shorter equivalent).
- All options and command line arguments you give are processed
- in sequential order. The order makes a difference when the
- @samp{-x} option is used.
- @menu
- * File Options:: Choosing files
- * Mode Options:: Choosing modes
- * Startup:: What @value{GDBN} does during startup
- * Initialization Files:: Initialization Files
- @end menu
- @node File Options
- @subsection Choosing Files
- When @value{GDBN} starts, it reads any arguments other than options as
- specifying an executable file and core file (or process ID). This is
- the same as if the arguments were specified by the @samp{-se} and
- @samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the
- first argument that does not have an associated option flag as
- equivalent to the @samp{-se} option followed by that argument; and the
- second argument that does not have an associated option flag, if any, as
- equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
- If the second argument begins with a decimal digit, @value{GDBN} will
- first attempt to attach to it as a process, and if that fails, attempt
- to open it as a corefile. If you have a corefile whose name begins with
- a digit, you can prevent @value{GDBN} from treating it as a pid by
- prefixing it with @file{./}, e.g.@: @file{./12345}.
- If @value{GDBN} has not been configured to included core file support,
- such as for most embedded targets, then it will complain about a second
- argument and ignore it.
- Many options have both long and short forms; both are shown in the
- following list. @value{GDBN} also recognizes the long forms if you truncate
- them, so long as enough of the option is present to be unambiguous.
- (If you prefer, you can flag option arguments with @samp{--} rather
- than @samp{-}, though we illustrate the more usual convention.)
- @c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
- @c way, both those who look for -foo and --foo in the index, will find
- @c it.
- @table @code
- @item -symbols @var{file}
- @itemx -s @var{file}
- @cindex @code{--symbols}
- @cindex @code{-s}
- Read symbol table from file @var{file}.
- @item -exec @var{file}
- @itemx -e @var{file}
- @cindex @code{--exec}
- @cindex @code{-e}
- Use file @var{file} as the executable file to execute when appropriate,
- and for examining pure data in conjunction with a core dump.
- @item -se @var{file}
- @cindex @code{--se}
- Read symbol table from file @var{file} and use it as the executable
- file.
- @item -core @var{file}
- @itemx -c @var{file}
- @cindex @code{--core}
- @cindex @code{-c}
- Use file @var{file} as a core dump to examine.
- @item -pid @var{number}
- @itemx -p @var{number}
- @cindex @code{--pid}
- @cindex @code{-p}
- Connect to process ID @var{number}, as with the @code{attach} command.
- @item -command @var{file}
- @itemx -x @var{file}
- @cindex @code{--command}
- @cindex @code{-x}
- Execute commands from file @var{file}. The contents of this file is
- evaluated exactly as the @code{source} command would.
- @xref{Command Files,, Command files}.
- @item -eval-command @var{command}
- @itemx -ex @var{command}
- @cindex @code{--eval-command}
- @cindex @code{-ex}
- Execute a single @value{GDBN} command.
- This option may be used multiple times to call multiple commands. It may
- also be interleaved with @samp{-command} as required.
- @smallexample
- @value{GDBP} -ex 'target sim' -ex 'load' \
- -x setbreakpoints -ex 'run' a.out
- @end smallexample
- @item -init-command @var{file}
- @itemx -ix @var{file}
- @cindex @code{--init-command}
- @cindex @code{-ix}
- Execute commands from file @var{file} before loading the inferior (but
- after loading gdbinit files).
- @xref{Startup}.
- @item -init-eval-command @var{command}
- @itemx -iex @var{command}
- @cindex @code{--init-eval-command}
- @cindex @code{-iex}
- Execute a single @value{GDBN} command before loading the inferior (but
- after loading gdbinit files).
- @xref{Startup}.
- @item -early-init-command @var{file}
- @itemx -eix @var{file}
- @cindex @code{--early-init-command}
- @cindex @code{-eix}
- Execute commands from @var{file} very early in the initialization
- process, before any output is produced. @xref{Startup}.
- @item -early-init-eval-command @var{command}
- @itemx -eiex @var{command}
- @cindex @code{--early-init-eval-command}
- @cindex @code{-eiex}
- Execute a single @value{GDBN} command very early in the initialization
- process, before any output is produced.
- @item -directory @var{directory}
- @itemx -d @var{directory}
- @cindex @code{--directory}
- @cindex @code{-d}
- Add @var{directory} to the path to search for source and script files.
- @item -r
- @itemx -readnow
- @cindex @code{--readnow}
- @cindex @code{-r}
- Read each symbol file's entire symbol table immediately, rather than
- the default, which is to read it incrementally as it is needed.
- This makes startup slower, but makes future operations faster.
- @item --readnever
- @anchor{--readnever}
- @cindex @code{--readnever}, command-line option
- Do not read each symbol file's symbolic debug information. This makes
- startup faster but at the expense of not being able to perform
- symbolic debugging. DWARF unwind information is also not read,
- meaning backtraces may become incomplete or inaccurate. One use of
- this is when a user simply wants to do the following sequence: attach,
- dump core, detach. Loading the debugging information in this case is
- an unnecessary cause of delay.
- @end table
- @node Mode Options
- @subsection Choosing Modes
- You can run @value{GDBN} in various alternative modes---for example, in
- batch mode or quiet mode.
- @table @code
- @anchor{-nx}
- @item -nx
- @itemx -n
- @cindex @code{--nx}
- @cindex @code{-n}
- Do not execute commands found in any initialization files
- (@pxref{Initialization Files}).
- @anchor{-nh}
- @item -nh
- @cindex @code{--nh}
- Do not execute commands found in any home directory initialization
- file (@pxref{Initialization Files,,Home directory initialization
- file}). The system wide and current directory initialization files
- are still loaded.
- @item -quiet
- @itemx -silent
- @itemx -q
- @cindex @code{--quiet}
- @cindex @code{--silent}
- @cindex @code{-q}
- ``Quiet''. Do not print the introductory and copyright messages. These
- messages are also suppressed in batch mode.
- @kindex set startup-quietly
- @kindex show startup-quietly
- This can also be enabled using @code{set startup-quietly on}. The
- default is @code{off}. Use @code{show startup-quietly} to see the
- current setting. Place @code{set startup-quietly on} into your early
- initialization file (@pxref{Initialization Files,,Initialization
- Files}) to have future @value{GDBN} sessions startup quietly.
- @item -batch
- @cindex @code{--batch}
- Run in batch mode. Exit with status @code{0} after processing all the
- command files specified with @samp{-x} (and all commands from
- initialization files, if not inhibited with @samp{-n}). Exit with
- nonzero status if an error occurs in executing the @value{GDBN} commands
- in the command files. Batch mode also disables pagination, sets unlimited
- terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm
- off} were in effect (@pxref{Messages/Warnings}).
- Batch mode may be useful for running @value{GDBN} as a filter, for
- example to download and run a program on another computer; in order to
- make this more useful, the message
- @smallexample
- Program exited normally.
- @end smallexample
- @noindent
- (which is ordinarily issued whenever a program running under
- @value{GDBN} control terminates) is not issued when running in batch
- mode.
- @item -batch-silent
- @cindex @code{--batch-silent}
- Run in batch mode exactly like @samp{-batch}, but totally silently. All
- @value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
- unaffected). This is much quieter than @samp{-silent} and would be useless
- for an interactive session.
- This is particularly useful when using targets that give @samp{Loading section}
- messages, for example.
- Note that targets that give their output via @value{GDBN}, as opposed to
- writing directly to @code{stdout}, will also be made silent.
- @item -return-child-result
- @cindex @code{--return-child-result}
- The return code from @value{GDBN} will be the return code from the child
- process (the process being debugged), with the following exceptions:
- @itemize @bullet
- @item
- @value{GDBN} exits abnormally. E.g., due to an incorrect argument or an
- internal error. In this case the exit code is the same as it would have been
- without @samp{-return-child-result}.
- @item
- The user quits with an explicit value. E.g., @samp{quit 1}.
- @item
- The child process never runs, or is not allowed to terminate, in which case
- the exit code will be -1.
- @end itemize
- This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
- when @value{GDBN} is being used as a remote program loader or simulator
- interface.
- @item -nowindows
- @itemx -nw
- @cindex @code{--nowindows}
- @cindex @code{-nw}
- ``No windows''. If @value{GDBN} comes with a graphical user interface
- (GUI) built in, then this option tells @value{GDBN} to only use the command-line
- interface. If no GUI is available, this option has no effect.
- @item -windows
- @itemx -w
- @cindex @code{--windows}
- @cindex @code{-w}
- If @value{GDBN} includes a GUI, then this option requires it to be
- used if possible.
- @item -cd @var{directory}
- @cindex @code{--cd}
- Run @value{GDBN} using @var{directory} as its working directory,
- instead of the current directory.
- @item -data-directory @var{directory}
- @itemx -D @var{directory}
- @cindex @code{--data-directory}
- @cindex @code{-D}
- Run @value{GDBN} using @var{directory} as its data directory.
- The data directory is where @value{GDBN} searches for its
- auxiliary files. @xref{Data Files}.
- @item -fullname
- @itemx -f
- @cindex @code{--fullname}
- @cindex @code{-f}
- @sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
- subprocess. It tells @value{GDBN} to output the full file name and line
- number in a standard, recognizable fashion each time a stack frame is
- displayed (which includes each time your program stops). This
- recognizable format looks like two @samp{\032} characters, followed by
- the file name, line number and character position separated by colons,
- and a newline. The Emacs-to-@value{GDBN} interface program uses the two
- @samp{\032} characters as a signal to display the source code for the
- frame.
- @item -annotate @var{level}
- @cindex @code{--annotate}
- This option sets the @dfn{annotation level} inside @value{GDBN}. Its
- effect is identical to using @samp{set annotate @var{level}}
- (@pxref{Annotations}). The annotation @var{level} controls how much
- information @value{GDBN} prints together with its prompt, values of
- expressions, source lines, and other types of output. Level 0 is the
- normal, level 1 is for use when @value{GDBN} is run as a subprocess of
- @sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
- that control @value{GDBN}, and level 2 has been deprecated.
- The annotation mechanism has largely been superseded by @sc{gdb/mi}
- (@pxref{GDB/MI}).
- @item --args
- @cindex @code{--args}
- Change interpretation of command line so that arguments following the
- executable file are passed as command line arguments to the inferior.
- This option stops option processing.
- @item -baud @var{bps}
- @itemx -b @var{bps}
- @cindex @code{--baud}
- @cindex @code{-b}
- Set the line speed (baud rate or bits per second) of any serial
- interface used by @value{GDBN} for remote debugging.
- @item -l @var{timeout}
- @cindex @code{-l}
- Set the timeout (in seconds) of any communication used by @value{GDBN}
- for remote debugging.
- @item -tty @var{device}
- @itemx -t @var{device}
- @cindex @code{--tty}
- @cindex @code{-t}
- Run using @var{device} for your program's standard input and output.
- @c FIXME: kingdon thinks there is more to -tty. Investigate.
- @c resolve the situation of these eventually
- @item -tui
- @cindex @code{--tui}
- Activate the @dfn{Text User Interface} when starting. The Text User
- Interface manages several text windows on the terminal, showing
- source, assembly, registers and @value{GDBN} command outputs
- (@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this
- option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
- Using @value{GDBN} under @sc{gnu} Emacs}).
- @item -interpreter @var{interp}
- @cindex @code{--interpreter}
- Use the interpreter @var{interp} for interface with the controlling
- program or device. This option is meant to be set by programs which
- communicate with @value{GDBN} using it as a back end.
- @xref{Interpreters, , Command Interpreters}.
- @samp{--interpreter=mi} (or @samp{--interpreter=mi3}) causes
- @value{GDBN} to use the @dfn{@sc{gdb/mi} interface} version 3 (@pxref{GDB/MI, ,
- The @sc{gdb/mi} Interface}) included since @value{GDBN} version 9.1. @sc{gdb/mi}
- version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}),
- included in @value{GDBN} 5.3, are also available. Earlier @sc{gdb/mi}
- interfaces are no longer supported.
- @item -write
- @cindex @code{--write}
- Open the executable and core files for both reading and writing. This
- is equivalent to the @samp{set write on} command inside @value{GDBN}
- (@pxref{Patching}).
- @item -statistics
- @cindex @code{--statistics}
- This option causes @value{GDBN} to print statistics about time and
- memory usage after it completes each command and returns to the prompt.
- @item -version
- @cindex @code{--version}
- This option causes @value{GDBN} to print its version number and
- no-warranty blurb, and exit.
- @item -configuration
- @cindex @code{--configuration}
- This option causes @value{GDBN} to print details about its build-time
- configuration parameters, and then exit. These details can be
- important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}).
- @end table
- @node Startup
- @subsection What @value{GDBN} Does During Startup
- @cindex @value{GDBN} startup
- Here's the description of what @value{GDBN} does during session startup:
- @enumerate
- @item
- Performs minimal setup required to initialize basic internal state.
- @item
- @cindex early initialization file
- Reads commands from the early initialization file (if any) in your
- home directory. Only a restricted set of commands can be placed into
- an early initialization file, see @ref{Initialization Files}, for
- details.
- @item
- Executes commands and command files specified by the @samp{-eiex} and
- @samp{-eix} command line options in their specified order. Only a
- restricted set of commands can be used with @samp{-eiex} and
- @samp{eix}, see @ref{Initialization Files}, for details.
- @item
- Sets up the command interpreter as specified by the command line
- (@pxref{Mode Options, interpreter}).
- @item
- @cindex init file
- Reads the system wide initialization file and the files from the
- system wide initialization directory, @pxref{System Wide Init Files}.
- @item
- Reads the initialization file (if any) in your home directory and
- executes all the commands in that file, @pxref{Home Directory Init
- File}.
- @anchor{Option -init-eval-command}
- @item
- Executes commands and command files specified by the @samp{-iex} and
- @samp{-ix} options in their specified order. Usually you should use the
- @samp{-ex} and @samp{-x} options instead, but this way you can apply
- settings before @value{GDBN} init files get executed and before inferior
- gets loaded.
- @item
- Processes command line options and operands.
- @item
- Reads and executes the commands from the initialization file (if any)
- in the current working directory as long as @samp{set auto-load
- local-gdbinit} is set to @samp{on} (@pxref{Init File in the Current
- Directory}). This is only done if the current directory is different
- from your home directory. Thus, you can have more than one init file,
- one generic in your home directory, and another, specific to the
- program you are debugging, in the directory where you invoke
- @value{GDBN}. @xref{Init File in the Current Directory during
- Startup}.
- @item
- If the command line specified a program to debug, or a process to
- attach to, or a core file, @value{GDBN} loads any auto-loaded
- scripts provided for the program or for its loaded shared libraries.
- @xref{Auto-loading}.
- If you wish to disable the auto-loading during startup,
- you must do something like the following:
- @smallexample
- $ gdb -iex "set auto-load python-scripts off" myprogram
- @end smallexample
- Option @samp{-ex} does not work because the auto-loading is then turned
- off too late.
- @item
- Executes commands and command files specified by the @samp{-ex} and
- @samp{-x} options in their specified order. @xref{Command Files}, for
- more details about @value{GDBN} command files.
- @item
- Reads the command history recorded in the @dfn{history file}.
- @xref{Command History}, for more details about the command history and the
- files where @value{GDBN} records it.
- @end enumerate
- @node Initialization Files
- @subsection Initialization Files
- @cindex init file name
- During startup (@pxref{Startup}) @value{GDBN} will execute commands
- from several initialization files. These initialization files use the
- same syntax as @dfn{command files} (@pxref{Command Files}) and are
- processed by @value{GDBN} in the same way.
- To display the list of initialization files loaded by @value{GDBN} at
- startup, in the order they will be loaded, you can use @kbd{gdb
- --help}.
- @cindex early initialization
- The @dfn{early initialization} file is loaded very early in
- @value{GDBN}'s initialization process, before the interpreter
- (@pxref{Interpreters}) has been initialized, and before the default
- target (@pxref{Targets}) is initialized. Only @code{set} or
- @code{source} commands should be placed into an early initialization
- file, and the only @code{set} commands that can be used are those that
- control how @value{GDBN} starts up.
- Commands that can be placed into an early initialization file will be
- documented as such throughout this manual. Any command that is not
- documented as being suitable for an early initialization file should
- instead be placed into a general initialization file. Command files
- passed to @code{--early-init-command} or @code{-eix} are also early
- initialization files, with the same command restrictions. Only
- commands that can appear in an early initialization file should be
- passed to @code{--early-init-eval-command} or @code{-eiex}.
- @cindex general initialization
- In contrast, the @dfn{general initialization} files are processed
- later, after @value{GDBN} has finished its own internal initialization
- process, any valid command can be used in these files.
- @cindex initialization file
- Throughout the rest of this document the term @dfn{initialization
- file} refers to one of the general initialization files, not the early
- initialization file. Any discussion of the early initialization file
- will specifically mention that it is the early initialization file
- being discussed.
- As the system wide and home directory initialization files are
- processed before most command line options, changes to settings
- (e.g.@: @samp{set complaints}) can affect subsequent processing of
- command line options and operands.
- The following sections describe where @value{GDBN} looks for the early
- initialization and initialization files, and the order that the files
- are searched for.
- @subsubsection Home directory early initialization files
- @value{GDBN} initially looks for an early initialization file in the
- users home directory@footnote{On DOS/Windows systems, the home
- directory is the one pointed to by the @env{HOME} environment
- variable.}. There are a number of locations that @value{GDBN} will
- search in the home directory, these locations are searched in order
- and @value{GDBN} will load the first file that it finds, and
- subsequent locations will not be checked.
- On non-macOS hosts the locations searched are:
- @itemize
- @item
- The file @file{gdb/gdbearlyinit} within the directory pointed to by the
- environment variable @env{XDG_CONFIG_HOME}, if it is defined.
- @item
- The file @file{.config/gdb/gdbearlyinit} within the directory pointed to
- by the environment variable @env{HOME}, if it is defined.
- @item
- The file @file{.gdbearlyinit} within the directory pointed to by the
- environment variable @env{HOME}, if it is defined.
- @end itemize
- By contrast, on macOS hosts the locations searched are:
- @itemize
- @item
- The file @file{Library/Preferences/gdb/gdbearlyinit} within the
- directory pointed to by the environment variable @env{HOME}, if it is
- defined.
- @item
- The file @file{.gdbearlyinit} within the directory pointed to by the
- environment variable @env{HOME}, if it is defined.
- @end itemize
- It is possible to prevent the home directory early initialization file
- from being loaded using the @samp{-nx} or @samp{-nh} command line
- options, @pxref{Mode Options,,Choosing Modes}.
- @anchor{System Wide Init Files}
- @subsubsection System wide initialization files
- There are two locations that are searched for system wide
- initialization files. Both of these locations are always checked:
- @table @code
- @item @file{system.gdbinit}
- This is a single system-wide initialization file. Its location is
- specified with the @code{--with-system-gdbinit} configure option
- (@pxref{System-wide configuration}). It is loaded first when
- @value{GDBN} starts, before command line options have been processed.
- @item @file{system.gdbinit.d}
- This is the system-wide initialization directory. Its location is
- specified with the @code{--with-system-gdbinit-dir} configure option
- (@pxref{System-wide configuration}). Files in this directory are
- loaded in alphabetical order immediately after @file{system.gdbinit}
- (if enabled) when @value{GDBN} starts, before command line options
- have been processed. Files need to have a recognized scripting
- language extension (@file{.py}/@file{.scm}) or be named with a
- @file{.gdb} extension to be interpreted as regular @value{GDBN}
- commands. @value{GDBN} will not recurse into any subdirectories of
- this directory.
- @end table
- It is possible to prevent the system wide initialization files from
- being loaded using the @samp{-nx} command line option, @pxref{Mode
- Options,,Choosing Modes}.
- @anchor{Home Directory Init File}
- @subsubsection Home directory initialization file
- @cindex @file{gdbinit}
- @cindex @file{.gdbinit}
- @cindex @file{gdb.ini}
- After loading the system wide initialization files @value{GDBN} will
- look for an initialization file in the users home
- directory@footnote{On DOS/Windows systems, the home directory is the
- one pointed to by the @env{HOME} environment variable.}. There are a
- number of locations that @value{GDBN} will search in the home
- directory, these locations are searched in order and @value{GDBN} will
- load the first file that it finds, and subsequent locations will not
- be checked.
- On non-Apple hosts the locations searched are:
- @table @file
- @item $XDG_CONFIG_HOME/gdb/gdbinit
- @item $HOME/.config/gdb/gdbinit
- @item $HOME/.gdbinit
- @end table
- While on Apple hosts the locations searched are:
- @table @file
- @item $HOME/Library/Preferences/gdb/gdbinit
- @item $HOME/.gdbinit
- @end table
- It is possible to prevent the home directory initialization file from
- being loaded using the @samp{-nx} or @samp{-nh} command line options,
- @pxref{Mode Options,,Choosing Modes}.
- The DJGPP port of @value{GDBN} uses the name @file{gdb.ini} instead of
- @file{.gdbinit} or @file{gdbinit}, due to the limitations of file
- names imposed by DOS filesystems. The Windows port of @value{GDBN}
- uses the standard name, but if it finds a @file{gdb.ini} file in your
- home directory, it warns you about that and suggests to rename the
- file to the standard name.
- @anchor{Init File in the Current Directory during Startup}
- @subsubsection Local directory initialization file
- @value{GDBN} will check the current directory for a file called
- @file{.gdbinit}. It is loaded last, after command line options
- other than @samp{-x} and @samp{-ex} have been processed. The command
- line options @samp{-x} and @samp{-ex} are processed last, after
- @file{.gdbinit} has been loaded, @pxref{File Options,,Choosing
- Files}.
- If the file in the current directory was already loaded as the home
- directory initialization file then it will not be loaded a second
- time.
- It is possible to prevent the local directory initialization file from
- being loaded using the @samp{-nx} command line option, @pxref{Mode
- Options,,Choosing Modes}.
- @node Quitting GDB
- @section Quitting @value{GDBN}
- @cindex exiting @value{GDBN}
- @cindex leaving @value{GDBN}
- @table @code
- @kindex quit @r{[}@var{expression}@r{]}
- @kindex exit @r{[}@var{expression}@r{]}
- @kindex q @r{(@code{quit})}
- @item quit @r{[}@var{expression}@r{]}
- @itemx exit @r{[}@var{expression}@r{]}
- @itemx q
- To exit @value{GDBN}, use the @code{quit} command (abbreviated
- @code{q}), the @code{exit} command, or type an end-of-file
- character (usually @kbd{Ctrl-d}). If you do not supply @var{expression},
- @value{GDBN} will terminate normally; otherwise it will terminate using
- the result of @var{expression} as the error code.
- @end table
- @cindex interrupt
- An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather
- terminates the action of any @value{GDBN} command that is in progress and
- returns to @value{GDBN} command level. It is safe to type the interrupt
- character at any time because @value{GDBN} does not allow it to take effect
- until a time when it is safe.
- If you have been using @value{GDBN} to control an attached process or
- device, you can release it with the @code{detach} command
- (@pxref{Attach, ,Debugging an Already-running Process}).
- @node Shell Commands
- @section Shell Commands
- If you need to execute occasional shell commands during your
- debugging session, there is no need to leave or suspend @value{GDBN}; you can
- just use the @code{shell} command.
- @table @code
- @kindex shell
- @kindex !
- @cindex shell escape
- @item shell @var{command-string}
- @itemx !@var{command-string}
- Invoke a standard shell to execute @var{command-string}.
- Note that no space is needed between @code{!} and @var{command-string}.
- On GNU and Unix systems, the environment variable @env{SHELL}, if it
- exists, determines which shell to run. Otherwise @value{GDBN} uses
- the default shell (@file{/bin/sh} on GNU and Unix systems,
- @file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.).
- @end table
- The utility @code{make} is often needed in development environments.
- You do not have to use the @code{shell} command for this purpose in
- @value{GDBN}:
- @table @code
- @kindex make
- @cindex calling make
- @item make @var{make-args}
- Execute the @code{make} program with the specified
- arguments. This is equivalent to @samp{shell make @var{make-args}}.
- @end table
- @table @code
- @kindex pipe
- @kindex |
- @cindex send the output of a gdb command to a shell command
- @anchor{pipe}
- @item pipe [@var{command}] | @var{shell_command}
- @itemx | [@var{command}] | @var{shell_command}
- @itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command}
- @itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command}
- Executes @var{command} and sends its output to @var{shell_command}.
- Note that no space is needed around @code{|}.
- If no @var{command} is provided, the last command executed is repeated.
- In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}}
- can be used to specify an alternate delimiter string @var{delim} that separates
- the @var{command} from the @var{shell_command}.
- Example:
- @smallexample
- @group
- (gdb) p var
- $1 = @{
- black = 144,
- red = 233,
- green = 377,
- blue = 610,
- white = 987
- @}
- @end group
- @group
- (gdb) pipe p var|wc
- 7 19 80
- (gdb) |p var|wc -l
- 7
- @end group
- @group
- (gdb) p /x var
- $4 = @{
- black = 0x90,
- red = 0xe9,
- green = 0x179,
- blue = 0x262,
- white = 0x3db
- @}
- (gdb) ||grep red
- red => 0xe9,
- @end group
- @group
- (gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
- this contains a PIPE char
- (gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
- this contains a PIPE char!
- (gdb)
- @end group
- @end smallexample
- @end table
- The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal}
- can be used to examine the exit status of the last shell command launched
- by @code{shell}, @code{make}, @code{pipe} and @code{|}.
- @xref{Convenience Vars,, Convenience Variables}.
- @node Logging Output
- @section Logging Output
- @cindex logging @value{GDBN} output
- @cindex save @value{GDBN} output to a file
- You may want to save the output of @value{GDBN} commands to a file.
- There are several commands to control @value{GDBN}'s logging.
- @table @code
- @kindex set logging enabled
- @item set logging enabled [on|off]
- Enable or disable logging.
- @cindex logging file name
- @item set logging file @var{file}
- Change the name of the current logfile. The default logfile is @file{gdb.txt}.
- @item set logging overwrite [on|off]
- By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if
- you want @code{set logging enabled on} to overwrite the logfile instead.
- @item set logging redirect [on|off]
- By default, @value{GDBN} output will go to both the terminal and the logfile.
- Set @code{redirect} if you want output to go only to the log file.
- @item set logging debugredirect [on|off]
- By default, @value{GDBN} debug output will go to both the terminal and the logfile.
- Set @code{debugredirect} if you want debug output to go only to the log file.
- @kindex show logging
- @item show logging
- Show the current values of the logging settings.
- @end table
- You can also redirect the output of a @value{GDBN} command to a
- shell command. @xref{pipe}.
- @node Commands
- @chapter @value{GDBN} Commands
- You can abbreviate a @value{GDBN} command to the first few letters of the command
- name, if that abbreviation is unambiguous; and you can repeat certain
- @value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB}
- key to get @value{GDBN} to fill out the rest of a word in a command (or to
- show you the alternatives available, if there is more than one possibility).
- @menu
- * Command Syntax:: How to give commands to @value{GDBN}
- * Command Settings:: How to change default behavior of commands
- * Completion:: Command completion
- * Command Options:: Command options
- * Help:: How to ask @value{GDBN} for help
- @end menu
- @node Command Syntax
- @section Command Syntax
- A @value{GDBN} command is a single line of input. There is no limit on
- how long it can be. It starts with a command name, which is followed by
- arguments whose meaning depends on the command name. For example, the
- command @code{step} accepts an argument which is the number of times to
- step, as in @samp{step 5}. You can also use the @code{step} command
- with no arguments. Some commands do not allow any arguments.
- @cindex abbreviation
- @value{GDBN} command names may always be truncated if that abbreviation is
- unambiguous. Other possible command abbreviations are listed in the
- documentation for individual commands. In some cases, even ambiguous
- abbreviations are allowed; for example, @code{s} is specially defined as
- equivalent to @code{step} even though there are other commands whose
- names start with @code{s}. You can test abbreviations by using them as
- arguments to the @code{help} command.
- @cindex repeating commands
- @kindex RET @r{(repeat last command)}
- A blank line as input to @value{GDBN} (typing just @key{RET}) means to
- repeat the previous command. Certain commands (for example, @code{run})
- will not repeat this way; these are commands whose unintentional
- repetition might cause trouble and which you are unlikely to want to
- repeat. User-defined commands can disable this feature; see
- @ref{Define, dont-repeat}.
- The @code{list} and @code{x} commands, when you repeat them with
- @key{RET}, construct new arguments rather than repeating
- exactly as typed. This permits easy scanning of source or memory.
- @value{GDBN} can also use @key{RET} in another way: to partition lengthy
- output, in a way similar to the common utility @code{more}
- (@pxref{Screen Size,,Screen Size}). Since it is easy to press one
- @key{RET} too many in this situation, @value{GDBN} disables command
- repetition after any command that generates this sort of display.
- @kindex # @r{(a comment)}
- @cindex comment
- Any text from a @kbd{#} to the end of the line is a comment; it does
- nothing. This is useful mainly in command files (@pxref{Command
- Files,,Command Files}).
- @cindex repeating command sequences
- @kindex Ctrl-o @r{(operate-and-get-next)}
- The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of
- commands. This command accepts the current line, like @key{RET}, and
- then fetches the next line relative to the current line from the history
- for editing.
- @node Command Settings
- @section Command Settings
- @cindex default behavior of commands, changing
- @cindex default settings, changing
- Many commands change their behavior according to command-specific
- variables or settings. These settings can be changed with the
- @code{set} subcommands. For example, the @code{print} command
- (@pxref{Data, ,Examining Data}) prints arrays differently depending on
- settings changeable with the commands @code{set print elements
- NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others.
- You can change these settings to your preference in the gdbinit files
- loaded at @value{GDBN} startup. @xref{Startup}.
- The settings can also be changed interactively during the debugging
- session. For example, to change the limit of array elements to print,
- you can do the following:
- @smallexample
- (@value{GDBN}) set print elements 10
- (@value{GDBN}) print some_array
- $1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
- @end smallexample
- The above @code{set print elements 10} command changes the number of
- elements to print from the default of 200 to 10. If you only intend
- this limit of 10 to be used for printing @code{some_array}, then you
- must restore the limit back to 200, with @code{set print elements
- 200}.
- Some commands allow overriding settings with command options. For
- example, the @code{print} command supports a number of options that
- allow overriding relevant global print settings as set by @code{set
- print} subcommands. @xref{print options}. The example above could be
- rewritten as:
- @smallexample
- (@value{GDBN}) print -elements 10 -- some_array
- $1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
- @end smallexample
- Alternatively, you can use the @code{with} command to change a setting
- temporarily, for the duration of a command invocation.
- @table @code
- @kindex with command
- @kindex w @r{(@code{with})}
- @cindex settings
- @cindex temporarily change settings
- @item with @var{setting} [@var{value}] [-- @var{command}]
- @itemx w @var{setting} [@var{value}] [-- @var{command}]
- Temporarily set @var{setting} to @var{value} for the duration of
- @var{command}.
- @var{setting} is any setting you can change with the @code{set}
- subcommands. @var{value} is the value to assign to @code{setting}
- while running @code{command}.
- If no @var{command} is provided, the last command executed is
- repeated.
- If a @var{command} is provided, it must be preceded by a double dash
- (@code{--}) separator. This is required because some settings accept
- free-form arguments, such as expressions or filenames.
- For example, the command
- @smallexample
- (@value{GDBN}) with print array on -- print some_array
- @end smallexample
- @noindent
- is equivalent to the following 3 commands:
- @smallexample
- (@value{GDBN}) set print array on
- (@value{GDBN}) print some_array
- (@value{GDBN}) set print array off
- @end smallexample
- The @code{with} command is particularly useful when you want to
- override a setting while running user-defined commands, or commands
- defined in Python or Guile. @xref{Extending GDB,, Extending GDB}.
- @smallexample
- (@value{GDBN}) with print pretty on -- my_complex_command
- @end smallexample
- To change several settings for the same command, you can nest
- @code{with} commands. For example, @code{with language ada -- with
- print elements 10} temporarily changes the language to Ada and sets a
- limit of 10 elements to print for arrays and strings.
- @end table
- @node Completion
- @section Command Completion
- @cindex completion
- @cindex word completion
- @value{GDBN} can fill in the rest of a word in a command for you, if there is
- only one possibility; it can also show you what the valid possibilities
- are for the next word in a command, at any time. This works for @value{GDBN}
- commands, @value{GDBN} subcommands, command options, and the names of symbols
- in your program.
- Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
- of a word. If there is only one possibility, @value{GDBN} fills in the
- word, and waits for you to finish the command (or press @key{RET} to
- enter it). For example, if you type
- @c FIXME "@key" does not distinguish its argument sufficiently to permit
- @c complete accuracy in these examples; space introduced for clarity.
- @c If texinfo enhancements make it unnecessary, it would be nice to
- @c replace " @key" by "@key" in the following...
- @smallexample
- (@value{GDBP}) info bre @key{TAB}
- @end smallexample
- @noindent
- @value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
- the only @code{info} subcommand beginning with @samp{bre}:
- @smallexample
- (@value{GDBP}) info breakpoints
- @end smallexample
- @noindent
- You can either press @key{RET} at this point, to run the @code{info
- breakpoints} command, or backspace and enter something else, if
- @samp{breakpoints} does not look like the command you expected. (If you
- were sure you wanted @code{info breakpoints} in the first place, you
- might as well just type @key{RET} immediately after @samp{info bre},
- to exploit command abbreviations rather than command completion).
- If there is more than one possibility for the next word when you press
- @key{TAB}, @value{GDBN} sounds a bell. You can either supply more
- characters and try again, or just press @key{TAB} a second time;
- @value{GDBN} displays all the possible completions for that word. For
- example, you might want to set a breakpoint on a subroutine whose name
- begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
- just sounds the bell. Typing @key{TAB} again displays all the
- function names in your program that begin with those characters, for
- example:
- @smallexample
- (@value{GDBP}) b make_ @key{TAB}
- @exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
- make_a_section_from_file make_environ
- make_abs_section make_function_type
- make_blockvector make_pointer_type
- make_cleanup make_reference_type
- make_command make_symbol_completion_list
- (@value{GDBP}) b make_
- @end smallexample
- @noindent
- After displaying the available possibilities, @value{GDBN} copies your
- partial input (@samp{b make_} in the example) so you can finish the
- command.
- If you just want to see the list of alternatives in the first place, you
- can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
- means @kbd{@key{META} ?}. You can type this either by holding down a
- key designated as the @key{META} shift on your keyboard (if there is
- one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
- If the number of possible completions is large, @value{GDBN} will
- print as much of the list as it has collected, as well as a message
- indicating that the list may be truncated.
- @smallexample
- (@value{GDBP}) b m@key{TAB}@key{TAB}
- main
- <... the rest of the possible completions ...>
- *** List may be truncated, max-completions reached. ***
- (@value{GDBP}) b m
- @end smallexample
- @noindent
- This behavior can be controlled with the following commands:
- @table @code
- @kindex set max-completions
- @item set max-completions @var{limit}
- @itemx set max-completions unlimited
- Set the maximum number of completion candidates. @value{GDBN} will
- stop looking for more completions once it collects this many candidates.
- This is useful when completing on things like function names as collecting
- all the possible candidates can be time consuming.
- The default value is 200. A value of zero disables tab-completion.
- Note that setting either no limit or a very large limit can make
- completion slow.
- @kindex show max-completions
- @item show max-completions
- Show the maximum number of candidates that @value{GDBN} will collect and show
- during completion.
- @end table
- @cindex quotes in commands
- @cindex completion of quoted strings
- Sometimes the string you need, while logically a ``word'', may contain
- parentheses or other characters that @value{GDBN} normally excludes from
- its notion of a word. To permit word completion to work in this
- situation, you may enclose words in @code{'} (single quote marks) in
- @value{GDBN} commands.
- A likely situation where you might need this is in typing an
- expression that involves a C@t{++} symbol name with template
- parameters. This is because when completing expressions, GDB treats
- the @samp{<} character as word delimiter, assuming that it's the
- less-than comparison operator (@pxref{C Operators, , C and C@t{++}
- Operators}).
- For example, when you want to call a C@t{++} template function
- interactively using the @code{print} or @code{call} commands, you may
- need to distinguish whether you mean the version of @code{name} that
- was specialized for @code{int}, @code{name<int>()}, or the version
- that was specialized for @code{float}, @code{name<float>()}. To use
- the word-completion facilities in this situation, type a single quote
- @code{'} at the beginning of the function name. This alerts
- @value{GDBN} that it may need to consider more information than usual
- when you press @key{TAB} or @kbd{M-?} to request word completion:
- @smallexample
- (@value{GDBP}) p 'func< @kbd{M-?}
- func<int>() func<float>()
- (@value{GDBP}) p 'func<
- @end smallexample
- When setting breakpoints however (@pxref{Specify Location}), you don't
- usually need to type a quote before the function name, because
- @value{GDBN} understands that you want to set a breakpoint on a
- function:
- @smallexample
- (@value{GDBP}) b func< @kbd{M-?}
- func<int>() func<float>()
- (@value{GDBP}) b func<
- @end smallexample
- This is true even in the case of typing the name of C@t{++} overloaded
- functions (multiple definitions of the same function, distinguished by
- argument type). For example, when you want to set a breakpoint you
- don't need to distinguish whether you mean the version of @code{name}
- that takes an @code{int} parameter, @code{name(int)}, or the version
- that takes a @code{float} parameter, @code{name(float)}.
- @smallexample
- (@value{GDBP}) b bubble( @kbd{M-?}
- bubble(int) bubble(double)
- (@value{GDBP}) b bubble(dou @kbd{M-?}
- bubble(double)
- @end smallexample
- See @ref{quoting names} for a description of other scenarios that
- require quoting.
- For more information about overloaded functions, see @ref{C Plus Plus
- Expressions, ,C@t{++} Expressions}. You can use the command @code{set
- overload-resolution off} to disable overload resolution;
- see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}.
- @cindex completion of structure field names
- @cindex structure field name completion
- @cindex completion of union field names
- @cindex union field name completion
- When completing in an expression which looks up a field in a
- structure, @value{GDBN} also tries@footnote{The completer can be
- confused by certain kinds of invalid expressions. Also, it only
- examines the static type of the expression, not the dynamic type.} to
- limit completions to the field names available in the type of the
- left-hand-side:
- @smallexample
- (@value{GDBP}) p gdb_stdout.@kbd{M-?}
- magic to_fputs to_rewind
- to_data to_isatty to_write
- to_delete to_put to_write_async_safe
- to_flush to_read
- @end smallexample
- @noindent
- This is because the @code{gdb_stdout} is a variable of the type
- @code{struct ui_file} that is defined in @value{GDBN} sources as
- follows:
- @smallexample
- struct ui_file
- @{
- int *magic;
- ui_file_flush_ftype *to_flush;
- ui_file_write_ftype *to_write;
- ui_file_write_async_safe_ftype *to_write_async_safe;
- ui_file_fputs_ftype *to_fputs;
- ui_file_read_ftype *to_read;
- ui_file_delete_ftype *to_delete;
- ui_file_isatty_ftype *to_isatty;
- ui_file_rewind_ftype *to_rewind;
- ui_file_put_ftype *to_put;
- void *to_data;
- @}
- @end smallexample
- @node Command Options
- @section Command options
- @cindex command options
- Some commands accept options starting with a leading dash. For
- example, @code{print -pretty}. Similarly to command names, you can
- abbreviate a @value{GDBN} option to the first few letters of the
- option name, if that abbreviation is unambiguous, and you can also use
- the @key{TAB} key to get @value{GDBN} to fill out the rest of a word
- in an option (or to show you the alternatives available, if there is
- more than one possibility).
- @cindex command options, raw input
- Some commands take raw input as argument. For example, the print
- command processes arbitrary expressions in any of the languages
- supported by @value{GDBN}. With such commands, because raw input may
- start with a leading dash that would be confused with an option or any
- of its abbreviations, e.g.@: @code{print -p} (short for @code{print
- -pretty} or printing negative @code{p}?), if you specify any command
- option, then you must use a double-dash (@code{--}) delimiter to
- indicate the end of options.
- @cindex command options, boolean
- Some options are described as accepting an argument which can be
- either @code{on} or @code{off}. These are known as @dfn{boolean
- options}. Similarly to boolean settings commands---@code{on} and
- @code{off} are the typical values, but any of @code{1}, @code{yes} and
- @code{enable} can also be used as ``true'' value, and any of @code{0},
- @code{no} and @code{disable} can also be used as ``false'' value. You
- can also omit a ``true'' value, as it is implied by default.
- For example, these are equivalent:
- @smallexample
- (@value{GDBP}) print -object on -pretty off -element unlimited -- *myptr
- (@value{GDBP}) p -o -p 0 -e u -- *myptr
- @end smallexample
- You can discover the set of options some command accepts by completing
- on @code{-} after the command name. For example:
- @smallexample
- (@value{GDBP}) print -@key{TAB}@key{TAB}
- -address -max-depth -pretty -symbol
- -array -memory-tag-violations -raw-values -union
- -array-indexes -null-stop -repeats -vtbl
- -elements -object -static-members
- @end smallexample
- Completion will in some cases guide you with a suggestion of what kind
- of argument an option expects. For example:
- @smallexample
- (@value{GDBP}) print -elements @key{TAB}@key{TAB}
- NUMBER unlimited
- @end smallexample
- Here, the option expects a number (e.g., @code{100}), not literal
- @code{NUMBER}. Such metasyntactical arguments are always presented in
- uppercase.
- (For more on using the @code{print} command, see @ref{Data, ,Examining
- Data}.)
- @node Help
- @section Getting Help
- @cindex online documentation
- @kindex help
- You can always ask @value{GDBN} itself for information on its commands,
- using the command @code{help}.
- @table @code
- @kindex h @r{(@code{help})}
- @item help
- @itemx h
- You can use @code{help} (abbreviated @code{h}) with no arguments to
- display a short list of named classes of commands:
- @smallexample
- (@value{GDBP}) help
- List of classes of commands:
- aliases -- User-defined aliases of other commands
- breakpoints -- Making program stop at certain points
- data -- Examining data
- files -- Specifying and examining files
- internals -- Maintenance commands
- obscure -- Obscure features
- running -- Running the program
- stack -- Examining the stack
- status -- Status inquiries
- support -- Support facilities
- tracepoints -- Tracing of program execution without
- stopping the program
- user-defined -- User-defined commands
- Type "help" followed by a class name for a list of
- commands in that class.
- Type "help" followed by command name for full
- documentation.
- Command name abbreviations are allowed if unambiguous.
- (@value{GDBP})
- @end smallexample
- @c the above line break eliminates huge line overfull...
- @item help @var{class}
- Using one of the general help classes as an argument, you can get a
- list of the individual commands in that class. If a command has
- aliases, the aliases are given after the command name, separated by
- commas. If an alias has default arguments, the full definition of
- the alias is given after the first line.
- For example, here is the help display for the class @code{status}:
- @smallexample
- (@value{GDBP}) help status
- Status inquiries.
- List of commands:
- @c Line break in "show" line falsifies real output, but needed
- @c to fit in smallbook page size.
- info, inf, i -- Generic command for showing things
- about the program being debugged
- info address, iamain -- Describe where symbol SYM is stored.
- alias iamain = info address main
- info all-registers -- List of all registers and their contents,
- for selected stack frame.
- ...
- show, info set -- Generic command for showing things
- about the debugger
- Type "help" followed by command name for full
- documentation.
- Command name abbreviations are allowed if unambiguous.
- (@value{GDBP})
- @end smallexample
- @item help @var{command}
- With a command name as @code{help} argument, @value{GDBN} displays a
- short paragraph on how to use that command. If that command has
- one or more aliases, @value{GDBN} will display a first line with
- the command name and all its aliases separated by commas.
- This first line will be followed by the full definition of all aliases
- having default arguments.
- @kindex apropos
- @item apropos [-v] @var{regexp}
- The @code{apropos} command searches through all of the @value{GDBN}
- commands, and their documentation, for the regular expression specified in
- @var{args}. It prints out all matches found. The optional flag @samp{-v},
- which stands for @samp{verbose}, indicates to output the full documentation
- of the matching commands and highlight the parts of the documentation
- matching @var{regexp}. For example:
- @smallexample
- apropos alias
- @end smallexample
- @noindent
- results in:
- @smallexample
- @group
- alias -- Define a new command that is an alias of an existing command
- aliases -- User-defined aliases of other commands
- @end group
- @end smallexample
- @noindent
- while
- @smallexample
- apropos -v cut.*thread apply
- @end smallexample
- @noindent
- results in the below output, where @samp{cut for 'thread apply}
- is highlighted if styling is enabled.
- @smallexample
- @group
- taas -- Apply a command to all threads (ignoring errors
- and empty output).
- Usage: taas COMMAND
- shortcut for 'thread apply all -s COMMAND'
- tfaas -- Apply a command to all frames of all threads
- (ignoring errors and empty output).
- Usage: tfaas COMMAND
- shortcut for 'thread apply all -s frame apply all -s COMMAND'
- @end group
- @end smallexample
- @kindex complete
- @item complete @var{args}
- The @code{complete @var{args}} command lists all the possible completions
- for the beginning of a command. Use @var{args} to specify the beginning of the
- command you want completed. For example:
- @smallexample
- complete i
- @end smallexample
- @noindent results in:
- @smallexample
- @group
- if
- ignore
- info
- inspect
- @end group
- @end smallexample
- @noindent This is intended for use by @sc{gnu} Emacs.
- @end table
- In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
- and @code{show} to inquire about the state of your program, or the state
- of @value{GDBN} itself. Each command supports many topics of inquiry; this
- manual introduces each of them in the appropriate context. The listings
- under @code{info} and under @code{show} in the Command, Variable, and
- Function Index point to all the sub-commands. @xref{Command and Variable
- Index}.
- @c @group
- @table @code
- @kindex info
- @kindex i @r{(@code{info})}
- @item info
- This command (abbreviated @code{i}) is for describing the state of your
- program. For example, you can show the arguments passed to a function
- with @code{info args}, list the registers currently in use with @code{info
- registers}, or list the breakpoints you have set with @code{info breakpoints}.
- You can get a complete list of the @code{info} sub-commands with
- @w{@code{help info}}.
- @kindex set
- @item set
- You can assign the result of an expression to an environment variable with
- @code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
- @code{set prompt $}.
- @kindex show
- @item show
- In contrast to @code{info}, @code{show} is for describing the state of
- @value{GDBN} itself.
- You can change most of the things you can @code{show}, by using the
- related command @code{set}; for example, you can control what number
- system is used for displays with @code{set radix}, or simply inquire
- which is currently in use with @code{show radix}.
- @kindex info set
- To display all the settable parameters and their current
- values, you can use @code{show} with no arguments; you may also use
- @code{info set}. Both commands produce the same display.
- @c FIXME: "info set" violates the rule that "info" is for state of
- @c FIXME...program. Ck w/ GNU: "info set" to be called something else,
- @c FIXME...or change desc of rule---eg "state of prog and debugging session"?
- @end table
- @c @end group
- Here are several miscellaneous @code{show} subcommands, all of which are
- exceptional in lacking corresponding @code{set} commands:
- @table @code
- @kindex show version
- @cindex @value{GDBN} version number
- @item show version
- Show what version of @value{GDBN} is running. You should include this
- information in @value{GDBN} bug-reports. If multiple versions of
- @value{GDBN} are in use at your site, you may need to determine which
- version of @value{GDBN} you are running; as @value{GDBN} evolves, new
- commands are introduced, and old ones may wither away. Also, many
- system vendors ship variant versions of @value{GDBN}, and there are
- variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
- The version number is the same as the one announced when you start
- @value{GDBN}.
- @kindex show copying
- @kindex info copying
- @cindex display @value{GDBN} copyright
- @item show copying
- @itemx info copying
- Display information about permission for copying @value{GDBN}.
- @kindex show warranty
- @kindex info warranty
- @item show warranty
- @itemx info warranty
- Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
- if your version of @value{GDBN} comes with one.
- @kindex show configuration
- @item show configuration
- Display detailed information about the way @value{GDBN} was configured
- when it was built. This displays the optional arguments passed to the
- @file{configure} script and also configuration parameters detected
- automatically by @command{configure}. When reporting a @value{GDBN}
- bug (@pxref{GDB Bugs}), it is important to include this information in
- your report.
- @end table
- @node Running
- @chapter Running Programs Under @value{GDBN}
- When you run a program under @value{GDBN}, you must first generate
- debugging information when you compile it.
- You may start @value{GDBN} with its arguments, if any, in an environment
- of your choice. If you are doing native debugging, you may redirect
- your program's input and output, debug an already running process, or
- kill a child process.
- @menu
- * Compilation:: Compiling for debugging
- * Starting:: Starting your program
- * Arguments:: Your program's arguments
- * Environment:: Your program's environment
- * Working Directory:: Your program's working directory
- * Input/Output:: Your program's input and output
- * Attach:: Debugging an already-running process
- * Kill Process:: Killing the child process
- * Inferiors Connections and Programs:: Debugging multiple inferiors
- connections and programs
- * Threads:: Debugging programs with multiple threads
- * Forks:: Debugging forks
- * Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
- @end menu
- @node Compilation
- @section Compiling for Debugging
- In order to debug a program effectively, you need to generate
- debugging information when you compile it. This debugging information
- is stored in the object file; it describes the data type of each
- variable or function and the correspondence between source line numbers
- and addresses in the executable code.
- To request debugging information, specify the @samp{-g} option when you run
- the compiler.
- Programs that are to be shipped to your customers are compiled with
- optimizations, using the @samp{-O} compiler option. However, some
- compilers are unable to handle the @samp{-g} and @samp{-O} options
- together. Using those compilers, you cannot generate optimized
- executables containing debugging information.
- @value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
- without @samp{-O}, making it possible to debug optimized code. We
- recommend that you @emph{always} use @samp{-g} whenever you compile a
- program. You may think your program is correct, but there is no sense
- in pushing your luck. For more information, see @ref{Optimized Code}.
- Older versions of the @sc{gnu} C compiler permitted a variant option
- @w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
- format; if your @sc{gnu} C compiler has this option, do not use it.
- @value{GDBN} knows about preprocessor macros and can show you their
- expansion (@pxref{Macros}). Most compilers do not include information
- about preprocessor macros in the debugging information if you specify
- the @option{-g} flag alone. Version 3.1 and later of @value{NGCC},
- the @sc{gnu} C compiler, provides macro information if you are using
- the DWARF debugging format, and specify the option @option{-g3}.
- @xref{Debugging Options,,Options for Debugging Your Program or GCC,
- gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more
- information on @value{NGCC} options affecting debug information.
- You will have the best debugging experience if you use the latest
- version of the DWARF debugging format that your compiler supports.
- DWARF is currently the most expressive and best supported debugging
- format in @value{GDBN}.
- @need 2000
- @node Starting
- @section Starting your Program
- @cindex starting
- @cindex running
- @table @code
- @kindex run
- @kindex r @r{(@code{run})}
- @item run
- @itemx r
- Use the @code{run} command to start your program under @value{GDBN}.
- You must first specify the program name with an argument to
- @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
- @value{GDBN}}), or by using the @code{file} or @code{exec-file}
- command (@pxref{Files, ,Commands to Specify Files}).
- @end table
- If you are running your program in an execution environment that
- supports processes, @code{run} creates an inferior process and makes
- that process run your program. In some environments without processes,
- @code{run} jumps to the start of your program. Other targets,
- like @samp{remote}, are always running. If you get an error
- message like this one:
- @smallexample
- The "remote" target does not support "run".
- Try "help target" or "continue".
- @end smallexample
- @noindent
- then use @code{continue} to run your program. You may need @code{load}
- first (@pxref{load}).
- The execution of a program is affected by certain information it
- receives from its superior. @value{GDBN} provides ways to specify this
- information, which you must do @emph{before} starting your program. (You
- can change it after starting your program, but such changes only affect
- your program the next time you start it.) This information may be
- divided into four categories:
- @table @asis
- @item The @emph{arguments.}
- Specify the arguments to give your program as the arguments of the
- @code{run} command. If a shell is available on your target, the shell
- is used to pass the arguments, so that you may use normal conventions
- (such as wildcard expansion or variable substitution) in describing
- the arguments.
- In Unix systems, you can control which shell is used with the
- @env{SHELL} environment variable. If you do not define @env{SHELL},
- @value{GDBN} uses the default shell (@file{/bin/sh}). You can disable
- use of any shell with the @code{set startup-with-shell} command (see
- below for details).
- @item The @emph{environment.}
- Your program normally inherits its environment from @value{GDBN}, but you can
- use the @value{GDBN} commands @code{set environment} and @code{unset
- environment} to change parts of the environment that affect
- your program. @xref{Environment, ,Your Program's Environment}.
- @item The @emph{working directory.}
- You can set your program's working directory with the command
- @kbd{set cwd}. If you do not set any working directory with this
- command, your program will inherit @value{GDBN}'s working directory if
- native debugging, or the remote server's working directory if remote
- debugging. @xref{Working Directory, ,Your Program's Working
- Directory}.
- @item The @emph{standard input and output.}
- Your program normally uses the same device for standard input and
- standard output as @value{GDBN} is using. You can redirect input and output
- in the @code{run} command line, or you can use the @code{tty} command to
- set a different device for your program.
- @xref{Input/Output, ,Your Program's Input and Output}.
- @cindex pipes
- @emph{Warning:} While input and output redirection work, you cannot use
- pipes to pass the output of the program you are debugging to another
- program; if you attempt this, @value{GDBN} is likely to wind up debugging the
- wrong program.
- @end table
- When you issue the @code{run} command, your program begins to execute
- immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion
- of how to arrange for your program to stop. Once your program has
- stopped, you may call functions in your program, using the @code{print}
- or @code{call} commands. @xref{Data, ,Examining Data}.
- If the modification time of your symbol file has changed since the last
- time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
- table, and reads it again. When it does this, @value{GDBN} tries to retain
- your current breakpoints.
- @table @code
- @kindex start
- @item start
- @cindex run to main procedure
- The name of the main procedure can vary from language to language.
- With C or C@t{++}, the main procedure name is always @code{main}, but
- other languages such as Ada do not require a specific name for their
- main procedure. The debugger provides a convenient way to start the
- execution of the program and to stop at the beginning of the main
- procedure, depending on the language used.
- The @samp{start} command does the equivalent of setting a temporary
- breakpoint at the beginning of the main procedure and then invoking
- the @samp{run} command.
- @cindex elaboration phase
- Some programs contain an @dfn{elaboration} phase where some startup code is
- executed before the main procedure is called. This depends on the
- languages used to write your program. In C@t{++}, for instance,
- constructors for static and global objects are executed before
- @code{main} is called. It is therefore possible that the debugger stops
- before reaching the main procedure. However, the temporary breakpoint
- will remain to halt execution.
- Specify the arguments to give to your program as arguments to the
- @samp{start} command. These arguments will be given verbatim to the
- underlying @samp{run} command. Note that the same arguments will be
- reused if no argument is provided during subsequent calls to
- @samp{start} or @samp{run}.
- It is sometimes necessary to debug the program during elaboration. In
- these cases, using the @code{start} command would stop the execution
- of your program too late, as the program would have already completed
- the elaboration phase. Under these circumstances, either insert
- breakpoints in your elaboration code before running your program or
- use the @code{starti} command.
- @kindex starti
- @item starti
- @cindex run to first instruction
- The @samp{starti} command does the equivalent of setting a temporary
- breakpoint at the first instruction of a program's execution and then
- invoking the @samp{run} command. For programs containing an
- elaboration phase, the @code{starti} command will stop execution at
- the start of the elaboration phase.
- @anchor{set exec-wrapper}
- @kindex set exec-wrapper
- @item set exec-wrapper @var{wrapper}
- @itemx show exec-wrapper
- @itemx unset exec-wrapper
- When @samp{exec-wrapper} is set, the specified wrapper is used to
- launch programs for debugging. @value{GDBN} starts your program
- with a shell command of the form @kbd{exec @var{wrapper}
- @var{program}}. Quoting is added to @var{program} and its
- arguments, but not to @var{wrapper}, so you should add quotes if
- appropriate for your shell. The wrapper runs until it executes
- your program, and then @value{GDBN} takes control.
- You can use any program that eventually calls @code{execve} with
- its arguments as a wrapper. Several standard Unix utilities do
- this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
- with @code{exec "$@@"} will also work.
- For example, you can use @code{env} to pass an environment variable to
- the debugged program, without setting the variable in your shell's
- environment:
- @smallexample
- (@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so'
- (@value{GDBP}) run
- @end smallexample
- This command is available when debugging locally on most targets, excluding
- @sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
- @kindex set startup-with-shell
- @anchor{set startup-with-shell}
- @item set startup-with-shell
- @itemx set startup-with-shell on
- @itemx set startup-with-shell off
- @itemx show startup-with-shell
- On Unix systems, by default, if a shell is available on your target,
- @value{GDBN}) uses it to start your program. Arguments of the
- @code{run} command are passed to the shell, which does variable
- substitution, expands wildcard characters and performs redirection of
- I/O. In some circumstances, it may be useful to disable such use of a
- shell, for example, when debugging the shell itself or diagnosing
- startup failures such as:
- @smallexample
- (@value{GDBP}) run
- Starting program: ./a.out
- During startup program terminated with signal SIGSEGV, Segmentation fault.
- @end smallexample
- @noindent
- which indicates the shell or the wrapper specified with
- @samp{exec-wrapper} crashed, not your program. Most often, this is
- caused by something odd in your shell's non-interactive mode
- initialization file---such as @file{.cshrc} for C-shell,
- $@file{.zshenv} for the Z shell, or the file specified in the
- @env{BASH_ENV} environment variable for BASH.
- @anchor{set auto-connect-native-target}
- @kindex set auto-connect-native-target
- @item set auto-connect-native-target
- @itemx set auto-connect-native-target on
- @itemx set auto-connect-native-target off
- @itemx show auto-connect-native-target
- By default, if the current inferior is not connected to any target yet
- (e.g., with @code{target remote}), the @code{run} command starts your
- program as a native process under @value{GDBN}, on your local machine.
- If you're sure you don't want to debug programs on your local machine,
- you can tell @value{GDBN} to not connect to the native target
- automatically with the @code{set auto-connect-native-target off}
- command.
- If @code{on}, which is the default, and if the current inferior is not
- connected to a target already, the @code{run} command automaticaly
- connects to the native target, if one is available.
- If @code{off}, and if the current inferior is not connected to a
- target already, the @code{run} command fails with an error:
- @smallexample
- (@value{GDBP}) run
- Don't know how to run. Try "help target".
- @end smallexample
- If the current inferior is already connected to a target, @value{GDBN}
- always uses it with the @code{run} command.
- In any case, you can explicitly connect to the native target with the
- @code{target native} command. For example,
- @smallexample
- (@value{GDBP}) set auto-connect-native-target off
- (@value{GDBP}) run
- Don't know how to run. Try "help target".
- (@value{GDBP}) target native
- (@value{GDBP}) run
- Starting program: ./a.out
- [Inferior 1 (process 10421) exited normally]
- @end smallexample
- In case you connected explicitly to the @code{native} target,
- @value{GDBN} remains connected even if all inferiors exit, ready for
- the next @code{run} command. Use the @code{disconnect} command to
- disconnect.
- Examples of other commands that likewise respect the
- @code{auto-connect-native-target} setting: @code{attach}, @code{info
- proc}, @code{info os}.
- @kindex set disable-randomization
- @item set disable-randomization
- @itemx set disable-randomization on
- This option (enabled by default in @value{GDBN}) will turn off the native
- randomization of the virtual address space of the started program. This option
- is useful for multiple debugging sessions to make the execution better
- reproducible and memory addresses reusable across debugging sessions.
- This feature is implemented only on certain targets, including @sc{gnu}/Linux.
- On @sc{gnu}/Linux you can get the same behavior using
- @smallexample
- (@value{GDBP}) set exec-wrapper setarch `uname -m` -R
- @end smallexample
- @item set disable-randomization off
- Leave the behavior of the started executable unchanged. Some bugs rear their
- ugly heads only when the program is loaded at certain addresses. If your bug
- disappears when you run the program under @value{GDBN}, that might be because
- @value{GDBN} by default disables the address randomization on platforms, such
- as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set
- disable-randomization off} to try to reproduce such elusive bugs.
- On targets where it is available, virtual address space randomization
- protects the programs against certain kinds of security attacks. In these
- cases the attacker needs to know the exact location of a concrete executable
- code. Randomizing its location makes it impossible to inject jumps misusing
- a code at its expected addresses.
- Prelinking shared libraries provides a startup performance advantage but it
- makes addresses in these libraries predictable for privileged processes by
- having just unprivileged access at the target system. Reading the shared
- library binary gives enough information for assembling the malicious code
- misusing it. Still even a prelinked shared library can get loaded at a new
- random address just requiring the regular relocation process during the
- startup. Shared libraries not already prelinked are always loaded at
- a randomly chosen address.
- Position independent executables (PIE) contain position independent code
- similar to the shared libraries and therefore such executables get loaded at
- a randomly chosen address upon startup. PIE executables always load even
- already prelinked shared libraries at a random address. You can build such
- executable using @command{gcc -fPIE -pie}.
- Heap (malloc storage), stack and custom mmap areas are always placed randomly
- (as long as the randomization is enabled).
- @item show disable-randomization
- Show the current setting of the explicit disable of the native randomization of
- the virtual address space of the started program.
- @end table
- @node Arguments
- @section Your Program's Arguments
- @cindex arguments (to your program)
- The arguments to your program can be specified by the arguments of the
- @code{run} command.
- They are passed to a shell, which expands wildcard characters and
- performs redirection of I/O, and thence to your program. Your
- @env{SHELL} environment variable (if it exists) specifies what shell
- @value{GDBN} uses. If you do not define @env{SHELL}, @value{GDBN} uses
- the default shell (@file{/bin/sh} on Unix).
- On non-Unix systems, the program is usually invoked directly by
- @value{GDBN}, which emulates I/O redirection via the appropriate system
- calls, and the wildcard characters are expanded by the startup code of
- the program, not by the shell.
- @code{run} with no arguments uses the same arguments used by the previous
- @code{run}, or those set by the @code{set args} command.
- @table @code
- @kindex set args
- @item set args
- Specify the arguments to be used the next time your program is run. If
- @code{set args} has no arguments, @code{run} executes your program
- with no arguments. Once you have run your program with arguments,
- using @code{set args} before the next @code{run} is the only way to run
- it again without arguments.
- @kindex show args
- @item show args
- Show the arguments to give your program when it is started.
- @end table
- @node Environment
- @section Your Program's Environment
- @cindex environment (of your program)
- The @dfn{environment} consists of a set of environment variables and
- their values. Environment variables conventionally record such things as
- your user name, your home directory, your terminal type, and your search
- path for programs to run. Usually you set up environment variables with
- the shell and they are inherited by all the other programs you run. When
- debugging, it can be useful to try running your program with a modified
- environment without having to start @value{GDBN} over again.
- @table @code
- @kindex path
- @item path @var{directory}
- Add @var{directory} to the front of the @env{PATH} environment variable
- (the search path for executables) that will be passed to your program.
- The value of @env{PATH} used by @value{GDBN} does not change.
- You may specify several directory names, separated by whitespace or by a
- system-dependent separator character (@samp{:} on Unix, @samp{;} on
- MS-DOS and MS-Windows). If @var{directory} is already in the path, it
- is moved to the front, so it is searched sooner.
- You can use the string @samp{$cwd} to refer to whatever is the current
- working directory at the time @value{GDBN} searches the path. If you
- use @samp{.} instead, it refers to the directory where you executed the
- @code{path} command. @value{GDBN} replaces @samp{.} in the
- @var{directory} argument (with the current path) before adding
- @var{directory} to the search path.
- @c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
- @c document that, since repeating it would be a no-op.
- @kindex show paths
- @item show paths
- Display the list of search paths for executables (the @env{PATH}
- environment variable).
- @kindex show environment
- @item show environment @r{[}@var{varname}@r{]}
- Print the value of environment variable @var{varname} to be given to
- your program when it starts. If you do not supply @var{varname},
- print the names and values of all environment variables to be given to
- your program. You can abbreviate @code{environment} as @code{env}.
- @kindex set environment
- @anchor{set environment}
- @item set environment @var{varname} @r{[}=@var{value}@r{]}
- Set environment variable @var{varname} to @var{value}. The value
- changes for your program (and the shell @value{GDBN} uses to launch
- it), not for @value{GDBN} itself. The @var{value} may be any string; the
- values of environment variables are just strings, and any
- interpretation is supplied by your program itself. The @var{value}
- parameter is optional; if it is eliminated, the variable is set to a
- null value.
- @c "any string" here does not include leading, trailing
- @c blanks. Gnu asks: does anyone care?
- For example, this command:
- @smallexample
- set env USER = foo
- @end smallexample
- @noindent
- tells the debugged program, when subsequently run, that its user is named
- @samp{foo}. (The spaces around @samp{=} are used for clarity here; they
- are not actually required.)
- Note that on Unix systems, @value{GDBN} runs your program via a shell,
- which also inherits the environment set with @code{set environment}.
- If necessary, you can avoid that by using the @samp{env} program as a
- wrapper instead of using @code{set environment}. @xref{set
- exec-wrapper}, for an example doing just that.
- Environment variables that are set by the user are also transmitted to
- @command{gdbserver} to be used when starting the remote inferior.
- @pxref{QEnvironmentHexEncoded}.
- @kindex unset environment
- @anchor{unset environment}
- @item unset environment @var{varname}
- Remove variable @var{varname} from the environment to be passed to your
- program. This is different from @samp{set env @var{varname} =};
- @code{unset environment} removes the variable from the environment,
- rather than assigning it an empty value.
- Environment variables that are unset by the user are also unset on
- @command{gdbserver} when starting the remote inferior.
- @pxref{QEnvironmentUnset}.
- @end table
- @emph{Warning:} On Unix systems, @value{GDBN} runs your program using
- the shell indicated by your @env{SHELL} environment variable if it
- exists (or @code{/bin/sh} if not). If your @env{SHELL} variable
- names a shell that runs an initialization file when started
- non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv}
- for the Z shell, or the file specified in the @env{BASH_ENV}
- environment variable for BASH---any variables you set in that file
- affect your program. You may wish to move setting of environment
- variables to files that are only run when you sign on, such as
- @file{.login} or @file{.profile}.
- @node Working Directory
- @section Your Program's Working Directory
- @cindex working directory (of your program)
- Each time you start your program with @code{run}, the inferior will be
- initialized with the current working directory specified by the
- @kbd{set cwd} command. If no directory has been specified by this
- command, then the inferior will inherit @value{GDBN}'s current working
- directory as its working directory if native debugging, or it will
- inherit the remote server's current working directory if remote
- debugging.
- @table @code
- @kindex set cwd
- @cindex change inferior's working directory
- @anchor{set cwd command}
- @item set cwd @r{[}@var{directory}@r{]}
- Set the inferior's working directory to @var{directory}, which will be
- @code{glob}-expanded in order to resolve tildes (@file{~}). If no
- argument has been specified, the command clears the setting and resets
- it to an empty state. This setting has no effect on @value{GDBN}'s
- working directory, and it only takes effect the next time you start
- the inferior. The @file{~} in @var{directory} is a short for the
- @dfn{home directory}, usually pointed to by the @env{HOME} environment
- variable. On MS-Windows, if @env{HOME} is not defined, @value{GDBN}
- uses the concatenation of @env{HOMEDRIVE} and @env{HOMEPATH} as
- fallback.
- You can also change @value{GDBN}'s current working directory by using
- the @code{cd} command.
- @xref{cd command}.
- @kindex show cwd
- @cindex show inferior's working directory
- @item show cwd
- Show the inferior's working directory. If no directory has been
- specified by @kbd{set cwd}, then the default inferior's working
- directory is the same as @value{GDBN}'s working directory.
- @kindex cd
- @cindex change @value{GDBN}'s working directory
- @anchor{cd command}
- @item cd @r{[}@var{directory}@r{]}
- Set the @value{GDBN} working directory to @var{directory}. If not
- given, @var{directory} uses @file{'~'}.
- The @value{GDBN} working directory serves as a default for the
- commands that specify files for @value{GDBN} to operate on.
- @xref{Files, ,Commands to Specify Files}.
- @xref{set cwd command}.
- @kindex pwd
- @item pwd
- Print the @value{GDBN} working directory.
- @end table
- It is generally impossible to find the current working directory of
- the process being debugged (since a program can change its directory
- during its run). If you work on a system where @value{GDBN} supports
- the @code{info proc} command (@pxref{Process Information}), you can
- use the @code{info proc} command to find out the
- current working directory of the debuggee.
- @node Input/Output
- @section Your Program's Input and Output
- @cindex redirection
- @cindex i/o
- @cindex terminal
- By default, the program you run under @value{GDBN} does input and output to
- the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
- to its own terminal modes to interact with you, but it records the terminal
- modes your program was using and switches back to them when you continue
- running your program.
- @table @code
- @kindex info terminal
- @item info terminal
- Displays information recorded by @value{GDBN} about the terminal modes your
- program is using.
- @end table
- You can redirect your program's input and/or output using shell
- redirection with the @code{run} command. For example,
- @smallexample
- run > outfile
- @end smallexample
- @noindent
- starts your program, diverting its output to the file @file{outfile}.
- @kindex tty
- @cindex controlling terminal
- Another way to specify where your program should do input and output is
- with the @code{tty} command. This command accepts a file name as
- argument, and causes this file to be the default for future @code{run}
- commands. It also resets the controlling terminal for the child
- process, for future @code{run} commands. For example,
- @smallexample
- tty /dev/ttyb
- @end smallexample
- @noindent
- directs that processes started with subsequent @code{run} commands
- default to do input and output on the terminal @file{/dev/ttyb} and have
- that as their controlling terminal.
- An explicit redirection in @code{run} overrides the @code{tty} command's
- effect on the input/output device, but not its effect on the controlling
- terminal.
- When you use the @code{tty} command or redirect input in the @code{run}
- command, only the input @emph{for your program} is affected. The input
- for @value{GDBN} still comes from your terminal. @code{tty} is an alias
- for @code{set inferior-tty}.
- @cindex inferior tty
- @cindex set inferior controlling terminal
- You can use the @code{show inferior-tty} command to tell @value{GDBN} to
- display the name of the terminal that will be used for future runs of your
- program.
- @table @code
- @item set inferior-tty [ @var{tty} ]
- @kindex set inferior-tty
- Set the tty for the program being debugged to @var{tty}. Omitting @var{tty}
- restores the default behavior, which is to use the same terminal as
- @value{GDBN}.
- @item show inferior-tty
- @kindex show inferior-tty
- Show the current tty for the program being debugged.
- @end table
- @node Attach
- @section Debugging an Already-running Process
- @kindex attach
- @cindex attach
- @table @code
- @item attach @var{process-id}
- This command attaches to a running process---one that was started
- outside @value{GDBN}. (@code{info files} shows your active
- targets.) The command takes as argument a process ID. The usual way to
- find out the @var{process-id} of a Unix process is with the @code{ps} utility,
- or with the @samp{jobs -l} shell command.
- @code{attach} does not repeat if you press @key{RET} a second time after
- executing the command.
- @end table
- To use @code{attach}, your program must be running in an environment
- which supports processes; for example, @code{attach} does not work for
- programs on bare-board targets that lack an operating system. You must
- also have permission to send the process a signal.
- When you use @code{attach}, the debugger finds the program running in
- the process first by looking in the current working directory, then (if
- the program is not found) by using the source file search path
- (@pxref{Source Path, ,Specifying Source Directories}). You can also use
- the @code{file} command to load the program. @xref{Files, ,Commands to
- Specify Files}.
- @anchor{set exec-file-mismatch}
- If the debugger can determine that the executable file running in the
- process it is attaching to does not match the current exec-file loaded
- by @value{GDBN}, the option @code{exec-file-mismatch} specifies how to
- handle the mismatch. @value{GDBN} tries to compare the files by
- comparing their build IDs (@pxref{build ID}), if available.
- @table @code
- @kindex exec-file-mismatch
- @cindex set exec-file-mismatch
- @item set exec-file-mismatch @samp{ask|warn|off}
- Whether to detect mismatch between the current executable file loaded
- by @value{GDBN} and the executable file used to start the process. If
- @samp{ask}, the default, display a warning and ask the user whether to
- load the process executable file; if @samp{warn}, just display a
- warning; if @samp{off}, don't attempt to detect a mismatch.
- If the user confirms loading the process executable file, then its symbols
- will be loaded as well.
- @cindex show exec-file-mismatch
- @item show exec-file-mismatch
- Show the current value of @code{exec-file-mismatch}.
- @end table
- The first thing @value{GDBN} does after arranging to debug the specified
- process is to stop it. You can examine and modify an attached process
- with all the @value{GDBN} commands that are ordinarily available when
- you start processes with @code{run}. You can insert breakpoints; you
- can step and continue; you can modify storage. If you would rather the
- process continue running, you may use the @code{continue} command after
- attaching @value{GDBN} to the process.
- @table @code
- @kindex detach
- @item detach
- When you have finished debugging the attached process, you can use the
- @code{detach} command to release it from @value{GDBN} control. Detaching
- the process continues its execution. After the @code{detach} command,
- that process and @value{GDBN} become completely independent once more, and you
- are ready to @code{attach} another process or start one with @code{run}.
- @code{detach} does not repeat if you press @key{RET} again after
- executing the command.
- @end table
- If you exit @value{GDBN} while you have an attached process, you detach
- that process. If you use the @code{run} command, you kill that process.
- By default, @value{GDBN} asks for confirmation if you try to do either of these
- things; you can control whether or not you need to confirm by using the
- @code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
- Messages}).
- @node Kill Process
- @section Killing the Child Process
- @table @code
- @kindex kill
- @item kill
- Kill the child process in which your program is running under @value{GDBN}.
- @end table
- This command is useful if you wish to debug a core dump instead of a
- running process. @value{GDBN} ignores any core dump file while your program
- is running.
- On some operating systems, a program cannot be executed outside @value{GDBN}
- while you have breakpoints set on it inside @value{GDBN}. You can use the
- @code{kill} command in this situation to permit running your program
- outside the debugger.
- The @code{kill} command is also useful if you wish to recompile and
- relink your program, since on many systems it is impossible to modify an
- executable file while it is running in a process. In this case, when you
- next type @code{run}, @value{GDBN} notices that the file has changed, and
- reads the symbol table again (while trying to preserve your current
- breakpoint settings).
- @node Inferiors Connections and Programs
- @section Debugging Multiple Inferiors Connections and Programs
- @value{GDBN} lets you run and debug multiple programs in a single
- session. In addition, @value{GDBN} on some systems may let you run
- several programs simultaneously (otherwise you have to exit from one
- before starting another). On some systems @value{GDBN} may even let
- you debug several programs simultaneously on different remote systems.
- In the most general case, you can have multiple threads of execution
- in each of multiple processes, launched from multiple executables,
- running on different machines.
- @cindex inferior
- @value{GDBN} represents the state of each program execution with an
- object called an @dfn{inferior}. An inferior typically corresponds to
- a process, but is more general and applies also to targets that do not
- have processes. Inferiors may be created before a process runs, and
- may be retained after a process exits. Inferiors have unique
- identifiers that are different from process ids. Usually each
- inferior will also have its own distinct address space, although some
- embedded targets may have several inferiors running in different parts
- of a single address space. Each inferior may in turn have multiple
- threads running in it.
- To find out what inferiors exist at any moment, use @w{@code{info
- inferiors}}:
- @table @code
- @kindex info inferiors [ @var{id}@dots{} ]
- @item info inferiors
- Print a list of all inferiors currently being managed by @value{GDBN}.
- By default all inferiors are printed, but the argument @var{id}@dots{}
- -- a space separated list of inferior numbers -- can be used to limit
- the display to just the requested inferiors.
- @value{GDBN} displays for each inferior (in this order):
- @enumerate
- @item
- the inferior number assigned by @value{GDBN}
- @item
- the target system's inferior identifier
- @item
- the target connection the inferior is bound to, including the unique
- connection number assigned by @value{GDBN}, and the protocol used by
- the connection.
- @item
- the name of the executable the inferior is running.
- @end enumerate
- @noindent
- An asterisk @samp{*} preceding the @value{GDBN} inferior number
- indicates the current inferior.
- For example,
- @end table
- @c end table here to get a little more width for example
- @smallexample
- (@value{GDBP}) info inferiors
- Num Description Connection Executable
- * 1 process 3401 1 (native) goodbye
- 2 process 2307 2 (extended-remote host:10000) hello
- @end smallexample
- To get informations about the current inferior, use @code{inferior}:
- @table @code
- @kindex inferior
- @item inferior
- Shows information about the current inferior.
- For example,
- @end table
- @c end table here to get a little more width for example
- @smallexample
- (@value{GDBP}) inferior
- [Current inferior is 1 [process 3401] (helloworld)]
- @end smallexample
- To find out what open target connections exist at any moment, use
- @w{@code{info connections}}:
- @table @code
- @kindex info connections [ @var{id}@dots{} ]
- @item info connections
- Print a list of all open target connections currently being managed by
- @value{GDBN}. By default all connections are printed, but the
- argument @var{id}@dots{} -- a space separated list of connections
- numbers -- can be used to limit the display to just the requested
- connections.
- @value{GDBN} displays for each connection (in this order):
- @enumerate
- @item
- the connection number assigned by @value{GDBN}.
- @item
- the protocol used by the connection.
- @item
- a textual description of the protocol used by the connection.
- @end enumerate
- @noindent
- An asterisk @samp{*} preceding the connection number indicates the
- connection of the current inferior.
- For example,
- @end table
- @c end table here to get a little more width for example
- @smallexample
- (@value{GDBP}) info connections
- Num What Description
- * 1 extended-remote host:10000 Extended remote serial target in gdb-specific protocol
- 2 native Native process
- 3 core Local core dump file
- @end smallexample
- To switch focus between inferiors, use the @code{inferior} command:
- @table @code
- @kindex inferior @var{infno}
- @item inferior @var{infno}
- Make inferior number @var{infno} the current inferior. The argument
- @var{infno} is the inferior number assigned by @value{GDBN}, as shown
- in the first field of the @samp{info inferiors} display.
- @end table
- @vindex $_inferior@r{, convenience variable}
- The debugger convenience variable @samp{$_inferior} contains the
- number of the current inferior. You may find this useful in writing
- breakpoint conditional expressions, command scripts, and so forth.
- @xref{Convenience Vars,, Convenience Variables}, for general
- information on convenience variables.
- You can get multiple executables into a debugging session via the
- @code{add-inferior} and @w{@code{clone-inferior}} commands. On some
- systems @value{GDBN} can add inferiors to the debug session
- automatically by following calls to @code{fork} and @code{exec}. To
- remove inferiors from the debugging session use the
- @w{@code{remove-inferiors}} command.
- @table @code
- @anchor{add_inferior_cli}
- @kindex add-inferior
- @item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] [-no-connection ]
- Adds @var{n} inferiors to be run using @var{executable} as the
- executable; @var{n} defaults to 1. If no executable is specified,
- the inferiors begins empty, with no program. You can still assign or
- change the program assigned to the inferior at any time by using the
- @code{file} command with the executable name as its argument.
- By default, the new inferior begins connected to the same target
- connection as the current inferior. For example, if the current
- inferior was connected to @code{gdbserver} with @code{target remote},
- then the new inferior will be connected to the same @code{gdbserver}
- instance. The @samp{-no-connection} option starts the new inferior
- with no connection yet. You can then for example use the @code{target
- remote} command to connect to some other @code{gdbserver} instance,
- use @code{run} to spawn a local program, etc.
- @kindex clone-inferior
- @item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
- Adds @var{n} inferiors ready to execute the same program as inferior
- @var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the
- number of the current inferior. This command copies the values of the
- @var{args}, @w{@var{inferior-tty}} and @var{cwd} properties from the
- current inferior to the new one. It also propagates changes the user
- made to environment variables using the @w{@code{set environment}} and
- @w{@code{unset environment}} commands. This is a convenient command
- when you want to run another instance of the inferior you are debugging.
- @smallexample
- (@value{GDBP}) info inferiors
- Num Description Connection Executable
- * 1 process 29964 1 (native) helloworld
- (@value{GDBP}) clone-inferior
- Added inferior 2.
- 1 inferiors added.
- (@value{GDBP}) info inferiors
- Num Description Connection Executable
- * 1 process 29964 1 (native) helloworld
- 2 <null> 1 (native) helloworld
- @end smallexample
- You can now simply switch focus to inferior 2 and run it.
- @kindex remove-inferiors
- @item remove-inferiors @var{infno}@dots{}
- Removes the inferior or inferiors @var{infno}@dots{}. It is not
- possible to remove an inferior that is running with this command. For
- those, use the @code{kill} or @code{detach} command first.
- @end table
- To quit debugging one of the running inferiors that is not the current
- inferior, you can either detach from it by using the @w{@code{detach
- inferior}} command (allowing it to run independently), or kill it
- using the @w{@code{kill inferiors}} command:
- @table @code
- @kindex detach inferiors @var{infno}@dots{}
- @item detach inferior @var{infno}@dots{}
- Detach from the inferior or inferiors identified by @value{GDBN}
- inferior number(s) @var{infno}@dots{}. Note that the inferior's entry
- still stays on the list of inferiors shown by @code{info inferiors},
- but its Description will show @samp{<null>}.
- @kindex kill inferiors @var{infno}@dots{}
- @item kill inferiors @var{infno}@dots{}
- Kill the inferior or inferiors identified by @value{GDBN} inferior
- number(s) @var{infno}@dots{}. Note that the inferior's entry still
- stays on the list of inferiors shown by @code{info inferiors}, but its
- Description will show @samp{<null>}.
- @end table
- After the successful completion of a command such as @code{detach},
- @code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after
- a normal process exit, the inferior is still valid and listed with
- @code{info inferiors}, ready to be restarted.
- To be notified when inferiors are started or exit under @value{GDBN}'s
- control use @w{@code{set print inferior-events}}:
- @table @code
- @kindex set print inferior-events
- @cindex print messages on inferior start and exit
- @item set print inferior-events
- @itemx set print inferior-events on
- @itemx set print inferior-events off
- The @code{set print inferior-events} command allows you to enable or
- disable printing of messages when @value{GDBN} notices that new
- inferiors have started or that inferiors have exited or have been
- detached. By default, these messages will be printed.
- @kindex show print inferior-events
- @item show print inferior-events
- Show whether messages will be printed when @value{GDBN} detects that
- inferiors have started, exited or have been detached.
- @end table
- Many commands will work the same with multiple programs as with a
- single program: e.g., @code{print myglobal} will simply display the
- value of @code{myglobal} in the current inferior.
- Occasionally, when debugging @value{GDBN} itself, it may be useful to
- get more info about the relationship of inferiors, programs, address
- spaces in a debug session. You can do that with the @w{@code{maint
- info program-spaces}} command.
- @table @code
- @kindex maint info program-spaces
- @item maint info program-spaces
- Print a list of all program spaces currently being managed by
- @value{GDBN}.
- @value{GDBN} displays for each program space (in this order):
- @enumerate
- @item
- the program space number assigned by @value{GDBN}
- @item
- the name of the executable loaded into the program space, with e.g.,
- the @code{file} command.
- @end enumerate
- @noindent
- An asterisk @samp{*} preceding the @value{GDBN} program space number
- indicates the current program space.
- In addition, below each program space line, @value{GDBN} prints extra
- information that isn't suitable to display in tabular form. For
- example, the list of inferiors bound to the program space.
- @smallexample
- (@value{GDBP}) maint info program-spaces
- Id Executable
- * 1 hello
- 2 goodbye
- Bound inferiors: ID 1 (process 21561)
- @end smallexample
- Here we can see that no inferior is running the program @code{hello},
- while @code{process 21561} is running the program @code{goodbye}. On
- some targets, it is possible that multiple inferiors are bound to the
- same program space. The most common example is that of debugging both
- the parent and child processes of a @code{vfork} call. For example,
- @smallexample
- (@value{GDBP}) maint info program-spaces
- Id Executable
- * 1 vfork-test
- Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
- @end smallexample
- Here, both inferior 2 and inferior 1 are running in the same program
- space as a result of inferior 1 having executed a @code{vfork} call.
- @end table
- @node Threads
- @section Debugging Programs with Multiple Threads
- @cindex threads of execution
- @cindex multiple threads
- @cindex switching threads
- In some operating systems, such as GNU/Linux and Solaris, a single program
- may have more than one @dfn{thread} of execution. The precise semantics
- of threads differ from one operating system to another, but in general
- the threads of a single program are akin to multiple processes---except
- that they share one address space (that is, they can all examine and
- modify the same variables). On the other hand, each thread has its own
- registers and execution stack, and perhaps private memory.
- @value{GDBN} provides these facilities for debugging multi-thread
- programs:
- @itemize @bullet
- @item automatic notification of new threads
- @item @samp{thread @var{thread-id}}, a command to switch among threads
- @item @samp{info threads}, a command to inquire about existing threads
- @item @samp{thread apply [@var{thread-id-list} | all] @var{args}},
- a command to apply a command to a list of threads
- @item thread-specific breakpoints
- @item @samp{set print thread-events}, which controls printing of
- messages on thread start and exit.
- @item @samp{set libthread-db-search-path @var{path}}, which lets
- the user specify which @code{libthread_db} to use if the default choice
- isn't compatible with the program.
- @end itemize
- @cindex focus of debugging
- @cindex current thread
- The @value{GDBN} thread debugging facility allows you to observe all
- threads while your program runs---but whenever @value{GDBN} takes
- control, one thread in particular is always the focus of debugging.
- This thread is called the @dfn{current thread}. Debugging commands show
- program information from the perspective of the current thread.
- @cindex @code{New} @var{systag} message
- @cindex thread identifier (system)
- @c FIXME-implementors!! It would be more helpful if the [New...] message
- @c included GDB's numeric thread handle, so you could just go to that
- @c thread without first checking `info threads'.
- Whenever @value{GDBN} detects a new thread in your program, it displays
- the target system's identification for the thread with a message in the
- form @samp{[New @var{systag}]}, where @var{systag} is a thread identifier
- whose form varies depending on the particular system. For example, on
- @sc{gnu}/Linux, you might see
- @smallexample
- [New Thread 0x41e02940 (LWP 25582)]
- @end smallexample
- @noindent
- when @value{GDBN} notices a new thread. In contrast, on other systems,
- the @var{systag} is simply something like @samp{process 368}, with no
- further qualifier.
- @c FIXME!! (1) Does the [New...] message appear even for the very first
- @c thread of a program, or does it only appear for the
- @c second---i.e.@: when it becomes obvious we have a multithread
- @c program?
- @c (2) *Is* there necessarily a first thread always? Or do some
- @c multithread systems permit starting a program with multiple
- @c threads ab initio?
- @anchor{thread numbers}
- @cindex thread number, per inferior
- @cindex thread identifier (GDB)
- For debugging purposes, @value{GDBN} associates its own thread number
- ---always a single integer---with each thread of an inferior. This
- number is unique between all threads of an inferior, but not unique
- between threads of different inferiors.
- @cindex qualified thread ID
- You can refer to a given thread in an inferior using the qualified
- @var{inferior-num}.@var{thread-num} syntax, also known as
- @dfn{qualified thread ID}, with @var{inferior-num} being the inferior
- number and @var{thread-num} being the thread number of the given
- inferior. For example, thread @code{2.3} refers to thread number 3 of
- inferior 2. If you omit @var{inferior-num} (e.g., @code{thread 3}),
- then @value{GDBN} infers you're referring to a thread of the current
- inferior.
- Until you create a second inferior, @value{GDBN} does not show the
- @var{inferior-num} part of thread IDs, even though you can always use
- the full @var{inferior-num}.@var{thread-num} form to refer to threads
- of inferior 1, the initial inferior.
- @anchor{thread ID lists}
- @cindex thread ID lists
- Some commands accept a space-separated @dfn{thread ID list} as
- argument. A list element can be:
- @enumerate
- @item
- A thread ID as shown in the first field of the @samp{info threads}
- display, with or without an inferior qualifier. E.g., @samp{2.1} or
- @samp{1}.
- @item
- A range of thread numbers, again with or without an inferior
- qualifier, as in @var{inf}.@var{thr1}-@var{thr2} or
- @var{thr1}-@var{thr2}. E.g., @samp{1.2-4} or @samp{2-4}.
- @item
- All threads of an inferior, specified with a star wildcard, with or
- without an inferior qualifier, as in @var{inf}.@code{*} (e.g.,
- @samp{1.*}) or @code{*}. The former refers to all threads of the
- given inferior, and the latter form without an inferior qualifier
- refers to all threads of the current inferior.
- @end enumerate
- For example, if the current inferior is 1, and inferior 7 has one
- thread with ID 7.1, the thread list @samp{1 2-3 4.5 6.7-9 7.*}
- includes threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads
- 7 to 9 of inferior 6 and all threads of inferior 7. That is, in
- expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5 6.7 6.8 6.9
- 7.1}.
- @anchor{global thread numbers}
- @cindex global thread number
- @cindex global thread identifier (GDB)
- In addition to a @emph{per-inferior} number, each thread is also
- assigned a unique @emph{global} number, also known as @dfn{global
- thread ID}, a single integer. Unlike the thread number component of
- the thread ID, no two threads have the same global ID, even when
- you're debugging multiple inferiors.
- From @value{GDBN}'s perspective, a process always has at least one
- thread. In other words, @value{GDBN} assigns a thread number to the
- program's ``main thread'' even if the program is not multi-threaded.
- @vindex $_thread@r{, convenience variable}
- @vindex $_gthread@r{, convenience variable}
- The debugger convenience variables @samp{$_thread} and
- @samp{$_gthread} contain, respectively, the per-inferior thread number
- and the global thread number of the current thread. You may find this
- useful in writing breakpoint conditional expressions, command scripts,
- and so forth. @xref{Convenience Vars,, Convenience Variables}, for
- general information on convenience variables.
- If @value{GDBN} detects the program is multi-threaded, it augments the
- usual message about stopping at a breakpoint with the ID and name of
- the thread that hit the breakpoint.
- @smallexample
- Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68
- @end smallexample
- Likewise when the program receives a signal:
- @smallexample
- Thread 1 "main" received signal SIGINT, Interrupt.
- @end smallexample
- @table @code
- @anchor{info_threads}
- @kindex info threads
- @item info threads @r{[}@var{thread-id-list}@r{]}
- Display information about one or more threads. With no arguments
- displays information about all threads. You can specify the list of
- threads that you want to display using the thread ID list syntax
- (@pxref{thread ID lists}).
- @value{GDBN} displays for each thread (in this order):
- @enumerate
- @item
- the per-inferior thread number assigned by @value{GDBN}
- @item
- the global thread number assigned by @value{GDBN}, if the @samp{-gid}
- option was specified
- @item
- the target system's thread identifier (@var{systag})
- @item
- the thread's name, if one is known. A thread can either be named by
- the user (see @code{thread name}, below), or, in some cases, by the
- program itself.
- @item
- the current stack frame summary for that thread
- @end enumerate
- @noindent
- An asterisk @samp{*} to the left of the @value{GDBN} thread number
- indicates the current thread.
- For example,
- @end table
- @c end table here to get a little more width for example
- @smallexample
- (@value{GDBP}) info threads
- Id Target Id Frame
- * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
- 2 process 35 thread 23 0x34e5 in sigpause ()
- 3 process 35 thread 27 0x34e5 in sigpause ()
- at threadtest.c:68
- @end smallexample
- If you're debugging multiple inferiors, @value{GDBN} displays thread
- IDs using the qualified @var{inferior-num}.@var{thread-num} format.
- Otherwise, only @var{thread-num} is shown.
- If you specify the @samp{-gid} option, @value{GDBN} displays a column
- indicating each thread's global thread ID:
- @smallexample
- (@value{GDBP}) info threads
- Id GId Target Id Frame
- 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
- 1.2 3 process 35 thread 23 0x34e5 in sigpause ()
- 1.3 4 process 35 thread 27 0x34e5 in sigpause ()
- * 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8)
- @end smallexample
- On Solaris, you can display more information about user threads with a
- Solaris-specific command:
- @table @code
- @item maint info sol-threads
- @kindex maint info sol-threads
- @cindex thread info (Solaris)
- Display info on Solaris user threads.
- @end table
- @table @code
- @kindex thread @var{thread-id}
- @item thread @var{thread-id}
- Make thread ID @var{thread-id} the current thread. The command
- argument @var{thread-id} is the @value{GDBN} thread ID, as shown in
- the first field of the @samp{info threads} display, with or without an
- inferior qualifier (e.g., @samp{2.1} or @samp{1}).
- @value{GDBN} responds by displaying the system identifier of the
- thread you selected, and its current stack frame summary:
- @smallexample
- (@value{GDBP}) thread 2
- [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]
- #0 some_function (ignore=0x0) at example.c:8
- 8 printf ("hello\n");
- @end smallexample
- @noindent
- As with the @samp{[New @dots{}]} message, the form of the text after
- @samp{Switching to} depends on your system's conventions for identifying
- threads.
- @anchor{thread apply all}
- @kindex thread apply
- @cindex apply command to several threads
- @item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command}
- The @code{thread apply} command allows you to apply the named
- @var{command} to one or more threads. Specify the threads that you
- want affected using the thread ID list syntax (@pxref{thread ID
- lists}), or specify @code{all} to apply to all threads. To apply a
- command to all threads in descending order, type @kbd{thread apply all
- @var{command}}. To apply a command to all threads in ascending order,
- type @kbd{thread apply all -ascending @var{command}}.
- The @var{flag} arguments control what output to produce and how to handle
- errors raised when applying @var{command} to a thread. @var{flag}
- must start with a @code{-} directly followed by one letter in
- @code{qcs}. If several flags are provided, they must be given
- individually, such as @code{-c -q}.
- By default, @value{GDBN} displays some thread information before the
- output produced by @var{command}, and an error raised during the
- execution of a @var{command} will abort @code{thread apply}. The
- following flags can be used to fine-tune this behavior:
- @table @code
- @item -c
- The flag @code{-c}, which stands for @samp{continue}, causes any
- errors in @var{command} to be displayed, and the execution of
- @code{thread apply} then continues.
- @item -s
- The flag @code{-s}, which stands for @samp{silent}, causes any errors
- or empty output produced by a @var{command} to be silently ignored.
- That is, the execution continues, but the thread information and errors
- are not printed.
- @item -q
- The flag @code{-q} (@samp{quiet}) disables printing the thread
- information.
- @end table
- Flags @code{-c} and @code{-s} cannot be used together.
- @kindex taas
- @cindex apply command to all threads (ignoring errors and empty output)
- @item taas [@var{option}]@dots{} @var{command}
- Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}.
- Applies @var{command} on all threads, ignoring errors and empty output.
- The @code{taas} command accepts the same options as the @code{thread
- apply all} command. @xref{thread apply all}.
- @kindex tfaas
- @cindex apply a command to all frames of all threads (ignoring errors and empty output)
- @item tfaas [@var{option}]@dots{} @var{command}
- Shortcut for @code{thread apply all -s -- frame apply all -s [@var{option}]@dots{} @var{command}}.
- Applies @var{command} on all frames of all threads, ignoring errors
- and empty output. Note that the flag @code{-s} is specified twice:
- The first @code{-s} ensures that @code{thread apply} only shows the thread
- information of the threads for which @code{frame apply} produces
- some output. The second @code{-s} is needed to ensure that @code{frame
- apply} shows the frame information of a frame only if the
- @var{command} successfully produced some output.
- It can for example be used to print a local variable or a function
- argument without knowing the thread or frame where this variable or argument
- is, using:
- @smallexample
- (@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is
- @end smallexample
- The @code{tfaas} command accepts the same options as the @code{frame
- apply} command. @xref{Frame Apply,,frame apply}.
- @kindex thread name
- @cindex name a thread
- @item thread name [@var{name}]
- This command assigns a name to the current thread. If no argument is
- given, any existing user-specified name is removed. The thread name
- appears in the @samp{info threads} display.
- On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to
- determine the name of the thread as given by the OS. On these
- systems, a name specified with @samp{thread name} will override the
- system-give name, and removing the user-specified name will cause
- @value{GDBN} to once again display the system-specified name.
- @kindex thread find
- @cindex search for a thread
- @item thread find [@var{regexp}]
- Search for and display thread ids whose name or @var{systag}
- matches the supplied regular expression.
- As well as being the complement to the @samp{thread name} command,
- this command also allows you to identify a thread by its target
- @var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag}
- is the LWP id.
- @smallexample
- (@value{GDBN}) thread find 26688
- Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
- (@value{GDBN}) info thread 4
- Id Target Id Frame
- 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()
- @end smallexample
- @kindex set print thread-events
- @cindex print messages on thread start and exit
- @item set print thread-events
- @itemx set print thread-events on
- @itemx set print thread-events off
- The @code{set print thread-events} command allows you to enable or
- disable printing of messages when @value{GDBN} notices that new threads have
- started or that threads have exited. By default, these messages will
- be printed if detection of these events is supported by the target.
- Note that these messages cannot be disabled on all targets.
- @kindex show print thread-events
- @item show print thread-events
- Show whether messages will be printed when @value{GDBN} detects that threads
- have started and exited.
- @end table
- @xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
- more information about how @value{GDBN} behaves when you stop and start
- programs with multiple threads.
- @xref{Set Watchpoints,,Setting Watchpoints}, for information about
- watchpoints in programs with multiple threads.
- @anchor{set libthread-db-search-path}
- @table @code
- @kindex set libthread-db-search-path
- @cindex search path for @code{libthread_db}
- @item set libthread-db-search-path @r{[}@var{path}@r{]}
- If this variable is set, @var{path} is a colon-separated list of
- directories @value{GDBN} will use to search for @code{libthread_db}.
- If you omit @var{path}, @samp{libthread-db-search-path} will be reset to
- its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems).
- Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH}
- macro.
- On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper''
- @code{libthread_db} library to obtain information about threads in the
- inferior process. @value{GDBN} will use @samp{libthread-db-search-path}
- to find @code{libthread_db}. @value{GDBN} also consults first if inferior
- specific thread debugging library loading is enabled
- by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}).
- A special entry @samp{$sdir} for @samp{libthread-db-search-path}
- refers to the default system directories that are
- normally searched for loading shared libraries. The @samp{$sdir} entry
- is the only kind not needing to be enabled by @samp{set auto-load libthread-db}
- (@pxref{libthread_db.so.1 file}).
- A special entry @samp{$pdir} for @samp{libthread-db-search-path}
- refers to the directory from which @code{libpthread}
- was loaded in the inferior process.
- For any @code{libthread_db} library @value{GDBN} finds in above directories,
- @value{GDBN} attempts to initialize it with the current inferior process.
- If this initialization fails (which could happen because of a version
- mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN}
- will unload @code{libthread_db}, and continue with the next directory.
- If none of @code{libthread_db} libraries initialize successfully,
- @value{GDBN} will issue a warning and thread debugging will be disabled.
- Setting @code{libthread-db-search-path} is currently implemented
- only on some platforms.
- @kindex show libthread-db-search-path
- @item show libthread-db-search-path
- Display current libthread_db search path.
- @kindex set debug libthread-db
- @kindex show debug libthread-db
- @cindex debugging @code{libthread_db}
- @item set debug libthread-db
- @itemx show debug libthread-db
- Turns on or off display of @code{libthread_db}-related events.
- Use @code{1} to enable, @code{0} to disable.
- @kindex set debug threads
- @kindex show debug threads
- @cindex debugging @code{threads}
- @item set debug threads @r{[}on@r{|}off@r{]}
- @itemx show debug threads
- When @samp{on} @value{GDBN} will print additional messages when
- threads are created and deleted.
- @end table
- @node Forks
- @section Debugging Forks
- @cindex fork, debugging programs which call
- @cindex multiple processes
- @cindex processes, multiple
- On most systems, @value{GDBN} has no special support for debugging
- programs which create additional processes using the @code{fork}
- function. When a program forks, @value{GDBN} will continue to debug the
- parent process and the child process will run unimpeded. If you have
- set a breakpoint in any code which the child then executes, the child
- will get a @code{SIGTRAP} signal which (unless it catches the signal)
- will cause it to terminate.
- However, if you want to debug the child process there is a workaround
- which isn't too painful. Put a call to @code{sleep} in the code which
- the child process executes after the fork. It may be useful to sleep
- only if a certain environment variable is set, or a certain file exists,
- so that the delay need not occur when you don't want to run @value{GDBN}
- on the child. While the child is sleeping, use the @code{ps} program to
- get its process ID. Then tell @value{GDBN} (a new invocation of
- @value{GDBN} if you are also debugging the parent process) to attach to
- the child process (@pxref{Attach}). From that point on you can debug
- the child process just like any other process which you attached to.
- On some systems, @value{GDBN} provides support for debugging programs
- that create additional processes using the @code{fork} or @code{vfork}
- functions. On @sc{gnu}/Linux platforms, this feature is supported
- with kernel version 2.5.46 and later.
- The fork debugging commands are supported in native mode and when
- connected to @code{gdbserver} in either @code{target remote} mode or
- @code{target extended-remote} mode.
- By default, when a program forks, @value{GDBN} will continue to debug
- the parent process and the child process will run unimpeded.
- If you want to follow the child process instead of the parent process,
- use the command @w{@code{set follow-fork-mode}}.
- @table @code
- @kindex set follow-fork-mode
- @item set follow-fork-mode @var{mode}
- Set the debugger response to a program call of @code{fork} or
- @code{vfork}. A call to @code{fork} or @code{vfork} creates a new
- process. The @var{mode} argument can be:
- @table @code
- @item parent
- The original process is debugged after a fork. The child process runs
- unimpeded. This is the default.
- @item child
- The new process is debugged after a fork. The parent process runs
- unimpeded.
- @end table
- @kindex show follow-fork-mode
- @item show follow-fork-mode
- Display the current debugger response to a @code{fork} or @code{vfork} call.
- @end table
- @cindex debugging multiple processes
- On Linux, if you want to debug both the parent and child processes, use the
- command @w{@code{set detach-on-fork}}.
- @table @code
- @kindex set detach-on-fork
- @item set detach-on-fork @var{mode}
- Tells gdb whether to detach one of the processes after a fork, or
- retain debugger control over them both.
- @table @code
- @item on
- The child process (or parent process, depending on the value of
- @code{follow-fork-mode}) will be detached and allowed to run
- independently. This is the default.
- @item off
- Both processes will be held under the control of @value{GDBN}.
- One process (child or parent, depending on the value of
- @code{follow-fork-mode}) is debugged as usual, while the other
- is held suspended.
- @end table
- @kindex show detach-on-fork
- @item show detach-on-fork
- Show whether detach-on-fork mode is on/off.
- @end table
- If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN}
- will retain control of all forked processes (including nested forks).
- You can list the forked processes under the control of @value{GDBN} by
- using the @w{@code{info inferiors}} command, and switch from one fork
- to another by using the @code{inferior} command (@pxref{Inferiors Connections and
- Programs, ,Debugging Multiple Inferiors Connections and Programs}).
- To quit debugging one of the forked processes, you can either detach
- from it by using the @w{@code{detach inferiors}} command (allowing it
- to run independently), or kill it using the @w{@code{kill inferiors}}
- command. @xref{Inferiors Connections and Programs, ,Debugging
- Multiple Inferiors Connections and Programs}.
- If you ask to debug a child process and a @code{vfork} is followed by an
- @code{exec}, @value{GDBN} executes the new target up to the first
- breakpoint in the new target. If you have a breakpoint set on
- @code{main} in your original program, the breakpoint will also be set on
- the child process's @code{main}.
- On some systems, when a child process is spawned by @code{vfork}, you
- cannot debug the child or parent until an @code{exec} call completes.
- If you issue a @code{run} command to @value{GDBN} after an @code{exec}
- call executes, the new target restarts. To restart the parent
- process, use the @code{file} command with the parent executable name
- as its argument. By default, after an @code{exec} call executes,
- @value{GDBN} discards the symbols of the previous executable image.
- You can change this behaviour with the @w{@code{set follow-exec-mode}}
- command.
- @table @code
- @kindex set follow-exec-mode
- @item set follow-exec-mode @var{mode}
- Set debugger response to a program call of @code{exec}. An
- @code{exec} call replaces the program image of a process.
- @code{follow-exec-mode} can be:
- @table @code
- @item new
- @value{GDBN} creates a new inferior and rebinds the process to this
- new inferior. The program the process was running before the
- @code{exec} call can be restarted afterwards by restarting the
- original inferior.
- For example:
- @smallexample
- (@value{GDBP}) info inferiors
- (gdb) info inferior
- Id Description Executable
- * 1 <null> prog1
- (@value{GDBP}) run
- process 12020 is executing new program: prog2
- Program exited normally.
- (@value{GDBP}) info inferiors
- Id Description Executable
- 1 <null> prog1
- * 2 <null> prog2
- @end smallexample
- @item same
- @value{GDBN} keeps the process bound to the same inferior. The new
- executable image replaces the previous executable loaded in the
- inferior. Restarting the inferior after the @code{exec} call, with
- e.g., the @code{run} command, restarts the executable the process was
- running after the @code{exec} call. This is the default mode.
- For example:
- @smallexample
- (@value{GDBP}) info inferiors
- Id Description Executable
- * 1 <null> prog1
- (@value{GDBP}) run
- process 12020 is executing new program: prog2
- Program exited normally.
- (@value{GDBP}) info inferiors
- Id Description Executable
- * 1 <null> prog2
- @end smallexample
- @end table
- @end table
- @code{follow-exec-mode} is supported in native mode and
- @code{target extended-remote} mode.
- You can use the @code{catch} command to make @value{GDBN} stop whenever
- a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
- Catchpoints, ,Setting Catchpoints}.
- @node Checkpoint/Restart
- @section Setting a @emph{Bookmark} to Return to Later
- @cindex checkpoint
- @cindex restart
- @cindex bookmark
- @cindex snapshot of a process
- @cindex rewind program state
- On certain operating systems@footnote{Currently, only
- @sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a
- program's state, called a @dfn{checkpoint}, and come back to it
- later.
- Returning to a checkpoint effectively undoes everything that has
- happened in the program since the @code{checkpoint} was saved. This
- includes changes in memory, registers, and even (within some limits)
- system state. Effectively, it is like going back in time to the
- moment when the checkpoint was saved.
- Thus, if you're stepping thru a program and you think you're
- getting close to the point where things go wrong, you can save
- a checkpoint. Then, if you accidentally go too far and miss
- the critical statement, instead of having to restart your program
- from the beginning, you can just go back to the checkpoint and
- start again from there.
- This can be especially useful if it takes a lot of time or
- steps to reach the point where you think the bug occurs.
- To use the @code{checkpoint}/@code{restart} method of debugging:
- @table @code
- @kindex checkpoint
- @item checkpoint
- Save a snapshot of the debugged program's current execution state.
- The @code{checkpoint} command takes no arguments, but each checkpoint
- is assigned a small integer id, similar to a breakpoint id.
- @kindex info checkpoints
- @item info checkpoints
- List the checkpoints that have been saved in the current debugging
- session. For each checkpoint, the following information will be
- listed:
- @table @code
- @item Checkpoint ID
- @item Process ID
- @item Code Address
- @item Source line, or label
- @end table
- @kindex restart @var{checkpoint-id}
- @item restart @var{checkpoint-id}
- Restore the program state that was saved as checkpoint number
- @var{checkpoint-id}. All program variables, registers, stack frames
- etc.@: will be returned to the values that they had when the checkpoint
- was saved. In essence, gdb will ``wind back the clock'' to the point
- in time when the checkpoint was saved.
- Note that breakpoints, @value{GDBN} variables, command history etc.
- are not affected by restoring a checkpoint. In general, a checkpoint
- only restores things that reside in the program being debugged, not in
- the debugger.
- @kindex delete checkpoint @var{checkpoint-id}
- @item delete checkpoint @var{checkpoint-id}
- Delete the previously-saved checkpoint identified by @var{checkpoint-id}.
- @end table
- Returning to a previously saved checkpoint will restore the user state
- of the program being debugged, plus a significant subset of the system
- (OS) state, including file pointers. It won't ``un-write'' data from
- a file, but it will rewind the file pointer to the previous location,
- so that the previously written data can be overwritten. For files
- opened in read mode, the pointer will also be restored so that the
- previously read data can be read again.
- Of course, characters that have been sent to a printer (or other
- external device) cannot be ``snatched back'', and characters received
- from eg.@: a serial device can be removed from internal program buffers,
- but they cannot be ``pushed back'' into the serial pipeline, ready to
- be received again. Similarly, the actual contents of files that have
- been changed cannot be restored (at this time).
- However, within those constraints, you actually can ``rewind'' your
- program to a previously saved point in time, and begin debugging it
- again --- and you can change the course of events so as to debug a
- different execution path this time.
- @cindex checkpoints and process id
- Finally, there is one bit of internal program state that will be
- different when you return to a checkpoint --- the program's process
- id. Each checkpoint will have a unique process id (or @var{pid}),
- and each will be different from the program's original @var{pid}.
- If your program has saved a local copy of its process id, this could
- potentially pose a problem.
- @subsection A Non-obvious Benefit of Using Checkpoints
- On some systems such as @sc{gnu}/Linux, address space randomization
- is performed on new processes for security reasons. This makes it
- difficult or impossible to set a breakpoint, or watchpoint, on an
- absolute address if you have to restart the program, since the
- absolute location of a symbol will change from one execution to the
- next.
- A checkpoint, however, is an @emph{identical} copy of a process.
- Therefore if you create a checkpoint at (eg.@:) the start of main,
- and simply return to that checkpoint instead of restarting the
- process, you can avoid the effects of address randomization and
- your symbols will all stay in the same place.
- @node Stopping
- @chapter Stopping and Continuing
- The principal purposes of using a debugger are so that you can stop your
- program before it terminates; or so that, if your program runs into
- trouble, you can investigate and find out why.
- Inside @value{GDBN}, your program may stop for any of several reasons,
- such as a signal, a breakpoint, or reaching a new line after a
- @value{GDBN} command such as @code{step}. You may then examine and
- change variables, set new breakpoints or remove old ones, and then
- continue execution. Usually, the messages shown by @value{GDBN} provide
- ample explanation of the status of your program---but you can also
- explicitly request this information at any time.
- @table @code
- @kindex info program
- @item info program
- Display information about the status of your program: whether it is
- running or not, what process it is, and why it stopped.
- @end table
- @menu
- * Breakpoints:: Breakpoints, watchpoints, and catchpoints
- * Continuing and Stepping:: Resuming execution
- * Skipping Over Functions and Files::
- Skipping over functions and files
- * Signals:: Signals
- * Thread Stops:: Stopping and starting multi-thread programs
- @end menu
- @node Breakpoints
- @section Breakpoints, Watchpoints, and Catchpoints
- @cindex breakpoints
- A @dfn{breakpoint} makes your program stop whenever a certain point in
- the program is reached. For each breakpoint, you can add conditions to
- control in finer detail whether your program stops. You can set
- breakpoints with the @code{break} command and its variants (@pxref{Set
- Breaks, ,Setting Breakpoints}), to specify the place where your program
- should stop by line number, function name or exact address in the
- program.
- On some systems, you can set breakpoints in shared libraries before
- the executable is run.
- @cindex watchpoints
- @cindex data breakpoints
- @cindex memory tracing
- @cindex breakpoint on memory address
- @cindex breakpoint on variable modification
- A @dfn{watchpoint} is a special breakpoint that stops your program
- when the value of an expression changes. The expression may be a value
- of a variable, or it could involve values of one or more variables
- combined by operators, such as @samp{a + b}. This is sometimes called
- @dfn{data breakpoints}. You must use a different command to set
- watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside
- from that, you can manage a watchpoint like any other breakpoint: you
- enable, disable, and delete both breakpoints and watchpoints using the
- same commands.
- You can arrange to have values from your program displayed automatically
- whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
- Automatic Display}.
- @cindex catchpoints
- @cindex breakpoint on events
- A @dfn{catchpoint} is another special breakpoint that stops your program
- when a certain kind of event occurs, such as the throwing of a C@t{++}
- exception or the loading of a library. As with watchpoints, you use a
- different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
- Catchpoints}), but aside from that, you can manage a catchpoint like any
- other breakpoint. (To stop when your program receives a signal, use the
- @code{handle} command; see @ref{Signals, ,Signals}.)
- @cindex breakpoint numbers
- @cindex numbers for breakpoints
- @value{GDBN} assigns a number to each breakpoint, watchpoint, or
- catchpoint when you create it; these numbers are successive integers
- starting with one. In many of the commands for controlling various
- features of breakpoints you use the breakpoint number to say which
- breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
- @dfn{disabled}; if disabled, it has no effect on your program until you
- enable it again.
- @cindex breakpoint ranges
- @cindex breakpoint lists
- @cindex ranges of breakpoints
- @cindex lists of breakpoints
- Some @value{GDBN} commands accept a space-separated list of breakpoints
- on which to operate. A list element can be either a single breakpoint number,
- like @samp{5}, or a range of such numbers, like @samp{5-7}.
- When a breakpoint list is given to a command, all breakpoints in that list
- are operated on.
- @menu
- * Set Breaks:: Setting breakpoints
- * Set Watchpoints:: Setting watchpoints
- * Set Catchpoints:: Setting catchpoints
- * Delete Breaks:: Deleting breakpoints
- * Disabling:: Disabling breakpoints
- * Conditions:: Break conditions
- * Break Commands:: Breakpoint command lists
- * Dynamic Printf:: Dynamic printf
- * Save Breakpoints:: How to save breakpoints in a file
- * Static Probe Points:: Listing static probe points
- * Error in Breakpoints:: ``Cannot insert breakpoints''
- * Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
- @end menu
- @node Set Breaks
- @subsection Setting Breakpoints
- @c FIXME LMB what does GDB do if no code on line of breakpt?
- @c consider in particular declaration with/without initialization.
- @c
- @c FIXME 2 is there stuff on this already? break at fun start, already init?
- @kindex break
- @kindex b @r{(@code{break})}
- @vindex $bpnum@r{, convenience variable}
- @cindex latest breakpoint
- Breakpoints are set with the @code{break} command (abbreviated
- @code{b}). The debugger convenience variable @samp{$bpnum} records the
- number of the breakpoint you've set most recently; see @ref{Convenience
- Vars,, Convenience Variables}, for a discussion of what you can do with
- convenience variables.
- @table @code
- @item break @var{location}
- Set a breakpoint at the given @var{location}, which can specify a
- function name, a line number, or an address of an instruction.
- (@xref{Specify Location}, for a list of all the possible ways to
- specify a @var{location}.) The breakpoint will stop your program just
- before it executes any of the code in the specified @var{location}.
- When using source languages that permit overloading of symbols, such as
- C@t{++}, a function name may refer to more than one possible place to break.
- @xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
- that situation.
- It is also possible to insert a breakpoint that will stop the program
- only if a specific thread (@pxref{Thread-Specific Breakpoints})
- or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
- @item break
- When called without any arguments, @code{break} sets a breakpoint at
- the next instruction to be executed in the selected stack frame
- (@pxref{Stack, ,Examining the Stack}). In any selected frame but the
- innermost, this makes your program stop as soon as control
- returns to that frame. This is similar to the effect of a
- @code{finish} command in the frame inside the selected frame---except
- that @code{finish} does not leave an active breakpoint. If you use
- @code{break} without an argument in the innermost frame, @value{GDBN} stops
- the next time it reaches the current location; this may be useful
- inside loops.
- @value{GDBN} normally ignores breakpoints when it resumes execution, until at
- least one instruction has been executed. If it did not do this, you
- would be unable to proceed past a breakpoint without first disabling the
- breakpoint. This rule applies whether or not the breakpoint already
- existed when your program stopped.
- @item break @dots{} if @var{cond}
- Set a breakpoint with condition @var{cond}; evaluate the expression
- @var{cond} each time the breakpoint is reached, and stop only if the
- value is nonzero---that is, if @var{cond} evaluates as true.
- @samp{@dots{}} stands for one of the possible arguments described
- above (or no argument) specifying where to break. @xref{Conditions,
- ,Break Conditions}, for more information on breakpoint conditions.
- The breakpoint may be mapped to multiple locations. If the breakpoint
- condition @var{cond} is invalid at some but not all of the locations,
- the locations for which the condition is invalid are disabled. For
- example, @value{GDBN} reports below that two of the three locations
- are disabled.
- @smallexample
- (@value{GDBP}) break func if a == 10
- warning: failed to validate condition at location 0x11ce, disabling:
- No symbol "a" in current context.
- warning: failed to validate condition at location 0x11b6, disabling:
- No symbol "a" in current context.
- Breakpoint 1 at 0x11b6: func. (3 locations)
- @end smallexample
- Locations that are disabled because of the condition are denoted by an
- uppercase @code{N} in the output of the @code{info breakpoints}
- command:
- @smallexample
- (@value{GDBP}) info breakpoints
- Num Type Disp Enb Address What
- 1 breakpoint keep y <MULTIPLE>
- stop only if a == 10
- 1.1 N* 0x00000000000011b6 in ...
- 1.2 y 0x00000000000011c2 in ...
- 1.3 N* 0x00000000000011ce in ...
- (*): Breakpoint condition is invalid at this location.
- @end smallexample
- If the breakpoint condition @var{cond} is invalid in the context of
- @emph{all} the locations of the breakpoint, @value{GDBN} refuses to
- define the breakpoint. For example, if variable @code{foo} is an
- undefined variable:
- @smallexample
- (@value{GDBP}) break func if foo
- No symbol "foo" in current context.
- @end smallexample
- @item break @dots{} -force-condition if @var{cond}
- There may be cases where the condition @var{cond} is invalid at all
- the current locations, but the user knows that it will be valid at a
- future location; for example, because of a library load. In such
- cases, by using the @code{-force-condition} keyword before @samp{if},
- @value{GDBN} can be forced to define the breakpoint with the given
- condition expression instead of refusing it.
- @smallexample
- (@value{GDBP}) break func -force-condition if foo
- warning: failed to validate condition at location 1, disabling:
- No symbol "foo" in current context.
- warning: failed to validate condition at location 2, disabling:
- No symbol "foo" in current context.
- warning: failed to validate condition at location 3, disabling:
- No symbol "foo" in current context.
- Breakpoint 1 at 0x1158: test.c:18. (3 locations)
- @end smallexample
- This causes all the present locations where the breakpoint would
- otherwise be inserted, to be disabled, as seen in the example above.
- However, if there exist locations at which the condition is valid, the
- @code{-force-condition} keyword has no effect.
- @kindex tbreak
- @item tbreak @var{args}
- Set a breakpoint enabled only for one stop. The @var{args} are the
- same as for the @code{break} command, and the breakpoint is set in the same
- way, but the breakpoint is automatically deleted after the first time your
- program stops there. @xref{Disabling, ,Disabling Breakpoints}.
- @kindex hbreak
- @cindex hardware breakpoints
- @item hbreak @var{args}
- Set a hardware-assisted breakpoint. The @var{args} are the same as for the
- @code{break} command and the breakpoint is set in the same way, but the
- breakpoint requires hardware support and some target hardware may not
- have this support. The main purpose of this is EPROM/ROM code
- debugging, so you can set a breakpoint at an instruction without
- changing the instruction. This can be used with the new trap-generation
- provided by SPARClite DSU and most x86-based targets. These targets
- will generate traps when a program accesses some data or instruction
- address that is assigned to the debug registers. However the hardware
- breakpoint registers can take a limited number of breakpoints. For
- example, on the DSU, only two data breakpoints can be set at a time, and
- @value{GDBN} will reject this command if more than two are used. Delete
- or disable unused hardware breakpoints before setting new ones
- (@pxref{Disabling, ,Disabling Breakpoints}).
- @xref{Conditions, ,Break Conditions}.
- For remote targets, you can restrict the number of hardware
- breakpoints @value{GDBN} will use, see @ref{set remote
- hardware-breakpoint-limit}.
- @kindex thbreak
- @item thbreak @var{args}
- Set a hardware-assisted breakpoint enabled only for one stop. The @var{args}
- are the same as for the @code{hbreak} command and the breakpoint is set in
- the same way. However, like the @code{tbreak} command,
- the breakpoint is automatically deleted after the
- first time your program stops there. Also, like the @code{hbreak}
- command, the breakpoint requires hardware support and some target hardware
- may not have this support. @xref{Disabling, ,Disabling Breakpoints}.
- See also @ref{Conditions, ,Break Conditions}.
- @kindex rbreak
- @cindex regular expression
- @cindex breakpoints at functions matching a regexp
- @cindex set breakpoints in many functions
- @item rbreak @var{regex}
- Set breakpoints on all functions matching the regular expression
- @var{regex}. This command sets an unconditional breakpoint on all
- matches, printing a list of all breakpoints it set. Once these
- breakpoints are set, they are treated just like the breakpoints set with
- the @code{break} command. You can delete them, disable them, or make
- them conditional the same way as any other breakpoint.
- In programs using different languages, @value{GDBN} chooses the syntax
- to print the list of all breakpoints it sets according to the
- @samp{set language} value: using @samp{set language auto}
- (see @ref{Automatically, ,Set Language Automatically}) means to use the
- language of the breakpoint's function, other values mean to use
- the manually specified language (see @ref{Manually, ,Set Language Manually}).
- The syntax of the regular expression is the standard one used with tools
- like @file{grep}. Note that this is different from the syntax used by
- shells, so for instance @code{foo*} matches all functions that include
- an @code{fo} followed by zero or more @code{o}s. There is an implicit
- @code{.*} leading and trailing the regular expression you supply, so to
- match only functions that begin with @code{foo}, use @code{^foo}.
- @cindex non-member C@t{++} functions, set breakpoint in
- When debugging C@t{++} programs, @code{rbreak} is useful for setting
- breakpoints on overloaded functions that are not members of any special
- classes.
- @cindex set breakpoints on all functions
- The @code{rbreak} command can be used to set breakpoints in
- @strong{all} the functions in a program, like this:
- @smallexample
- (@value{GDBP}) rbreak .
- @end smallexample
- @item rbreak @var{file}:@var{regex}
- If @code{rbreak} is called with a filename qualification, it limits
- the search for functions matching the given regular expression to the
- specified @var{file}. This can be used, for example, to set breakpoints on
- every function in a given file:
- @smallexample
- (@value{GDBP}) rbreak file.c:.
- @end smallexample
- The colon separating the filename qualifier from the regex may
- optionally be surrounded by spaces.
- @kindex info breakpoints
- @cindex @code{$_} and @code{info breakpoints}
- @item info breakpoints @r{[}@var{list}@dots{}@r{]}
- @itemx info break @r{[}@var{list}@dots{}@r{]}
- Print a table of all breakpoints, watchpoints, and catchpoints set and
- not deleted. Optional argument @var{n} means print information only
- about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)).
- For each breakpoint, following columns are printed:
- @table @emph
- @item Breakpoint Numbers
- @item Type
- Breakpoint, watchpoint, or catchpoint.
- @item Disposition
- Whether the breakpoint is marked to be disabled or deleted when hit.
- @item Enabled or Disabled
- Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
- that are not enabled.
- @item Address
- Where the breakpoint is in your program, as a memory address. For a
- pending breakpoint whose address is not yet known, this field will
- contain @samp{<PENDING>}. Such breakpoint won't fire until a shared
- library that has the symbol or line referred by breakpoint is loaded.
- See below for details. A breakpoint with several locations will
- have @samp{<MULTIPLE>} in this field---see below for details.
- @item What
- Where the breakpoint is in the source for your program, as a file and
- line number. For a pending breakpoint, the original string passed to
- the breakpoint command will be listed as it cannot be resolved until
- the appropriate shared library is loaded in the future.
- @end table
- @noindent
- If a breakpoint is conditional, there are two evaluation modes: ``host'' and
- ``target''. If mode is ``host'', breakpoint condition evaluation is done by
- @value{GDBN} on the host's side. If it is ``target'', then the condition
- is evaluated by the target. The @code{info break} command shows
- the condition on the line following the affected breakpoint, together with
- its condition evaluation mode in between parentheses.
- Breakpoint commands, if any, are listed after that. A pending breakpoint is
- allowed to have a condition specified for it. The condition is not parsed for
- validity until a shared library is loaded that allows the pending
- breakpoint to resolve to a valid location.
- @noindent
- @code{info break} with a breakpoint
- number @var{n} as argument lists only that breakpoint. The
- convenience variable @code{$_} and the default examining-address for
- the @code{x} command are set to the address of the last breakpoint
- listed (@pxref{Memory, ,Examining Memory}).
- @noindent
- @code{info break} displays a count of the number of times the breakpoint
- has been hit. This is especially useful in conjunction with the
- @code{ignore} command. You can ignore a large number of breakpoint
- hits, look at the breakpoint info to see how many times the breakpoint
- was hit, and then run again, ignoring one less than that number. This
- will get you quickly to the last hit of that breakpoint.
- @noindent
- For a breakpoints with an enable count (xref) greater than 1,
- @code{info break} also displays that count.
- @end table
- @value{GDBN} allows you to set any number of breakpoints at the same place in
- your program. There is nothing silly or meaningless about this. When
- the breakpoints are conditional, this is even useful
- (@pxref{Conditions, ,Break Conditions}).
- @cindex multiple locations, breakpoints
- @cindex breakpoints, multiple locations
- It is possible that a breakpoint corresponds to several locations
- in your program. Examples of this situation are:
- @itemize @bullet
- @item
- Multiple functions in the program may have the same name.
- @item
- For a C@t{++} constructor, the @value{NGCC} compiler generates several
- instances of the function body, used in different cases.
- @item
- For a C@t{++} template function, a given line in the function can
- correspond to any number of instantiations.
- @item
- For an inlined function, a given source line can correspond to
- several places where that function is inlined.
- @end itemize
- In all those cases, @value{GDBN} will insert a breakpoint at all
- the relevant locations.
- A breakpoint with multiple locations is displayed in the breakpoint
- table using several rows---one header row, followed by one row for
- each breakpoint location. The header row has @samp{<MULTIPLE>} in the
- address column. The rows for individual locations contain the actual
- addresses for locations, and show the functions to which those
- locations belong. The number column for a location is of the form
- @var{breakpoint-number}.@var{location-number}.
- For example:
- @smallexample
- Num Type Disp Enb Address What
- 1 breakpoint keep y <MULTIPLE>
- stop only if i==1
- breakpoint already hit 1 time
- 1.1 y 0x080486a2 in void foo<int>() at t.cc:8
- 1.2 y 0x080486ca in void foo<double>() at t.cc:8
- @end smallexample
- You cannot delete the individual locations from a breakpoint. However,
- each location can be individually enabled or disabled by passing
- @var{breakpoint-number}.@var{location-number} as argument to the
- @code{enable} and @code{disable} commands. It's also possible to
- @code{enable} and @code{disable} a range of @var{location-number}
- locations using a @var{breakpoint-number} and two @var{location-number}s,
- in increasing order, separated by a hyphen, like
- @kbd{@var{breakpoint-number}.@var{location-number1}-@var{location-number2}},
- in which case @value{GDBN} acts on all the locations in the range (inclusive).
- Disabling or enabling the parent breakpoint (@pxref{Disabling}) affects
- all of the locations that belong to that breakpoint.
- @cindex pending breakpoints
- It's quite common to have a breakpoint inside a shared library.
- Shared libraries can be loaded and unloaded explicitly,
- and possibly repeatedly, as the program is executed. To support
- this use case, @value{GDBN} updates breakpoint locations whenever
- any shared library is loaded or unloaded. Typically, you would
- set a breakpoint in a shared library at the beginning of your
- debugging session, when the library is not loaded, and when the
- symbols from the library are not available. When you try to set
- breakpoint, @value{GDBN} will ask you if you want to set
- a so called @dfn{pending breakpoint}---breakpoint whose address
- is not yet resolved.
- After the program is run, whenever a new shared library is loaded,
- @value{GDBN} reevaluates all the breakpoints. When a newly loaded
- shared library contains the symbol or line referred to by some
- pending breakpoint, that breakpoint is resolved and becomes an
- ordinary breakpoint. When a library is unloaded, all breakpoints
- that refer to its symbols or source lines become pending again.
- This logic works for breakpoints with multiple locations, too. For
- example, if you have a breakpoint in a C@t{++} template function, and
- a newly loaded shared library has an instantiation of that template,
- a new location is added to the list of locations for the breakpoint.
- Except for having unresolved address, pending breakpoints do not
- differ from regular breakpoints. You can set conditions or commands,
- enable and disable them and perform other breakpoint operations.
- @value{GDBN} provides some additional commands for controlling what
- happens when the @samp{break} command cannot resolve breakpoint
- address specification to an address:
- @kindex set breakpoint pending
- @kindex show breakpoint pending
- @table @code
- @item set breakpoint pending auto
- This is the default behavior. When @value{GDBN} cannot find the breakpoint
- location, it queries you whether a pending breakpoint should be created.
- @item set breakpoint pending on
- This indicates that an unrecognized breakpoint location should automatically
- result in a pending breakpoint being created.
- @item set breakpoint pending off
- This indicates that pending breakpoints are not to be created. Any
- unrecognized breakpoint location results in an error. This setting does
- not affect any pending breakpoints previously created.
- @item show breakpoint pending
- Show the current behavior setting for creating pending breakpoints.
- @end table
- The settings above only affect the @code{break} command and its
- variants. Once breakpoint is set, it will be automatically updated
- as shared libraries are loaded and unloaded.
- @cindex automatic hardware breakpoints
- For some targets, @value{GDBN} can automatically decide if hardware or
- software breakpoints should be used, depending on whether the
- breakpoint address is read-only or read-write. This applies to
- breakpoints set with the @code{break} command as well as to internal
- breakpoints set by commands like @code{next} and @code{finish}. For
- breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
- breakpoints.
- You can control this automatic behaviour with the following commands:
- @kindex set breakpoint auto-hw
- @kindex show breakpoint auto-hw
- @table @code
- @item set breakpoint auto-hw on
- This is the default behavior. When @value{GDBN} sets a breakpoint, it
- will try to use the target memory map to decide if software or hardware
- breakpoint must be used.
- @item set breakpoint auto-hw off
- This indicates @value{GDBN} should not automatically select breakpoint
- type. If the target provides a memory map, @value{GDBN} will warn when
- trying to set software breakpoint at a read-only address.
- @end table
- @value{GDBN} normally implements breakpoints by replacing the program code
- at the breakpoint address with a special instruction, which, when
- executed, given control to the debugger. By default, the program
- code is so modified only when the program is resumed. As soon as
- the program stops, @value{GDBN} restores the original instructions. This
- behaviour guards against leaving breakpoints inserted in the
- target should gdb abrubptly disconnect. However, with slow remote
- targets, inserting and removing breakpoint can reduce the performance.
- This behavior can be controlled with the following commands::
- @kindex set breakpoint always-inserted
- @kindex show breakpoint always-inserted
- @table @code
- @item set breakpoint always-inserted off
- All breakpoints, including newly added by the user, are inserted in
- the target only when the target is resumed. All breakpoints are
- removed from the target when it stops. This is the default mode.
- @item set breakpoint always-inserted on
- Causes all breakpoints to be inserted in the target at all times. If
- the user adds a new breakpoint, or changes an existing breakpoint, the
- breakpoints in the target are updated immediately. A breakpoint is
- removed from the target only when breakpoint itself is deleted.
- @end table
- @value{GDBN} handles conditional breakpoints by evaluating these conditions
- when a breakpoint breaks. If the condition is true, then the process being
- debugged stops, otherwise the process is resumed.
- If the target supports evaluating conditions on its end, @value{GDBN} may
- download the breakpoint, together with its conditions, to it.
- This feature can be controlled via the following commands:
- @kindex set breakpoint condition-evaluation
- @kindex show breakpoint condition-evaluation
- @table @code
- @item set breakpoint condition-evaluation host
- This option commands @value{GDBN} to evaluate the breakpoint
- conditions on the host's side. Unconditional breakpoints are sent to
- the target which in turn receives the triggers and reports them back to GDB
- for condition evaluation. This is the standard evaluation mode.
- @item set breakpoint condition-evaluation target
- This option commands @value{GDBN} to download breakpoint conditions
- to the target at the moment of their insertion. The target
- is responsible for evaluating the conditional expression and reporting
- breakpoint stop events back to @value{GDBN} whenever the condition
- is true. Due to limitations of target-side evaluation, some conditions
- cannot be evaluated there, e.g., conditions that depend on local data
- that is only known to the host. Examples include
- conditional expressions involving convenience variables, complex types
- that cannot be handled by the agent expression parser and expressions
- that are too long to be sent over to the target, specially when the
- target is a remote system. In these cases, the conditions will be
- evaluated by @value{GDBN}.
- @item set breakpoint condition-evaluation auto
- This is the default mode. If the target supports evaluating breakpoint
- conditions on its end, @value{GDBN} will download breakpoint conditions to
- the target (limitations mentioned previously apply). If the target does
- not support breakpoint condition evaluation, then @value{GDBN} will fallback
- to evaluating all these conditions on the host's side.
- @end table
- @cindex negative breakpoint numbers
- @cindex internal @value{GDBN} breakpoints
- @value{GDBN} itself sometimes sets breakpoints in your program for
- special purposes, such as proper handling of @code{longjmp} (in C
- programs). These internal breakpoints are assigned negative numbers,
- starting with @code{-1}; @samp{info breakpoints} does not display them.
- You can see these breakpoints with the @value{GDBN} maintenance command
- @samp{maint info breakpoints} (@pxref{maint info breakpoints}).
- @node Set Watchpoints
- @subsection Setting Watchpoints
- @cindex setting watchpoints
- You can use a watchpoint to stop execution whenever the value of an
- expression changes, without having to predict a particular place where
- this may happen. (This is sometimes called a @dfn{data breakpoint}.)
- The expression may be as simple as the value of a single variable, or
- as complex as many variables combined by operators. Examples include:
- @itemize @bullet
- @item
- A reference to the value of a single variable.
- @item
- An address cast to an appropriate data type. For example,
- @samp{*(int *)0x12345678} will watch a 4-byte region at the specified
- address (assuming an @code{int} occupies 4 bytes).
- @item
- An arbitrarily complex expression, such as @samp{a*b + c/d}. The
- expression can use any operators valid in the program's native
- language (@pxref{Languages}).
- @end itemize
- You can set a watchpoint on an expression even if the expression can
- not be evaluated yet. For instance, you can set a watchpoint on
- @samp{*global_ptr} before @samp{global_ptr} is initialized.
- @value{GDBN} will stop when your program sets @samp{global_ptr} and
- the expression produces a valid value. If the expression becomes
- valid in some other way than changing a variable (e.g.@: if the memory
- pointed to by @samp{*global_ptr} becomes readable as the result of a
- @code{malloc} call), @value{GDBN} may not stop until the next time
- the expression changes.
- @cindex software watchpoints
- @cindex hardware watchpoints
- Depending on your system, watchpoints may be implemented in software or
- hardware. @value{GDBN} does software watchpointing by single-stepping your
- program and testing the variable's value each time, which is hundreds of
- times slower than normal execution. (But this may still be worth it, to
- catch errors where you have no clue what part of your program is the
- culprit.)
- On some systems, such as most PowerPC or x86-based targets,
- @value{GDBN} includes support for hardware watchpoints, which do not
- slow down the running of your program.
- @table @code
- @kindex watch
- @item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} @r{[}task @var{task-id}@r{]}
- Set a watchpoint for an expression. @value{GDBN} will break when the
- expression @var{expr} is written into by the program and its value
- changes. The simplest (and the most popular) use of this command is
- to watch the value of a single variable:
- @smallexample
- (@value{GDBP}) watch foo
- @end smallexample
- If the command includes a @code{@r{[}thread @var{thread-id}@r{]}}
- argument, @value{GDBN} breaks only when the thread identified by
- @var{thread-id} changes the value of @var{expr}. If any other threads
- change the value of @var{expr}, @value{GDBN} will not break. Note
- that watchpoints restricted to a single thread in this way only work
- with Hardware Watchpoints.
- Similarly, if the @code{task} argument is given, then the watchpoint
- will be specific to the indicated Ada task (@pxref{Ada Tasks}).
- Ordinarily a watchpoint respects the scope of variables in @var{expr}
- (see below). The @code{-location} argument tells @value{GDBN} to
- instead watch the memory referred to by @var{expr}. In this case,
- @value{GDBN} will evaluate @var{expr}, take the address of the result,
- and watch the memory at that address. The type of the result is used
- to determine the size of the watched memory. If the expression's
- result does not have an address, then @value{GDBN} will print an
- error.
- The @code{@r{[}mask @var{maskvalue}@r{]}} argument allows creation
- of masked watchpoints, if the current architecture supports this
- feature (e.g., PowerPC Embedded architecture, see @ref{PowerPC
- Embedded}.) A @dfn{masked watchpoint} specifies a mask in addition
- to an address to watch. The mask specifies that some bits of an address
- (the bits which are reset in the mask) should be ignored when matching
- the address accessed by the inferior against the watchpoint address.
- Thus, a masked watchpoint watches many addresses simultaneously---those
- addresses whose unmasked bits are identical to the unmasked bits in the
- watchpoint address. The @code{mask} argument implies @code{-location}.
- Examples:
- @smallexample
- (@value{GDBP}) watch foo mask 0xffff00ff
- (@value{GDBP}) watch *0xdeadbeef mask 0xffffff00
- @end smallexample
- @kindex rwatch
- @item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
- Set a watchpoint that will break when the value of @var{expr} is read
- by the program.
- @kindex awatch
- @item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
- Set a watchpoint that will break when @var{expr} is either read from
- or written into by the program.
- @kindex info watchpoints @r{[}@var{list}@dots{}@r{]}
- @item info watchpoints @r{[}@var{list}@dots{}@r{]}
- This command prints a list of watchpoints, using the same format as
- @code{info break} (@pxref{Set Breaks}).
- @end table
- If you watch for a change in a numerically entered address you need to
- dereference it, as the address itself is just a constant number which will
- never change. @value{GDBN} refuses to create a watchpoint that watches
- a never-changing value:
- @smallexample
- (@value{GDBP}) watch 0x600850
- Cannot watch constant value 0x600850.
- (@value{GDBP}) watch *(int *) 0x600850
- Watchpoint 1: *(int *) 6293584
- @end smallexample
- @value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
- watchpoints execute very quickly, and the debugger reports a change in
- value at the exact instruction where the change occurs. If @value{GDBN}
- cannot set a hardware watchpoint, it sets a software watchpoint, which
- executes more slowly and reports the change in value at the next
- @emph{statement}, not the instruction, after the change occurs.
- @cindex use only software watchpoints
- You can force @value{GDBN} to use only software watchpoints with the
- @kbd{set can-use-hw-watchpoints 0} command. With this variable set to
- zero, @value{GDBN} will never try to use hardware watchpoints, even if
- the underlying system supports them. (Note that hardware-assisted
- watchpoints that were set @emph{before} setting
- @code{can-use-hw-watchpoints} to zero will still use the hardware
- mechanism of watching expression values.)
- @table @code
- @item set can-use-hw-watchpoints
- @kindex set can-use-hw-watchpoints
- Set whether or not to use hardware watchpoints.
- @item show can-use-hw-watchpoints
- @kindex show can-use-hw-watchpoints
- Show the current mode of using hardware watchpoints.
- @end table
- For remote targets, you can restrict the number of hardware
- watchpoints @value{GDBN} will use, see @ref{set remote
- hardware-breakpoint-limit}.
- When you issue the @code{watch} command, @value{GDBN} reports
- @smallexample
- Hardware watchpoint @var{num}: @var{expr}
- @end smallexample
- @noindent
- if it was able to set a hardware watchpoint.
- Currently, the @code{awatch} and @code{rwatch} commands can only set
- hardware watchpoints, because accesses to data that don't change the
- value of the watched expression cannot be detected without examining
- every instruction as it is being executed, and @value{GDBN} does not do
- that currently. If @value{GDBN} finds that it is unable to set a
- hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
- will print a message like this:
- @smallexample
- Expression cannot be implemented with read/access watchpoint.
- @end smallexample
- Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
- data type of the watched expression is wider than what a hardware
- watchpoint on the target machine can handle. For example, some systems
- can only watch regions that are up to 4 bytes wide; on such systems you
- cannot set hardware watchpoints for an expression that yields a
- double-precision floating-point number (which is typically 8 bytes
- wide). As a work-around, it might be possible to break the large region
- into a series of smaller ones and watch them with separate watchpoints.
- If you set too many hardware watchpoints, @value{GDBN} might be unable
- to insert all of them when you resume the execution of your program.
- Since the precise number of active watchpoints is unknown until such
- time as the program is about to be resumed, @value{GDBN} might not be
- able to warn you about this when you set the watchpoints, and the
- warning will be printed only when the program is resumed:
- @smallexample
- Hardware watchpoint @var{num}: Could not insert watchpoint
- @end smallexample
- @noindent
- If this happens, delete or disable some of the watchpoints.
- Watching complex expressions that reference many variables can also
- exhaust the resources available for hardware-assisted watchpoints.
- That's because @value{GDBN} needs to watch every variable in the
- expression with separately allocated resources.
- If you call a function interactively using @code{print} or @code{call},
- any watchpoints you have set will be inactive until @value{GDBN} reaches another
- kind of breakpoint or the call completes.
- @value{GDBN} automatically deletes watchpoints that watch local
- (automatic) variables, or expressions that involve such variables, when
- they go out of scope, that is, when the execution leaves the block in
- which these variables were defined. In particular, when the program
- being debugged terminates, @emph{all} local variables go out of scope,
- and so only watchpoints that watch global variables remain set. If you
- rerun the program, you will need to set all such watchpoints again. One
- way of doing that would be to set a code breakpoint at the entry to the
- @code{main} function and when it breaks, set all the watchpoints.
- @cindex watchpoints and threads
- @cindex threads and watchpoints
- In multi-threaded programs, watchpoints will detect changes to the
- watched expression from every thread.
- @quotation
- @emph{Warning:} In multi-threaded programs, software watchpoints
- have only limited usefulness. If @value{GDBN} creates a software
- watchpoint, it can only watch the value of an expression @emph{in a
- single thread}. If you are confident that the expression can only
- change due to the current thread's activity (and if you are also
- confident that no other thread can become current), then you can use
- software watchpoints as usual. However, @value{GDBN} may not notice
- when a non-current thread's activity changes the expression. (Hardware
- watchpoints, in contrast, watch an expression in all threads.)
- @end quotation
- @xref{set remote hardware-watchpoint-limit}.
- @node Set Catchpoints
- @subsection Setting Catchpoints
- @cindex catchpoints, setting
- @cindex exception handlers
- @cindex event handling
- You can use @dfn{catchpoints} to cause the debugger to stop for certain
- kinds of program events, such as C@t{++} exceptions or the loading of a
- shared library. Use the @code{catch} command to set a catchpoint.
- @table @code
- @kindex catch
- @item catch @var{event}
- Stop when @var{event} occurs. The @var{event} can be any of the following:
- @table @code
- @item throw @r{[}@var{regexp}@r{]}
- @itemx rethrow @r{[}@var{regexp}@r{]}
- @itemx catch @r{[}@var{regexp}@r{]}
- @kindex catch throw
- @kindex catch rethrow
- @kindex catch catch
- @cindex stop on C@t{++} exceptions
- The throwing, re-throwing, or catching of a C@t{++} exception.
- If @var{regexp} is given, then only exceptions whose type matches the
- regular expression will be caught.
- @vindex $_exception@r{, convenience variable}
- The convenience variable @code{$_exception} is available at an
- exception-related catchpoint, on some systems. This holds the
- exception being thrown.
- There are currently some limitations to C@t{++} exception handling in
- @value{GDBN}:
- @itemize @bullet
- @item
- The support for these commands is system-dependent. Currently, only
- systems using the @samp{gnu-v3} C@t{++} ABI (@pxref{ABI}) are
- supported.
- @item
- The regular expression feature and the @code{$_exception} convenience
- variable rely on the presence of some SDT probes in @code{libstdc++}.
- If these probes are not present, then these features cannot be used.
- These probes were first available in the GCC 4.8 release, but whether
- or not they are available in your GCC also depends on how it was
- built.
- @item
- The @code{$_exception} convenience variable is only valid at the
- instruction at which an exception-related catchpoint is set.
- @item
- When an exception-related catchpoint is hit, @value{GDBN} stops at a
- location in the system library which implements runtime exception
- support for C@t{++}, usually @code{libstdc++}. You can use @code{up}
- (@pxref{Selection}) to get to your code.
- @item
- If you call a function interactively, @value{GDBN} normally returns
- control to you when the function has finished executing. If the call
- raises an exception, however, the call may bypass the mechanism that
- returns control to you and cause your program either to abort or to
- simply continue running until it hits a breakpoint, catches a signal
- that @value{GDBN} is listening for, or exits. This is the case even if
- you set a catchpoint for the exception; catchpoints on exceptions are
- disabled within interactive calls. @xref{Calling}, for information on
- controlling this with @code{set unwind-on-terminating-exception}.
- @item
- You cannot raise an exception interactively.
- @item
- You cannot install an exception handler interactively.
- @end itemize
- @item exception @r{[}@var{name}@r{]}
- @kindex catch exception
- @cindex Ada exception catching
- @cindex catch Ada exceptions
- An Ada exception being raised. If an exception name is specified
- at the end of the command (eg @code{catch exception Program_Error}),
- the debugger will stop only when this specific exception is raised.
- Otherwise, the debugger stops execution when any Ada exception is raised.
- When inserting an exception catchpoint on a user-defined exception whose
- name is identical to one of the exceptions defined by the language, the
- fully qualified name must be used as the exception name. Otherwise,
- @value{GDBN} will assume that it should stop on the pre-defined exception
- rather than the user-defined one. For instance, assuming an exception
- called @code{Constraint_Error} is defined in package @code{Pck}, then
- the command to use to catch such exceptions is @kbd{catch exception
- Pck.Constraint_Error}.
- @vindex $_ada_exception@r{, convenience variable}
- The convenience variable @code{$_ada_exception} holds the address of
- the exception being thrown. This can be useful when setting a
- condition for such a catchpoint.
- @item exception unhandled
- @kindex catch exception unhandled
- An exception that was raised but is not handled by the program. The
- convenience variable @code{$_ada_exception} is set as for @code{catch
- exception}.
- @item handlers @r{[}@var{name}@r{]}
- @kindex catch handlers
- @cindex Ada exception handlers catching
- @cindex catch Ada exceptions when handled
- An Ada exception being handled. If an exception name is
- specified at the end of the command
- (eg @kbd{catch handlers Program_Error}), the debugger will stop
- only when this specific exception is handled.
- Otherwise, the debugger stops execution when any Ada exception is handled.
- When inserting a handlers catchpoint on a user-defined
- exception whose name is identical to one of the exceptions
- defined by the language, the fully qualified name must be used
- as the exception name. Otherwise, @value{GDBN} will assume that it
- should stop on the pre-defined exception rather than the
- user-defined one. For instance, assuming an exception called
- @code{Constraint_Error} is defined in package @code{Pck}, then the
- command to use to catch such exceptions handling is
- @kbd{catch handlers Pck.Constraint_Error}.
- The convenience variable @code{$_ada_exception} is set as for
- @code{catch exception}.
- @item assert
- @kindex catch assert
- A failed Ada assertion. Note that the convenience variable
- @code{$_ada_exception} is @emph{not} set by this catchpoint.
- @item exec
- @kindex catch exec
- @cindex break on fork/exec
- A call to @code{exec}.
- @anchor{catch syscall}
- @item syscall
- @itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @r{group:}@var{groupname} @r{|} @r{g:}@var{groupname}@r{]} @dots{}
- @kindex catch syscall
- @cindex break on a system call.
- A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
- syscall is a mechanism for application programs to request a service
- from the operating system (OS) or one of the OS system services.
- @value{GDBN} can catch some or all of the syscalls issued by the
- debuggee, and show the related information for each syscall. If no
- argument is specified, calls to and returns from all system calls
- will be caught.
- @var{name} can be any system call name that is valid for the
- underlying OS. Just what syscalls are valid depends on the OS. On
- GNU and Unix systems, you can find the full list of valid syscall
- names on @file{/usr/include/asm/unistd.h}.
- @c For MS-Windows, the syscall names and the corresponding numbers
- @c can be found, e.g., on this URL:
- @c http://www.metasploit.com/users/opcode/syscalls.html
- @c but we don't support Windows syscalls yet.
- Normally, @value{GDBN} knows in advance which syscalls are valid for
- each OS, so you can use the @value{GDBN} command-line completion
- facilities (@pxref{Completion,, command completion}) to list the
- available choices.
- You may also specify the system call numerically. A syscall's
- number is the value passed to the OS's syscall dispatcher to
- identify the requested service. When you specify the syscall by its
- name, @value{GDBN} uses its database of syscalls to convert the name
- into the corresponding numeric code, but using the number directly
- may be useful if @value{GDBN}'s database does not have the complete
- list of syscalls on your system (e.g., because @value{GDBN} lags
- behind the OS upgrades).
- You may specify a group of related syscalls to be caught at once using
- the @code{group:} syntax (@code{g:} is a shorter equivalent). For
- instance, on some platforms @value{GDBN} allows you to catch all
- network related syscalls, by passing the argument @code{group:network}
- to @code{catch syscall}. Note that not all syscall groups are
- available in every system. You can use the command completion
- facilities (@pxref{Completion,, command completion}) to list the
- syscall groups available on your environment.
- The example below illustrates how this command works if you don't provide
- arguments to it:
- @smallexample
- (@value{GDBP}) catch syscall
- Catchpoint 1 (syscall)
- (@value{GDBP}) r
- Starting program: /tmp/catch-syscall
- Catchpoint 1 (call to syscall 'close'), \
- 0xffffe424 in __kernel_vsyscall ()
- (@value{GDBP}) c
- Continuing.
- Catchpoint 1 (returned from syscall 'close'), \
- 0xffffe424 in __kernel_vsyscall ()
- (@value{GDBP})
- @end smallexample
- Here is an example of catching a system call by name:
- @smallexample
- (@value{GDBP}) catch syscall chroot
- Catchpoint 1 (syscall 'chroot' [61])
- (@value{GDBP}) r
- Starting program: /tmp/catch-syscall
- Catchpoint 1 (call to syscall 'chroot'), \
- 0xffffe424 in __kernel_vsyscall ()
- (@value{GDBP}) c
- Continuing.
- Catchpoint 1 (returned from syscall 'chroot'), \
- 0xffffe424 in __kernel_vsyscall ()
- (@value{GDBP})
- @end smallexample
- An example of specifying a system call numerically. In the case
- below, the syscall number has a corresponding entry in the XML
- file, so @value{GDBN} finds its name and prints it:
- @smallexample
- (@value{GDBP}) catch syscall 252
- Catchpoint 1 (syscall(s) 'exit_group')
- (@value{GDBP}) r
- Starting program: /tmp/catch-syscall
- Catchpoint 1 (call to syscall 'exit_group'), \
- 0xffffe424 in __kernel_vsyscall ()
- (@value{GDBP}) c
- Continuing.
- Program exited normally.
- (@value{GDBP})
- @end smallexample
- Here is an example of catching a syscall group:
- @smallexample
- (@value{GDBP}) catch syscall group:process
- Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7]
- 'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190]
- 'exit_group' [252] 'waitid' [284] 'unshare' [310])
- (@value{GDBP}) r
- Starting program: /tmp/catch-syscall
- Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 ()
- from /lib64/ld-linux-x86-64.so.2
- (@value{GDBP}) c
- Continuing.
- @end smallexample
- However, there can be situations when there is no corresponding name
- in XML file for that syscall number. In this case, @value{GDBN} prints
- a warning message saying that it was not able to find the syscall name,
- but the catchpoint will be set anyway. See the example below:
- @smallexample
- (@value{GDBP}) catch syscall 764
- warning: The number '764' does not represent a known syscall.
- Catchpoint 2 (syscall 764)
- (@value{GDBP})
- @end smallexample
- If you configure @value{GDBN} using the @samp{--without-expat} option,
- it will not be able to display syscall names. Also, if your
- architecture does not have an XML file describing its system calls,
- you will not be able to see the syscall names. It is important to
- notice that these two features are used for accessing the syscall
- name database. In either case, you will see a warning like this:
- @smallexample
- (@value{GDBP}) catch syscall
- warning: Could not open "syscalls/i386-linux.xml"
- warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
- GDB will not be able to display syscall names.
- Catchpoint 1 (syscall)
- (@value{GDBP})
- @end smallexample
- Of course, the file name will change depending on your architecture and system.
- Still using the example above, you can also try to catch a syscall by its
- number. In this case, you would see something like:
- @smallexample
- (@value{GDBP}) catch syscall 252
- Catchpoint 1 (syscall(s) 252)
- @end smallexample
- Again, in this case @value{GDBN} would not be able to display syscall's names.
- @item fork
- @kindex catch fork
- A call to @code{fork}.
- @item vfork
- @kindex catch vfork
- A call to @code{vfork}.
- @item load @r{[}@var{regexp}@r{]}
- @itemx unload @r{[}@var{regexp}@r{]}
- @kindex catch load
- @kindex catch unload
- The loading or unloading of a shared library. If @var{regexp} is
- given, then the catchpoint will stop only if the regular expression
- matches one of the affected libraries.
- @item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
- @kindex catch signal
- The delivery of a signal.
- With no arguments, this catchpoint will catch any signal that is not
- used internally by @value{GDBN}, specifically, all signals except
- @samp{SIGTRAP} and @samp{SIGINT}.
- With the argument @samp{all}, all signals, including those used by
- @value{GDBN}, will be caught. This argument cannot be used with other
- signal names.
- Otherwise, the arguments are a list of signal names as given to
- @code{handle} (@pxref{Signals}). Only signals specified in this list
- will be caught.
- One reason that @code{catch signal} can be more useful than
- @code{handle} is that you can attach commands and conditions to the
- catchpoint.
- When a signal is caught by a catchpoint, the signal's @code{stop} and
- @code{print} settings, as specified by @code{handle}, are ignored.
- However, whether the signal is still delivered to the inferior depends
- on the @code{pass} setting; this can be changed in the catchpoint's
- commands.
- @end table
- @item tcatch @var{event}
- @kindex tcatch
- Set a catchpoint that is enabled only for one stop. The catchpoint is
- automatically deleted after the first time the event is caught.
- @end table
- Use the @code{info break} command to list the current catchpoints.
- @node Delete Breaks
- @subsection Deleting Breakpoints
- @cindex clearing breakpoints, watchpoints, catchpoints
- @cindex deleting breakpoints, watchpoints, catchpoints
- It is often necessary to eliminate a breakpoint, watchpoint, or
- catchpoint once it has done its job and you no longer want your program
- to stop there. This is called @dfn{deleting} the breakpoint. A
- breakpoint that has been deleted no longer exists; it is forgotten.
- With the @code{clear} command you can delete breakpoints according to
- where they are in your program. With the @code{delete} command you can
- delete individual breakpoints, watchpoints, or catchpoints by specifying
- their breakpoint numbers.
- It is not necessary to delete a breakpoint to proceed past it. @value{GDBN}
- automatically ignores breakpoints on the first instruction to be executed
- when you continue execution without changing the execution address.
- @table @code
- @kindex clear
- @item clear
- Delete any breakpoints at the next instruction to be executed in the
- selected stack frame (@pxref{Selection, ,Selecting a Frame}). When
- the innermost frame is selected, this is a good way to delete a
- breakpoint where your program just stopped.
- @item clear @var{location}
- Delete any breakpoints set at the specified @var{location}.
- @xref{Specify Location}, for the various forms of @var{location}; the
- most useful ones are listed below:
- @table @code
- @item clear @var{function}
- @itemx clear @var{filename}:@var{function}
- Delete any breakpoints set at entry to the named @var{function}.
- @item clear @var{linenum}
- @itemx clear @var{filename}:@var{linenum}
- Delete any breakpoints set at or within the code of the specified
- @var{linenum} of the specified @var{filename}.
- @end table
- @cindex delete breakpoints
- @kindex delete
- @kindex d @r{(@code{delete})}
- @item delete @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
- Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
- list specified as argument. If no argument is specified, delete all
- breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
- confirm off}). You can abbreviate this command as @code{d}.
- @end table
- @node Disabling
- @subsection Disabling Breakpoints
- @cindex enable/disable a breakpoint
- Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
- prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
- it had been deleted, but remembers the information on the breakpoint so
- that you can @dfn{enable} it again later.
- You disable and enable breakpoints, watchpoints, and catchpoints with
- the @code{enable} and @code{disable} commands, optionally specifying
- one or more breakpoint numbers as arguments. Use @code{info break} to
- print a list of all breakpoints, watchpoints, and catchpoints if you
- do not know which numbers to use.
- Disabling and enabling a breakpoint that has multiple locations
- affects all of its locations.
- A breakpoint, watchpoint, or catchpoint can have any of several
- different states of enablement:
- @itemize @bullet
- @item
- Enabled. The breakpoint stops your program. A breakpoint set
- with the @code{break} command starts out in this state.
- @item
- Disabled. The breakpoint has no effect on your program.
- @item
- Enabled once. The breakpoint stops your program, but then becomes
- disabled.
- @item
- Enabled for a count. The breakpoint stops your program for the next
- N times, then becomes disabled.
- @item
- Enabled for deletion. The breakpoint stops your program, but
- immediately after it does so it is deleted permanently. A breakpoint
- set with the @code{tbreak} command starts out in this state.
- @end itemize
- You can use the following commands to enable or disable breakpoints,
- watchpoints, and catchpoints:
- @table @code
- @kindex disable
- @kindex dis @r{(@code{disable})}
- @item disable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
- Disable the specified breakpoints---or all breakpoints, if none are
- listed. A disabled breakpoint has no effect but is not forgotten. All
- options such as ignore-counts, conditions and commands are remembered in
- case the breakpoint is enabled again later. You may abbreviate
- @code{disable} as @code{dis}.
- @kindex enable
- @item enable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
- Enable the specified breakpoints (or all defined breakpoints). They
- become effective once again in stopping your program.
- @item enable @r{[}breakpoints@r{]} once @var{list}@dots{}
- Enable the specified breakpoints temporarily. @value{GDBN} disables any
- of these breakpoints immediately after stopping your program.
- @item enable @r{[}breakpoints@r{]} count @var{count} @var{list}@dots{}
- Enable the specified breakpoints temporarily. @value{GDBN} records
- @var{count} with each of the specified breakpoints, and decrements a
- breakpoint's count when it is hit. When any count reaches 0,
- @value{GDBN} disables that breakpoint. If a breakpoint has an ignore
- count (@pxref{Conditions, ,Break Conditions}), that will be
- decremented to 0 before @var{count} is affected.
- @item enable @r{[}breakpoints@r{]} delete @var{list}@dots{}
- Enable the specified breakpoints to work once, then die. @value{GDBN}
- deletes any of these breakpoints as soon as your program stops there.
- Breakpoints set by the @code{tbreak} command start out in this state.
- @end table
- @c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
- @c confusing: tbreak is also initially enabled.
- Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
- ,Setting Breakpoints}), breakpoints that you set are initially enabled;
- subsequently, they become disabled or enabled only when you use one of
- the commands above. (The command @code{until} can set and delete a
- breakpoint of its own, but it does not change the state of your other
- breakpoints; see @ref{Continuing and Stepping, ,Continuing and
- Stepping}.)
- @node Conditions
- @subsection Break Conditions
- @cindex conditional breakpoints
- @cindex breakpoint conditions
- @c FIXME what is scope of break condition expr? Context where wanted?
- @c in particular for a watchpoint?
- The simplest sort of breakpoint breaks every time your program reaches a
- specified place. You can also specify a @dfn{condition} for a
- breakpoint. A condition is just a Boolean expression in your
- programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
- a condition evaluates the expression each time your program reaches it,
- and your program stops only if the condition is @emph{true}.
- This is the converse of using assertions for program validation; in that
- situation, you want to stop when the assertion is violated---that is,
- when the condition is false. In C, if you want to test an assertion expressed
- by the condition @var{assert}, you should set the condition
- @samp{! @var{assert}} on the appropriate breakpoint.
- Conditions are also accepted for watchpoints; you may not need them,
- since a watchpoint is inspecting the value of an expression anyhow---but
- it might be simpler, say, to just set a watchpoint on a variable name,
- and specify a condition that tests whether the new value is an interesting
- one.
- Break conditions can have side effects, and may even call functions in
- your program. This can be useful, for example, to activate functions
- that log program progress, or to use your own print functions to
- format special data structures. The effects are completely predictable
- unless there is another enabled breakpoint at the same address. (In
- that case, @value{GDBN} might see the other breakpoint first and stop your
- program without checking the condition of this one.) Note that
- breakpoint commands are usually more convenient and flexible than break
- conditions for the
- purpose of performing side effects when a breakpoint is reached
- (@pxref{Break Commands, ,Breakpoint Command Lists}).
- Breakpoint conditions can also be evaluated on the target's side if
- the target supports it. Instead of evaluating the conditions locally,
- @value{GDBN} encodes the expression into an agent expression
- (@pxref{Agent Expressions}) suitable for execution on the target,
- independently of @value{GDBN}. Global variables become raw memory
- locations, locals become stack accesses, and so forth.
- In this case, @value{GDBN} will only be notified of a breakpoint trigger
- when its condition evaluates to true. This mechanism may provide faster
- response times depending on the performance characteristics of the target
- since it does not need to keep @value{GDBN} informed about
- every breakpoint trigger, even those with false conditions.
- Break conditions can be specified when a breakpoint is set, by using
- @samp{if} in the arguments to the @code{break} command. @xref{Set
- Breaks, ,Setting Breakpoints}. They can also be changed at any time
- with the @code{condition} command.
- You can also use the @code{if} keyword with the @code{watch} command.
- The @code{catch} command does not recognize the @code{if} keyword;
- @code{condition} is the only way to impose a further condition on a
- catchpoint.
- @table @code
- @kindex condition
- @item condition @var{bnum} @var{expression}
- Specify @var{expression} as the break condition for breakpoint,
- watchpoint, or catchpoint number @var{bnum}. After you set a condition,
- breakpoint @var{bnum} stops your program only if the value of
- @var{expression} is true (nonzero, in C). When you use
- @code{condition}, @value{GDBN} checks @var{expression} immediately for
- syntactic correctness, and to determine whether symbols in it have
- referents in the context of your breakpoint. If @var{expression} uses
- symbols not referenced in the context of the breakpoint, @value{GDBN}
- prints an error message:
- @smallexample
- No symbol "foo" in current context.
- @end smallexample
- @noindent
- @value{GDBN} does
- not actually evaluate @var{expression} at the time the @code{condition}
- command (or a command that sets a breakpoint with a condition, like
- @code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}.
- @item condition -force @var{bnum} @var{expression}
- When the @code{-force} flag is used, define the condition even if
- @var{expression} is invalid at all the current locations of breakpoint
- @var{bnum}. This is similar to the @code{-force-condition} option
- of the @code{break} command.
- @item condition @var{bnum}
- Remove the condition from breakpoint number @var{bnum}. It becomes
- an ordinary unconditional breakpoint.
- @end table
- @cindex ignore count (of breakpoint)
- A special case of a breakpoint condition is to stop only when the
- breakpoint has been reached a certain number of times. This is so
- useful that there is a special way to do it, using the @dfn{ignore
- count} of the breakpoint. Every breakpoint has an ignore count, which
- is an integer. Most of the time, the ignore count is zero, and
- therefore has no effect. But if your program reaches a breakpoint whose
- ignore count is positive, then instead of stopping, it just decrements
- the ignore count by one and continues. As a result, if the ignore count
- value is @var{n}, the breakpoint does not stop the next @var{n} times
- your program reaches it.
- @table @code
- @kindex ignore
- @item ignore @var{bnum} @var{count}
- Set the ignore count of breakpoint number @var{bnum} to @var{count}.
- The next @var{count} times the breakpoint is reached, your program's
- execution does not stop; other than to decrement the ignore count, @value{GDBN}
- takes no action.
- To make the breakpoint stop the next time it is reached, specify
- a count of zero.
- When you use @code{continue} to resume execution of your program from a
- breakpoint, you can specify an ignore count directly as an argument to
- @code{continue}, rather than using @code{ignore}. @xref{Continuing and
- Stepping,,Continuing and Stepping}.
- If a breakpoint has a positive ignore count and a condition, the
- condition is not checked. Once the ignore count reaches zero,
- @value{GDBN} resumes checking the condition.
- You could achieve the effect of the ignore count with a condition such
- as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
- is decremented each time. @xref{Convenience Vars, ,Convenience
- Variables}.
- @end table
- Ignore counts apply to breakpoints, watchpoints, and catchpoints.
- @node Break Commands
- @subsection Breakpoint Command Lists
- @cindex breakpoint commands
- You can give any breakpoint (or watchpoint or catchpoint) a series of
- commands to execute when your program stops due to that breakpoint. For
- example, you might want to print the values of certain expressions, or
- enable other breakpoints.
- @table @code
- @kindex commands
- @kindex end@r{ (breakpoint commands)}
- @item commands @r{[}@var{list}@dots{}@r{]}
- @itemx @dots{} @var{command-list} @dots{}
- @itemx end
- Specify a list of commands for the given breakpoints. The commands
- themselves appear on the following lines. Type a line containing just
- @code{end} to terminate the commands.
- To remove all commands from a breakpoint, type @code{commands} and
- follow it immediately with @code{end}; that is, give no commands.
- With no argument, @code{commands} refers to the last breakpoint,
- watchpoint, or catchpoint set (not to the breakpoint most recently
- encountered). If the most recent breakpoints were set with a single
- command, then the @code{commands} will apply to all the breakpoints
- set by that command. This applies to breakpoints set by
- @code{rbreak}, and also applies when a single @code{break} command
- creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous
- Expressions}).
- @end table
- Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
- disabled within a @var{command-list}.
- You can use breakpoint commands to start your program up again. Simply
- use the @code{continue} command, or @code{step}, or any other command
- that resumes execution.
- Any other commands in the command list, after a command that resumes
- execution, are ignored. This is because any time you resume execution
- (even with a simple @code{next} or @code{step}), you may encounter
- another breakpoint---which could have its own command list, leading to
- ambiguities about which list to execute.
- @kindex silent
- If the first command you specify in a command list is @code{silent}, the
- usual message about stopping at a breakpoint is not printed. This may
- be desirable for breakpoints that are to print a specific message and
- then continue. If none of the remaining commands print anything, you
- see no sign that the breakpoint was reached. @code{silent} is
- meaningful only at the beginning of a breakpoint command list.
- The commands @code{echo}, @code{output}, and @code{printf} allow you to
- print precisely controlled output, and are often useful in silent
- breakpoints. @xref{Output, ,Commands for Controlled Output}.
- For example, here is how you could use breakpoint commands to print the
- value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
- @smallexample
- break foo if x>0
- commands
- silent
- printf "x is %d\n",x
- cont
- end
- @end smallexample
- One application for breakpoint commands is to compensate for one bug so
- you can test for another. Put a breakpoint just after the erroneous line
- of code, give it a condition to detect the case in which something
- erroneous has been done, and give it commands to assign correct values
- to any variables that need them. End with the @code{continue} command
- so that your program does not stop, and start with the @code{silent}
- command so that no output is produced. Here is an example:
- @smallexample
- break 403
- commands
- silent
- set x = y + 4
- cont
- end
- @end smallexample
- @node Dynamic Printf
- @subsection Dynamic Printf
- @cindex dynamic printf
- @cindex dprintf
- The dynamic printf command @code{dprintf} combines a breakpoint with
- formatted printing of your program's data to give you the effect of
- inserting @code{printf} calls into your program on-the-fly, without
- having to recompile it.
- In its most basic form, the output goes to the GDB console. However,
- you can set the variable @code{dprintf-style} for alternate handling.
- For instance, you can ask to format the output by calling your
- program's @code{printf} function. This has the advantage that the
- characters go to the program's output device, so they can recorded in
- redirects to files and so forth.
- If you are doing remote debugging with a stub or agent, you can also
- ask to have the printf handled by the remote agent. In addition to
- ensuring that the output goes to the remote program's device along
- with any other output the program might produce, you can also ask that
- the dprintf remain active even after disconnecting from the remote
- target. Using the stub/agent is also more efficient, as it can do
- everything without needing to communicate with @value{GDBN}.
- @table @code
- @kindex dprintf
- @item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}]
- Whenever execution reaches @var{location}, print the values of one or
- more @var{expressions} under the control of the string @var{template}.
- To print several values, separate them with commas.
- @item set dprintf-style @var{style}
- Set the dprintf output to be handled in one of several different
- styles enumerated below. A change of style affects all existing
- dynamic printfs immediately. (If you need individual control over the
- print commands, simply define normal breakpoints with
- explicitly-supplied command lists.)
- @table @code
- @item gdb
- @kindex dprintf-style gdb
- Handle the output using the @value{GDBN} @code{printf} command.
- @item call
- @kindex dprintf-style call
- Handle the output by calling a function in your program (normally
- @code{printf}).
- @item agent
- @kindex dprintf-style agent
- Have the remote debugging agent (such as @code{gdbserver}) handle
- the output itself. This style is only available for agents that
- support running commands on the target.
- @end table
- @item set dprintf-function @var{function}
- Set the function to call if the dprintf style is @code{call}. By
- default its value is @code{printf}. You may set it to any expression.
- that @value{GDBN} can evaluate to a function, as per the @code{call}
- command.
- @item set dprintf-channel @var{channel}
- Set a ``channel'' for dprintf. If set to a non-empty value,
- @value{GDBN} will evaluate it as an expression and pass the result as
- a first argument to the @code{dprintf-function}, in the manner of
- @code{fprintf} and similar functions. Otherwise, the dprintf format
- string will be the first argument, in the manner of @code{printf}.
- As an example, if you wanted @code{dprintf} output to go to a logfile
- that is a standard I/O stream assigned to the variable @code{mylog},
- you could do the following:
- @example
- (gdb) set dprintf-style call
- (gdb) set dprintf-function fprintf
- (gdb) set dprintf-channel mylog
- (gdb) dprintf 25,"at line 25, glob=%d\n",glob
- Dprintf 1 at 0x123456: file main.c, line 25.
- (gdb) info break
- 1 dprintf keep y 0x00123456 in main at main.c:25
- call (void) fprintf (mylog,"at line 25, glob=%d\n",glob)
- continue
- (gdb)
- @end example
- Note that the @code{info break} displays the dynamic printf commands
- as normal breakpoint commands; you can thus easily see the effect of
- the variable settings.
- @item set disconnected-dprintf on
- @itemx set disconnected-dprintf off
- @kindex set disconnected-dprintf
- Choose whether @code{dprintf} commands should continue to run if
- @value{GDBN} has disconnected from the target. This only applies
- if the @code{dprintf-style} is @code{agent}.
- @item show disconnected-dprintf off
- @kindex show disconnected-dprintf
- Show the current choice for disconnected @code{dprintf}.
- @end table
- @value{GDBN} does not check the validity of function and channel,
- relying on you to supply values that are meaningful for the contexts
- in which they are being used. For instance, the function and channel
- may be the values of local variables, but if that is the case, then
- all enabled dynamic prints must be at locations within the scope of
- those locals. If evaluation fails, @value{GDBN} will report an error.
- @node Save Breakpoints
- @subsection How to save breakpoints to a file
- To save breakpoint definitions to a file use the @w{@code{save
- breakpoints}} command.
- @table @code
- @kindex save breakpoints
- @cindex save breakpoints to a file for future sessions
- @item save breakpoints [@var{filename}]
- This command saves all current breakpoint definitions together with
- their commands and ignore counts, into a file @file{@var{filename}}
- suitable for use in a later debugging session. This includes all
- types of breakpoints (breakpoints, watchpoints, catchpoints,
- tracepoints). To read the saved breakpoint definitions, use the
- @code{source} command (@pxref{Command Files}). Note that watchpoints
- with expressions involving local variables may fail to be recreated
- because it may not be possible to access the context where the
- watchpoint is valid anymore. Because the saved breakpoint definitions
- are simply a sequence of @value{GDBN} commands that recreate the
- breakpoints, you can edit the file in your favorite editing program,
- and remove the breakpoint definitions you're not interested in, or
- that can no longer be recreated.
- @end table
- @node Static Probe Points
- @subsection Static Probe Points
- @cindex static probe point, SystemTap
- @cindex static probe point, DTrace
- @value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands
- for Statically Defined Tracing, and the probes are designed to have a tiny
- runtime code and data footprint, and no dynamic relocations.
- Currently, the following types of probes are supported on
- ELF-compatible systems:
- @itemize @bullet
- @item @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
- @acronym{SDT} probes@footnote{See
- @uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
- for more information on how to add @code{SystemTap} @acronym{SDT}
- probes in your applications.}. @code{SystemTap} probes are usable
- from assembly, C and C@t{++} languages@footnote{See
- @uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
- for a good reference on how the @acronym{SDT} probes are implemented.}.
- @item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace})
- @acronym{USDT} probes. @code{DTrace} probes are usable from C and
- C@t{++} languages.
- @end itemize
- @cindex semaphores on static probe points
- Some @code{SystemTap} probes have an associated semaphore variable;
- for instance, this happens automatically if you defined your probe
- using a DTrace-style @file{.d} file. If your probe has a semaphore,
- @value{GDBN} will automatically enable it when you specify a
- breakpoint using the @samp{-probe-stap} notation. But, if you put a
- breakpoint at a probe's location by some other method (e.g.,
- @code{break file:line}), then @value{GDBN} will not automatically set
- the semaphore. @code{DTrace} probes do not support semaphores.
- You can examine the available static static probes using @code{info
- probes}, with optional arguments:
- @table @code
- @kindex info probes
- @item info probes @r{[}@var{type}@r{]} @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
- If given, @var{type} is either @code{stap} for listing
- @code{SystemTap} probes or @code{dtrace} for listing @code{DTrace}
- probes. If omitted all probes are listed regardless of their types.
- If given, @var{provider} is a regular expression used to match against provider
- names when selecting which probes to list. If omitted, probes by all
- probes from all providers are listed.
- If given, @var{name} is a regular expression to match against probe names
- when selecting which probes to list. If omitted, probe names are not
- considered when deciding whether to display them.
- If given, @var{objfile} is a regular expression used to select which
- object files (executable or shared libraries) to examine. If not
- given, all object files are considered.
- @item info probes all
- List the available static probes, from all types.
- @end table
- @cindex enabling and disabling probes
- Some probe points can be enabled and/or disabled. The effect of
- enabling or disabling a probe depends on the type of probe being
- handled. Some @code{DTrace} probes can be enabled or
- disabled, but @code{SystemTap} probes cannot be disabled.
- You can enable (or disable) one or more probes using the following
- commands, with optional arguments:
- @table @code
- @kindex enable probes
- @item enable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
- If given, @var{provider} is a regular expression used to match against
- provider names when selecting which probes to enable. If omitted,
- all probes from all providers are enabled.
- If given, @var{name} is a regular expression to match against probe
- names when selecting which probes to enable. If omitted, probe names
- are not considered when deciding whether to enable them.
- If given, @var{objfile} is a regular expression used to select which
- object files (executable or shared libraries) to examine. If not
- given, all object files are considered.
- @kindex disable probes
- @item disable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
- See the @code{enable probes} command above for a description of the
- optional arguments accepted by this command.
- @end table
- @vindex $_probe_arg@r{, convenience variable}
- A probe may specify up to twelve arguments. These are available at the
- point at which the probe is defined---that is, when the current PC is
- at the probe's location. The arguments are available using the
- convenience variables (@pxref{Convenience Vars})
- @code{$_probe_arg0}@dots{}@code{$_probe_arg11}. In @code{SystemTap}
- probes each probe argument is an integer of the appropriate size;
- types are not preserved. In @code{DTrace} probes types are preserved
- provided that they are recognized as such by @value{GDBN}; otherwise
- the value of the probe argument will be a long integer. The
- convenience variable @code{$_probe_argc} holds the number of arguments
- at the current probe point.
- These variables are always available, but attempts to access them at
- any location other than a probe point will cause @value{GDBN} to give
- an error message.
- @c @ifclear BARETARGET
- @node Error in Breakpoints
- @subsection ``Cannot insert breakpoints''
- If you request too many active hardware-assisted breakpoints and
- watchpoints, you will see this error message:
- @c FIXME: the precise wording of this message may change; the relevant
- @c source change is not committed yet (Sep 3, 1999).
- @smallexample
- Stopped; cannot insert breakpoints.
- You may have requested too many hardware breakpoints and watchpoints.
- @end smallexample
- @noindent
- This message is printed when you attempt to resume the program, since
- only then @value{GDBN} knows exactly how many hardware breakpoints and
- watchpoints it needs to insert.
- When this message is printed, you need to disable or remove some of the
- hardware-assisted breakpoints and watchpoints, and then continue.
- @node Breakpoint-related Warnings
- @subsection ``Breakpoint address adjusted...''
- @cindex breakpoint address adjusted
- Some processor architectures place constraints on the addresses at
- which breakpoints may be placed. For architectures thus constrained,
- @value{GDBN} will attempt to adjust the breakpoint's address to comply
- with the constraints dictated by the architecture.
- One example of such an architecture is the Fujitsu FR-V. The FR-V is
- a VLIW architecture in which a number of RISC-like instructions may be
- bundled together for parallel execution. The FR-V architecture
- constrains the location of a breakpoint instruction within such a
- bundle to the instruction with the lowest address. @value{GDBN}
- honors this constraint by adjusting a breakpoint's address to the
- first in the bundle.
- It is not uncommon for optimized code to have bundles which contain
- instructions from different source statements, thus it may happen that
- a breakpoint's address will be adjusted from one source statement to
- another. Since this adjustment may significantly alter @value{GDBN}'s
- breakpoint related behavior from what the user expects, a warning is
- printed when the breakpoint is first set and also when the breakpoint
- is hit.
- A warning like the one below is printed when setting a breakpoint
- that's been subject to address adjustment:
- @smallexample
- warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
- @end smallexample
- Such warnings are printed both for user settable and @value{GDBN}'s
- internal breakpoints. If you see one of these warnings, you should
- verify that a breakpoint set at the adjusted address will have the
- desired affect. If not, the breakpoint in question may be removed and
- other breakpoints may be set which will have the desired behavior.
- E.g., it may be sufficient to place the breakpoint at a later
- instruction. A conditional breakpoint may also be useful in some
- cases to prevent the breakpoint from triggering too often.
- @value{GDBN} will also issue a warning when stopping at one of these
- adjusted breakpoints:
- @smallexample
- warning: Breakpoint 1 address previously adjusted from 0x00010414
- to 0x00010410.
- @end smallexample
- When this warning is encountered, it may be too late to take remedial
- action except in cases where the breakpoint is hit earlier or more
- frequently than expected.
- @node Continuing and Stepping
- @section Continuing and Stepping
- @cindex stepping
- @cindex continuing
- @cindex resuming execution
- @dfn{Continuing} means resuming program execution until your program
- completes normally. In contrast, @dfn{stepping} means executing just
- one more ``step'' of your program, where ``step'' may mean either one
- line of source code, or one machine instruction (depending on what
- particular command you use). Either when continuing or when stepping,
- your program may stop even sooner, due to a breakpoint or a signal. (If
- it stops due to a signal, you may want to use @code{handle}, or use
- @samp{signal 0} to resume execution (@pxref{Signals, ,Signals}),
- or you may step into the signal's handler (@pxref{stepping and signal
- handlers}).)
- @table @code
- @kindex continue
- @kindex c @r{(@code{continue})}
- @kindex fg @r{(resume foreground execution)}
- @item continue @r{[}@var{ignore-count}@r{]}
- @itemx c @r{[}@var{ignore-count}@r{]}
- @itemx fg @r{[}@var{ignore-count}@r{]}
- Resume program execution, at the address where your program last stopped;
- any breakpoints set at that address are bypassed. The optional argument
- @var{ignore-count} allows you to specify a further number of times to
- ignore a breakpoint at this location; its effect is like that of
- @code{ignore} (@pxref{Conditions, ,Break Conditions}).
- The argument @var{ignore-count} is meaningful only when your program
- stopped due to a breakpoint. At other times, the argument to
- @code{continue} is ignored.
- The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the
- debugged program is deemed to be the foreground program) are provided
- purely for convenience, and have exactly the same behavior as
- @code{continue}.
- @end table
- To resume execution at a different place, you can use @code{return}
- (@pxref{Returning, ,Returning from a Function}) to go back to the
- calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
- Different Address}) to go to an arbitrary location in your program.
- A typical technique for using stepping is to set a breakpoint
- (@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the
- beginning of the function or the section of your program where a problem
- is believed to lie, run your program until it stops at that breakpoint,
- and then step through the suspect area, examining the variables that are
- interesting, until you see the problem happen.
- @table @code
- @kindex step
- @kindex s @r{(@code{step})}
- @item step
- Continue running your program until control reaches a different source
- line, then stop it and return control to @value{GDBN}. This command is
- abbreviated @code{s}.
- @quotation
- @c "without debugging information" is imprecise; actually "without line
- @c numbers in the debugging information". (gcc -g1 has debugging info but
- @c not line numbers). But it seems complex to try to make that
- @c distinction here.
- @emph{Warning:} If you use the @code{step} command while control is
- within a function that was compiled without debugging information,
- execution proceeds until control reaches a function that does have
- debugging information. Likewise, it will not step into a function which
- is compiled without debugging information. To step through functions
- without debugging information, use the @code{stepi} command, described
- below.
- @end quotation
- The @code{step} command only stops at the first instruction of a source
- line. This prevents the multiple stops that could otherwise occur in
- @code{switch} statements, @code{for} loops, etc. @code{step} continues
- to stop if a function that has debugging information is called within
- the line. In other words, @code{step} @emph{steps inside} any functions
- called within the line.
- Also, the @code{step} command only enters a function if there is line
- number information for the function. Otherwise it acts like the
- @code{next} command. This avoids problems when using @code{cc -gl}
- on @acronym{MIPS} machines. Previously, @code{step} entered subroutines if there
- was any debugging information about the routine.
- @item step @var{count}
- Continue running as in @code{step}, but do so @var{count} times. If a
- breakpoint is reached, or a signal not related to stepping occurs before
- @var{count} steps, stepping stops right away.
- @kindex next
- @kindex n @r{(@code{next})}
- @item next @r{[}@var{count}@r{]}
- Continue to the next source line in the current (innermost) stack frame.
- This is similar to @code{step}, but function calls that appear within
- the line of code are executed without stopping. Execution stops when
- control reaches a different line of code at the original stack level
- that was executing when you gave the @code{next} command. This command
- is abbreviated @code{n}.
- An argument @var{count} is a repeat count, as for @code{step}.
- @c FIX ME!! Do we delete this, or is there a way it fits in with
- @c the following paragraph? --- Vctoria
- @c
- @c @code{next} within a function that lacks debugging information acts like
- @c @code{step}, but any function calls appearing within the code of the
- @c function are executed without stopping.
- The @code{next} command only stops at the first instruction of a
- source line. This prevents multiple stops that could otherwise occur in
- @code{switch} statements, @code{for} loops, etc.
- @kindex set step-mode
- @item set step-mode
- @cindex functions without line info, and stepping
- @cindex stepping into functions with no line info
- @itemx set step-mode on
- The @code{set step-mode on} command causes the @code{step} command to
- stop at the first instruction of a function which contains no debug line
- information rather than stepping over it.
- This is useful in cases where you may be interested in inspecting the
- machine instructions of a function which has no symbolic info and do not
- want @value{GDBN} to automatically skip over this function.
- @item set step-mode off
- Causes the @code{step} command to step over any functions which contains no
- debug information. This is the default.
- @item show step-mode
- Show whether @value{GDBN} will stop in or step over functions without
- source line debug information.
- @kindex finish
- @kindex fin @r{(@code{finish})}
- @item finish
- Continue running until just after function in the selected stack frame
- returns. Print the returned value (if any). This command can be
- abbreviated as @code{fin}.
- Contrast this with the @code{return} command (@pxref{Returning,
- ,Returning from a Function}).
- @kindex set print finish
- @kindex show print finish
- @item set print finish @r{[}on|off@r{]}
- @itemx show print finish
- By default the @code{finish} command will show the value that is
- returned by the function. This can be disabled using @code{set print
- finish off}. When disabled, the value is still entered into the value
- history (@pxref{Value History}), but not displayed.
- @kindex until
- @kindex u @r{(@code{until})}
- @cindex run until specified location
- @item until
- @itemx u
- Continue running until a source line past the current line, in the
- current stack frame, is reached. This command is used to avoid single
- stepping through a loop more than once. It is like the @code{next}
- command, except that when @code{until} encounters a jump, it
- automatically continues execution until the program counter is greater
- than the address of the jump.
- This means that when you reach the end of a loop after single stepping
- though it, @code{until} makes your program continue execution until it
- exits the loop. In contrast, a @code{next} command at the end of a loop
- simply steps back to the beginning of the loop, which forces you to step
- through the next iteration.
- @code{until} always stops your program if it attempts to exit the current
- stack frame.
- @code{until} may produce somewhat counterintuitive results if the order
- of machine code does not match the order of the source lines. For
- example, in the following excerpt from a debugging session, the @code{f}
- (@code{frame}) command shows that execution is stopped at line
- @code{206}; yet when we use @code{until}, we get to line @code{195}:
- @smallexample
- (@value{GDBP}) f
- #0 main (argc=4, argv=0xf7fffae8) at m4.c:206
- 206 expand_input();
- (@value{GDBP}) until
- 195 for ( ; argc > 0; NEXTARG) @{
- @end smallexample
- This happened because, for execution efficiency, the compiler had
- generated code for the loop closure test at the end, rather than the
- start, of the loop---even though the test in a C @code{for}-loop is
- written before the body of the loop. The @code{until} command appeared
- to step back to the beginning of the loop when it advanced to this
- expression; however, it has not really gone to an earlier
- statement---not in terms of the actual machine code.
- @code{until} with no argument works by means of single
- instruction stepping, and hence is slower than @code{until} with an
- argument.
- @item until @var{location}
- @itemx u @var{location}
- Continue running your program until either the specified @var{location} is
- reached, or the current stack frame returns. The location is any of
- the forms described in @ref{Specify Location}.
- This form of the command uses temporary breakpoints, and
- hence is quicker than @code{until} without an argument. The specified
- location is actually reached only if it is in the current frame. This
- implies that @code{until} can be used to skip over recursive function
- invocations. For instance in the code below, if the current location is
- line @code{96}, issuing @code{until 99} will execute the program up to
- line @code{99} in the same invocation of factorial, i.e., after the inner
- invocations have returned.
- @smallexample
- 94 int factorial (int value)
- 95 @{
- 96 if (value > 1) @{
- 97 value *= factorial (value - 1);
- 98 @}
- 99 return (value);
- 100 @}
- @end smallexample
- @kindex advance @var{location}
- @item advance @var{location}
- Continue running the program up to the given @var{location}. An argument is
- required, which should be of one of the forms described in
- @ref{Specify Location}.
- Execution will also stop upon exit from the current stack
- frame. This command is similar to @code{until}, but @code{advance} will
- not skip over recursive function calls, and the target location doesn't
- have to be in the same frame as the current one.
- @kindex stepi
- @kindex si @r{(@code{stepi})}
- @item stepi
- @itemx stepi @var{arg}
- @itemx si
- Execute one machine instruction, then stop and return to the debugger.
- It is often useful to do @samp{display/i $pc} when stepping by machine
- instructions. This makes @value{GDBN} automatically display the next
- instruction to be executed, each time your program stops. @xref{Auto
- Display,, Automatic Display}.
- An argument is a repeat count, as in @code{step}.
- @need 750
- @kindex nexti
- @kindex ni @r{(@code{nexti})}
- @item nexti
- @itemx nexti @var{arg}
- @itemx ni
- Execute one machine instruction, but if it is a function call,
- proceed until the function returns.
- An argument is a repeat count, as in @code{next}.
- @end table
- @anchor{range stepping}
- @cindex range stepping
- @cindex target-assisted range stepping
- By default, and if available, @value{GDBN} makes use of
- target-assisted @dfn{range stepping}. In other words, whenever you
- use a stepping command (e.g., @code{step}, @code{next}), @value{GDBN}
- tells the target to step the corresponding range of instruction
- addresses instead of issuing multiple single-steps. This speeds up
- line stepping, particularly for remote targets. Ideally, there should
- be no reason you would want to turn range stepping off. However, it's
- possible that a bug in the debug info, a bug in the remote stub (for
- remote targets), or even a bug in @value{GDBN} could make line
- stepping behave incorrectly when target-assisted range stepping is
- enabled. You can use the following command to turn off range stepping
- if necessary:
- @table @code
- @kindex set range-stepping
- @kindex show range-stepping
- @item set range-stepping
- @itemx show range-stepping
- Control whether range stepping is enabled.
- If @code{on}, and the target supports it, @value{GDBN} tells the
- target to step a range of addresses itself, instead of issuing
- multiple single-steps. If @code{off}, @value{GDBN} always issues
- single-steps, even if range stepping is supported by the target. The
- default is @code{on}.
- @end table
- @node Skipping Over Functions and Files
- @section Skipping Over Functions and Files
- @cindex skipping over functions and files
- The program you are debugging may contain some functions which are
- uninteresting to debug. The @code{skip} command lets you tell @value{GDBN} to
- skip a function, all functions in a file or a particular function in
- a particular file when stepping.
- For example, consider the following C function:
- @smallexample
- 101 int func()
- 102 @{
- 103 foo(boring());
- 104 bar(boring());
- 105 @}
- @end smallexample
- @noindent
- Suppose you wish to step into the functions @code{foo} and @code{bar}, but you
- are not interested in stepping through @code{boring}. If you run @code{step}
- at line 103, you'll enter @code{boring()}, but if you run @code{next}, you'll
- step over both @code{foo} and @code{boring}!
- One solution is to @code{step} into @code{boring} and use the @code{finish}
- command to immediately exit it. But this can become tedious if @code{boring}
- is called from many places.
- A more flexible solution is to execute @kbd{skip boring}. This instructs
- @value{GDBN} never to step into @code{boring}. Now when you execute
- @code{step} at line 103, you'll step over @code{boring} and directly into
- @code{foo}.
- Functions may be skipped by providing either a function name, linespec
- (@pxref{Specify Location}), regular expression that matches the function's
- name, file name or a @code{glob}-style pattern that matches the file name.
- On Posix systems the form of the regular expression is
- ``Extended Regular Expressions''. See for example @samp{man 7 regex}
- on @sc{gnu}/Linux systems. On non-Posix systems the form of the regular
- expression is whatever is provided by the @code{regcomp} function of
- the underlying system.
- See for example @samp{man 7 glob} on @sc{gnu}/Linux systems for a
- description of @code{glob}-style patterns.
- @table @code
- @kindex skip
- @item skip @r{[}@var{options}@r{]}
- The basic form of the @code{skip} command takes zero or more options
- that specify what to skip.
- The @var{options} argument is any useful combination of the following:
- @table @code
- @item -file @var{file}
- @itemx -fi @var{file}
- Functions in @var{file} will be skipped over when stepping.
- @item -gfile @var{file-glob-pattern}
- @itemx -gfi @var{file-glob-pattern}
- @cindex skipping over files via glob-style patterns
- Functions in files matching @var{file-glob-pattern} will be skipped
- over when stepping.
- @smallexample
- (gdb) skip -gfi utils/*.c
- @end smallexample
- @item -function @var{linespec}
- @itemx -fu @var{linespec}
- Functions named by @var{linespec} or the function containing the line
- named by @var{linespec} will be skipped over when stepping.
- @xref{Specify Location}.
- @item -rfunction @var{regexp}
- @itemx -rfu @var{regexp}
- @cindex skipping over functions via regular expressions
- Functions whose name matches @var{regexp} will be skipped over when stepping.
- This form is useful for complex function names.
- For example, there is generally no need to step into C@t{++} @code{std::string}
- constructors or destructors. Plus with C@t{++} templates it can be hard to
- write out the full name of the function, and often it doesn't matter what
- the template arguments are. Specifying the function to be skipped as a
- regular expression makes this easier.
- @smallexample
- (gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(
- @end smallexample
- If you want to skip every templated C@t{++} constructor and destructor
- in the @code{std} namespace you can do:
- @smallexample
- (gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(
- @end smallexample
- @end table
- If no options are specified, the function you're currently debugging
- will be skipped.
- @kindex skip function
- @item skip function @r{[}@var{linespec}@r{]}
- After running this command, the function named by @var{linespec} or the
- function containing the line named by @var{linespec} will be skipped over when
- stepping. @xref{Specify Location}.
- If you do not specify @var{linespec}, the function you're currently debugging
- will be skipped.
- (If you have a function called @code{file} that you want to skip, use
- @kbd{skip function file}.)
- @kindex skip file
- @item skip file @r{[}@var{filename}@r{]}
- After running this command, any function whose source lives in @var{filename}
- will be skipped over when stepping.
- @smallexample
- (gdb) skip file boring.c
- File boring.c will be skipped when stepping.
- @end smallexample
- If you do not specify @var{filename}, functions whose source lives in the file
- you're currently debugging will be skipped.
- @end table
- Skips can be listed, deleted, disabled, and enabled, much like breakpoints.
- These are the commands for managing your list of skips:
- @table @code
- @kindex info skip
- @item info skip @r{[}@var{range}@r{]}
- Print details about the specified skip(s). If @var{range} is not specified,
- print a table with details about all functions and files marked for skipping.
- @code{info skip} prints the following information about each skip:
- @table @emph
- @item Identifier
- A number identifying this skip.
- @item Enabled or Disabled
- Enabled skips are marked with @samp{y}.
- Disabled skips are marked with @samp{n}.
- @item Glob
- If the file name is a @samp{glob} pattern this is @samp{y}.
- Otherwise it is @samp{n}.
- @item File
- The name or @samp{glob} pattern of the file to be skipped.
- If no file is specified this is @samp{<none>}.
- @item RE
- If the function name is a @samp{regular expression} this is @samp{y}.
- Otherwise it is @samp{n}.
- @item Function
- The name or regular expression of the function to skip.
- If no function is specified this is @samp{<none>}.
- @end table
- @kindex skip delete
- @item skip delete @r{[}@var{range}@r{]}
- Delete the specified skip(s). If @var{range} is not specified, delete all
- skips.
- @kindex skip enable
- @item skip enable @r{[}@var{range}@r{]}
- Enable the specified skip(s). If @var{range} is not specified, enable all
- skips.
- @kindex skip disable
- @item skip disable @r{[}@var{range}@r{]}
- Disable the specified skip(s). If @var{range} is not specified, disable all
- skips.
- @kindex set debug skip
- @item set debug skip @r{[}on|off@r{]}
- Set whether to print the debug output about skipping files and functions.
- @kindex show debug skip
- @item show debug skip
- Show whether the debug output about skipping files and functions is printed.
- @end table
- @node Signals
- @section Signals
- @cindex signals
- A signal is an asynchronous event that can happen in a program. The
- operating system defines the possible kinds of signals, and gives each
- kind a name and a number. For example, in Unix @code{SIGINT} is the
- signal a program gets when you type an interrupt character (often @kbd{Ctrl-c});
- @code{SIGSEGV} is the signal a program gets from referencing a place in
- memory far away from all the areas in use; @code{SIGALRM} occurs when
- the alarm clock timer goes off (which happens only if your program has
- requested an alarm).
- @cindex fatal signals
- Some signals, including @code{SIGALRM}, are a normal part of the
- functioning of your program. Others, such as @code{SIGSEGV}, indicate
- errors; these signals are @dfn{fatal} (they kill your program immediately) if the
- program has not specified in advance some other way to handle the signal.
- @code{SIGINT} does not indicate an error in your program, but it is normally
- fatal so it can carry out the purpose of the interrupt: to kill the program.
- @value{GDBN} has the ability to detect any occurrence of a signal in your
- program. You can tell @value{GDBN} in advance what to do for each kind of
- signal.
- @cindex handling signals
- Normally, @value{GDBN} is set up to let the non-erroneous signals like
- @code{SIGALRM} be silently passed to your program
- (so as not to interfere with their role in the program's functioning)
- but to stop your program immediately whenever an error signal happens.
- You can change these settings with the @code{handle} command.
- @table @code
- @kindex info signals
- @kindex info handle
- @item info signals
- @itemx info handle
- Print a table of all the kinds of signals and how @value{GDBN} has been told to
- handle each one. You can use this to see the signal numbers of all
- the defined types of signals.
- @item info signals @var{sig}
- Similar, but print information only about the specified signal number.
- @code{info handle} is an alias for @code{info signals}.
- @item catch signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
- Set a catchpoint for the indicated signals. @xref{Set Catchpoints},
- for details about this command.
- @kindex handle
- @item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
- Change the way @value{GDBN} handles signal @var{signal}. The @var{signal}
- can be the number of a signal or its name (with or without the
- @samp{SIG} at the beginning); a list of signal numbers of the form
- @samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
- known signals. Optional arguments @var{keywords}, described below,
- say what change to make.
- @end table
- @c @group
- The keywords allowed by the @code{handle} command can be abbreviated.
- Their full names are:
- @table @code
- @item nostop
- @value{GDBN} should not stop your program when this signal happens. It may
- still print a message telling you that the signal has come in.
- @item stop
- @value{GDBN} should stop your program when this signal happens. This implies
- the @code{print} keyword as well.
- @item print
- @value{GDBN} should print a message when this signal happens.
- @item noprint
- @value{GDBN} should not mention the occurrence of the signal at all. This
- implies the @code{nostop} keyword as well.
- @item pass
- @itemx noignore
- @value{GDBN} should allow your program to see this signal; your program
- can handle the signal, or else it may terminate if the signal is fatal
- and not handled. @code{pass} and @code{noignore} are synonyms.
- @item nopass
- @itemx ignore
- @value{GDBN} should not allow your program to see this signal.
- @code{nopass} and @code{ignore} are synonyms.
- @end table
- @c @end group
- When a signal stops your program, the signal is not visible to the
- program until you
- continue. Your program sees the signal then, if @code{pass} is in
- effect for the signal in question @emph{at that time}. In other words,
- after @value{GDBN} reports a signal, you can use the @code{handle}
- command with @code{pass} or @code{nopass} to control whether your
- program sees that signal when you continue.
- The default is set to @code{nostop}, @code{noprint}, @code{pass} for
- non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and
- @code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the
- erroneous signals.
- You can also use the @code{signal} command to prevent your program from
- seeing a signal, or cause it to see a signal it normally would not see,
- or to give it any signal at any time. For example, if your program stopped
- due to some sort of memory reference error, you might store correct
- values into the erroneous variables and continue, hoping to see more
- execution; but your program would probably terminate immediately as
- a result of the fatal signal once it saw the signal. To prevent this,
- you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
- Program a Signal}.
- @cindex stepping and signal handlers
- @anchor{stepping and signal handlers}
- @value{GDBN} optimizes for stepping the mainline code. If a signal
- that has @code{handle nostop} and @code{handle pass} set arrives while
- a stepping command (e.g., @code{stepi}, @code{step}, @code{next}) is
- in progress, @value{GDBN} lets the signal handler run and then resumes
- stepping the mainline code once the signal handler returns. In other
- words, @value{GDBN} steps over the signal handler. This prevents
- signals that you've specified as not interesting (with @code{handle
- nostop}) from changing the focus of debugging unexpectedly. Note that
- the signal handler itself may still hit a breakpoint, stop for another
- signal that has @code{handle stop} in effect, or for any other event
- that normally results in stopping the stepping command sooner. Also
- note that @value{GDBN} still informs you that the program received a
- signal if @code{handle print} is set.
- @anchor{stepping into signal handlers}
- If you set @code{handle pass} for a signal, and your program sets up a
- handler for it, then issuing a stepping command, such as @code{step}
- or @code{stepi}, when your program is stopped due to the signal will
- step @emph{into} the signal handler (if the target supports that).
- Likewise, if you use the @code{queue-signal} command to queue a signal
- to be delivered to the current thread when execution of the thread
- resumes (@pxref{Signaling, ,Giving your Program a Signal}), then a
- stepping command will step into the signal handler.
- Here's an example, using @code{stepi} to step to the first instruction
- of @code{SIGUSR1}'s handler:
- @smallexample
- (@value{GDBP}) handle SIGUSR1
- Signal Stop Print Pass to program Description
- SIGUSR1 Yes Yes Yes User defined signal 1
- (@value{GDBP}) c
- Continuing.
- Program received signal SIGUSR1, User defined signal 1.
- main () sigusr1.c:28
- 28 p = 0;
- (@value{GDBP}) si
- sigusr1_handler () at sigusr1.c:9
- 9 @{
- @end smallexample
- The same, but using @code{queue-signal} instead of waiting for the
- program to receive the signal first:
- @smallexample
- (@value{GDBP}) n
- 28 p = 0;
- (@value{GDBP}) queue-signal SIGUSR1
- (@value{GDBP}) si
- sigusr1_handler () at sigusr1.c:9
- 9 @{
- (@value{GDBP})
- @end smallexample
- @cindex extra signal information
- @anchor{extra signal information}
- On some targets, @value{GDBN} can inspect extra signal information
- associated with the intercepted signal, before it is actually
- delivered to the program being debugged. This information is exported
- by the convenience variable @code{$_siginfo}, and consists of data
- that is passed by the kernel to the signal handler at the time of the
- receipt of a signal. The data type of the information itself is
- target dependent. You can see the data type using the @code{ptype
- $_siginfo} command. On Unix systems, it typically corresponds to the
- standard @code{siginfo_t} type, as defined in the @file{signal.h}
- system header.
- Here's an example, on a @sc{gnu}/Linux system, printing the stray
- referenced address that raised a segmentation fault.
- @smallexample
- @group
- (@value{GDBP}) continue
- Program received signal SIGSEGV, Segmentation fault.
- 0x0000000000400766 in main ()
- 69 *(int *)p = 0;
- (@value{GDBP}) ptype $_siginfo
- type = struct @{
- int si_signo;
- int si_errno;
- int si_code;
- union @{
- int _pad[28];
- struct @{...@} _kill;
- struct @{...@} _timer;
- struct @{...@} _rt;
- struct @{...@} _sigchld;
- struct @{...@} _sigfault;
- struct @{...@} _sigpoll;
- @} _sifields;
- @}
- (@value{GDBP}) ptype $_siginfo._sifields._sigfault
- type = struct @{
- void *si_addr;
- @}
- (@value{GDBP}) p $_siginfo._sifields._sigfault.si_addr
- $1 = (void *) 0x7ffff7ff7000
- @end group
- @end smallexample
- Depending on target support, @code{$_siginfo} may also be writable.
- @cindex Intel MPX boundary violations
- @cindex boundary violations, Intel MPX
- On some targets, a @code{SIGSEGV} can be caused by a boundary
- violation, i.e., accessing an address outside of the allowed range.
- In those cases @value{GDBN} may displays additional information,
- depending on how @value{GDBN} has been told to handle the signal.
- With @code{handle stop SIGSEGV}, @value{GDBN} displays the violation
- kind: "Upper" or "Lower", the memory address accessed and the
- bounds, while with @code{handle nostop SIGSEGV} no additional
- information is displayed.
- The usual output of a segfault is:
- @smallexample
- Program received signal SIGSEGV, Segmentation fault
- 0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
- 68 value = *(p + len);
- @end smallexample
- While a bound violation is presented as:
- @smallexample
- Program received signal SIGSEGV, Segmentation fault
- Upper bound violation while accessing address 0x7fffffffc3b3
- Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3]
- 0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
- 68 value = *(p + len);
- @end smallexample
- @node Thread Stops
- @section Stopping and Starting Multi-thread Programs
- @cindex stopped threads
- @cindex threads, stopped
- @cindex continuing threads
- @cindex threads, continuing
- @value{GDBN} supports debugging programs with multiple threads
- (@pxref{Threads,, Debugging Programs with Multiple Threads}). There
- are two modes of controlling execution of your program within the
- debugger. In the default mode, referred to as @dfn{all-stop mode},
- when any thread in your program stops (for example, at a breakpoint
- or while being stepped), all other threads in the program are also stopped by
- @value{GDBN}. On some targets, @value{GDBN} also supports
- @dfn{non-stop mode}, in which other threads can continue to run freely while
- you examine the stopped thread in the debugger.
- @menu
- * All-Stop Mode:: All threads stop when GDB takes control
- * Non-Stop Mode:: Other threads continue to execute
- * Background Execution:: Running your program asynchronously
- * Thread-Specific Breakpoints:: Controlling breakpoints
- * Interrupted System Calls:: GDB may interfere with system calls
- * Observer Mode:: GDB does not alter program behavior
- @end menu
- @node All-Stop Mode
- @subsection All-Stop Mode
- @cindex all-stop mode
- In all-stop mode, whenever your program stops under @value{GDBN} for any reason,
- @emph{all} threads of execution stop, not just the current thread. This
- allows you to examine the overall state of the program, including
- switching between threads, without worrying that things may change
- underfoot.
- Conversely, whenever you restart the program, @emph{all} threads start
- executing. @emph{This is true even when single-stepping} with commands
- like @code{step} or @code{next}.
- In particular, @value{GDBN} cannot single-step all threads in lockstep.
- Since thread scheduling is up to your debugging target's operating
- system (not controlled by @value{GDBN}), other threads may
- execute more than one statement while the current thread completes a
- single step. Moreover, in general other threads stop in the middle of a
- statement, rather than at a clean statement boundary, when the program
- stops.
- You might even find your program stopped in another thread after
- continuing or even single-stepping. This happens whenever some other
- thread runs into a breakpoint, a signal, or an exception before the
- first thread completes whatever you requested.
- @cindex automatic thread selection
- @cindex switching threads automatically
- @cindex threads, automatic switching
- Whenever @value{GDBN} stops your program, due to a breakpoint or a
- signal, it automatically selects the thread where that breakpoint or
- signal happened. @value{GDBN} alerts you to the context switch with a
- message such as @samp{[Switching to Thread @var{n}]} to identify the
- thread.
- On some OSes, you can modify @value{GDBN}'s default behavior by
- locking the OS scheduler to allow only a single thread to run.
- @table @code
- @item set scheduler-locking @var{mode}
- @cindex scheduler locking mode
- @cindex lock scheduler
- Set the scheduler locking mode. It applies to normal execution,
- record mode, and replay mode. If it is @code{off}, then there is no
- locking and any thread may run at any time. If @code{on}, then only
- the current thread may run when the inferior is resumed. The
- @code{step} mode optimizes for single-stepping; it prevents other
- threads from preempting the current thread while you are stepping, so
- that the focus of debugging does not change unexpectedly. Other
- threads never get a chance to run when you step, and they are
- completely free to run when you use commands like @samp{continue},
- @samp{until}, or @samp{finish}. However, unless another thread hits a
- breakpoint during its timeslice, @value{GDBN} does not change the
- current thread away from the thread that you are debugging. The
- @code{replay} mode behaves like @code{off} in record mode and like
- @code{on} in replay mode.
- @item show scheduler-locking
- Display the current scheduler locking mode.
- @end table
- @cindex resume threads of multiple processes simultaneously
- By default, when you issue one of the execution commands such as
- @code{continue}, @code{next} or @code{step}, @value{GDBN} allows only
- threads of the current inferior to run. For example, if @value{GDBN}
- is attached to two inferiors, each with two threads, the
- @code{continue} command resumes only the two threads of the current
- inferior. This is useful, for example, when you debug a program that
- forks and you want to hold the parent stopped (so that, for instance,
- it doesn't run to exit), while you debug the child. In other
- situations, you may not be interested in inspecting the current state
- of any of the processes @value{GDBN} is attached to, and you may want
- to resume them all until some breakpoint is hit. In the latter case,
- you can instruct @value{GDBN} to allow all threads of all the
- inferiors to run with the @w{@code{set schedule-multiple}} command.
- @table @code
- @kindex set schedule-multiple
- @item set schedule-multiple
- Set the mode for allowing threads of multiple processes to be resumed
- when an execution command is issued. When @code{on}, all threads of
- all processes are allowed to run. When @code{off}, only the threads
- of the current process are resumed. The default is @code{off}. The
- @code{scheduler-locking} mode takes precedence when set to @code{on},
- or while you are stepping and set to @code{step}.
- @item show schedule-multiple
- Display the current mode for resuming the execution of threads of
- multiple processes.
- @end table
- @node Non-Stop Mode
- @subsection Non-Stop Mode
- @cindex non-stop mode
- @c This section is really only a place-holder, and needs to be expanded
- @c with more details.
- For some multi-threaded targets, @value{GDBN} supports an optional
- mode of operation in which you can examine stopped program threads in
- the debugger while other threads continue to execute freely. This
- minimizes intrusion when debugging live systems, such as programs
- where some threads have real-time constraints or must continue to
- respond to external events. This is referred to as @dfn{non-stop} mode.
- In non-stop mode, when a thread stops to report a debugging event,
- @emph{only} that thread is stopped; @value{GDBN} does not stop other
- threads as well, in contrast to the all-stop mode behavior. Additionally,
- execution commands such as @code{continue} and @code{step} apply by default
- only to the current thread in non-stop mode, rather than all threads as
- in all-stop mode. This allows you to control threads explicitly in
- ways that are not possible in all-stop mode --- for example, stepping
- one thread while allowing others to run freely, stepping
- one thread while holding all others stopped, or stepping several threads
- independently and simultaneously.
- To enter non-stop mode, use this sequence of commands before you run
- or attach to your program:
- @smallexample
- # If using the CLI, pagination breaks non-stop.
- set pagination off
- # Finally, turn it on!
- set non-stop on
- @end smallexample
- You can use these commands to manipulate the non-stop mode setting:
- @table @code
- @kindex set non-stop
- @item set non-stop on
- Enable selection of non-stop mode.
- @item set non-stop off
- Disable selection of non-stop mode.
- @kindex show non-stop
- @item show non-stop
- Show the current non-stop enablement setting.
- @end table
- Note these commands only reflect whether non-stop mode is enabled,
- not whether the currently-executing program is being run in non-stop mode.
- In particular, the @code{set non-stop} preference is only consulted when
- @value{GDBN} starts or connects to the target program, and it is generally
- not possible to switch modes once debugging has started. Furthermore,
- since not all targets support non-stop mode, even when you have enabled
- non-stop mode, @value{GDBN} may still fall back to all-stop operation by
- default.
- In non-stop mode, all execution commands apply only to the current thread
- by default. That is, @code{continue} only continues one thread.
- To continue all threads, issue @code{continue -a} or @code{c -a}.
- You can use @value{GDBN}'s background execution commands
- (@pxref{Background Execution}) to run some threads in the background
- while you continue to examine or step others from @value{GDBN}.
- The MI execution commands (@pxref{GDB/MI Program Execution}) are
- always executed asynchronously in non-stop mode.
- Suspending execution is done with the @code{interrupt} command when
- running in the background, or @kbd{Ctrl-c} during foreground execution.
- In all-stop mode, this stops the whole process;
- but in non-stop mode the interrupt applies only to the current thread.
- To stop the whole program, use @code{interrupt -a}.
- Other execution commands do not currently support the @code{-a} option.
- In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make
- that thread current, as it does in all-stop mode. This is because the
- thread stop notifications are asynchronous with respect to @value{GDBN}'s
- command interpreter, and it would be confusing if @value{GDBN} unexpectedly
- changed to a different thread just as you entered a command to operate on the
- previously current thread.
- @node Background Execution
- @subsection Background Execution
- @cindex foreground execution
- @cindex background execution
- @cindex asynchronous execution
- @cindex execution, foreground, background and asynchronous
- @value{GDBN}'s execution commands have two variants: the normal
- foreground (synchronous) behavior, and a background
- (asynchronous) behavior. In foreground execution, @value{GDBN} waits for
- the program to report that some thread has stopped before prompting for
- another command. In background execution, @value{GDBN} immediately gives
- a command prompt so that you can issue other commands while your program runs.
- If the target doesn't support async mode, @value{GDBN} issues an error
- message if you attempt to use the background execution commands.
- @cindex @code{&}, background execution of commands
- To specify background execution, add a @code{&} to the command. For example,
- the background form of the @code{continue} command is @code{continue&}, or
- just @code{c&}. The execution commands that accept background execution
- are:
- @table @code
- @kindex run&
- @item run
- @xref{Starting, , Starting your Program}.
- @item attach
- @kindex attach&
- @xref{Attach, , Debugging an Already-running Process}.
- @item step
- @kindex step&
- @xref{Continuing and Stepping, step}.
- @item stepi
- @kindex stepi&
- @xref{Continuing and Stepping, stepi}.
- @item next
- @kindex next&
- @xref{Continuing and Stepping, next}.
- @item nexti
- @kindex nexti&
- @xref{Continuing and Stepping, nexti}.
- @item continue
- @kindex continue&
- @xref{Continuing and Stepping, continue}.
- @item finish
- @kindex finish&
- @xref{Continuing and Stepping, finish}.
- @item until
- @kindex until&
- @xref{Continuing and Stepping, until}.
- @end table
- Background execution is especially useful in conjunction with non-stop
- mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}.
- However, you can also use these commands in the normal all-stop mode with
- the restriction that you cannot issue another execution command until the
- previous one finishes. Examples of commands that are valid in all-stop
- mode while the program is running include @code{help} and @code{info break}.
- You can interrupt your program while it is running in the background by
- using the @code{interrupt} command.
- @table @code
- @kindex interrupt
- @item interrupt
- @itemx interrupt -a
- Suspend execution of the running program. In all-stop mode,
- @code{interrupt} stops the whole process, but in non-stop mode, it stops
- only the current thread. To stop the whole program in non-stop mode,
- use @code{interrupt -a}.
- @end table
- @node Thread-Specific Breakpoints
- @subsection Thread-Specific Breakpoints
- When your program has multiple threads (@pxref{Threads,, Debugging
- Programs with Multiple Threads}), you can choose whether to set
- breakpoints on all threads, or on a particular thread.
- @table @code
- @cindex breakpoints and threads
- @cindex thread breakpoints
- @kindex break @dots{} thread @var{thread-id}
- @item break @var{location} thread @var{thread-id}
- @itemx break @var{location} thread @var{thread-id} if @dots{}
- @var{location} specifies source lines; there are several ways of
- writing them (@pxref{Specify Location}), but the effect is always to
- specify some source line.
- Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command
- to specify that you only want @value{GDBN} to stop the program when a
- particular thread reaches this breakpoint. The @var{thread-id} specifier
- is one of the thread identifiers assigned by @value{GDBN}, shown
- in the first column of the @samp{info threads} display.
- If you do not specify @samp{thread @var{thread-id}} when you set a
- breakpoint, the breakpoint applies to @emph{all} threads of your
- program.
- You can use the @code{thread} qualifier on conditional breakpoints as
- well; in this case, place @samp{thread @var{thread-id}} before or
- after the breakpoint condition, like this:
- @smallexample
- (@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
- @end smallexample
- @end table
- Thread-specific breakpoints are automatically deleted when
- @value{GDBN} detects the corresponding thread is no longer in the
- thread list. For example:
- @smallexample
- (@value{GDBP}) c
- Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.
- @end smallexample
- There are several ways for a thread to disappear, such as a regular
- thread exit, but also when you detach from the process with the
- @code{detach} command (@pxref{Attach, ,Debugging an Already-running
- Process}), or if @value{GDBN} loses the remote connection
- (@pxref{Remote Debugging}), etc. Note that with some targets,
- @value{GDBN} is only able to detect a thread has exited when the user
- explictly asks for the thread list with the @code{info threads}
- command.
- @node Interrupted System Calls
- @subsection Interrupted System Calls
- @cindex thread breakpoints and system calls
- @cindex system calls and thread breakpoints
- @cindex premature return from system calls
- There is an unfortunate side effect when using @value{GDBN} to debug
- multi-threaded programs. If one thread stops for a
- breakpoint, or for some other reason, and another thread is blocked in a
- system call, then the system call may return prematurely. This is a
- consequence of the interaction between multiple threads and the signals
- that @value{GDBN} uses to implement breakpoints and other events that
- stop execution.
- To handle this problem, your program should check the return value of
- each system call and react appropriately. This is good programming
- style anyways.
- For example, do not write code like this:
- @smallexample
- sleep (10);
- @end smallexample
- The call to @code{sleep} will return early if a different thread stops
- at a breakpoint or for some other reason.
- Instead, write this:
- @smallexample
- int unslept = 10;
- while (unslept > 0)
- unslept = sleep (unslept);
- @end smallexample
- A system call is allowed to return early, so the system is still
- conforming to its specification. But @value{GDBN} does cause your
- multi-threaded program to behave differently than it would without
- @value{GDBN}.
- Also, @value{GDBN} uses internal breakpoints in the thread library to
- monitor certain events such as thread creation and thread destruction.
- When such an event happens, a system call in another thread may return
- prematurely, even though your program does not appear to stop.
- @node Observer Mode
- @subsection Observer Mode
- If you want to build on non-stop mode and observe program behavior
- without any chance of disruption by @value{GDBN}, you can set
- variables to disable all of the debugger's attempts to modify state,
- whether by writing memory, inserting breakpoints, etc. These operate
- at a low level, intercepting operations from all commands.
- When all of these are set to @code{off}, then @value{GDBN} is said to
- be @dfn{observer mode}. As a convenience, the variable
- @code{observer} can be set to disable these, plus enable non-stop
- mode.
- Note that @value{GDBN} will not prevent you from making nonsensical
- combinations of these settings. For instance, if you have enabled
- @code{may-insert-breakpoints} but disabled @code{may-write-memory},
- then breakpoints that work by writing trap instructions into the code
- stream will still not be able to be placed.
- @table @code
- @kindex observer
- @item set observer on
- @itemx set observer off
- When set to @code{on}, this disables all the permission variables
- below (except for @code{insert-fast-tracepoints}), plus enables
- non-stop debugging. Setting this to @code{off} switches back to
- normal debugging, though remaining in non-stop mode.
- @item show observer
- Show whether observer mode is on or off.
- @kindex may-write-registers
- @item set may-write-registers on
- @itemx set may-write-registers off
- This controls whether @value{GDBN} will attempt to alter the values of
- registers, such as with assignment expressions in @code{print}, or the
- @code{jump} command. It defaults to @code{on}.
- @item show may-write-registers
- Show the current permission to write registers.
- @kindex may-write-memory
- @item set may-write-memory on
- @itemx set may-write-memory off
- This controls whether @value{GDBN} will attempt to alter the contents
- of memory, such as with assignment expressions in @code{print}. It
- defaults to @code{on}.
- @item show may-write-memory
- Show the current permission to write memory.
- @kindex may-insert-breakpoints
- @item set may-insert-breakpoints on
- @itemx set may-insert-breakpoints off
- This controls whether @value{GDBN} will attempt to insert breakpoints.
- This affects all breakpoints, including internal breakpoints defined
- by @value{GDBN}. It defaults to @code{on}.
- @item show may-insert-breakpoints
- Show the current permission to insert breakpoints.
- @kindex may-insert-tracepoints
- @item set may-insert-tracepoints on
- @itemx set may-insert-tracepoints off
- This controls whether @value{GDBN} will attempt to insert (regular)
- tracepoints at the beginning of a tracing experiment. It affects only
- non-fast tracepoints, fast tracepoints being under the control of
- @code{may-insert-fast-tracepoints}. It defaults to @code{on}.
- @item show may-insert-tracepoints
- Show the current permission to insert tracepoints.
- @kindex may-insert-fast-tracepoints
- @item set may-insert-fast-tracepoints on
- @itemx set may-insert-fast-tracepoints off
- This controls whether @value{GDBN} will attempt to insert fast
- tracepoints at the beginning of a tracing experiment. It affects only
- fast tracepoints, regular (non-fast) tracepoints being under the
- control of @code{may-insert-tracepoints}. It defaults to @code{on}.
- @item show may-insert-fast-tracepoints
- Show the current permission to insert fast tracepoints.
- @kindex may-interrupt
- @item set may-interrupt on
- @itemx set may-interrupt off
- This controls whether @value{GDBN} will attempt to interrupt or stop
- program execution. When this variable is @code{off}, the
- @code{interrupt} command will have no effect, nor will
- @kbd{Ctrl-c}. It defaults to @code{on}.
- @item show may-interrupt
- Show the current permission to interrupt or stop the program.
- @end table
- @node Reverse Execution
- @chapter Running programs backward
- @cindex reverse execution
- @cindex running programs backward
- When you are debugging a program, it is not unusual to realize that
- you have gone too far, and some event of interest has already happened.
- If the target environment supports it, @value{GDBN} can allow you to
- ``rewind'' the program by running it backward.
- A target environment that supports reverse execution should be able
- to ``undo'' the changes in machine state that have taken place as the
- program was executing normally. Variables, registers etc.@: should
- revert to their previous values. Obviously this requires a great
- deal of sophistication on the part of the target environment; not
- all target environments can support reverse execution.
- When a program is executed in reverse, the instructions that
- have most recently been executed are ``un-executed'', in reverse
- order. The program counter runs backward, following the previous
- thread of execution in reverse. As each instruction is ``un-executed'',
- the values of memory and/or registers that were changed by that
- instruction are reverted to their previous states. After executing
- a piece of source code in reverse, all side effects of that code
- should be ``undone'', and all variables should be returned to their
- prior values@footnote{
- Note that some side effects are easier to undo than others. For instance,
- memory and registers are relatively easy, but device I/O is hard. Some
- targets may be able undo things like device I/O, and some may not.
- The contract between @value{GDBN} and the reverse executing target
- requires only that the target do something reasonable when
- @value{GDBN} tells it to execute backwards, and then report the
- results back to @value{GDBN}. Whatever the target reports back to
- @value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN}
- assumes that the memory and registers that the target reports are in a
- consistent state, but @value{GDBN} accepts whatever it is given.
- }.
- On some platforms, @value{GDBN} has built-in support for reverse
- execution, activated with the @code{record} or @code{record btrace}
- commands. @xref{Process Record and Replay}. Some remote targets,
- typically full system emulators, support reverse execution directly
- without requiring any special command.
- If you are debugging in a target environment that supports
- reverse execution, @value{GDBN} provides the following commands.
- @table @code
- @kindex reverse-continue
- @kindex rc @r{(@code{reverse-continue})}
- @item reverse-continue @r{[}@var{ignore-count}@r{]}
- @itemx rc @r{[}@var{ignore-count}@r{]}
- Beginning at the point where your program last stopped, start executing
- in reverse. Reverse execution will stop for breakpoints and synchronous
- exceptions (signals), just like normal execution. Behavior of
- asynchronous signals depends on the target environment.
- @kindex reverse-step
- @kindex rs @r{(@code{step})}
- @item reverse-step @r{[}@var{count}@r{]}
- Run the program backward until control reaches the start of a
- different source line; then stop it, and return control to @value{GDBN}.
- Like the @code{step} command, @code{reverse-step} will only stop
- at the beginning of a source line. It ``un-executes'' the previously
- executed source line. If the previous source line included calls to
- debuggable functions, @code{reverse-step} will step (backward) into
- the called function, stopping at the beginning of the @emph{last}
- statement in the called function (typically a return statement).
- Also, as with the @code{step} command, if non-debuggable functions are
- called, @code{reverse-step} will run thru them backward without stopping.
- @kindex reverse-stepi
- @kindex rsi @r{(@code{reverse-stepi})}
- @item reverse-stepi @r{[}@var{count}@r{]}
- Reverse-execute one machine instruction. Note that the instruction
- to be reverse-executed is @emph{not} the one pointed to by the program
- counter, but the instruction executed prior to that one. For instance,
- if the last instruction was a jump, @code{reverse-stepi} will take you
- back from the destination of the jump to the jump instruction itself.
- @kindex reverse-next
- @kindex rn @r{(@code{reverse-next})}
- @item reverse-next @r{[}@var{count}@r{]}
- Run backward to the beginning of the previous line executed in
- the current (innermost) stack frame. If the line contains function
- calls, they will be ``un-executed'' without stopping. Starting from
- the first line of a function, @code{reverse-next} will take you back
- to the caller of that function, @emph{before} the function was called,
- just as the normal @code{next} command would take you from the last
- line of a function back to its return to its caller
- @footnote{Unless the code is too heavily optimized.}.
- @kindex reverse-nexti
- @kindex rni @r{(@code{reverse-nexti})}
- @item reverse-nexti @r{[}@var{count}@r{]}
- Like @code{nexti}, @code{reverse-nexti} executes a single instruction
- in reverse, except that called functions are ``un-executed'' atomically.
- That is, if the previously executed instruction was a return from
- another function, @code{reverse-nexti} will continue to execute
- in reverse until the call to that function (from the current stack
- frame) is reached.
- @kindex reverse-finish
- @item reverse-finish
- Just as the @code{finish} command takes you to the point where the
- current function returns, @code{reverse-finish} takes you to the point
- where it was called. Instead of ending up at the end of the current
- function invocation, you end up at the beginning.
- @kindex set exec-direction
- @item set exec-direction
- Set the direction of target execution.
- @item set exec-direction reverse
- @cindex execute forward or backward in time
- @value{GDBN} will perform all execution commands in reverse, until the
- exec-direction mode is changed to ``forward''. Affected commands include
- @code{step, stepi, next, nexti, continue, and finish}. The @code{return}
- command cannot be used in reverse mode.
- @item set exec-direction forward
- @value{GDBN} will perform all execution commands in the normal fashion.
- This is the default.
- @end table
- @node Process Record and Replay
- @chapter Recording Inferior's Execution and Replaying It
- @cindex process record and replay
- @cindex recording inferior's execution and replaying it
- On some platforms, @value{GDBN} provides a special @dfn{process record
- and replay} target that can record a log of the process execution, and
- replay it later with both forward and reverse execution commands.
- @cindex replay mode
- When this target is in use, if the execution log includes the record
- for the next instruction, @value{GDBN} will debug in @dfn{replay
- mode}. In the replay mode, the inferior does not really execute code
- instructions. Instead, all the events that normally happen during
- code execution are taken from the execution log. While code is not
- really executed in replay mode, the values of registers (including the
- program counter register) and the memory of the inferior are still
- changed as they normally would. Their contents are taken from the
- execution log.
- @cindex record mode
- If the record for the next instruction is not in the execution log,
- @value{GDBN} will debug in @dfn{record mode}. In this mode, the
- inferior executes normally, and @value{GDBN} records the execution log
- for future replay.
- The process record and replay target supports reverse execution
- (@pxref{Reverse Execution}), even if the platform on which the
- inferior runs does not. However, the reverse execution is limited in
- this case by the range of the instructions recorded in the execution
- log. In other words, reverse execution on platforms that don't
- support it directly can only be done in the replay mode.
- When debugging in the reverse direction, @value{GDBN} will work in
- replay mode as long as the execution log includes the record for the
- previous instruction; otherwise, it will work in record mode, if the
- platform supports reverse execution, or stop if not.
- Currently, process record and replay is supported on ARM, Aarch64,
- Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running
- GNU/Linux. Process record and replay can be used both when native
- debugging, and when remote debugging via @code{gdbserver}.
- For architecture environments that support process record and replay,
- @value{GDBN} provides the following commands:
- @table @code
- @kindex target record
- @kindex target record-full
- @kindex target record-btrace
- @kindex record
- @kindex record full
- @kindex record btrace
- @kindex record btrace bts
- @kindex record btrace pt
- @kindex record bts
- @kindex record pt
- @kindex rec
- @kindex rec full
- @kindex rec btrace
- @kindex rec btrace bts
- @kindex rec btrace pt
- @kindex rec bts
- @kindex rec pt
- @item record @var{method}
- This command starts the process record and replay target. The
- recording method can be specified as parameter. Without a parameter
- the command uses the @code{full} recording method. The following
- recording methods are available:
- @table @code
- @item full
- Full record/replay recording using @value{GDBN}'s software record and
- replay implementation. This method allows replaying and reverse
- execution.
- @item btrace @var{format}
- Hardware-supported instruction recording, supported on Intel
- processors. This method does not record data. Further, the data is
- collected in a ring buffer so old data will be overwritten when the
- buffer is full. It allows limited reverse execution. Variables and
- registers are not available during reverse execution. In remote
- debugging, recording continues on disconnect. Recorded data can be
- inspected after reconnecting. The recording may be stopped using
- @code{record stop}.
- The recording format can be specified as parameter. Without a parameter
- the command chooses the recording format. The following recording
- formats are available:
- @table @code
- @item bts
- @cindex branch trace store
- Use the @dfn{Branch Trace Store} (@acronym{BTS}) recording format. In
- this format, the processor stores a from/to record for each executed
- branch in the btrace ring buffer.
- @item pt
- @cindex Intel Processor Trace
- Use the @dfn{Intel Processor Trace} recording format. In this
- format, the processor stores the execution trace in a compressed form
- that is afterwards decoded by @value{GDBN}.
- The trace can be recorded with very low overhead. The compressed
- trace format also allows small trace buffers to already contain a big
- number of instructions compared to @acronym{BTS}.
- Decoding the recorded execution trace, on the other hand, is more
- expensive than decoding @acronym{BTS} trace. This is mostly due to the
- increased number of instructions to process. You should increase the
- buffer-size with care.
- @end table
- Not all recording formats may be available on all processors.
- @end table
- The process record and replay target can only debug a process that is
- already running. Therefore, you need first to start the process with
- the @kbd{run} or @kbd{start} commands, and then start the recording
- with the @kbd{record @var{method}} command.
- @cindex displaced stepping, and process record and replay
- Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
- will be automatically disabled when process record and replay target
- is started. That's because the process record and replay target
- doesn't support displaced stepping.
- @cindex non-stop mode, and process record and replay
- @cindex asynchronous execution, and process record and replay
- If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in
- the asynchronous execution mode (@pxref{Background Execution}), not
- all recording methods are available. The @code{full} recording method
- does not support these two modes.
- @kindex record stop
- @kindex rec s
- @item record stop
- Stop the process record and replay target. When process record and
- replay target stops, the entire execution log will be deleted and the
- inferior will either be terminated, or will remain in its final state.
- When you stop the process record and replay target in record mode (at
- the end of the execution log), the inferior will be stopped at the
- next instruction that would have been recorded. In other words, if
- you record for a while and then stop recording, the inferior process
- will be left in the same state as if the recording never happened.
- On the other hand, if the process record and replay target is stopped
- while in replay mode (that is, not at the end of the execution log,
- but at some earlier point), the inferior process will become ``live''
- at that earlier state, and it will then be possible to continue the
- usual ``live'' debugging of the process from that state.
- When the inferior process exits, or @value{GDBN} detaches from it,
- process record and replay target will automatically stop itself.
- @kindex record goto
- @item record goto
- Go to a specific location in the execution log. There are several
- ways to specify the location to go to:
- @table @code
- @item record goto begin
- @itemx record goto start
- Go to the beginning of the execution log.
- @item record goto end
- Go to the end of the execution log.
- @item record goto @var{n}
- Go to instruction number @var{n} in the execution log.
- @end table
- @kindex record save
- @item record save @var{filename}
- Save the execution log to a file @file{@var{filename}}.
- Default filename is @file{gdb_record.@var{process_id}}, where
- @var{process_id} is the process ID of the inferior.
- This command may not be available for all recording methods.
- @kindex record restore
- @item record restore @var{filename}
- Restore the execution log from a file @file{@var{filename}}.
- File must have been created with @code{record save}.
- @kindex set record full
- @item set record full insn-number-max @var{limit}
- @itemx set record full insn-number-max unlimited
- Set the limit of instructions to be recorded for the @code{full}
- recording method. Default value is 200000.
- If @var{limit} is a positive number, then @value{GDBN} will start
- deleting instructions from the log once the number of the record
- instructions becomes greater than @var{limit}. For every new recorded
- instruction, @value{GDBN} will delete the earliest recorded
- instruction to keep the number of recorded instructions at the limit.
- (Since deleting recorded instructions loses information, @value{GDBN}
- lets you control what happens when the limit is reached, by means of
- the @code{stop-at-limit} option, described below.)
- If @var{limit} is @code{unlimited} or zero, @value{GDBN} will never
- delete recorded instructions from the execution log. The number of
- recorded instructions is limited only by the available memory.
- @kindex show record full
- @item show record full insn-number-max
- Show the limit of instructions to be recorded with the @code{full}
- recording method.
- @item set record full stop-at-limit
- Control the behavior of the @code{full} recording method when the
- number of recorded instructions reaches the limit. If ON (the
- default), @value{GDBN} will stop when the limit is reached for the
- first time and ask you whether you want to stop the inferior or
- continue running it and recording the execution log. If you decide
- to continue recording, each new recorded instruction will cause the
- oldest one to be deleted.
- If this option is OFF, @value{GDBN} will automatically delete the
- oldest record to make room for each new one, without asking.
- @item show record full stop-at-limit
- Show the current setting of @code{stop-at-limit}.
- @item set record full memory-query
- Control the behavior when @value{GDBN} is unable to record memory
- changes caused by an instruction for the @code{full} recording method.
- If ON, @value{GDBN} will query whether to stop the inferior in that
- case.
- If this option is OFF (the default), @value{GDBN} will automatically
- ignore the effect of such instructions on memory. Later, when
- @value{GDBN} replays this execution log, it will mark the log of this
- instruction as not accessible, and it will not affect the replay
- results.
- @item show record full memory-query
- Show the current setting of @code{memory-query}.
- @kindex set record btrace
- The @code{btrace} record target does not trace data. As a
- convenience, when replaying, @value{GDBN} reads read-only memory off
- the live program directly, assuming that the addresses of the
- read-only areas don't change. This for example makes it possible to
- disassemble code while replaying, but not to print variables.
- In some cases, being able to inspect variables might be useful.
- You can use the following command for that:
- @item set record btrace replay-memory-access
- Control the behavior of the @code{btrace} recording method when
- accessing memory during replay. If @code{read-only} (the default),
- @value{GDBN} will only allow accesses to read-only memory.
- If @code{read-write}, @value{GDBN} will allow accesses to read-only
- and to read-write memory. Beware that the accessed memory corresponds
- to the live target and not necessarily to the current replay
- position.
- @item set record btrace cpu @var{identifier}
- Set the processor to be used for enabling workarounds for processor
- errata when decoding the trace.
- Processor errata are defects in processor operation, caused by its
- design or manufacture. They can cause a trace not to match the
- specification. This, in turn, may cause trace decode to fail.
- @value{GDBN} can detect erroneous trace packets and correct them, thus
- avoiding the decoding failures. These corrections are known as
- @dfn{errata workarounds}, and are enabled based on the processor on
- which the trace was recorded.
- By default, @value{GDBN} attempts to detect the processor
- automatically, and apply the necessary workarounds for it. However,
- you may need to specify the processor if @value{GDBN} does not yet
- support it. This command allows you to do that, and also allows to
- disable the workarounds.
- The argument @var{identifier} identifies the @sc{cpu} and is of the
- form: @code{@var{vendor}:@var{processor identifier}}. In addition,
- there are two special identifiers, @code{none} and @code{auto}
- (default).
- The following vendor identifiers and corresponding processor
- identifiers are currently supported:
- @multitable @columnfractions .1 .9
- @item @code{intel}
- @tab @var{family}/@var{model}[/@var{stepping}]
- @end multitable
- On GNU/Linux systems, the processor @var{family}, @var{model}, and
- @var{stepping} can be obtained from @code{/proc/cpuinfo}.
- If @var{identifier} is @code{auto}, enable errata workarounds for the
- processor on which the trace was recorded. If @var{identifier} is
- @code{none}, errata workarounds are disabled.
- For example, when using an old @value{GDBN} on a new system, decode
- may fail because @value{GDBN} does not support the new processor. It
- often suffices to specify an older processor that @value{GDBN}
- supports.
- @smallexample
- (gdb) info record
- Active record target: record-btrace
- Recording format: Intel Processor Trace.
- Buffer size: 16kB.
- Failed to configure the Intel Processor Trace decoder: unknown cpu.
- (gdb) set record btrace cpu intel:6/158
- (gdb) info record
- Active record target: record-btrace
- Recording format: Intel Processor Trace.
- Buffer size: 16kB.
- Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...).
- @end smallexample
- @kindex show record btrace
- @item show record btrace replay-memory-access
- Show the current setting of @code{replay-memory-access}.
- @item show record btrace cpu
- Show the processor to be used for enabling trace decode errata
- workarounds.
- @kindex set record btrace bts
- @item set record btrace bts buffer-size @var{size}
- @itemx set record btrace bts buffer-size unlimited
- Set the requested ring buffer size for branch tracing in @acronym{BTS}
- format. Default is 64KB.
- If @var{size} is a positive number, then @value{GDBN} will try to
- allocate a buffer of at least @var{size} bytes for each new thread
- that uses the btrace recording method and the @acronym{BTS} format.
- The actually obtained buffer size may differ from the requested
- @var{size}. Use the @code{info record} command to see the actual
- buffer size for each thread that uses the btrace recording method and
- the @acronym{BTS} format.
- If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to
- allocate a buffer of 4MB.
- Bigger buffers mean longer traces. On the other hand, @value{GDBN} will
- also need longer to process the branch trace data before it can be used.
- @item show record btrace bts buffer-size @var{size}
- Show the current setting of the requested ring buffer size for branch
- tracing in @acronym{BTS} format.
- @kindex set record btrace pt
- @item set record btrace pt buffer-size @var{size}
- @itemx set record btrace pt buffer-size unlimited
- Set the requested ring buffer size for branch tracing in Intel
- Processor Trace format. Default is 16KB.
- If @var{size} is a positive number, then @value{GDBN} will try to
- allocate a buffer of at least @var{size} bytes for each new thread
- that uses the btrace recording method and the Intel Processor Trace
- format. The actually obtained buffer size may differ from the
- requested @var{size}. Use the @code{info record} command to see the
- actual buffer size for each thread.
- If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to
- allocate a buffer of 4MB.
- Bigger buffers mean longer traces. On the other hand, @value{GDBN} will
- also need longer to process the branch trace data before it can be used.
- @item show record btrace pt buffer-size @var{size}
- Show the current setting of the requested ring buffer size for branch
- tracing in Intel Processor Trace format.
- @kindex info record
- @item info record
- Show various statistics about the recording depending on the recording
- method:
- @table @code
- @item full
- For the @code{full} recording method, it shows the state of process
- record and its in-memory execution log buffer, including:
- @itemize @bullet
- @item
- Whether in record mode or replay mode.
- @item
- Lowest recorded instruction number (counting from when the current execution log started recording instructions).
- @item
- Highest recorded instruction number.
- @item
- Current instruction about to be replayed (if in replay mode).
- @item
- Number of instructions contained in the execution log.
- @item
- Maximum number of instructions that may be contained in the execution log.
- @end itemize
- @item btrace
- For the @code{btrace} recording method, it shows:
- @itemize @bullet
- @item
- Recording format.
- @item
- Number of instructions that have been recorded.
- @item
- Number of blocks of sequential control-flow formed by the recorded
- instructions.
- @item
- Whether in record mode or replay mode.
- @end itemize
- For the @code{bts} recording format, it also shows:
- @itemize @bullet
- @item
- Size of the perf ring buffer.
- @end itemize
- For the @code{pt} recording format, it also shows:
- @itemize @bullet
- @item
- Size of the perf ring buffer.
- @end itemize
- @end table
- @kindex record delete
- @kindex rec del
- @item record delete
- When record target runs in replay mode (``in the past''), delete the
- subsequent execution log and begin to record a new execution log starting
- from the current address. This means you will abandon the previously
- recorded ``future'' and begin recording a new ``future''.
- @kindex record instruction-history
- @kindex rec instruction-history
- @item record instruction-history
- Disassembles instructions from the recorded execution log. By
- default, ten instructions are disassembled. This can be changed using
- the @code{set record instruction-history-size} command. Instructions
- are printed in execution order.
- It can also print mixed source+disassembly if you specify the the
- @code{/m} or @code{/s} modifier, and print the raw instructions in hex
- as well as in symbolic form by specifying the @code{/r} modifier.
- The current position marker is printed for the instruction at the
- current program counter value. This instruction can appear multiple
- times in the trace and the current position marker will be printed
- every time. To omit the current position marker, specify the
- @code{/p} modifier.
- To better align the printed instructions when the trace contains
- instructions from more than one function, the function name may be
- omitted by specifying the @code{/f} modifier.
- Speculatively executed instructions are prefixed with @samp{?}. This
- feature is not available for all recording formats.
- There are several ways to specify what part of the execution log to
- disassemble:
- @table @code
- @item record instruction-history @var{insn}
- Disassembles ten instructions starting from instruction number
- @var{insn}.
- @item record instruction-history @var{insn}, +/-@var{n}
- Disassembles @var{n} instructions around instruction number
- @var{insn}. If @var{n} is preceded with @code{+}, disassembles
- @var{n} instructions after instruction number @var{insn}. If
- @var{n} is preceded with @code{-}, disassembles @var{n}
- instructions before instruction number @var{insn}.
- @item record instruction-history
- Disassembles ten more instructions after the last disassembly.
- @item record instruction-history -
- Disassembles ten more instructions before the last disassembly.
- @item record instruction-history @var{begin}, @var{end}
- Disassembles instructions beginning with instruction number
- @var{begin} until instruction number @var{end}. The instruction
- number @var{end} is included.
- @end table
- This command may not be available for all recording methods.
- @kindex set record
- @item set record instruction-history-size @var{size}
- @itemx set record instruction-history-size unlimited
- Define how many instructions to disassemble in the @code{record
- instruction-history} command. The default value is 10.
- A @var{size} of @code{unlimited} means unlimited instructions.
- @kindex show record
- @item show record instruction-history-size
- Show how many instructions to disassemble in the @code{record
- instruction-history} command.
- @kindex record function-call-history
- @kindex rec function-call-history
- @item record function-call-history
- Prints the execution history at function granularity. For each sequence
- of instructions that belong to the same function, it prints the name of
- that function, the source lines for this instruction sequence (if the
- @code{/l} modifier is specified), and the instructions numbers that form
- the sequence (if the @code{/i} modifier is specified). The function names
- are indented to reflect the call stack depth if the @code{/c} modifier is
- specified. The @code{/l}, @code{/i}, and @code{/c} modifiers can be given
- together.
- @smallexample
- (@value{GDBP}) @b{list 1, 10}
- 1 void foo (void)
- 2 @{
- 3 @}
- 4
- 5 void bar (void)
- 6 @{
- 7 ...
- 8 foo ();
- 9 ...
- 10 @}
- (@value{GDBP}) @b{record function-call-history /ilc}
- 1 bar inst 1,4 at foo.c:6,8
- 2 foo inst 5,10 at foo.c:2,3
- 3 bar inst 11,13 at foo.c:9,10
- @end smallexample
- By default, ten functions are printed. This can be changed using the
- @code{set record function-call-history-size} command. Functions are
- printed in execution order. There are several ways to specify what
- to print:
- @table @code
- @item record function-call-history @var{func}
- Prints ten functions starting from function number @var{func}.
- @item record function-call-history @var{func}, +/-@var{n}
- Prints @var{n} functions around function number @var{func}. If
- @var{n} is preceded with @code{+}, prints @var{n} functions after
- function number @var{func}. If @var{n} is preceded with @code{-},
- prints @var{n} functions before function number @var{func}.
- @item record function-call-history
- Prints ten more functions after the last ten-function print.
- @item record function-call-history -
- Prints ten more functions before the last ten-function print.
- @item record function-call-history @var{begin}, @var{end}
- Prints functions beginning with function number @var{begin} until
- function number @var{end}. The function number @var{end} is included.
- @end table
- This command may not be available for all recording methods.
- @item set record function-call-history-size @var{size}
- @itemx set record function-call-history-size unlimited
- Define how many functions to print in the
- @code{record function-call-history} command. The default value is 10.
- A size of @code{unlimited} means unlimited functions.
- @item show record function-call-history-size
- Show how many functions to print in the
- @code{record function-call-history} command.
- @end table
- @node Stack
- @chapter Examining the Stack
- When your program has stopped, the first thing you need to know is where it
- stopped and how it got there.
- @cindex call stack
- Each time your program performs a function call, information about the call
- is generated.
- That information includes the location of the call in your program,
- the arguments of the call,
- and the local variables of the function being called.
- The information is saved in a block of data called a @dfn{stack frame}.
- The stack frames are allocated in a region of memory called the @dfn{call
- stack}.
- When your program stops, the @value{GDBN} commands for examining the
- stack allow you to see all of this information.
- @cindex selected frame
- One of the stack frames is @dfn{selected} by @value{GDBN} and many
- @value{GDBN} commands refer implicitly to the selected frame. In
- particular, whenever you ask @value{GDBN} for the value of a variable in
- your program, the value is found in the selected frame. There are
- special @value{GDBN} commands to select whichever frame you are
- interested in. @xref{Selection, ,Selecting a Frame}.
- When your program stops, @value{GDBN} automatically selects the
- currently executing frame and describes it briefly, similar to the
- @code{frame} command (@pxref{Frame Info, ,Information about a Frame}).
- @menu
- * Frames:: Stack frames
- * Backtrace:: Backtraces
- * Selection:: Selecting a frame
- * Frame Info:: Information on a frame
- * Frame Apply:: Applying a command to several frames
- * Frame Filter Management:: Managing frame filters
- @end menu
- @node Frames
- @section Stack Frames
- @cindex frame, definition
- @cindex stack frame
- The call stack is divided up into contiguous pieces called @dfn{stack
- frames}, or @dfn{frames} for short; each frame is the data associated
- with one call to one function. The frame contains the arguments given
- to the function, the function's local variables, and the address at
- which the function is executing.
- @cindex initial frame
- @cindex outermost frame
- @cindex innermost frame
- When your program is started, the stack has only one frame, that of the
- function @code{main}. This is called the @dfn{initial} frame or the
- @dfn{outermost} frame. Each time a function is called, a new frame is
- made. Each time a function returns, the frame for that function invocation
- is eliminated. If a function is recursive, there can be many frames for
- the same function. The frame for the function in which execution is
- actually occurring is called the @dfn{innermost} frame. This is the most
- recently created of all the stack frames that still exist.
- @cindex frame pointer
- Inside your program, stack frames are identified by their addresses. A
- stack frame consists of many bytes, each of which has its own address; each
- kind of computer has a convention for choosing one byte whose
- address serves as the address of the frame. Usually this address is kept
- in a register called the @dfn{frame pointer register}
- (@pxref{Registers, $fp}) while execution is going on in that frame.
- @cindex frame level
- @cindex frame number
- @value{GDBN} labels each existing stack frame with a @dfn{level}, a
- number that is zero for the innermost frame, one for the frame that
- called it, and so on upward. These level numbers give you a way of
- designating stack frames in @value{GDBN} commands. The terms
- @dfn{frame number} and @dfn{frame level} can be used interchangeably to
- describe this number.
- @c The -fomit-frame-pointer below perennially causes hbox overflow
- @c underflow problems.
- @cindex frameless execution
- Some compilers provide a way to compile functions so that they operate
- without stack frames. (For example, the @value{NGCC} option
- @smallexample
- @samp{-fomit-frame-pointer}
- @end smallexample
- generates functions without a frame.)
- This is occasionally done with heavily used library functions to save
- the frame setup time. @value{GDBN} has limited facilities for dealing
- with these function invocations. If the innermost function invocation
- has no stack frame, @value{GDBN} nevertheless regards it as though
- it had a separate frame, which is numbered zero as usual, allowing
- correct tracing of the function call chain. However, @value{GDBN} has
- no provision for frameless functions elsewhere in the stack.
- @node Backtrace
- @section Backtraces
- @cindex traceback
- @cindex call stack traces
- A backtrace is a summary of how your program got where it is. It shows one
- line per frame, for many frames, starting with the currently executing
- frame (frame zero), followed by its caller (frame one), and on up the
- stack.
- @anchor{backtrace-command}
- @kindex backtrace
- @kindex bt @r{(@code{backtrace})}
- To print a backtrace of the entire stack, use the @code{backtrace}
- command, or its alias @code{bt}. This command will print one line per
- frame for frames in the stack. By default, all stack frames are
- printed. You can stop the backtrace at any time by typing the system
- interrupt character, normally @kbd{Ctrl-c}.
- @table @code
- @item backtrace [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}]
- @itemx bt [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}]
- Print the backtrace of the entire stack.
- The optional @var{count} can be one of the following:
- @table @code
- @item @var{n}
- @itemx @var{n}
- Print only the innermost @var{n} frames, where @var{n} is a positive
- number.
- @item -@var{n}
- @itemx -@var{n}
- Print only the outermost @var{n} frames, where @var{n} is a positive
- number.
- @end table
- Options:
- @table @code
- @item -full
- Print the values of the local variables also. This can be combined
- with the optional @var{count} to limit the number of frames shown.
- @item -no-filters
- Do not run Python frame filters on this backtrace. @xref{Frame
- Filter API}, for more information. Additionally use @ref{disable
- frame-filter all} to turn off all frame filters. This is only
- relevant when @value{GDBN} has been configured with @code{Python}
- support.
- @item -hide
- A Python frame filter might decide to ``elide'' some frames. Normally
- such elided frames are still printed, but they are indented relative
- to the filtered frames that cause them to be elided. The @code{-hide}
- option causes elided frames to not be printed at all.
- @end table
- The @code{backtrace} command also supports a number of options that
- allow overriding relevant global print settings as set by @code{set
- backtrace} and @code{set print} subcommands:
- @table @code
- @item -past-main [@code{on}|@code{off}]
- Set whether backtraces should continue past @code{main}. Related setting:
- @ref{set backtrace past-main}.
- @item -past-entry [@code{on}|@code{off}]
- Set whether backtraces should continue past the entry point of a program.
- Related setting: @ref{set backtrace past-entry}.
- @item -entry-values @code{no}|@code{only}|@code{preferred}|@code{if-needed}|@code{both}|@code{compact}|@code{default}
- Set printing of function arguments at function entry.
- Related setting: @ref{set print entry-values}.
- @item -frame-arguments @code{all}|@code{scalars}|@code{none}
- Set printing of non-scalar frame arguments.
- Related setting: @ref{set print frame-arguments}.
- @item -raw-frame-arguments [@code{on}|@code{off}]
- Set whether to print frame arguments in raw form.
- Related setting: @ref{set print raw-frame-arguments}.
- @item -frame-info @code{auto}|@code{source-line}|@code{location}|@code{source-and-location}|@code{location-and-address}|@code{short-location}
- Set printing of frame information.
- Related setting: @ref{set print frame-info}.
- @end table
- The optional @var{qualifier} is maintained for backward compatibility.
- It can be one of the following:
- @table @code
- @item full
- Equivalent to the @code{-full} option.
- @item no-filters
- Equivalent to the @code{-no-filters} option.
- @item hide
- Equivalent to the @code{-hide} option.
- @end table
- @end table
- @kindex where
- @kindex info stack
- The names @code{where} and @code{info stack} (abbreviated @code{info s})
- are additional aliases for @code{backtrace}.
- @cindex multiple threads, backtrace
- In a multi-threaded program, @value{GDBN} by default shows the
- backtrace only for the current thread. To display the backtrace for
- several or all of the threads, use the command @code{thread apply}
- (@pxref{Threads, thread apply}). For example, if you type @kbd{thread
- apply all backtrace}, @value{GDBN} will display the backtrace for all
- the threads; this is handy when you debug a core dump of a
- multi-threaded program.
- Each line in the backtrace shows the frame number and the function name.
- The program counter value is also shown---unless you use @code{set
- print address off}. The backtrace also shows the source file name and
- line number, as well as the arguments to the function. The program
- counter value is omitted if it is at the beginning of the code for that
- line number.
- Here is an example of a backtrace. It was made with the command
- @samp{bt 3}, so it shows the innermost three frames.
- @smallexample
- @group
- #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
- at builtin.c:993
- #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
- #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
- at macro.c:71
- (More stack frames follow...)
- @end group
- @end smallexample
- @noindent
- The display for frame zero does not begin with a program counter
- value, indicating that your program has stopped at the beginning of the
- code for line @code{993} of @code{builtin.c}.
- @noindent
- The value of parameter @code{data} in frame 1 has been replaced by
- @code{@dots{}}. By default, @value{GDBN} prints the value of a parameter
- only if it is a scalar (integer, pointer, enumeration, etc). See command
- @kbd{set print frame-arguments} in @ref{Print Settings} for more details
- on how to configure the way function parameter values are printed.
- The command @kbd{set print frame-info} (@pxref{Print Settings}) controls
- what frame information is printed.
- @cindex optimized out, in backtrace
- @cindex function call arguments, optimized out
- If your program was compiled with optimizations, some compilers will
- optimize away arguments passed to functions if those arguments are
- never used after the call. Such optimizations generate code that
- passes arguments through registers, but doesn't store those arguments
- in the stack frame. @value{GDBN} has no way of displaying such
- arguments in stack frames other than the innermost one. Here's what
- such a backtrace might look like:
- @smallexample
- @group
- #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
- at builtin.c:993
- #1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242
- #2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08)
- at macro.c:71
- (More stack frames follow...)
- @end group
- @end smallexample
- @noindent
- The values of arguments that were not saved in their stack frames are
- shown as @samp{<optimized out>}.
- If you need to display the values of such optimized-out arguments,
- either deduce that from other variables whose values depend on the one
- you are interested in, or recompile without optimizations.
- @cindex backtrace beyond @code{main} function
- @cindex program entry point
- @cindex startup code, and backtrace
- Most programs have a standard user entry point---a place where system
- libraries and startup code transition into user code. For C this is
- @code{main}@footnote{
- Note that embedded programs (the so-called ``free-standing''
- environment) are not required to have a @code{main} function as the
- entry point. They could even have multiple entry points.}.
- When @value{GDBN} finds the entry function in a backtrace
- it will terminate the backtrace, to avoid tracing into highly
- system-specific (and generally uninteresting) code.
- If you need to examine the startup code, or limit the number of levels
- in a backtrace, you can change this behavior:
- @table @code
- @item set backtrace past-main
- @itemx set backtrace past-main on
- @anchor{set backtrace past-main}
- @kindex set backtrace
- Backtraces will continue past the user entry point.
- @item set backtrace past-main off
- Backtraces will stop when they encounter the user entry point. This is the
- default.
- @item show backtrace past-main
- @kindex show backtrace
- Display the current user entry point backtrace policy.
- @item set backtrace past-entry
- @itemx set backtrace past-entry on
- @anchor{set backtrace past-entry}
- Backtraces will continue past the internal entry point of an application.
- This entry point is encoded by the linker when the application is built,
- and is likely before the user entry point @code{main} (or equivalent) is called.
- @item set backtrace past-entry off
- Backtraces will stop when they encounter the internal entry point of an
- application. This is the default.
- @item show backtrace past-entry
- Display the current internal entry point backtrace policy.
- @item set backtrace limit @var{n}
- @itemx set backtrace limit 0
- @itemx set backtrace limit unlimited
- @anchor{set backtrace limit}
- @cindex backtrace limit
- Limit the backtrace to @var{n} levels. A value of @code{unlimited}
- or zero means unlimited levels.
- @item show backtrace limit
- Display the current limit on backtrace levels.
- @end table
- You can control how file names are displayed.
- @table @code
- @item set filename-display
- @itemx set filename-display relative
- @cindex filename-display
- Display file names relative to the compilation directory. This is the default.
- @item set filename-display basename
- Display only basename of a filename.
- @item set filename-display absolute
- Display an absolute filename.
- @item show filename-display
- Show the current way to display filenames.
- @end table
- @node Selection
- @section Selecting a Frame
- Most commands for examining the stack and other data in your program work on
- whichever stack frame is selected at the moment. Here are the commands for
- selecting a stack frame; all of them finish by printing a brief description
- of the stack frame just selected.
- @table @code
- @kindex frame@r{, selecting}
- @kindex f @r{(@code{frame})}
- @item frame @r{[} @var{frame-selection-spec} @r{]}
- @item f @r{[} @var{frame-selection-spec} @r{]}
- The @command{frame} command allows different stack frames to be
- selected. The @var{frame-selection-spec} can be any of the following:
- @table @code
- @kindex frame level
- @item @var{num}
- @item level @var{num}
- Select frame level @var{num}. Recall that frame zero is the innermost
- (currently executing) frame, frame one is the frame that called the
- innermost one, and so on. The highest level frame is usually the one
- for @code{main}.
- As this is the most common method of navigating the frame stack, the
- string @command{level} can be omitted. For example, the following two
- commands are equivalent:
- @smallexample
- (@value{GDBP}) frame 3
- (@value{GDBP}) frame level 3
- @end smallexample
- @kindex frame address
- @item address @var{stack-address}
- Select the frame with stack address @var{stack-address}. The
- @var{stack-address} for a frame can be seen in the output of
- @command{info frame}, for example:
- @smallexample
- (gdb) info frame
- Stack level 1, frame at 0x7fffffffda30:
- rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
- tail call frame, caller of frame at 0x7fffffffda30
- source language c++.
- Arglist at unknown address.
- Locals at unknown address, Previous frame's sp is 0x7fffffffda30
- @end smallexample
- The @var{stack-address} for this frame is @code{0x7fffffffda30} as
- indicated by the line:
- @smallexample
- Stack level 1, frame at 0x7fffffffda30:
- @end smallexample
- @kindex frame function
- @item function @var{function-name}
- Select the stack frame for function @var{function-name}. If there are
- multiple stack frames for function @var{function-name} then the inner
- most stack frame is selected.
- @kindex frame view
- @item view @var{stack-address} @r{[} @var{pc-addr} @r{]}
- View a frame that is not part of @value{GDBN}'s backtrace. The frame
- viewed has stack address @var{stack-addr}, and optionally, a program
- counter address of @var{pc-addr}.
- This is useful mainly if the chaining of stack frames has been
- damaged by a bug, making it impossible for @value{GDBN} to assign
- numbers properly to all frames. In addition, this can be useful
- when your program has multiple stacks and switches between them.
- When viewing a frame outside the current backtrace using
- @command{frame view} then you can always return to the original
- stack using one of the previous stack frame selection instructions,
- for example @command{frame level 0}.
- @end table
- @kindex up
- @item up @var{n}
- Move @var{n} frames up the stack; @var{n} defaults to 1. For positive
- numbers @var{n}, this advances toward the outermost frame, to higher
- frame numbers, to frames that have existed longer.
- @kindex down
- @kindex do @r{(@code{down})}
- @item down @var{n}
- Move @var{n} frames down the stack; @var{n} defaults to 1. For
- positive numbers @var{n}, this advances toward the innermost frame, to
- lower frame numbers, to frames that were created more recently.
- You may abbreviate @code{down} as @code{do}.
- @end table
- All of these commands end by printing two lines of output describing the
- frame. The first line shows the frame number, the function name, the
- arguments, and the source file and line number of execution in that
- frame. The second line shows the text of that source line.
- @need 1000
- For example:
- @smallexample
- @group
- (@value{GDBP}) up
- #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
- at env.c:10
- 10 read_input_file (argv[i]);
- @end group
- @end smallexample
- After such a printout, the @code{list} command with no arguments
- prints ten lines centered on the point of execution in the frame.
- You can also edit the program at the point of execution with your favorite
- editing program by typing @code{edit}.
- @xref{List, ,Printing Source Lines},
- for details.
- @table @code
- @kindex select-frame
- @item select-frame @r{[} @var{frame-selection-spec} @r{]}
- The @code{select-frame} command is a variant of @code{frame} that does
- not display the new frame after selecting it. This command is
- intended primarily for use in @value{GDBN} command scripts, where the
- output might be unnecessary and distracting. The
- @var{frame-selection-spec} is as for the @command{frame} command
- described in @ref{Selection, ,Selecting a Frame}.
- @kindex down-silently
- @kindex up-silently
- @item up-silently @var{n}
- @itemx down-silently @var{n}
- These two commands are variants of @code{up} and @code{down},
- respectively; they differ in that they do their work silently, without
- causing display of the new frame. They are intended primarily for use
- in @value{GDBN} command scripts, where the output might be unnecessary and
- distracting.
- @end table
- @node Frame Info
- @section Information About a Frame
- There are several other commands to print information about the selected
- stack frame.
- @table @code
- @item frame
- @itemx f
- When used without any argument, this command does not change which
- frame is selected, but prints a brief description of the currently
- selected stack frame. It can be abbreviated @code{f}. With an
- argument, this command is used to select a stack frame.
- @xref{Selection, ,Selecting a Frame}.
- @kindex info frame
- @kindex info f @r{(@code{info frame})}
- @item info frame
- @itemx info f
- This command prints a verbose description of the selected stack frame,
- including:
- @itemize @bullet
- @item
- the address of the frame
- @item
- the address of the next frame down (called by this frame)
- @item
- the address of the next frame up (caller of this frame)
- @item
- the language in which the source code corresponding to this frame is written
- @item
- the address of the frame's arguments
- @item
- the address of the frame's local variables
- @item
- the program counter saved in it (the address of execution in the caller frame)
- @item
- which registers were saved in the frame
- @end itemize
- @noindent The verbose description is useful when
- something has gone wrong that has made the stack format fail to fit
- the usual conventions.
- @item info frame @r{[} @var{frame-selection-spec} @r{]}
- @itemx info f @r{[} @var{frame-selection-spec} @r{]}
- Print a verbose description of the frame selected by
- @var{frame-selection-spec}. The @var{frame-selection-spec} is the
- same as for the @command{frame} command (@pxref{Selection, ,Selecting
- a Frame}). The selected frame remains unchanged by this command.
- @kindex info args
- @item info args [-q]
- Print the arguments of the selected frame, each on a separate line.
- The optional flag @samp{-q}, which stands for @samp{quiet}, disables
- printing header information and messages explaining why no argument
- have been printed.
- @item info args [-q] [-t @var{type_regexp}] [@var{regexp}]
- Like @kbd{info args}, but only print the arguments selected
- with the provided regexp(s).
- If @var{regexp} is provided, print only the arguments whose names
- match the regular expression @var{regexp}.
- If @var{type_regexp} is provided, print only the arguments whose
- types, as printed by the @code{whatis} command, match
- the regular expression @var{type_regexp}.
- If @var{type_regexp} contains space(s), it should be enclosed in
- quote characters. If needed, use backslash to escape the meaning
- of special characters or quotes.
- If both @var{regexp} and @var{type_regexp} are provided, an argument
- is printed only if its name matches @var{regexp} and its type matches
- @var{type_regexp}.
- @item info locals [-q]
- @kindex info locals
- Print the local variables of the selected frame, each on a separate
- line. These are all variables (declared either static or automatic)
- accessible at the point of execution of the selected frame.
- The optional flag @samp{-q}, which stands for @samp{quiet}, disables
- printing header information and messages explaining why no local variables
- have been printed.
- @item info locals [-q] [-t @var{type_regexp}] [@var{regexp}]
- Like @kbd{info locals}, but only print the local variables selected
- with the provided regexp(s).
- If @var{regexp} is provided, print only the local variables whose names
- match the regular expression @var{regexp}.
- If @var{type_regexp} is provided, print only the local variables whose
- types, as printed by the @code{whatis} command, match
- the regular expression @var{type_regexp}.
- If @var{type_regexp} contains space(s), it should be enclosed in
- quote characters. If needed, use backslash to escape the meaning
- of special characters or quotes.
- If both @var{regexp} and @var{type_regexp} are provided, a local variable
- is printed only if its name matches @var{regexp} and its type matches
- @var{type_regexp}.
- The command @kbd{info locals -q -t @var{type_regexp}} can usefully be
- combined with the commands @kbd{frame apply} and @kbd{thread apply}.
- For example, your program might use Resource Acquisition Is
- Initialization types (RAII) such as @code{lock_something_t}: each
- local variable of type @code{lock_something_t} automatically places a
- lock that is destroyed when the variable goes out of scope. You can
- then list all acquired locks in your program by doing
- @smallexample
- thread apply all -s frame apply all -s info locals -q -t lock_something_t
- @end smallexample
- @noindent
- or the equivalent shorter form
- @smallexample
- tfaas i lo -q -t lock_something_t
- @end smallexample
- @end table
- @node Frame Apply
- @section Applying a Command to Several Frames.
- @kindex frame apply
- @cindex apply command to several frames
- @table @code
- @item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{option}]@dots{} @var{command}
- The @code{frame apply} command allows you to apply the named
- @var{command} to one or more frames.
- @table @code
- @item @code{all}
- Specify @code{all} to apply @var{command} to all frames.
- @item @var{count}
- Use @var{count} to apply @var{command} to the innermost @var{count}
- frames, where @var{count} is a positive number.
- @item @var{-count}
- Use @var{-count} to apply @var{command} to the outermost @var{count}
- frames, where @var{count} is a positive number.
- @item @code{level}
- Use @code{level} to apply @var{command} to the set of frames identified
- by the @var{level} list. @var{level} is a frame level or a range of frame
- levels as @var{level1}-@var{level2}. The frame level is the number shown
- in the first field of the @samp{backtrace} command output.
- E.g., @samp{2-4 6-8 3} indicates to apply @var{command} for the frames
- at levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3.
- @end table
- Note that the frames on which @code{frame apply} applies a command are
- also influenced by the @code{set backtrace} settings such as @code{set
- backtrace past-main} and @code{set backtrace limit N}.
- @xref{Backtrace,,Backtraces}.
- The @code{frame apply} command also supports a number of options that
- allow overriding relevant @code{set backtrace} settings:
- @table @code
- @item -past-main [@code{on}|@code{off}]
- Whether backtraces should continue past @code{main}.
- Related setting: @ref{set backtrace past-main}.
- @item -past-entry [@code{on}|@code{off}]
- Whether backtraces should continue past the entry point of a program.
- Related setting: @ref{set backtrace past-entry}.
- @end table
- By default, @value{GDBN} displays some frame information before the
- output produced by @var{command}, and an error raised during the
- execution of a @var{command} will abort @code{frame apply}. The
- following options can be used to fine-tune these behaviors:
- @table @code
- @item -c
- The flag @code{-c}, which stands for @samp{continue}, causes any
- errors in @var{command} to be displayed, and the execution of
- @code{frame apply} then continues.
- @item -s
- The flag @code{-s}, which stands for @samp{silent}, causes any errors
- or empty output produced by a @var{command} to be silently ignored.
- That is, the execution continues, but the frame information and errors
- are not printed.
- @item -q
- The flag @code{-q} (@samp{quiet}) disables printing the frame
- information.
- @end table
- The following example shows how the flags @code{-c} and @code{-s} are
- working when applying the command @code{p j} to all frames, where
- variable @code{j} can only be successfully printed in the outermost
- @code{#1 main} frame.
- @smallexample
- @group
- (gdb) frame apply all p j
- #0 some_function (i=5) at fun.c:4
- No symbol "j" in current context.
- (gdb) frame apply all -c p j
- #0 some_function (i=5) at fun.c:4
- No symbol "j" in current context.
- #1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
- $1 = 5
- (gdb) frame apply all -s p j
- #1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
- $2 = 5
- (gdb)
- @end group
- @end smallexample
- By default, @samp{frame apply}, prints the frame location
- information before the command output:
- @smallexample
- @group
- (gdb) frame apply all p $sp
- #0 some_function (i=5) at fun.c:4
- $4 = (void *) 0xffffd1e0
- #1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
- $5 = (void *) 0xffffd1f0
- (gdb)
- @end group
- @end smallexample
- If the flag @code{-q} is given, no frame information is printed:
- @smallexample
- @group
- (gdb) frame apply all -q p $sp
- $12 = (void *) 0xffffd1e0
- $13 = (void *) 0xffffd1f0
- (gdb)
- @end group
- @end smallexample
- @end table
- @table @code
- @kindex faas
- @cindex apply a command to all frames (ignoring errors and empty output)
- @item faas @var{command}
- Shortcut for @code{frame apply all -s @var{command}}.
- Applies @var{command} on all frames, ignoring errors and empty output.
- It can for example be used to print a local variable or a function
- argument without knowing the frame where this variable or argument
- is, using:
- @smallexample
- (@value{GDBP}) faas p some_local_var_i_do_not_remember_where_it_is
- @end smallexample
- The @code{faas} command accepts the same options as the @code{frame
- apply} command. @xref{Frame Apply,,frame apply}.
- Note that the command @code{tfaas @var{command}} applies @var{command}
- on all frames of all threads. See @xref{Threads,,Threads}.
- @end table
- @node Frame Filter Management
- @section Management of Frame Filters.
- @cindex managing frame filters
- Frame filters are Python based utilities to manage and decorate the
- output of frames. @xref{Frame Filter API}, for further information.
- Managing frame filters is performed by several commands available
- within @value{GDBN}, detailed here.
- @table @code
- @kindex info frame-filter
- @item info frame-filter
- Print a list of installed frame filters from all dictionaries, showing
- their name, priority and enabled status.
- @kindex disable frame-filter
- @anchor{disable frame-filter all}
- @item disable frame-filter @var{filter-dictionary} @var{filter-name}
- Disable a frame filter in the dictionary matching
- @var{filter-dictionary} and @var{filter-name}. The
- @var{filter-dictionary} may be @code{all}, @code{global},
- @code{progspace}, or the name of the object file where the frame filter
- dictionary resides. When @code{all} is specified, all frame filters
- across all dictionaries are disabled. The @var{filter-name} is the name
- of the frame filter and is used when @code{all} is not the option for
- @var{filter-dictionary}. A disabled frame-filter is not deleted, it
- may be enabled again later.
- @kindex enable frame-filter
- @item enable frame-filter @var{filter-dictionary} @var{filter-name}
- Enable a frame filter in the dictionary matching
- @var{filter-dictionary} and @var{filter-name}. The
- @var{filter-dictionary} may be @code{all}, @code{global},
- @code{progspace} or the name of the object file where the frame filter
- dictionary resides. When @code{all} is specified, all frame filters across
- all dictionaries are enabled. The @var{filter-name} is the name of the frame
- filter and is used when @code{all} is not the option for
- @var{filter-dictionary}.
- Example:
- @smallexample
- (gdb) info frame-filter
- global frame-filters:
- Priority Enabled Name
- 1000 No PrimaryFunctionFilter
- 100 Yes Reverse
- progspace /build/test frame-filters:
- Priority Enabled Name
- 100 Yes ProgspaceFilter
- objfile /build/test frame-filters:
- Priority Enabled Name
- 999 Yes BuildProgramFilter
- (gdb) disable frame-filter /build/test BuildProgramFilter
- (gdb) info frame-filter
- global frame-filters:
- Priority Enabled Name
- 1000 No PrimaryFunctionFilter
- 100 Yes Reverse
- progspace /build/test frame-filters:
- Priority Enabled Name
- 100 Yes ProgspaceFilter
- objfile /build/test frame-filters:
- Priority Enabled Name
- 999 No BuildProgramFilter
- (gdb) enable frame-filter global PrimaryFunctionFilter
- (gdb) info frame-filter
- global frame-filters:
- Priority Enabled Name
- 1000 Yes PrimaryFunctionFilter
- 100 Yes Reverse
- progspace /build/test frame-filters:
- Priority Enabled Name
- 100 Yes ProgspaceFilter
- objfile /build/test frame-filters:
- Priority Enabled Name
- 999 No BuildProgramFilter
- @end smallexample
- @kindex set frame-filter priority
- @item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority}
- Set the @var{priority} of a frame filter in the dictionary matching
- @var{filter-dictionary}, and the frame filter name matching
- @var{filter-name}. The @var{filter-dictionary} may be @code{global},
- @code{progspace} or the name of the object file where the frame filter
- dictionary resides. The @var{priority} is an integer.
- @kindex show frame-filter priority
- @item show frame-filter priority @var{filter-dictionary} @var{filter-name}
- Show the @var{priority} of a frame filter in the dictionary matching
- @var{filter-dictionary}, and the frame filter name matching
- @var{filter-name}. The @var{filter-dictionary} may be @code{global},
- @code{progspace} or the name of the object file where the frame filter
- dictionary resides.
- Example:
- @smallexample
- (gdb) info frame-filter
- global frame-filters:
- Priority Enabled Name
- 1000 Yes PrimaryFunctionFilter
- 100 Yes Reverse
- progspace /build/test frame-filters:
- Priority Enabled Name
- 100 Yes ProgspaceFilter
- objfile /build/test frame-filters:
- Priority Enabled Name
- 999 No BuildProgramFilter
- (gdb) set frame-filter priority global Reverse 50
- (gdb) info frame-filter
- global frame-filters:
- Priority Enabled Name
- 1000 Yes PrimaryFunctionFilter
- 50 Yes Reverse
- progspace /build/test frame-filters:
- Priority Enabled Name
- 100 Yes ProgspaceFilter
- objfile /build/test frame-filters:
- Priority Enabled Name
- 999 No BuildProgramFilter
- @end smallexample
- @end table
- @node Source
- @chapter Examining Source Files
- @value{GDBN} can print parts of your program's source, since the debugging
- information recorded in the program tells @value{GDBN} what source files were
- used to build it. When your program stops, @value{GDBN} spontaneously prints
- the line where it stopped. Likewise, when you select a stack frame
- (@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where
- execution in that frame has stopped. You can print other portions of
- source files by explicit command.
- If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may
- prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
- @value{GDBN} under @sc{gnu} Emacs}.
- @menu
- * List:: Printing source lines
- * Specify Location:: How to specify code locations
- * Edit:: Editing source files
- * Search:: Searching source files
- * Source Path:: Specifying source directories
- * Machine Code:: Source and machine code
- * Disable Reading Source:: Disable Reading Source Code
- @end menu
- @node List
- @section Printing Source Lines
- @kindex list
- @kindex l @r{(@code{list})}
- To print lines from a source file, use the @code{list} command
- (abbreviated @code{l}). By default, ten lines are printed.
- There are several ways to specify what part of the file you want to
- print; see @ref{Specify Location}, for the full list.
- Here are the forms of the @code{list} command most commonly used:
- @table @code
- @item list @var{linenum}
- Print lines centered around line number @var{linenum} in the
- current source file.
- @item list @var{function}
- Print lines centered around the beginning of function
- @var{function}.
- @item list
- Print more lines. If the last lines printed were printed with a
- @code{list} command, this prints lines following the last lines
- printed; however, if the last line printed was a solitary line printed
- as part of displaying a stack frame (@pxref{Stack, ,Examining the
- Stack}), this prints lines centered around that line.
- @item list -
- Print lines just before the lines last printed.
- @end table
- @cindex @code{list}, how many lines to display
- By default, @value{GDBN} prints ten source lines with any of these forms of
- the @code{list} command. You can change this using @code{set listsize}:
- @table @code
- @kindex set listsize
- @item set listsize @var{count}
- @itemx set listsize unlimited
- Make the @code{list} command display @var{count} source lines (unless
- the @code{list} argument explicitly specifies some other number).
- Setting @var{count} to @code{unlimited} or 0 means there's no limit.
- @kindex show listsize
- @item show listsize
- Display the number of lines that @code{list} prints.
- @end table
- Repeating a @code{list} command with @key{RET} discards the argument,
- so it is equivalent to typing just @code{list}. This is more useful
- than listing the same lines again. An exception is made for an
- argument of @samp{-}; that argument is preserved in repetition so that
- each repetition moves up in the source file.
- In general, the @code{list} command expects you to supply zero, one or two
- @dfn{locations}. Locations specify source lines; there are several ways
- of writing them (@pxref{Specify Location}), but the effect is always
- to specify some source line.
- Here is a complete description of the possible arguments for @code{list}:
- @table @code
- @item list @var{location}
- Print lines centered around the line specified by @var{location}.
- @item list @var{first},@var{last}
- Print lines from @var{first} to @var{last}. Both arguments are
- locations. When a @code{list} command has two locations, and the
- source file of the second location is omitted, this refers to
- the same source file as the first location.
- @item list ,@var{last}
- Print lines ending with @var{last}.
- @item list @var{first},
- Print lines starting with @var{first}.
- @item list +
- Print lines just after the lines last printed.
- @item list -
- Print lines just before the lines last printed.
- @item list
- As described in the preceding table.
- @end table
- @node Specify Location
- @section Specifying a Location
- @cindex specifying location
- @cindex location
- @cindex source location
- Several @value{GDBN} commands accept arguments that specify a location
- of your program's code. Since @value{GDBN} is a source-level
- debugger, a location usually specifies some line in the source code.
- Locations may be specified using three different formats:
- linespec locations, explicit locations, or address locations.
- @menu
- * Linespec Locations:: Linespec locations
- * Explicit Locations:: Explicit locations
- * Address Locations:: Address locations
- @end menu
- @node Linespec Locations
- @subsection Linespec Locations
- @cindex linespec locations
- A @dfn{linespec} is a colon-separated list of source location parameters such
- as file name, function name, etc. Here are all the different ways of
- specifying a linespec:
- @table @code
- @item @var{linenum}
- Specifies the line number @var{linenum} of the current source file.
- @item -@var{offset}
- @itemx +@var{offset}
- Specifies the line @var{offset} lines before or after the @dfn{current
- line}. For the @code{list} command, the current line is the last one
- printed; for the breakpoint commands, this is the line at which
- execution stopped in the currently selected @dfn{stack frame}
- (@pxref{Frames, ,Frames}, for a description of stack frames.) When
- used as the second of the two linespecs in a @code{list} command,
- this specifies the line @var{offset} lines up or down from the first
- linespec.
- @item @var{filename}:@var{linenum}
- Specifies the line @var{linenum} in the source file @var{filename}.
- If @var{filename} is a relative file name, then it will match any
- source file name with the same trailing components. For example, if
- @var{filename} is @samp{gcc/expr.c}, then it will match source file
- name of @file{/build/trunk/gcc/expr.c}, but not
- @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
- @item @var{function}
- Specifies the line that begins the body of the function @var{function}.
- For example, in C, this is the line with the open brace.
- By default, in C@t{++} and Ada, @var{function} is interpreted as
- specifying all functions named @var{function} in all scopes. For
- C@t{++}, this means in all namespaces and classes. For Ada, this
- means in all packages.
- For example, assuming a program with C@t{++} symbols named
- @code{A::B::func} and @code{B::func}, both commands @w{@kbd{break
- func}} and @w{@kbd{break B::func}} set a breakpoint on both symbols.
- Commands that accept a linespec let you override this with the
- @code{-qualified} option. For example, @w{@kbd{break -qualified
- func}} sets a breakpoint on a free-function named @code{func} ignoring
- any C@t{++} class methods and namespace functions called @code{func}.
- @xref{Explicit Locations}.
- @item @var{function}:@var{label}
- Specifies the line where @var{label} appears in @var{function}.
- @item @var{filename}:@var{function}
- Specifies the line that begins the body of the function @var{function}
- in the file @var{filename}. You only need the file name with a
- function name to avoid ambiguity when there are identically named
- functions in different source files.
- @item @var{label}
- Specifies the line at which the label named @var{label} appears
- in the function corresponding to the currently selected stack frame.
- If there is no current selected stack frame (for instance, if the inferior
- is not running), then @value{GDBN} will not search for a label.
- @cindex breakpoint at static probe point
- @item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
- The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
- applications to embed static probes. @xref{Static Probe Points}, for more
- information on finding and using static probes. This form of linespec
- specifies the location of such a static probe.
- If @var{objfile} is given, only probes coming from that shared library
- or executable matching @var{objfile} as a regular expression are considered.
- If @var{provider} is given, then only probes from that provider are considered.
- If several probes match the spec, @value{GDBN} will insert a breakpoint at
- each one of those probes.
- @end table
- @node Explicit Locations
- @subsection Explicit Locations
- @cindex explicit locations
- @dfn{Explicit locations} allow the user to directly specify the source
- location's parameters using option-value pairs.
- Explicit locations are useful when several functions, labels, or
- file names have the same name (base name for files) in the program's
- sources. In these cases, explicit locations point to the source
- line you meant more accurately and unambiguously. Also, using
- explicit locations might be faster in large programs.
- For example, the linespec @samp{foo:bar} may refer to a function @code{bar}
- defined in the file named @file{foo} or the label @code{bar} in a function
- named @code{foo}. @value{GDBN} must search either the file system or
- the symbol table to know.
- The list of valid explicit location options is summarized in the
- following table:
- @table @code
- @item -source @var{filename}
- The value specifies the source file name. To differentiate between
- files with the same base name, prepend as many directories as is necessary
- to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise
- @value{GDBN} will use the first file it finds with the given base
- name. This option requires the use of either @code{-function} or @code{-line}.
- @item -function @var{function}
- The value specifies the name of a function. Operations
- on function locations unmodified by other options (such as @code{-label}
- or @code{-line}) refer to the line that begins the body of the function.
- In C, for example, this is the line with the open brace.
- By default, in C@t{++} and Ada, @var{function} is interpreted as
- specifying all functions named @var{function} in all scopes. For
- C@t{++}, this means in all namespaces and classes. For Ada, this
- means in all packages.
- For example, assuming a program with C@t{++} symbols named
- @code{A::B::func} and @code{B::func}, both commands @w{@kbd{break
- -function func}} and @w{@kbd{break -function B::func}} set a
- breakpoint on both symbols.
- You can use the @kbd{-qualified} flag to override this (see below).
- @item -qualified
- This flag makes @value{GDBN} interpret a function name specified with
- @kbd{-function} as a complete fully-qualified name.
- For example, assuming a C@t{++} program with symbols named
- @code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified
- -function B::func}} command sets a breakpoint on @code{B::func}, only.
- (Note: the @kbd{-qualified} option can precede a linespec as well
- (@pxref{Linespec Locations}), so the particular example above could be
- simplified as @w{@kbd{break -qualified B::func}}.)
- @item -label @var{label}
- The value specifies the name of a label. When the function
- name is not specified, the label is searched in the function of the currently
- selected stack frame.
- @item -line @var{number}
- The value specifies a line offset for the location. The offset may either
- be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on
- the command. When specified without any other options, the line offset is
- relative to the current line.
- @end table
- Explicit location options may be abbreviated by omitting any non-unique
- trailing characters from the option name, e.g., @w{@kbd{break -s main.c -li 3}}.
- @node Address Locations
- @subsection Address Locations
- @cindex address locations
- @dfn{Address locations} indicate a specific program address. They have
- the generalized form *@var{address}.
- For line-oriented commands, such as @code{list} and @code{edit}, this
- specifies a source line that contains @var{address}. For @code{break} and
- other breakpoint-oriented commands, this can be used to set breakpoints in
- parts of your program which do not have debugging information or
- source files.
- Here @var{address} may be any expression valid in the current working
- language (@pxref{Languages, working language}) that specifies a code
- address. In addition, as a convenience, @value{GDBN} extends the
- semantics of expressions used in locations to cover several situations
- that frequently occur during debugging. Here are the various forms
- of @var{address}:
- @table @code
- @item @var{expression}
- Any expression valid in the current working language.
- @item @var{funcaddr}
- An address of a function or procedure derived from its name. In C,
- C@t{++}, Objective-C, Fortran, minimal, and assembly, this is
- simply the function's name @var{function} (and actually a special case
- of a valid expression). In Pascal and Modula-2, this is
- @code{&@var{function}}. In Ada, this is @code{@var{function}'Address}
- (although the Pascal form also works).
- This form specifies the address of the function's first instruction,
- before the stack frame and arguments have been set up.
- @item '@var{filename}':@var{funcaddr}
- Like @var{funcaddr} above, but also specifies the name of the source
- file explicitly. This is useful if the name of the function does not
- specify the function unambiguously, e.g., if there are several
- functions with identical names in different source files.
- @end table
- @node Edit
- @section Editing Source Files
- @cindex editing source files
- @kindex edit
- @kindex e @r{(@code{edit})}
- To edit the lines in a source file, use the @code{edit} command.
- The editing program of your choice
- is invoked with the current line set to
- the active line in the program.
- Alternatively, there are several ways to specify what part of the file you
- want to print if you want to see other parts of the program:
- @table @code
- @item edit @var{location}
- Edit the source file specified by @code{location}. Editing starts at
- that @var{location}, e.g., at the specified source line of the
- specified file. @xref{Specify Location}, for all the possible forms
- of the @var{location} argument; here are the forms of the @code{edit}
- command most commonly used:
- @table @code
- @item edit @var{number}
- Edit the current source file with @var{number} as the active line number.
- @item edit @var{function}
- Edit the file containing @var{function} at the beginning of its definition.
- @end table
- @end table
- @subsection Choosing your Editor
- You can customize @value{GDBN} to use any editor you want
- @footnote{
- The only restriction is that your editor (say @code{ex}), recognizes the
- following command-line syntax:
- @smallexample
- ex +@var{number} file
- @end smallexample
- The optional numeric value +@var{number} specifies the number of the line in
- the file where to start editing.}.
- By default, it is @file{@value{EDITOR}}, but you can change this
- by setting the environment variable @env{EDITOR} before using
- @value{GDBN}. For example, to configure @value{GDBN} to use the
- @code{vi} editor, you could use these commands with the @code{sh} shell:
- @smallexample
- EDITOR=/usr/bin/vi
- export EDITOR
- gdb @dots{}
- @end smallexample
- or in the @code{csh} shell,
- @smallexample
- setenv EDITOR /usr/bin/vi
- gdb @dots{}
- @end smallexample
- @node Search
- @section Searching Source Files
- @cindex searching source files
- There are two commands for searching through the current source file for a
- regular expression.
- @table @code
- @kindex search
- @kindex forward-search
- @kindex fo @r{(@code{forward-search})}
- @item forward-search @var{regexp}
- @itemx search @var{regexp}
- The command @samp{forward-search @var{regexp}} checks each line,
- starting with the one following the last line listed, for a match for
- @var{regexp}. It lists the line that is found. You can use the
- synonym @samp{search @var{regexp}} or abbreviate the command name as
- @code{fo}.
- @kindex reverse-search
- @item reverse-search @var{regexp}
- The command @samp{reverse-search @var{regexp}} checks each line, starting
- with the one before the last line listed and going backward, for a match
- for @var{regexp}. It lists the line that is found. You can abbreviate
- this command as @code{rev}.
- @end table
- @node Source Path
- @section Specifying Source Directories
- @cindex source path
- @cindex directories for source files
- Executable programs sometimes do not record the directories of the source
- files from which they were compiled, just the names. Even when they do,
- the directories could be moved between the compilation and your debugging
- session. @value{GDBN} has a list of directories to search for source files;
- this is called the @dfn{source path}. Each time @value{GDBN} wants a source file,
- it tries all the directories in the list, in the order they are present
- in the list, until it finds a file with the desired name.
- For example, suppose an executable references the file
- @file{/usr/src/foo-1.0/lib/foo.c}, does not record a compilation
- directory, and the @dfn{source path} is @file{/mnt/cross}.
- @value{GDBN} would look for the source file in the following
- locations:
- @enumerate
- @item @file{/usr/src/foo-1.0/lib/foo.c}
- @item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c}
- @item @file{/mnt/cross/foo.c}
- @end enumerate
- If the source file is not present at any of the above locations then
- an error is printed. @value{GDBN} does not look up the parts of the
- source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
- Likewise, the subdirectories of the source path are not searched: if
- the source path is @file{/mnt/cross}, and the binary refers to
- @file{foo.c}, @value{GDBN} would not find it under
- @file{/mnt/cross/usr/src/foo-1.0/lib}.
- Plain file names, relative file names with leading directories, file
- names containing dots, etc.@: are all treated as described above,
- except that non-absolute file names are not looked up literally. If
- the @dfn{source path} is @file{/mnt/cross}, the source file is
- recorded as @file{../lib/foo.c}, and no compilation directory is
- recorded, then @value{GDBN} will search in the following locations:
- @enumerate
- @item @file{/mnt/cross/../lib/foo.c}
- @item @file{/mnt/cross/foo.c}
- @end enumerate
- @kindex cdir
- @kindex cwd
- @vindex $cdir@r{, convenience variable}
- @vindex $cwd@r{, convenience variable}
- @cindex compilation directory
- @cindex current directory
- @cindex working directory
- @cindex directory, current
- @cindex directory, compilation
- The @dfn{source path} will always include two special entries
- @samp{$cdir} and @samp{$cwd}, these refer to the compilation directory
- (if one is recorded) and the current working directory respectively.
- @samp{$cdir} causes @value{GDBN} to search within the compilation
- directory, if one is recorded in the debug information. If no
- compilation directory is recorded in the debug information then
- @samp{$cdir} is ignored.
- @samp{$cwd} is not the same as @samp{.}---the former tracks the
- current working directory as it changes during your @value{GDBN}
- session, while the latter is immediately expanded to the current
- directory at the time you add an entry to the source path.
- If a compilation directory is recorded in the debug information, and
- @value{GDBN} has not found the source file after the first search
- using @dfn{source path}, then @value{GDBN} will combine the
- compilation directory and the filename, and then search for the source
- file again using the @dfn{source path}.
- For example, if the executable records the source file as
- @file{/usr/src/foo-1.0/lib/foo.c}, the compilation directory is
- recorded as @file{/project/build}, and the @dfn{source path} is
- @file{/mnt/cross:$cdir:$cwd} while the current working directory of
- the @value{GDBN} session is @file{/home/user}, then @value{GDBN} will
- search for the source file in the following locations:
- @enumerate
- @item @file{/usr/src/foo-1.0/lib/foo.c}
- @item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c}
- @item @file{/project/build/usr/src/foo-1.0/lib/foo.c}
- @item @file{/home/user/usr/src/foo-1.0/lib/foo.c}
- @item @file{/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c}
- @item @file{/project/build/project/build/usr/src/foo-1.0/lib/foo.c}
- @item @file{/home/user/project/build/usr/src/foo-1.0/lib/foo.c}
- @item @file{/mnt/cross/foo.c}
- @item @file{/project/build/foo.c}
- @item @file{/home/user/foo.c}
- @end enumerate
- If the file name in the previous example had been recorded in the
- executable as a relative path rather than an absolute path, then the
- first look up would not have occurred, but all of the remaining steps
- would be similar.
- When searching for source files on MS-DOS and MS-Windows, where
- absolute paths start with a drive letter (e.g.@:
- @file{C:/project/foo.c}), @value{GDBN} will remove the drive letter
- from the file name before appending it to a search directory from
- @dfn{source path}; for instance if the executable references the
- source file @file{C:/project/foo.c} and @dfn{source path} is set to
- @file{D:/mnt/cross}, then @value{GDBN} will search in the following
- locations for the source file:
- @enumerate
- @item @file{C:/project/foo.c}
- @item @file{D:/mnt/cross/project/foo.c}
- @item @file{D:/mnt/cross/foo.c}
- @end enumerate
- Note that the executable search path is @emph{not} used to locate the
- source files.
- Whenever you reset or rearrange the source path, @value{GDBN} clears out
- any information it has cached about where source files are found and where
- each line is in the file.
- @kindex directory
- @kindex dir
- When you start @value{GDBN}, its source path includes only @samp{$cdir}
- and @samp{$cwd}, in that order.
- To add other directories, use the @code{directory} command.
- The search path is used to find both program source files and @value{GDBN}
- script files (read using the @samp{-command} option and @samp{source} command).
- In addition to the source path, @value{GDBN} provides a set of commands
- that manage a list of source path substitution rules. A @dfn{substitution
- rule} specifies how to rewrite source directories stored in the program's
- debug information in case the sources were moved to a different
- directory between compilation and debugging. A rule is made of
- two strings, the first specifying what needs to be rewritten in
- the path, and the second specifying how it should be rewritten.
- In @ref{set substitute-path}, we name these two parts @var{from} and
- @var{to} respectively. @value{GDBN} does a simple string replacement
- of @var{from} with @var{to} at the start of the directory part of the
- source file name, and uses that result instead of the original file
- name to look up the sources.
- Using the previous example, suppose the @file{foo-1.0} tree has been
- moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
- @value{GDBN} to replace @file{/usr/src} in all source path names with
- @file{/mnt/cross}. The first lookup will then be
- @file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
- of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
- substitution rule, use the @code{set substitute-path} command
- (@pxref{set substitute-path}).
- To avoid unexpected substitution results, a rule is applied only if the
- @var{from} part of the directory name ends at a directory separator.
- For instance, a rule substituting @file{/usr/source} into
- @file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but
- not to @file{/usr/sourceware/foo-2.0}. And because the substitution
- is applied only at the beginning of the directory name, this rule will
- not be applied to @file{/root/usr/source/baz.c} either.
- In many cases, you can achieve the same result using the @code{directory}
- command. However, @code{set substitute-path} can be more efficient in
- the case where the sources are organized in a complex tree with multiple
- subdirectories. With the @code{directory} command, you need to add each
- subdirectory of your project. If you moved the entire tree while
- preserving its internal organization, then @code{set substitute-path}
- allows you to direct the debugger to all the sources with one single
- command.
- @code{set substitute-path} is also more than just a shortcut command.
- The source path is only used if the file at the original location no
- longer exists. On the other hand, @code{set substitute-path} modifies
- the debugger behavior to look at the rewritten location instead. So, if
- for any reason a source file that is not relevant to your executable is
- located at the original location, a substitution rule is the only
- method available to point @value{GDBN} at the new location.
- @cindex @samp{--with-relocated-sources}
- @cindex default source path substitution
- You can configure a default source path substitution rule by
- configuring @value{GDBN} with the
- @samp{--with-relocated-sources=@var{dir}} option. The @var{dir}
- should be the name of a directory under @value{GDBN}'s configured
- prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and
- directory names in debug information under @var{dir} will be adjusted
- automatically if the installed @value{GDBN} is moved to a new
- location. This is useful if @value{GDBN}, libraries or executables
- with debug information and corresponding source code are being moved
- together.
- @table @code
- @item directory @var{dirname} @dots{}
- @item dir @var{dirname} @dots{}
- Add directory @var{dirname} to the front of the source path. Several
- directory names may be given to this command, separated by @samp{:}
- (@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as
- part of absolute file names) or
- whitespace. You may specify a directory that is already in the source
- path; this moves it forward, so @value{GDBN} searches it sooner.
- The special strings @samp{$cdir} (to refer to the compilation
- directory, if one is recorded), and @samp{$cwd} (to refer to the
- current working directory) can also be included in the list of
- directories @var{dirname}. Though these will already be in the source
- path they will be moved forward in the list so @value{GDBN} searches
- them sooner.
- @item directory
- Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
- @c RET-repeat for @code{directory} is explicitly disabled, but since
- @c repeating it would be a no-op we do not say that. (thanks to RMS)
- @item set directories @var{path-list}
- @kindex set directories
- Set the source path to @var{path-list}.
- @samp{$cdir:$cwd} are added if missing.
- @item show directories
- @kindex show directories
- Print the source path: show which directories it contains.
- @anchor{set substitute-path}
- @item set substitute-path @var{from} @var{to}
- @kindex set substitute-path
- Define a source path substitution rule, and add it at the end of the
- current list of existing substitution rules. If a rule with the same
- @var{from} was already defined, then the old rule is also deleted.
- For example, if the file @file{/foo/bar/baz.c} was moved to
- @file{/mnt/cross/baz.c}, then the command
- @smallexample
- (@value{GDBP}) set substitute-path /foo/bar /mnt/cross
- @end smallexample
- @noindent
- will tell @value{GDBN} to replace @samp{/foo/bar} with
- @samp{/mnt/cross}, which will allow @value{GDBN} to find the file
- @file{baz.c} even though it was moved.
- In the case when more than one substitution rule have been defined,
- the rules are evaluated one by one in the order where they have been
- defined. The first one matching, if any, is selected to perform
- the substitution.
- For instance, if we had entered the following commands:
- @smallexample
- (@value{GDBP}) set substitute-path /usr/src/include /mnt/include
- (@value{GDBP}) set substitute-path /usr/src /mnt/src
- @end smallexample
- @noindent
- @value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into
- @file{/mnt/include/defs.h} by using the first rule. However, it would
- use the second rule to rewrite @file{/usr/src/lib/foo.c} into
- @file{/mnt/src/lib/foo.c}.
- @item unset substitute-path [path]
- @kindex unset substitute-path
- If a path is specified, search the current list of substitution rules
- for a rule that would rewrite that path. Delete that rule if found.
- A warning is emitted by the debugger if no rule could be found.
- If no path is specified, then all substitution rules are deleted.
- @item show substitute-path [path]
- @kindex show substitute-path
- If a path is specified, then print the source path substitution rule
- which would rewrite that path, if any.
- If no path is specified, then print all existing source path substitution
- rules.
- @end table
- If your source path is cluttered with directories that are no longer of
- interest, @value{GDBN} may sometimes cause confusion by finding the wrong
- versions of source. You can correct the situation as follows:
- @enumerate
- @item
- Use @code{directory} with no argument to reset the source path to its default value.
- @item
- Use @code{directory} with suitable arguments to reinstall the
- directories you want in the source path. You can add all the
- directories in one command.
- @end enumerate
- @node Machine Code
- @section Source and Machine Code
- @cindex source line and its code address
- You can use the command @code{info line} to map source lines to program
- addresses (and vice versa), and the command @code{disassemble} to display
- a range of addresses as machine instructions. You can use the command
- @code{set disassemble-next-line} to set whether to disassemble next
- source line when execution stops. When run under @sc{gnu} Emacs
- mode, the @code{info line} command causes the arrow to point to the
- line specified. Also, @code{info line} prints addresses in symbolic form as
- well as hex.
- @table @code
- @kindex info line
- @item info line
- @itemx info line @var{location}
- Print the starting and ending addresses of the compiled code for
- source line @var{location}. You can specify source lines in any of
- the ways documented in @ref{Specify Location}. With no @var{location}
- information about the current source line is printed.
- @end table
- For example, we can use @code{info line} to discover the location of
- the object code for the first line of function
- @code{m4_changequote}:
- @smallexample
- (@value{GDBP}) info line m4_changequote
- Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \
- ends at 0x6350 <m4_changequote+4>.
- @end smallexample
- @noindent
- @cindex code address and its source line
- We can also inquire (using @code{*@var{addr}} as the form for
- @var{location}) what source line covers a particular address:
- @smallexample
- (@value{GDBP}) info line *0x63ff
- Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
- ends at 0x6404 <m4_changequote+184>.
- @end smallexample
- @cindex @code{$_} and @code{info line}
- @cindex @code{x} command, default address
- @kindex x@r{(examine), and} info line
- After @code{info line}, the default address for the @code{x} command
- is changed to the starting address of the line, so that @samp{x/i} is
- sufficient to begin examining the machine code (@pxref{Memory,
- ,Examining Memory}). Also, this address is saved as the value of the
- convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
- Variables}).
- @cindex info line, repeated calls
- After @code{info line}, using @code{info line} again without
- specifying a location will display information about the next source
- line.
- @table @code
- @kindex disassemble
- @cindex assembly instructions
- @cindex instructions, assembly
- @cindex machine instructions
- @cindex listing machine instructions
- @item disassemble
- @itemx disassemble /m
- @itemx disassemble /s
- @itemx disassemble /r
- This specialized command dumps a range of memory as machine
- instructions. It can also print mixed source+disassembly by specifying
- the @code{/m} or @code{/s} modifier and print the raw instructions in hex
- as well as in symbolic form by specifying the @code{/r} modifier.
- The default memory range is the function surrounding the
- program counter of the selected frame. A single argument to this
- command is a program counter value; @value{GDBN} dumps the function
- surrounding this value. When two arguments are given, they should
- be separated by a comma, possibly surrounded by whitespace. The
- arguments specify a range of addresses to dump, in one of two forms:
- @table @code
- @item @var{start},@var{end}
- the addresses from @var{start} (inclusive) to @var{end} (exclusive)
- @item @var{start},+@var{length}
- the addresses from @var{start} (inclusive) to
- @code{@var{start}+@var{length}} (exclusive).
- @end table
- @noindent
- When 2 arguments are specified, the name of the function is also
- printed (since there could be several functions in the given range).
- The argument(s) can be any expression yielding a numeric value, such as
- @samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}.
- If the range of memory being disassembled contains current program counter,
- the instruction at that location is shown with a @code{=>} marker.
- @end table
- The following example shows the disassembly of a range of addresses of
- HP PA-RISC 2.0 code:
- @smallexample
- (@value{GDBP}) disas 0x32c4, 0x32e4
- Dump of assembler code from 0x32c4 to 0x32e4:
- 0x32c4 <main+204>: addil 0,dp
- 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
- 0x32cc <main+212>: ldil 0x3000,r31
- 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
- 0x32d4 <main+220>: ldo 0(r31),rp
- 0x32d8 <main+224>: addil -0x800,dp
- 0x32dc <main+228>: ldo 0x588(r1),r26
- 0x32e0 <main+232>: ldil 0x3000,r31
- End of assembler dump.
- @end smallexample
- Here is an example showing mixed source+assembly for Intel x86
- with @code{/m} or @code{/s}, when the program is stopped just after
- function prologue in a non-optimized function with no inline code.
- @smallexample
- (@value{GDBP}) disas /m main
- Dump of assembler code for function main:
- 5 @{
- 0x08048330 <+0>: push %ebp
- 0x08048331 <+1>: mov %esp,%ebp
- 0x08048333 <+3>: sub $0x8,%esp
- 0x08048336 <+6>: and $0xfffffff0,%esp
- 0x08048339 <+9>: sub $0x10,%esp
- 6 printf ("Hello.\n");
- => 0x0804833c <+12>: movl $0x8048440,(%esp)
- 0x08048343 <+19>: call 0x8048284 <puts@@plt>
- 7 return 0;
- 8 @}
- 0x08048348 <+24>: mov $0x0,%eax
- 0x0804834d <+29>: leave
- 0x0804834e <+30>: ret
- End of assembler dump.
- @end smallexample
- The @code{/m} option is deprecated as its output is not useful when
- there is either inlined code or re-ordered code.
- The @code{/s} option is the preferred choice.
- Here is an example for AMD x86-64 showing the difference between
- @code{/m} output and @code{/s} output.
- This example has one inline function defined in a header file,
- and the code is compiled with @samp{-O2} optimization.
- Note how the @code{/m} output is missing the disassembly of
- several instructions that are present in the @code{/s} output.
- @file{foo.h}:
- @smallexample
- int
- foo (int a)
- @{
- if (a < 0)
- return a * 2;
- if (a == 0)
- return 1;
- return a + 10;
- @}
- @end smallexample
- @file{foo.c}:
- @smallexample
- #include "foo.h"
- volatile int x, y;
- int
- main ()
- @{
- x = foo (y);
- return 0;
- @}
- @end smallexample
- @smallexample
- (@value{GDBP}) disas /m main
- Dump of assembler code for function main:
- 5 @{
- 6 x = foo (y);
- 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y>
- 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x>
- 7 return 0;
- 8 @}
- 0x000000000040041d <+29>: xor %eax,%eax
- 0x000000000040041f <+31>: retq
- 0x0000000000400420 <+32>: add %eax,%eax
- 0x0000000000400422 <+34>: jmp 0x400417 <main+23>
- End of assembler dump.
- (@value{GDBP}) disas /s main
- Dump of assembler code for function main:
- foo.c:
- 5 @{
- 6 x = foo (y);
- 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y>
- foo.h:
- 4 if (a < 0)
- 0x0000000000400406 <+6>: test %eax,%eax
- 0x0000000000400408 <+8>: js 0x400420 <main+32>
- 6 if (a == 0)
- 7 return 1;
- 8 return a + 10;
- 0x000000000040040a <+10>: lea 0xa(%rax),%edx
- 0x000000000040040d <+13>: test %eax,%eax
- 0x000000000040040f <+15>: mov $0x1,%eax
- 0x0000000000400414 <+20>: cmovne %edx,%eax
- foo.c:
- 6 x = foo (y);
- 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x>
- 7 return 0;
- 8 @}
- 0x000000000040041d <+29>: xor %eax,%eax
- 0x000000000040041f <+31>: retq
- foo.h:
- 5 return a * 2;
- 0x0000000000400420 <+32>: add %eax,%eax
- 0x0000000000400422 <+34>: jmp 0x400417 <main+23>
- End of assembler dump.
- @end smallexample
- Here is another example showing raw instructions in hex for AMD x86-64,
- @smallexample
- (gdb) disas /r 0x400281,+10
- Dump of assembler code from 0x400281 to 0x40028b:
- 0x0000000000400281: 38 36 cmp %dh,(%rsi)
- 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
- 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
- 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
- End of assembler dump.
- @end smallexample
- Addresses cannot be specified as a location (@pxref{Specify Location}).
- So, for example, if you want to disassemble function @code{bar}
- in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar}
- and not @samp{disassemble foo.c:bar}.
- Some architectures have more than one commonly-used set of instruction
- mnemonics or other syntax.
- For programs that were dynamically linked and use shared libraries,
- instructions that call functions or branch to locations in the shared
- libraries might show a seemingly bogus location---it's actually a
- location of the relocation table. On some architectures, @value{GDBN}
- might be able to resolve these to actual function names.
- @table @code
- @kindex set disassembler-options
- @cindex disassembler options
- @item set disassembler-options @var{option1}[,@var{option2}@dots{}]
- This command controls the passing of target specific information to
- the disassembler. For a list of valid options, please refer to the
- @code{-M}/@code{--disassembler-options} section of the @samp{objdump}
- manual and/or the output of @kbd{objdump --help}
- (@pxref{objdump,,objdump,binutils,The GNU Binary Utilities}).
- The default value is the empty string.
- If it is necessary to specify more than one disassembler option, then
- multiple options can be placed together into a comma separated list.
- Currently this command is only supported on targets ARC, ARM, MIPS,
- PowerPC and S/390.
- @kindex show disassembler-options
- @item show disassembler-options
- Show the current setting of the disassembler options.
- @end table
- @table @code
- @kindex set disassembly-flavor
- @cindex Intel disassembly flavor
- @cindex AT&T disassembly flavor
- @item set disassembly-flavor @var{instruction-set}
- Select the instruction set to use when disassembling the
- program via the @code{disassemble} or @code{x/i} commands.
- Currently this command is only defined for the Intel x86 family. You
- can set @var{instruction-set} to either @code{intel} or @code{att}.
- The default is @code{att}, the AT&T flavor used by default by Unix
- assemblers for x86-based targets.
- @kindex show disassembly-flavor
- @item show disassembly-flavor
- Show the current setting of the disassembly flavor.
- @end table
- @table @code
- @kindex set disassemble-next-line
- @kindex show disassemble-next-line
- @item set disassemble-next-line
- @itemx show disassemble-next-line
- Control whether or not @value{GDBN} will disassemble the next source
- line or instruction when execution stops. If ON, @value{GDBN} will
- display disassembly of the next source line when execution of the
- program being debugged stops. This is @emph{in addition} to
- displaying the source line itself, which @value{GDBN} always does if
- possible. If the next source line cannot be displayed for some reason
- (e.g., if @value{GDBN} cannot find the source file, or there's no line
- info in the debug info), @value{GDBN} will display disassembly of the
- next @emph{instruction} instead of showing the next source line. If
- AUTO, @value{GDBN} will display disassembly of next instruction only
- if the source line cannot be displayed. This setting causes
- @value{GDBN} to display some feedback when you step through a function
- with no line info or whose source file is unavailable. The default is
- OFF, which means never display the disassembly of the next line or
- instruction.
- @end table
- @node Disable Reading Source
- @section Disable Reading Source Code
- @cindex source code, disable access
- In some cases it can be desirable to prevent @value{GDBN} from
- accessing source code files. One case where this might be desirable
- is if the source code files are located over a slow network
- connection.
- The following command can be used to control whether @value{GDBN}
- should access source code files or not:
- @table @code
- @kindex set source open
- @kindex show source open
- @item set source open @r{[}on@r{|}off@r{]}
- @itemx show source open
- When this option is @code{on}, which is the default, @value{GDBN} will
- access source code files when needed, for example to print source
- lines when @value{GDBN} stops, or in response to the @code{list}
- command.
- When this option is @code{off}, @value{GDBN} will not access source
- code files.
- @end table
- @node Data
- @chapter Examining Data
- @cindex printing data
- @cindex examining data
- @kindex print
- @kindex inspect
- The usual way to examine data in your program is with the @code{print}
- command (abbreviated @code{p}), or its synonym @code{inspect}. It
- evaluates and prints the value of an expression of the language your
- program is written in (@pxref{Languages, ,Using @value{GDBN} with
- Different Languages}). It may also print the expression using a
- Python-based pretty-printer (@pxref{Pretty Printing}).
- @table @code
- @item print [[@var{options}] --] @var{expr}
- @itemx print [[@var{options}] --] /@var{f} @var{expr}
- @var{expr} is an expression (in the source language). By default the
- value of @var{expr} is printed in a format appropriate to its data type;
- you can choose a different format by specifying @samp{/@var{f}}, where
- @var{f} is a letter specifying the format; see @ref{Output Formats,,Output
- Formats}.
- @anchor{print options}
- The @code{print} command supports a number of options that allow
- overriding relevant global print settings as set by @code{set print}
- subcommands:
- @table @code
- @item -address [@code{on}|@code{off}]
- Set printing of addresses.
- Related setting: @ref{set print address}.
- @item -array [@code{on}|@code{off}]
- Pretty formatting of arrays.
- Related setting: @ref{set print array}.
- @item -array-indexes [@code{on}|@code{off}]
- Set printing of array indexes.
- Related setting: @ref{set print array-indexes}.
- @item -elements @var{number-of-elements}|@code{unlimited}
- Set limit on string chars or array elements to print. The value
- @code{unlimited} causes there to be no limit. Related setting:
- @ref{set print elements}.
- @item -max-depth @var{depth}|@code{unlimited}
- Set the threshold after which nested structures are replaced with
- ellipsis. Related setting: @ref{set print max-depth}.
- @item -memory-tag-violations [@code{on}|@code{off}]
- Set printing of additional information about memory tag violations.
- @xref{set print memory-tag-violations}.
- @item -null-stop [@code{on}|@code{off}]
- Set printing of char arrays to stop at first null char. Related
- setting: @ref{set print null-stop}.
- @item -object [@code{on}|@code{off}]
- Set printing C@t{++} virtual function tables. Related setting:
- @ref{set print object}.
- @item -pretty [@code{on}|@code{off}]
- Set pretty formatting of structures. Related setting: @ref{set print
- pretty}.
- @item -raw-values [@code{on}|@code{off}]
- Set whether to print values in raw form, bypassing any
- pretty-printers for that value. Related setting: @ref{set print
- raw-values}.
- @item -repeats @var{number-of-repeats}|@code{unlimited}
- Set threshold for repeated print elements. @code{unlimited} causes
- all elements to be individually printed. Related setting: @ref{set
- print repeats}.
- @item -static-members [@code{on}|@code{off}]
- Set printing C@t{++} static members. Related setting: @ref{set print
- static-members}.
- @item -symbol [@code{on}|@code{off}]
- Set printing of symbol names when printing pointers. Related setting:
- @ref{set print symbol}.
- @item -union [@code{on}|@code{off}]
- Set printing of unions interior to structures. Related setting:
- @ref{set print union}.
- @item -vtbl [@code{on}|@code{off}]
- Set printing of C++ virtual function tables. Related setting:
- @ref{set print vtbl}.
- @end table
- Because the @code{print} command accepts arbitrary expressions which
- may look like options (including abbreviations), if you specify any
- command option, then you must use a double dash (@code{--}) to mark
- the end of option processing.
- For example, this prints the value of the @code{-p} expression:
- @smallexample
- (@value{GDBP}) print -p
- @end smallexample
- While this repeats the last value in the value history (see below)
- with the @code{-pretty} option in effect:
- @smallexample
- (@value{GDBP}) print -p --
- @end smallexample
- Here is an example including both on option and an expression:
- @smallexample
- @group
- (@value{GDBP}) print -pretty -- *myptr
- $1 = @{
- next = 0x0,
- flags = @{
- sweet = 1,
- sour = 1
- @},
- meat = 0x54 "Pork"
- @}
- @end group
- @end smallexample
- @item print [@var{options}]
- @itemx print [@var{options}] /@var{f}
- @cindex reprint the last value
- If you omit @var{expr}, @value{GDBN} displays the last value again (from the
- @dfn{value history}; @pxref{Value History, ,Value History}). This allows you to
- conveniently inspect the same value in an alternative format.
- @end table
- If the architecture supports memory tagging, the @code{print} command will
- display pointer/memory tag mismatches if what is being printed is a pointer
- or reference type. @xref{Memory Tagging}.
- A more low-level way of examining data is with the @code{x} command.
- It examines data in memory at a specified address and prints it in a
- specified format. @xref{Memory, ,Examining Memory}.
- If you are interested in information about types, or about how the
- fields of a struct or a class are declared, use the @code{ptype @var{exp}}
- command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
- Table}.
- @cindex exploring hierarchical data structures
- @kindex explore
- Another way of examining values of expressions and type information is
- through the Python extension command @code{explore} (available only if
- the @value{GDBN} build is configured with @code{--with-python}). It
- offers an interactive way to start at the highest level (or, the most
- abstract level) of the data type of an expression (or, the data type
- itself) and explore all the way down to leaf scalar values/fields
- embedded in the higher level data types.
- @table @code
- @item explore @var{arg}
- @var{arg} is either an expression (in the source language), or a type
- visible in the current context of the program being debugged.
- @end table
- The working of the @code{explore} command can be illustrated with an
- example. If a data type @code{struct ComplexStruct} is defined in your
- C program as
- @smallexample
- struct SimpleStruct
- @{
- int i;
- double d;
- @};
- struct ComplexStruct
- @{
- struct SimpleStruct *ss_p;
- int arr[10];
- @};
- @end smallexample
- @noindent
- followed by variable declarations as
- @smallexample
- struct SimpleStruct ss = @{ 10, 1.11 @};
- struct ComplexStruct cs = @{ &ss, @{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 @} @};
- @end smallexample
- @noindent
- then, the value of the variable @code{cs} can be explored using the
- @code{explore} command as follows.
- @smallexample
- (gdb) explore cs
- The value of `cs' is a struct/class of type `struct ComplexStruct' with
- the following fields:
- ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'>
- arr = <Enter 1 to explore this field of type `int [10]'>
- Enter the field number of choice:
- @end smallexample
- @noindent
- Since the fields of @code{cs} are not scalar values, you are being
- prompted to chose the field you want to explore. Let's say you choose
- the field @code{ss_p} by entering @code{0}. Then, since this field is a
- pointer, you will be asked if it is pointing to a single value. From
- the declaration of @code{cs} above, it is indeed pointing to a single
- value, hence you enter @code{y}. If you enter @code{n}, then you will
- be asked if it were pointing to an array of values, in which case this
- field will be explored as if it were an array.
- @smallexample
- `cs.ss_p' is a pointer to a value of type `struct SimpleStruct'
- Continue exploring it as a pointer to a single value [y/n]: y
- The value of `*(cs.ss_p)' is a struct/class of type `struct
- SimpleStruct' with the following fields:
- i = 10 .. (Value of type `int')
- d = 1.1100000000000001 .. (Value of type `double')
- Press enter to return to parent value:
- @end smallexample
- @noindent
- If the field @code{arr} of @code{cs} was chosen for exploration by
- entering @code{1} earlier, then since it is as array, you will be
- prompted to enter the index of the element in the array that you want
- to explore.
- @smallexample
- `cs.arr' is an array of `int'.
- Enter the index of the element you want to explore in `cs.arr': 5
- `(cs.arr)[5]' is a scalar value of type `int'.
- (cs.arr)[5] = 4
- Press enter to return to parent value:
- @end smallexample
- In general, at any stage of exploration, you can go deeper towards the
- leaf values by responding to the prompts appropriately, or hit the
- return key to return to the enclosing data structure (the @i{higher}
- level data structure).
- Similar to exploring values, you can use the @code{explore} command to
- explore types. Instead of specifying a value (which is typically a
- variable name or an expression valid in the current context of the
- program being debugged), you specify a type name. If you consider the
- same example as above, your can explore the type
- @code{struct ComplexStruct} by passing the argument
- @code{struct ComplexStruct} to the @code{explore} command.
- @smallexample
- (gdb) explore struct ComplexStruct
- @end smallexample
- @noindent
- By responding to the prompts appropriately in the subsequent interactive
- session, you can explore the type @code{struct ComplexStruct} in a
- manner similar to how the value @code{cs} was explored in the above
- example.
- The @code{explore} command also has two sub-commands,
- @code{explore value} and @code{explore type}. The former sub-command is
- a way to explicitly specify that value exploration of the argument is
- being invoked, while the latter is a way to explicitly specify that type
- exploration of the argument is being invoked.
- @table @code
- @item explore value @var{expr}
- @cindex explore value
- This sub-command of @code{explore} explores the value of the
- expression @var{expr} (if @var{expr} is an expression valid in the
- current context of the program being debugged). The behavior of this
- command is identical to that of the behavior of the @code{explore}
- command being passed the argument @var{expr}.
- @item explore type @var{arg}
- @cindex explore type
- This sub-command of @code{explore} explores the type of @var{arg} (if
- @var{arg} is a type visible in the current context of program being
- debugged), or the type of the value/expression @var{arg} (if @var{arg}
- is an expression valid in the current context of the program being
- debugged). If @var{arg} is a type, then the behavior of this command is
- identical to that of the @code{explore} command being passed the
- argument @var{arg}. If @var{arg} is an expression, then the behavior of
- this command will be identical to that of the @code{explore} command
- being passed the type of @var{arg} as the argument.
- @end table
- @menu
- * Expressions:: Expressions
- * Ambiguous Expressions:: Ambiguous Expressions
- * Variables:: Program variables
- * Arrays:: Artificial arrays
- * Output Formats:: Output formats
- * Memory:: Examining memory
- * Memory Tagging:: Memory Tagging
- * Auto Display:: Automatic display
- * Print Settings:: Print settings
- * Pretty Printing:: Python pretty printing
- * Value History:: Value history
- * Convenience Vars:: Convenience variables
- * Convenience Funs:: Convenience functions
- * Registers:: Registers
- * Floating Point Hardware:: Floating point hardware
- * Vector Unit:: Vector Unit
- * OS Information:: Auxiliary data provided by operating system
- * Memory Region Attributes:: Memory region attributes
- * Dump/Restore Files:: Copy between memory and a file
- * Core File Generation:: Cause a program dump its core
- * Character Sets:: Debugging programs that use a different
- character set than GDB does
- * Caching Target Data:: Data caching for targets
- * Searching Memory:: Searching memory for a sequence of bytes
- * Value Sizes:: Managing memory allocated for values
- @end menu
- @node Expressions
- @section Expressions
- @cindex expressions
- @code{print} and many other @value{GDBN} commands accept an expression and
- compute its value. Any kind of constant, variable or operator defined
- by the programming language you are using is valid in an expression in
- @value{GDBN}. This includes conditional expressions, function calls,
- casts, and string constants. It also includes preprocessor macros, if
- you compiled your program to include this information; see
- @ref{Compilation}.
- @cindex arrays in expressions
- @value{GDBN} supports array constants in expressions input by
- the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
- you can use the command @code{print @{1, 2, 3@}} to create an array
- of three integers. If you pass an array to a function or assign it
- to a program variable, @value{GDBN} copies the array to memory that
- is @code{malloc}ed in the target program.
- Because C is so widespread, most of the expressions shown in examples in
- this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
- Languages}, for information on how to use expressions in other
- languages.
- In this section, we discuss operators that you can use in @value{GDBN}
- expressions regardless of your programming language.
- @cindex casts, in expressions
- Casts are supported in all languages, not just in C, because it is so
- useful to cast a number into a pointer in order to examine a structure
- at that address in memory.
- @c FIXME: casts supported---Mod2 true?
- @value{GDBN} supports these operators, in addition to those common
- to programming languages:
- @table @code
- @item @@
- @samp{@@} is a binary operator for treating parts of memory as arrays.
- @xref{Arrays, ,Artificial Arrays}, for more information.
- @item ::
- @samp{::} allows you to specify a variable in terms of the file or
- function where it is defined. @xref{Variables, ,Program Variables}.
- @cindex @{@var{type}@}
- @cindex type casting memory
- @cindex memory, viewing as typed object
- @cindex casts, to view memory
- @item @{@var{type}@} @var{addr}
- Refers to an object of type @var{type} stored at address @var{addr} in
- memory. The address @var{addr} may be any expression whose value is
- an integer or pointer (but parentheses are required around binary
- operators, just as in a cast). This construct is allowed regardless
- of what kind of data is normally supposed to reside at @var{addr}.
- @end table
- @node Ambiguous Expressions
- @section Ambiguous Expressions
- @cindex ambiguous expressions
- Expressions can sometimes contain some ambiguous elements. For instance,
- some programming languages (notably Ada, C@t{++} and Objective-C) permit
- a single function name to be defined several times, for application in
- different contexts. This is called @dfn{overloading}. Another example
- involving Ada is generics. A @dfn{generic package} is similar to C@t{++}
- templates and is typically instantiated several times, resulting in
- the same function name being defined in different contexts.
- In some cases and depending on the language, it is possible to adjust
- the expression to remove the ambiguity. For instance in C@t{++}, you
- can specify the signature of the function you want to break on, as in
- @kbd{break @var{function}(@var{types})}. In Ada, using the fully
- qualified name of your function often makes the expression unambiguous
- as well.
- When an ambiguity that needs to be resolved is detected, the debugger
- has the capability to display a menu of numbered choices for each
- possibility, and then waits for the selection with the prompt @samp{>}.
- The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}}
- aborts the current command. If the command in which the expression was
- used allows more than one choice to be selected, the next option in the
- menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible
- choices.
- For example, the following session excerpt shows an attempt to set a
- breakpoint at the overloaded symbol @code{String::after}.
- We choose three particular definitions of that function name:
- @c FIXME! This is likely to change to show arg type lists, at least
- @smallexample
- @group
- (@value{GDBP}) b String::after
- [0] cancel
- [1] all
- [2] file:String.cc; line number:867
- [3] file:String.cc; line number:860
- [4] file:String.cc; line number:875
- [5] file:String.cc; line number:853
- [6] file:String.cc; line number:846
- [7] file:String.cc; line number:735
- > 2 4 6
- Breakpoint 1 at 0xb26c: file String.cc, line 867.
- Breakpoint 2 at 0xb344: file String.cc, line 875.
- Breakpoint 3 at 0xafcc: file String.cc, line 846.
- Multiple breakpoints were set.
- Use the "delete" command to delete unwanted
- breakpoints.
- (@value{GDBP})
- @end group
- @end smallexample
- @table @code
- @kindex set multiple-symbols
- @item set multiple-symbols @var{mode}
- @cindex multiple-symbols menu
- This option allows you to adjust the debugger behavior when an expression
- is ambiguous.
- By default, @var{mode} is set to @code{all}. If the command with which
- the expression is used allows more than one choice, then @value{GDBN}
- automatically selects all possible choices. For instance, inserting
- a breakpoint on a function using an ambiguous name results in a breakpoint
- inserted on each possible match. However, if a unique choice must be made,
- then @value{GDBN} uses the menu to help you disambiguate the expression.
- For instance, printing the address of an overloaded function will result
- in the use of the menu.
- When @var{mode} is set to @code{ask}, the debugger always uses the menu
- when an ambiguity is detected.
- Finally, when @var{mode} is set to @code{cancel}, the debugger reports
- an error due to the ambiguity and the command is aborted.
- @kindex show multiple-symbols
- @item show multiple-symbols
- Show the current value of the @code{multiple-symbols} setting.
- @end table
- @node Variables
- @section Program Variables
- The most common kind of expression to use is the name of a variable
- in your program.
- Variables in expressions are understood in the selected stack frame
- (@pxref{Selection, ,Selecting a Frame}); they must be either:
- @itemize @bullet
- @item
- global (or file-static)
- @end itemize
- @noindent or
- @itemize @bullet
- @item
- visible according to the scope rules of the
- programming language from the point of execution in that frame
- @end itemize
- @noindent This means that in the function
- @smallexample
- foo (a)
- int a;
- @{
- bar (a);
- @{
- int b = test ();
- bar (b);
- @}
- @}
- @end smallexample
- @noindent
- you can examine and use the variable @code{a} whenever your program is
- executing within the function @code{foo}, but you can only use or
- examine the variable @code{b} while your program is executing inside
- the block where @code{b} is declared.
- @cindex variable name conflict
- There is an exception: you can refer to a variable or function whose
- scope is a single source file even if the current execution point is not
- in this file. But it is possible to have more than one such variable or
- function with the same name (in different source files). If that
- happens, referring to that name has unpredictable effects. If you wish,
- you can specify a static variable in a particular function or file by
- using the colon-colon (@code{::}) notation:
- @cindex colon-colon, context for variables/functions
- @ifnotinfo
- @c info cannot cope with a :: index entry, but why deprive hard copy readers?
- @cindex @code{::}, context for variables/functions
- @end ifnotinfo
- @smallexample
- @var{file}::@var{variable}
- @var{function}::@var{variable}
- @end smallexample
- @noindent
- Here @var{file} or @var{function} is the name of the context for the
- static @var{variable}. In the case of file names, you can use quotes to
- make sure @value{GDBN} parses the file name as a single word---for example,
- to print a global value of @code{x} defined in @file{f2.c}:
- @smallexample
- (@value{GDBP}) p 'f2.c'::x
- @end smallexample
- The @code{::} notation is normally used for referring to
- static variables, since you typically disambiguate uses of local variables
- in functions by selecting the appropriate frame and using the
- simple name of the variable. However, you may also use this notation
- to refer to local variables in frames enclosing the selected frame:
- @smallexample
- void
- foo (int a)
- @{
- if (a < 10)
- bar (a);
- else
- process (a); /* Stop here */
- @}
- int
- bar (int a)
- @{
- foo (a + 5);
- @}
- @end smallexample
- @noindent
- For example, if there is a breakpoint at the commented line,
- here is what you might see
- when the program stops after executing the call @code{bar(0)}:
- @smallexample
- (@value{GDBP}) p a
- $1 = 10
- (@value{GDBP}) p bar::a
- $2 = 5
- (@value{GDBP}) up 2
- #2 0x080483d0 in foo (a=5) at foobar.c:12
- (@value{GDBP}) p a
- $3 = 5
- (@value{GDBP}) p bar::a
- $4 = 0
- @end smallexample
- @cindex C@t{++} scope resolution
- These uses of @samp{::} are very rarely in conflict with the very
- similar use of the same notation in C@t{++}. When they are in
- conflict, the C@t{++} meaning takes precedence; however, this can be
- overridden by quoting the file or function name with single quotes.
- For example, suppose the program is stopped in a method of a class
- that has a field named @code{includefile}, and there is also an
- include file named @file{includefile} that defines a variable,
- @code{some_global}.
- @smallexample
- (@value{GDBP}) p includefile
- $1 = 23
- (@value{GDBP}) p includefile::some_global
- A syntax error in expression, near `'.
- (@value{GDBP}) p 'includefile'::some_global
- $2 = 27
- @end smallexample
- @cindex wrong values
- @cindex variable values, wrong
- @cindex function entry/exit, wrong values of variables
- @cindex optimized code, wrong values of variables
- @quotation
- @emph{Warning:} Occasionally, a local variable may appear to have the
- wrong value at certain points in a function---just after entry to a new
- scope, and just before exit.
- @end quotation
- You may see this problem when you are stepping by machine instructions.
- This is because, on most machines, it takes more than one instruction to
- set up a stack frame (including local variable definitions); if you are
- stepping by machine instructions, variables may appear to have the wrong
- values until the stack frame is completely built. On exit, it usually
- also takes more than one machine instruction to destroy a stack frame;
- after you begin stepping through that group of instructions, local
- variable definitions may be gone.
- This may also happen when the compiler does significant optimizations.
- To be sure of always seeing accurate values, turn off all optimization
- when compiling.
- @cindex ``No symbol "foo" in current context''
- Another possible effect of compiler optimizations is to optimize
- unused variables out of existence, or assign variables to registers (as
- opposed to memory addresses). Depending on the support for such cases
- offered by the debug info format used by the compiler, @value{GDBN}
- might not be able to display values for such local variables. If that
- happens, @value{GDBN} will print a message like this:
- @smallexample
- No symbol "foo" in current context.
- @end smallexample
- To solve such problems, either recompile without optimizations, or use a
- different debug info format, if the compiler supports several such
- formats. @xref{Compilation}, for more information on choosing compiler
- options. @xref{C, ,C and C@t{++}}, for more information about debug
- info formats that are best suited to C@t{++} programs.
- If you ask to print an object whose contents are unknown to
- @value{GDBN}, e.g., because its data type is not completely specified
- by the debug information, @value{GDBN} will say @samp{<incomplete
- type>}. @xref{Symbols, incomplete type}, for more about this.
- @cindex no debug info variables
- If you try to examine or use the value of a (global) variable for
- which @value{GDBN} has no type information, e.g., because the program
- includes no debug information, @value{GDBN} displays an error message.
- @xref{Symbols, unknown type}, for more about unknown types. If you
- cast the variable to its declared type, @value{GDBN} gets the
- variable's value using the cast-to type as the variable's type. For
- example, in a C program:
- @smallexample
- (@value{GDBP}) p var
- 'var' has unknown type; cast it to its declared type
- (@value{GDBP}) p (float) var
- $1 = 3.14
- @end smallexample
- If you append @kbd{@@entry} string to a function parameter name you get its
- value at the time the function got called. If the value is not available an
- error message is printed. Entry values are available only with some compilers.
- Entry values are normally also printed at the function parameter list according
- to @ref{set print entry-values}.
- @smallexample
- Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29
- 29 i++;
- (gdb) next
- 30 e (i);
- (gdb) print i
- $1 = 31
- (gdb) print i@@entry
- $2 = 30
- @end smallexample
- Strings are identified as arrays of @code{char} values without specified
- signedness. Arrays of either @code{signed char} or @code{unsigned char} get
- printed as arrays of 1 byte sized integers. @code{-fsigned-char} or
- @code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN}
- defines literal string type @code{"char"} as @code{char} without a sign.
- For program code
- @smallexample
- char var0[] = "A";
- signed char var1[] = "A";
- @end smallexample
- You get during debugging
- @smallexample
- (gdb) print var0
- $1 = "A"
- (gdb) print var1
- $2 = @{65 'A', 0 '\0'@}
- @end smallexample
- @node Arrays
- @section Artificial Arrays
- @cindex artificial array
- @cindex arrays
- @kindex @@@r{, referencing memory as an array}
- It is often useful to print out several successive objects of the
- same type in memory; a section of an array, or an array of
- dynamically determined size for which only a pointer exists in the
- program.
- You can do this by referring to a contiguous span of memory as an
- @dfn{artificial array}, using the binary operator @samp{@@}. The left
- operand of @samp{@@} should be the first element of the desired array
- and be an individual object. The right operand should be the desired length
- of the array. The result is an array value whose elements are all of
- the type of the left argument. The first element is actually the left
- argument; the second element comes from bytes of memory immediately
- following those that hold the first element, and so on. Here is an
- example. If a program says
- @smallexample
- int *array = (int *) malloc (len * sizeof (int));
- @end smallexample
- @noindent
- you can print the contents of @code{array} with
- @smallexample
- p *array@@len
- @end smallexample
- The left operand of @samp{@@} must reside in memory. Array values made
- with @samp{@@} in this way behave just like other arrays in terms of
- subscripting, and are coerced to pointers when used in expressions.
- Artificial arrays most often appear in expressions via the value history
- (@pxref{Value History, ,Value History}), after printing one out.
- Another way to create an artificial array is to use a cast.
- This re-interprets a value as if it were an array.
- The value need not be in memory:
- @smallexample
- (@value{GDBP}) p/x (short[2])0x12345678
- $1 = @{0x1234, 0x5678@}
- @end smallexample
- As a convenience, if you leave the array length out (as in
- @samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
- the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
- @smallexample
- (@value{GDBP}) p/x (short[])0x12345678
- $2 = @{0x1234, 0x5678@}
- @end smallexample
- Sometimes the artificial array mechanism is not quite enough; in
- moderately complex data structures, the elements of interest may not
- actually be adjacent---for example, if you are interested in the values
- of pointers in an array. One useful work-around in this situation is
- to use a convenience variable (@pxref{Convenience Vars, ,Convenience
- Variables}) as a counter in an expression that prints the first
- interesting value, and then repeat that expression via @key{RET}. For
- instance, suppose you have an array @code{dtab} of pointers to
- structures, and you are interested in the values of a field @code{fv}
- in each structure. Here is an example of what you might type:
- @smallexample
- set $i = 0
- p dtab[$i++]->fv
- @key{RET}
- @key{RET}
- @dots{}
- @end smallexample
- @node Output Formats
- @section Output Formats
- @cindex formatted output
- @cindex output formats
- By default, @value{GDBN} prints a value according to its data type. Sometimes
- this is not what you want. For example, you might want to print a number
- in hex, or a pointer in decimal. Or you might want to view data in memory
- at a certain address as a character string or as an instruction. To do
- these things, specify an @dfn{output format} when you print a value.
- The simplest use of output formats is to say how to print a value
- already computed. This is done by starting the arguments of the
- @code{print} command with a slash and a format letter. The format
- letters supported are:
- @table @code
- @item x
- Print the binary representation of the value in hexadecimal.
- @item d
- Print the binary representation of the value in decimal.
- @item u
- Print the binary representation of the value as an decimal, as if it
- were unsigned.
- @item o
- Print the binary representation of the value in octal.
- @item t
- Print the binary representation of the value in binary. The letter
- @samp{t} stands for ``two''. @footnote{@samp{b} cannot be used
- because these format letters are also used with the @code{x} command,
- where @samp{b} stands for ``byte''; see @ref{Memory,,Examining
- Memory}.}
- @item a
- @cindex unknown address, locating
- @cindex locate address
- Print as an address, both absolute in hexadecimal and as an offset from
- the nearest preceding symbol. You can use this format used to discover
- where (in what function) an unknown address is located:
- @smallexample
- (@value{GDBP}) p/a 0x54320
- $3 = 0x54320 <_initialize_vx+396>
- @end smallexample
- @noindent
- The command @code{info symbol 0x54320} yields similar results.
- @xref{Symbols, info symbol}.
- @item c
- Cast the value to an integer (unlike other formats, this does not just
- reinterpret the underlying bits) and print it as a character constant.
- This prints both the numerical value and its character representation.
- The character representation is replaced with the octal escape
- @samp{\nnn} for characters outside the 7-bit @sc{ascii} range.
- Without this format, @value{GDBN} displays @code{char},
- @w{@code{unsigned char}}, and @w{@code{signed char}} data as character
- constants. Single-byte members of vectors are displayed as integer
- data.
- @item f
- Regard the bits of the value as a floating point number and print
- using typical floating point syntax.
- @item s
- @cindex printing strings
- @cindex printing byte arrays
- Regard as a string, if possible. With this format, pointers to single-byte
- data are displayed as null-terminated strings and arrays of single-byte data
- are displayed as fixed-length strings. Other values are displayed in their
- natural types.
- Without this format, @value{GDBN} displays pointers to and arrays of
- @code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as
- strings. Single-byte members of a vector are displayed as an integer
- array.
- @item z
- Like @samp{x} formatting, the value is treated as an integer and
- printed as hexadecimal, but leading zeros are printed to pad the value
- to the size of the integer type.
- @item r
- @cindex raw printing
- Print using the @samp{raw} formatting. By default, @value{GDBN} will
- use a Python-based pretty-printer, if one is available (@pxref{Pretty
- Printing}). This typically results in a higher-level display of the
- value's contents. The @samp{r} format bypasses any Python
- pretty-printer which might exist.
- @end table
- For example, to print the program counter in hex (@pxref{Registers}), type
- @smallexample
- p/x $pc
- @end smallexample
- @noindent
- Note that no space is required before the slash; this is because command
- names in @value{GDBN} cannot contain a slash.
- To reprint the last value in the value history with a different format,
- you can use the @code{print} command with just a format and no
- expression. For example, @samp{p/x} reprints the last value in hex.
- @node Memory
- @section Examining Memory
- You can use the command @code{x} (for ``examine'') to examine memory in
- any of several formats, independently of your program's data types.
- @cindex examining memory
- @table @code
- @kindex x @r{(examine memory)}
- @item x/@var{nfu} @var{addr}
- @itemx x @var{addr}
- @itemx x
- Use the @code{x} command to examine memory.
- @end table
- @var{n}, @var{f}, and @var{u} are all optional parameters that specify how
- much memory to display and how to format it; @var{addr} is an
- expression giving the address where you want to start displaying memory.
- If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
- Several commands set convenient defaults for @var{addr}.
- @table @r
- @item @var{n}, the repeat count
- The repeat count is a decimal integer; the default is 1. It specifies
- how much memory (counting by units @var{u}) to display. If a negative
- number is specified, memory is examined backward from @var{addr}.
- @c This really is **decimal**; unaffected by 'set radix' as of GDB
- @c 4.1.2.
- @item @var{f}, the display format
- The display format is one of the formats used by @code{print}
- (@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
- @samp{f}, @samp{s}), @samp{i} (for machine instructions) and
- @samp{m} (for displaying memory tags).
- The default is @samp{x} (hexadecimal) initially. The default changes
- each time you use either @code{x} or @code{print}.
- @item @var{u}, the unit size
- The unit size is any of
- @table @code
- @item b
- Bytes.
- @item h
- Halfwords (two bytes).
- @item w
- Words (four bytes). This is the initial default.
- @item g
- Giant words (eight bytes).
- @end table
- Each time you specify a unit size with @code{x}, that size becomes the
- default unit the next time you use @code{x}. For the @samp{i} format,
- the unit size is ignored and is normally not written. For the @samp{s} format,
- the unit size defaults to @samp{b}, unless it is explicitly given.
- Use @kbd{x /hs} to display 16-bit char strings and @kbd{x /ws} to display
- 32-bit strings. The next use of @kbd{x /s} will again display 8-bit strings.
- Note that the results depend on the programming language of the
- current compilation unit. If the language is C, the @samp{s}
- modifier will use the UTF-16 encoding while @samp{w} will use
- UTF-32. The encoding is set by the programming language and cannot
- be altered.
- @item @var{addr}, starting display address
- @var{addr} is the address where you want @value{GDBN} to begin displaying
- memory. The expression need not have a pointer value (though it may);
- it is always interpreted as an integer address of a byte of memory.
- @xref{Expressions, ,Expressions}, for more information on expressions. The default for
- @var{addr} is usually just after the last address examined---but several
- other commands also set the default address: @code{info breakpoints} (to
- the address of the last breakpoint listed), @code{info line} (to the
- starting address of a line), and @code{print} (if you use it to display
- a value from memory).
- @end table
- For example, @samp{x/3uh 0x54320} is a request to display three halfwords
- (@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
- starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
- words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
- @pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
- You can also specify a negative repeat count to examine memory backward
- from the given address. For example, @samp{x/-3uh 0x54320} prints three
- halfwords (@code{h}) at @code{0x5431a}, @code{0x5431c}, and @code{0x5431e}.
- Since the letters indicating unit sizes are all distinct from the
- letters specifying output formats, you do not have to remember whether
- unit size or format comes first; either order works. The output
- specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
- (However, the count @var{n} must come first; @samp{wx4} does not work.)
- Even though the unit size @var{u} is ignored for the formats @samp{s}
- and @samp{i}, you might still want to use a count @var{n}; for example,
- @samp{3i} specifies that you want to see three machine instructions,
- including any operands. For convenience, especially when used with
- the @code{display} command, the @samp{i} format also prints branch delay
- slot instructions, if any, beyond the count specified, which immediately
- follow the last instruction that is within the count. The command
- @code{disassemble} gives an alternative way of inspecting machine
- instructions; see @ref{Machine Code,,Source and Machine Code}.
- If a negative repeat count is specified for the formats @samp{s} or @samp{i},
- the command displays null-terminated strings or instructions before the given
- address as many as the absolute value of the given number. For the @samp{i}
- format, we use line number information in the debug info to accurately locate
- instruction boundaries while disassembling backward. If line info is not
- available, the command stops examining memory with an error message.
- All the defaults for the arguments to @code{x} are designed to make it
- easy to continue scanning memory with minimal specifications each time
- you use @code{x}. For example, after you have inspected three machine
- instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
- with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
- the repeat count @var{n} is used again; the other arguments default as
- for successive uses of @code{x}.
- When examining machine instructions, the instruction at current program
- counter is shown with a @code{=>} marker. For example:
- @smallexample
- (@value{GDBP}) x/5i $pc-6
- 0x804837f <main+11>: mov %esp,%ebp
- 0x8048381 <main+13>: push %ecx
- 0x8048382 <main+14>: sub $0x4,%esp
- => 0x8048385 <main+17>: movl $0x8048460,(%esp)
- 0x804838c <main+24>: call 0x80482d4 <puts@@plt>
- @end smallexample
- If the architecture supports memory tagging, the tags can be displayed by
- using @samp{m}. @xref{Memory Tagging}.
- The information will be displayed once per granule size
- (the amount of bytes a particular memory tag covers). For example, AArch64
- has a granule size of 16 bytes, so it will display a tag every 16 bytes.
- Due to the way @value{GDBN} prints information with the @code{x} command (not
- aligned to a particular boundary), the tag information will refer to the
- initial address displayed on a particular line. If a memory tag boundary
- is crossed in the middle of a line displayed by the @code{x} command, it
- will be displayed on the next line.
- The @samp{m} format doesn't affect any other specified formats that were
- passed to the @code{x} command.
- @cindex @code{$_}, @code{$__}, and value history
- The addresses and contents printed by the @code{x} command are not saved
- in the value history because there is often too much of them and they
- would get in the way. Instead, @value{GDBN} makes these values available for
- subsequent use in expressions as values of the convenience variables
- @code{$_} and @code{$__}. After an @code{x} command, the last address
- examined is available for use in expressions in the convenience variable
- @code{$_}. The contents of that address, as examined, are available in
- the convenience variable @code{$__}.
- If the @code{x} command has a repeat count, the address and contents saved
- are from the last memory unit printed; this is not the same as the last
- address printed if several units were printed on the last line of output.
- @anchor{addressable memory unit}
- @cindex addressable memory unit
- Most targets have an addressable memory unit size of 8 bits. This means
- that to each memory address are associated 8 bits of data. Some
- targets, however, have other addressable memory unit sizes.
- Within @value{GDBN} and this document, the term
- @dfn{addressable memory unit} (or @dfn{memory unit} for short) is used
- when explicitly referring to a chunk of data of that size. The word
- @dfn{byte} is used to refer to a chunk of data of 8 bits, regardless of
- the addressable memory unit size of the target. For most systems,
- addressable memory unit is a synonym of byte.
- @cindex remote memory comparison
- @cindex target memory comparison
- @cindex verify remote memory image
- @cindex verify target memory image
- When you are debugging a program running on a remote target machine
- (@pxref{Remote Debugging}), you may wish to verify the program's image
- in the remote machine's memory against the executable file you
- downloaded to the target. Or, on any target, you may want to check
- whether the program has corrupted its own read-only sections. The
- @code{compare-sections} command is provided for such situations.
- @table @code
- @kindex compare-sections
- @item compare-sections @r{[}@var{section-name}@r{|}@code{-r}@r{]}
- Compare the data of a loadable section @var{section-name} in the
- executable file of the program being debugged with the same section in
- the target machine's memory, and report any mismatches. With no
- arguments, compares all loadable sections. With an argument of
- @code{-r}, compares all loadable read-only sections.
- Note: for remote targets, this command can be accelerated if the
- target supports computing the CRC checksum of a block of memory
- (@pxref{qCRC packet}).
- @end table
- @node Memory Tagging
- @section Memory Tagging
- Memory tagging is a memory protection technology that uses a pair of tags to
- validate memory accesses through pointers. The tags are integer values
- usually comprised of a few bits, depending on the architecture.
- There are two types of tags that are used in this setup: logical and
- allocation. A logical tag is stored in the pointers themselves, usually at the
- higher bits of the pointers. An allocation tag is the tag associated
- with particular ranges of memory in the physical address space, against which
- the logical tags from pointers are compared.
- The pointer tag (logical tag) must match the memory tag (allocation tag)
- for the memory access to be valid. If the logical tag does not match the
- allocation tag, that will raise a memory violation.
- Allocation tags cover multiple contiguous bytes of physical memory. This
- range of bytes is called a memory tag granule and is architecture-specific.
- For example, AArch64 has a tag granule of 16 bytes, meaning each allocation
- tag spans 16 bytes of memory.
- If the underlying architecture supports memory tagging, like AArch64 MTE
- or SPARC ADI do, @value{GDBN} can make use of it to validate pointers
- against memory allocation tags.
- The @code{print} (@pxref{Data}) and @code{x} (@pxref{Memory}) commands will
- display tag information when appropriate, and a command prefix of
- @code{memory-tag} gives access to the various memory tagging commands.
- The @code{memory-tag} commands are the following:
- @table @code
- @kindex memory-tag print-logical-tag
- @item memory-tag print-logical-tag @var{pointer_expression}
- Print the logical tag stored in @var{pointer_expression}.
- @kindex memory-tag with-logical-tag
- @item memory-tag with-logical-tag @var{pointer_expression} @var{tag_bytes}
- Print the pointer given by @var{pointer_expression}, augmented with a logical
- tag of @var{tag_bytes}.
- @kindex memory-tag print-allocation-tag
- @item memory-tag print-allocation-tag @var{address_expression}
- Print the allocation tag associated with the memory address given by
- @var{address_expression}.
- @kindex memory-tag setatag
- @item memory-tag setatag @var{starting_address} @var{length} @var{tag_bytes}
- Set the allocation tag(s) for memory range @r{[}@var{starting_address},
- @var{starting_address} + @var{length}@r{)} to @var{tag_bytes}.
- @kindex memory-tag check
- @item memory-tag check @var{pointer_expression}
- Check if the logical tag in the pointer given by @var{pointer_expression}
- matches the allocation tag for the memory referenced by the pointer.
- This essentially emulates the hardware validation that is done when tagged
- memory is accessed through a pointer, but does not cause a memory fault as
- it would during hardware validation.
- It can be used to inspect potential memory tagging violations in the running
- process, before any faults get triggered.
- @end table
- @node Auto Display
- @section Automatic Display
- @cindex automatic display
- @cindex display of expressions
- If you find that you want to print the value of an expression frequently
- (to see how it changes), you might want to add it to the @dfn{automatic
- display list} so that @value{GDBN} prints its value each time your program stops.
- Each expression added to the list is given a number to identify it;
- to remove an expression from the list, you specify that number.
- The automatic display looks like this:
- @smallexample
- 2: foo = 38
- 3: bar[5] = (struct hack *) 0x3804
- @end smallexample
- @noindent
- This display shows item numbers, expressions and their current values. As with
- displays you request manually using @code{x} or @code{print}, you can
- specify the output format you prefer; in fact, @code{display} decides
- whether to use @code{print} or @code{x} depending your format
- specification---it uses @code{x} if you specify either the @samp{i}
- or @samp{s} format, or a unit size; otherwise it uses @code{print}.
- @table @code
- @kindex display
- @item display @var{expr}
- Add the expression @var{expr} to the list of expressions to display
- each time your program stops. @xref{Expressions, ,Expressions}.
- @code{display} does not repeat if you press @key{RET} again after using it.
- @item display/@var{fmt} @var{expr}
- For @var{fmt} specifying only a display format and not a size or
- count, add the expression @var{expr} to the auto-display list but
- arrange to display it each time in the specified format @var{fmt}.
- @xref{Output Formats,,Output Formats}.
- @item display/@var{fmt} @var{addr}
- For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
- number of units, add the expression @var{addr} as a memory address to
- be examined each time your program stops. Examining means in effect
- doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}.
- @end table
- For example, @samp{display/i $pc} can be helpful, to see the machine
- instruction about to be executed each time execution stops (@samp{$pc}
- is a common name for the program counter; @pxref{Registers, ,Registers}).
- @table @code
- @kindex delete display
- @kindex undisplay
- @item undisplay @var{dnums}@dots{}
- @itemx delete display @var{dnums}@dots{}
- Remove items from the list of expressions to display. Specify the
- numbers of the displays that you want affected with the command
- argument @var{dnums}. It can be a single display number, one of the
- numbers shown in the first field of the @samp{info display} display;
- or it could be a range of display numbers, as in @code{2-4}.
- @code{undisplay} does not repeat if you press @key{RET} after using it.
- (Otherwise you would just get the error @samp{No display number @dots{}}.)
- @kindex disable display
- @item disable display @var{dnums}@dots{}
- Disable the display of item numbers @var{dnums}. A disabled display
- item is not printed automatically, but is not forgotten. It may be
- enabled again later. Specify the numbers of the displays that you
- want affected with the command argument @var{dnums}. It can be a
- single display number, one of the numbers shown in the first field of
- the @samp{info display} display; or it could be a range of display
- numbers, as in @code{2-4}.
- @kindex enable display
- @item enable display @var{dnums}@dots{}
- Enable display of item numbers @var{dnums}. It becomes effective once
- again in auto display of its expression, until you specify otherwise.
- Specify the numbers of the displays that you want affected with the
- command argument @var{dnums}. It can be a single display number, one
- of the numbers shown in the first field of the @samp{info display}
- display; or it could be a range of display numbers, as in @code{2-4}.
- @item display
- Display the current values of the expressions on the list, just as is
- done when your program stops.
- @kindex info display
- @item info display
- Print the list of expressions previously set up to display
- automatically, each one with its item number, but without showing the
- values. This includes disabled expressions, which are marked as such.
- It also includes expressions which would not be displayed right now
- because they refer to automatic variables not currently available.
- @end table
- @cindex display disabled out of scope
- If a display expression refers to local variables, then it does not make
- sense outside the lexical context for which it was set up. Such an
- expression is disabled when execution enters a context where one of its
- variables is not defined. For example, if you give the command
- @code{display last_char} while inside a function with an argument
- @code{last_char}, @value{GDBN} displays this argument while your program
- continues to stop inside that function. When it stops elsewhere---where
- there is no variable @code{last_char}---the display is disabled
- automatically. The next time your program stops where @code{last_char}
- is meaningful, you can enable the display expression once again.
- @node Print Settings
- @section Print Settings
- @cindex format options
- @cindex print settings
- @value{GDBN} provides the following ways to control how arrays, structures,
- and symbols are printed.
- @noindent
- These settings are useful for debugging programs in any language:
- @table @code
- @kindex set print
- @anchor{set print address}
- @item set print address
- @itemx set print address on
- @cindex print/don't print memory addresses
- @value{GDBN} prints memory addresses showing the location of stack
- traces, structure values, pointer values, breakpoints, and so forth,
- even when it also displays the contents of those addresses. The default
- is @code{on}. For example, this is what a stack frame display looks like with
- @code{set print address on}:
- @smallexample
- @group
- (@value{GDBP}) f
- #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
- at input.c:530
- 530 if (lquote != def_lquote)
- @end group
- @end smallexample
- @item set print address off
- Do not print addresses when displaying their contents. For example,
- this is the same stack frame displayed with @code{set print address off}:
- @smallexample
- @group
- (@value{GDBP}) set print addr off
- (@value{GDBP}) f
- #0 set_quotes (lq="<<", rq=">>") at input.c:530
- 530 if (lquote != def_lquote)
- @end group
- @end smallexample
- You can use @samp{set print address off} to eliminate all machine
- dependent displays from the @value{GDBN} interface. For example, with
- @code{print address off}, you should get the same text for backtraces on
- all machines---whether or not they involve pointer arguments.
- @kindex show print
- @item show print address
- Show whether or not addresses are to be printed.
- @end table
- When @value{GDBN} prints a symbolic address, it normally prints the
- closest earlier symbol plus an offset. If that symbol does not uniquely
- identify the address (for example, it is a name whose scope is a single
- source file), you may need to clarify. One way to do this is with
- @code{info line}, for example @samp{info line *0x4537}. Alternately,
- you can set @value{GDBN} to print the source file and line number when
- it prints a symbolic address:
- @table @code
- @item set print symbol-filename on
- @cindex source file and line of a symbol
- @cindex symbol, source file and line
- Tell @value{GDBN} to print the source file name and line number of a
- symbol in the symbolic form of an address.
- @item set print symbol-filename off
- Do not print source file name and line number of a symbol. This is the
- default.
- @item show print symbol-filename
- Show whether or not @value{GDBN} will print the source file name and
- line number of a symbol in the symbolic form of an address.
- @end table
- Another situation where it is helpful to show symbol filenames and line
- numbers is when disassembling code; @value{GDBN} shows you the line
- number and source file that corresponds to each instruction.
- Also, you may wish to see the symbolic form only if the address being
- printed is reasonably close to the closest earlier symbol:
- @table @code
- @item set print max-symbolic-offset @var{max-offset}
- @itemx set print max-symbolic-offset unlimited
- @cindex maximum value for offset of closest symbol
- Tell @value{GDBN} to only display the symbolic form of an address if the
- offset between the closest earlier symbol and the address is less than
- @var{max-offset}. The default is @code{unlimited}, which tells @value{GDBN}
- to always print the symbolic form of an address if any symbol precedes
- it. Zero is equivalent to @code{unlimited}.
- @item show print max-symbolic-offset
- Ask how large the maximum offset is that @value{GDBN} prints in a
- symbolic address.
- @end table
- @cindex wild pointer, interpreting
- @cindex pointer, finding referent
- If you have a pointer and you are not sure where it points, try
- @samp{set print symbol-filename on}. Then you can determine the name
- and source file location of the variable where it points, using
- @samp{p/a @var{pointer}}. This interprets the address in symbolic form.
- For example, here @value{GDBN} shows that a variable @code{ptt} points
- at another variable @code{t}, defined in @file{hi2.c}:
- @smallexample
- (@value{GDBP}) set print symbol-filename on
- (@value{GDBP}) p/a ptt
- $4 = 0xe008 <t in hi2.c>
- @end smallexample
- @quotation
- @emph{Warning:} For pointers that point to a local variable, @samp{p/a}
- does not show the symbol name and filename of the referent, even with
- the appropriate @code{set print} options turned on.
- @end quotation
- You can also enable @samp{/a}-like formatting all the time using
- @samp{set print symbol on}:
- @anchor{set print symbol}
- @table @code
- @item set print symbol on
- Tell @value{GDBN} to print the symbol corresponding to an address, if
- one exists.
- @item set print symbol off
- Tell @value{GDBN} not to print the symbol corresponding to an
- address. In this mode, @value{GDBN} will still print the symbol
- corresponding to pointers to functions. This is the default.
- @item show print symbol
- Show whether @value{GDBN} will display the symbol corresponding to an
- address.
- @end table
- Other settings control how different kinds of objects are printed:
- @table @code
- @anchor{set print array}
- @item set print array
- @itemx set print array on
- @cindex pretty print arrays
- Pretty print arrays. This format is more convenient to read,
- but uses more space. The default is off.
- @item set print array off
- Return to compressed format for arrays.
- @item show print array
- Show whether compressed or pretty format is selected for displaying
- arrays.
- @cindex print array indexes
- @anchor{set print array-indexes}
- @item set print array-indexes
- @itemx set print array-indexes on
- Print the index of each element when displaying arrays. May be more
- convenient to locate a given element in the array or quickly find the
- index of a given element in that printed array. The default is off.
- @item set print array-indexes off
- Stop printing element indexes when displaying arrays.
- @item show print array-indexes
- Show whether the index of each element is printed when displaying
- arrays.
- @anchor{set print elements}
- @item set print elements @var{number-of-elements}
- @itemx set print elements unlimited
- @cindex number of array elements to print
- @cindex limit on number of printed array elements
- Set a limit on how many elements of an array @value{GDBN} will print.
- If @value{GDBN} is printing a large array, it stops printing after it has
- printed the number of elements set by the @code{set print elements} command.
- This limit also applies to the display of strings.
- When @value{GDBN} starts, this limit is set to 200.
- Setting @var{number-of-elements} to @code{unlimited} or zero means
- that the number of elements to print is unlimited.
- @item show print elements
- Display the number of elements of a large array that @value{GDBN} will print.
- @anchor{set print frame-arguments}
- @item set print frame-arguments @var{value}
- @kindex set print frame-arguments
- @cindex printing frame argument values
- @cindex print all frame argument values
- @cindex print frame argument values for scalars only
- @cindex do not print frame arguments
- This command allows to control how the values of arguments are printed
- when the debugger prints a frame (@pxref{Frames}). The possible
- values are:
- @table @code
- @item all
- The values of all arguments are printed.
- @item scalars
- Print the value of an argument only if it is a scalar. The value of more
- complex arguments such as arrays, structures, unions, etc, is replaced
- by @code{@dots{}}. This is the default. Here is an example where
- only scalar arguments are shown:
- @smallexample
- #1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
- at frame-args.c:23
- @end smallexample
- @item none
- None of the argument values are printed. Instead, the value of each argument
- is replaced by @code{@dots{}}. In this case, the example above now becomes:
- @smallexample
- #1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
- at frame-args.c:23
- @end smallexample
- @item presence
- Only the presence of arguments is indicated by @code{@dots{}}.
- The @code{@dots{}} are not printed for function without any arguments.
- None of the argument names and values are printed.
- In this case, the example above now becomes:
- @smallexample
- #1 0x08048361 in call_me (@dots{}) at frame-args.c:23
- @end smallexample
- @end table
- By default, only scalar arguments are printed. This command can be used
- to configure the debugger to print the value of all arguments, regardless
- of their type. However, it is often advantageous to not print the value
- of more complex parameters. For instance, it reduces the amount of
- information printed in each frame, making the backtrace more readable.
- Also, it improves performance when displaying Ada frames, because
- the computation of large arguments can sometimes be CPU-intensive,
- especially in large applications. Setting @code{print frame-arguments}
- to @code{scalars} (the default), @code{none} or @code{presence} avoids
- this computation, thus speeding up the display of each Ada frame.
- @item show print frame-arguments
- Show how the value of arguments should be displayed when printing a frame.
- @anchor{set print raw-frame-arguments}
- @item set print raw-frame-arguments on
- Print frame arguments in raw, non pretty-printed, form.
- @item set print raw-frame-arguments off
- Print frame arguments in pretty-printed form, if there is a pretty-printer
- for the value (@pxref{Pretty Printing}),
- otherwise print the value in raw form.
- This is the default.
- @item show print raw-frame-arguments
- Show whether to print frame arguments in raw form.
- @anchor{set print entry-values}
- @item set print entry-values @var{value}
- @kindex set print entry-values
- Set printing of frame argument values at function entry. In some cases
- @value{GDBN} can determine the value of function argument which was passed by
- the function caller, even if the value was modified inside the called function
- and therefore is different. With optimized code, the current value could be
- unavailable, but the entry value may still be known.
- The default value is @code{default} (see below for its description). Older
- @value{GDBN} behaved as with the setting @code{no}. Compilers not supporting
- this feature will behave in the @code{default} setting the same way as with the
- @code{no} setting.
- This functionality is currently supported only by DWARF 2 debugging format and
- the compiler has to produce @samp{DW_TAG_call_site} tags. With
- @value{NGCC}, you need to specify @option{-O -g} during compilation, to get
- this information.
- The @var{value} parameter can be one of the following:
- @table @code
- @item no
- Print only actual parameter values, never print values from function entry
- point.
- @smallexample
- #0 equal (val=5)
- #0 different (val=6)
- #0 lost (val=<optimized out>)
- #0 born (val=10)
- #0 invalid (val=<optimized out>)
- @end smallexample
- @item only
- Print only parameter values from function entry point. The actual parameter
- values are never printed.
- @smallexample
- #0 equal (val@@entry=5)
- #0 different (val@@entry=5)
- #0 lost (val@@entry=5)
- #0 born (val@@entry=<optimized out>)
- #0 invalid (val@@entry=<optimized out>)
- @end smallexample
- @item preferred
- Print only parameter values from function entry point. If value from function
- entry point is not known while the actual value is known, print the actual
- value for such parameter.
- @smallexample
- #0 equal (val@@entry=5)
- #0 different (val@@entry=5)
- #0 lost (val@@entry=5)
- #0 born (val=10)
- #0 invalid (val@@entry=<optimized out>)
- @end smallexample
- @item if-needed
- Print actual parameter values. If actual parameter value is not known while
- value from function entry point is known, print the entry point value for such
- parameter.
- @smallexample
- #0 equal (val=5)
- #0 different (val=6)
- #0 lost (val@@entry=5)
- #0 born (val=10)
- #0 invalid (val=<optimized out>)
- @end smallexample
- @item both
- Always print both the actual parameter value and its value from function entry
- point, even if values of one or both are not available due to compiler
- optimizations.
- @smallexample
- #0 equal (val=5, val@@entry=5)
- #0 different (val=6, val@@entry=5)
- #0 lost (val=<optimized out>, val@@entry=5)
- #0 born (val=10, val@@entry=<optimized out>)
- #0 invalid (val=<optimized out>, val@@entry=<optimized out>)
- @end smallexample
- @item compact
- Print the actual parameter value if it is known and also its value from
- function entry point if it is known. If neither is known, print for the actual
- value @code{<optimized out>}. If not in MI mode (@pxref{GDB/MI}) and if both
- values are known and identical, print the shortened
- @code{param=param@@entry=VALUE} notation.
- @smallexample
- #0 equal (val=val@@entry=5)
- #0 different (val=6, val@@entry=5)
- #0 lost (val@@entry=5)
- #0 born (val=10)
- #0 invalid (val=<optimized out>)
- @end smallexample
- @item default
- Always print the actual parameter value. Print also its value from function
- entry point, but only if it is known. If not in MI mode (@pxref{GDB/MI}) and
- if both values are known and identical, print the shortened
- @code{param=param@@entry=VALUE} notation.
- @smallexample
- #0 equal (val=val@@entry=5)
- #0 different (val=6, val@@entry=5)
- #0 lost (val=<optimized out>, val@@entry=5)
- #0 born (val=10)
- #0 invalid (val=<optimized out>)
- @end smallexample
- @end table
- For analysis messages on possible failures of frame argument values at function
- entry resolution see @ref{set debug entry-values}.
- @item show print entry-values
- Show the method being used for printing of frame argument values at function
- entry.
- @anchor{set print frame-info}
- @item set print frame-info @var{value}
- @kindex set print frame-info
- @cindex printing frame information
- @cindex frame information, printing
- This command allows to control the information printed when
- the debugger prints a frame. See @ref{Frames}, @ref{Backtrace},
- for a general explanation about frames and frame information.
- Note that some other settings (such as @code{set print frame-arguments}
- and @code{set print address}) are also influencing if and how some frame
- information is displayed. In particular, the frame program counter is never
- printed if @code{set print address} is off.
- The possible values for @code{set print frame-info} are:
- @table @code
- @item short-location
- Print the frame level, the program counter (if not at the
- beginning of the location source line), the function, the function
- arguments.
- @item location
- Same as @code{short-location} but also print the source file and source line
- number.
- @item location-and-address
- Same as @code{location} but print the program counter even if located at the
- beginning of the location source line.
- @item source-line
- Print the program counter (if not at the beginning of the location
- source line), the line number and the source line.
- @item source-and-location
- Print what @code{location} and @code{source-line} are printing.
- @item auto
- The information printed for a frame is decided automatically
- by the @value{GDBN} command that prints a frame.
- For example, @code{frame} prints the information printed by
- @code{source-and-location} while @code{stepi} will switch between
- @code{source-line} and @code{source-and-location} depending on the program
- counter.
- The default value is @code{auto}.
- @end table
- @anchor{set print repeats}
- @item set print repeats @var{number-of-repeats}
- @itemx set print repeats unlimited
- @cindex repeated array elements
- Set the threshold for suppressing display of repeated array
- elements. When the number of consecutive identical elements of an
- array exceeds the threshold, @value{GDBN} prints the string
- @code{"<repeats @var{n} times>"}, where @var{n} is the number of
- identical repetitions, instead of displaying the identical elements
- themselves. Setting the threshold to @code{unlimited} or zero will
- cause all elements to be individually printed. The default threshold
- is 10.
- @item show print repeats
- Display the current threshold for printing repeated identical
- elements.
- @anchor{set print max-depth}
- @item set print max-depth @var{depth}
- @item set print max-depth unlimited
- @cindex printing nested structures
- Set the threshold after which nested structures are replaced with
- ellipsis, this can make visualising deeply nested structures easier.
- For example, given this C code
- @smallexample
- typedef struct s1 @{ int a; @} s1;
- typedef struct s2 @{ s1 b; @} s2;
- typedef struct s3 @{ s2 c; @} s3;
- typedef struct s4 @{ s3 d; @} s4;
- s4 var = @{ @{ @{ @{ 3 @} @} @} @};
- @end smallexample
- The following table shows how different values of @var{depth} will
- effect how @code{var} is printed by @value{GDBN}:
- @multitable @columnfractions .3 .7
- @headitem @var{depth} setting @tab Result of @samp{p var}
- @item unlimited
- @tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
- @item @code{0}
- @tab @code{$1 = @{...@}}
- @item @code{1}
- @tab @code{$1 = @{d = @{...@}@}}
- @item @code{2}
- @tab @code{$1 = @{d = @{c = @{...@}@}@}}
- @item @code{3}
- @tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}}
- @item @code{4}
- @tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
- @end multitable
- To see the contents of structures that have been hidden the user can
- either increase the print max-depth, or they can print the elements of
- the structure that are visible, for example
- @smallexample
- (gdb) set print max-depth 2
- (gdb) p var
- $1 = @{d = @{c = @{...@}@}@}
- (gdb) p var.d
- $2 = @{c = @{b = @{...@}@}@}
- (gdb) p var.d.c
- $3 = @{b = @{a = 3@}@}
- @end smallexample
- The pattern used to replace nested structures varies based on
- language, for most languages @code{@{...@}} is used, but Fortran uses
- @code{(...)}.
- @item show print max-depth
- Display the current threshold after which nested structures are
- replaces with ellipsis.
- @anchor{set print memory-tag-violations}
- @cindex printing memory tag violation information
- @item set print memory-tag-violations
- @itemx set print memory-tag-violations on
- Cause @value{GDBN} to display additional information about memory tag violations
- when printing pointers and addresses.
- @item set print memory-tag-violations off
- Stop printing memory tag violation information.
- @item show print memory-tag-violations
- Show whether memory tag violation information is displayed when printing
- pointers and addresses.
- @anchor{set print null-stop}
- @item set print null-stop
- @cindex @sc{null} elements in arrays
- Cause @value{GDBN} to stop printing the characters of an array when the first
- @sc{null} is encountered. This is useful when large arrays actually
- contain only short strings.
- The default is off.
- @item show print null-stop
- Show whether @value{GDBN} stops printing an array on the first
- @sc{null} character.
- @anchor{set print pretty}
- @item set print pretty on
- @cindex print structures in indented form
- @cindex indentation in structure display
- Cause @value{GDBN} to print structures in an indented format with one member
- per line, like this:
- @smallexample
- @group
- $1 = @{
- next = 0x0,
- flags = @{
- sweet = 1,
- sour = 1
- @},
- meat = 0x54 "Pork"
- @}
- @end group
- @end smallexample
- @item set print pretty off
- Cause @value{GDBN} to print structures in a compact format, like this:
- @smallexample
- @group
- $1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
- meat = 0x54 "Pork"@}
- @end group
- @end smallexample
- @noindent
- This is the default format.
- @item show print pretty
- Show which format @value{GDBN} is using to print structures.
- @anchor{set print raw-values}
- @item set print raw-values on
- Print values in raw form, without applying the pretty
- printers for the value.
- @item set print raw-values off
- Print values in pretty-printed form, if there is a pretty-printer
- for the value (@pxref{Pretty Printing}),
- otherwise print the value in raw form.
- The default setting is ``off''.
- @item show print raw-values
- Show whether to print values in raw form.
- @item set print sevenbit-strings on
- @cindex eight-bit characters in strings
- @cindex octal escapes in strings
- Print using only seven-bit characters; if this option is set,
- @value{GDBN} displays any eight-bit characters (in strings or
- character values) using the notation @code{\}@var{nnn}. This setting is
- best if you are working in English (@sc{ascii}) and you use the
- high-order bit of characters as a marker or ``meta'' bit.
- @item set print sevenbit-strings off
- Print full eight-bit characters. This allows the use of more
- international character sets, and is the default.
- @item show print sevenbit-strings
- Show whether or not @value{GDBN} is printing only seven-bit characters.
- @anchor{set print union}
- @item set print union on
- @cindex unions in structures, printing
- Tell @value{GDBN} to print unions which are contained in structures
- and other unions. This is the default setting.
- @item set print union off
- Tell @value{GDBN} not to print unions which are contained in
- structures and other unions. @value{GDBN} will print @code{"@{...@}"}
- instead.
- @item show print union
- Ask @value{GDBN} whether or not it will print unions which are contained in
- structures and other unions.
- For example, given the declarations
- @smallexample
- typedef enum @{Tree, Bug@} Species;
- typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
- typedef enum @{Caterpillar, Cocoon, Butterfly@}
- Bug_forms;
- struct thing @{
- Species it;
- union @{
- Tree_forms tree;
- Bug_forms bug;
- @} form;
- @};
- struct thing foo = @{Tree, @{Acorn@}@};
- @end smallexample
- @noindent
- with @code{set print union on} in effect @samp{p foo} would print
- @smallexample
- $1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
- @end smallexample
- @noindent
- and with @code{set print union off} in effect it would print
- @smallexample
- $1 = @{it = Tree, form = @{...@}@}
- @end smallexample
- @noindent
- @code{set print union} affects programs written in C-like languages
- and in Pascal.
- @end table
- @need 1000
- @noindent
- These settings are of interest when debugging C@t{++} programs:
- @table @code
- @cindex demangling C@t{++} names
- @item set print demangle
- @itemx set print demangle on
- Print C@t{++} names in their source form rather than in the encoded
- (``mangled'') form passed to the assembler and linker for type-safe
- linkage. The default is on.
- @item show print demangle
- Show whether C@t{++} names are printed in mangled or demangled form.
- @item set print asm-demangle
- @itemx set print asm-demangle on
- Print C@t{++} names in their source form rather than their mangled form, even
- in assembler code printouts such as instruction disassemblies.
- The default is off.
- @item show print asm-demangle
- Show whether C@t{++} names in assembly listings are printed in mangled
- or demangled form.
- @cindex C@t{++} symbol decoding style
- @cindex symbol decoding style, C@t{++}
- @kindex set demangle-style
- @item set demangle-style @var{style}
- Choose among several encoding schemes used by different compilers to represent
- C@t{++} names. If you omit @var{style}, you will see a list of possible
- formats. The default value is @var{auto}, which lets @value{GDBN} choose a
- decoding style by inspecting your program.
- @item show demangle-style
- Display the encoding style currently in use for decoding C@t{++} symbols.
- @anchor{set print object}
- @item set print object
- @itemx set print object on
- @cindex derived type of an object, printing
- @cindex display derived types
- When displaying a pointer to an object, identify the @emph{actual}
- (derived) type of the object rather than the @emph{declared} type, using
- the virtual function table. Note that the virtual function table is
- required---this feature can only work for objects that have run-time
- type identification; a single virtual method in the object's declared
- type is sufficient. Note that this setting is also taken into account when
- working with variable objects via MI (@pxref{GDB/MI}).
- @item set print object off
- Display only the declared type of objects, without reference to the
- virtual function table. This is the default setting.
- @item show print object
- Show whether actual, or declared, object types are displayed.
- @anchor{set print static-members}
- @item set print static-members
- @itemx set print static-members on
- @cindex static members of C@t{++} objects
- Print static members when displaying a C@t{++} object. The default is on.
- @item set print static-members off
- Do not print static members when displaying a C@t{++} object.
- @item show print static-members
- Show whether C@t{++} static members are printed or not.
- @item set print pascal_static-members
- @itemx set print pascal_static-members on
- @cindex static members of Pascal objects
- @cindex Pascal objects, static members display
- Print static members when displaying a Pascal object. The default is on.
- @item set print pascal_static-members off
- Do not print static members when displaying a Pascal object.
- @item show print pascal_static-members
- Show whether Pascal static members are printed or not.
- @c These don't work with HP ANSI C++ yet.
- @anchor{set print vtbl}
- @item set print vtbl
- @itemx set print vtbl on
- @cindex pretty print C@t{++} virtual function tables
- @cindex virtual functions (C@t{++}) display
- @cindex VTBL display
- Pretty print C@t{++} virtual function tables. The default is off.
- (The @code{vtbl} commands do not work on programs compiled with the HP
- ANSI C@t{++} compiler (@code{aCC}).)
- @item set print vtbl off
- Do not pretty print C@t{++} virtual function tables.
- @item show print vtbl
- Show whether C@t{++} virtual function tables are pretty printed, or not.
- @end table
- @node Pretty Printing
- @section Pretty Printing
- @value{GDBN} provides a mechanism to allow pretty-printing of values using
- Python code. It greatly simplifies the display of complex objects. This
- mechanism works for both MI and the CLI.
- @menu
- * Pretty-Printer Introduction:: Introduction to pretty-printers
- * Pretty-Printer Example:: An example pretty-printer
- * Pretty-Printer Commands:: Pretty-printer commands
- @end menu
- @node Pretty-Printer Introduction
- @subsection Pretty-Printer Introduction
- When @value{GDBN} prints a value, it first sees if there is a pretty-printer
- registered for the value. If there is then @value{GDBN} invokes the
- pretty-printer to print the value. Otherwise the value is printed normally.
- Pretty-printers are normally named. This makes them easy to manage.
- The @samp{info pretty-printer} command will list all the installed
- pretty-printers with their names.
- If a pretty-printer can handle multiple data types, then its
- @dfn{subprinters} are the printers for the individual data types.
- Each such subprinter has its own name.
- The format of the name is @var{printer-name};@var{subprinter-name}.
- Pretty-printers are installed by @dfn{registering} them with @value{GDBN}.
- Typically they are automatically loaded and registered when the corresponding
- debug information is loaded, thus making them available without having to
- do anything special.
- There are three places where a pretty-printer can be registered.
- @itemize @bullet
- @item
- Pretty-printers registered globally are available when debugging
- all inferiors.
- @item
- Pretty-printers registered with a program space are available only
- when debugging that program.
- @xref{Progspaces In Python}, for more details on program spaces in Python.
- @item
- Pretty-printers registered with an objfile are loaded and unloaded
- with the corresponding objfile (e.g., shared library).
- @xref{Objfiles In Python}, for more details on objfiles in Python.
- @end itemize
- @xref{Selecting Pretty-Printers}, for further information on how
- pretty-printers are selected,
- @xref{Writing a Pretty-Printer}, for implementing pretty printers
- for new types.
- @node Pretty-Printer Example
- @subsection Pretty-Printer Example
- Here is how a C@t{++} @code{std::string} looks without a pretty-printer:
- @smallexample
- (@value{GDBP}) print s
- $1 = @{
- static npos = 4294967295,
- _M_dataplus = @{
- <std::allocator<char>> = @{
- <__gnu_cxx::new_allocator<char>> = @{
- <No data fields>@}, <No data fields>
- @},
- members of std::basic_string<char, std::char_traits<char>,
- std::allocator<char> >::_Alloc_hider:
- _M_p = 0x804a014 "abcd"
- @}
- @}
- @end smallexample
- With a pretty-printer for @code{std::string} only the contents are printed:
- @smallexample
- (@value{GDBP}) print s
- $2 = "abcd"
- @end smallexample
- @node Pretty-Printer Commands
- @subsection Pretty-Printer Commands
- @cindex pretty-printer commands
- @table @code
- @kindex info pretty-printer
- @item info pretty-printer [@var{object-regexp} [@var{name-regexp}]]
- Print the list of installed pretty-printers.
- This includes disabled pretty-printers, which are marked as such.
- @var{object-regexp} is a regular expression matching the objects
- whose pretty-printers to list.
- Objects can be @code{global}, the program space's file
- (@pxref{Progspaces In Python}),
- and the object files within that program space (@pxref{Objfiles In Python}).
- @xref{Selecting Pretty-Printers}, for details on how @value{GDBN}
- looks up a printer from these three objects.
- @var{name-regexp} is a regular expression matching the name of the printers
- to list.
- @kindex disable pretty-printer
- @item disable pretty-printer [@var{object-regexp} [@var{name-regexp}]]
- Disable pretty-printers matching @var{object-regexp} and @var{name-regexp}.
- A disabled pretty-printer is not forgotten, it may be enabled again later.
- @kindex enable pretty-printer
- @item enable pretty-printer [@var{object-regexp} [@var{name-regexp}]]
- Enable pretty-printers matching @var{object-regexp} and @var{name-regexp}.
- @end table
- Example:
- Suppose we have three pretty-printers installed: one from library1.so
- named @code{foo} that prints objects of type @code{foo}, and
- another from library2.so named @code{bar} that prints two types of objects,
- @code{bar1} and @code{bar2}.
- @smallexample
- (gdb) info pretty-printer
- library1.so:
- foo
- library2.so:
- bar
- bar1
- bar2
- (gdb) info pretty-printer library2
- library2.so:
- bar
- bar1
- bar2
- (gdb) disable pretty-printer library1
- 1 printer disabled
- 2 of 3 printers enabled
- (gdb) info pretty-printer
- library1.so:
- foo [disabled]
- library2.so:
- bar
- bar1
- bar2
- (gdb) disable pretty-printer library2 bar;bar1
- 1 printer disabled
- 1 of 3 printers enabled
- (gdb) info pretty-printer library2
- library1.so:
- foo [disabled]
- library2.so:
- bar
- bar1 [disabled]
- bar2
- (gdb) disable pretty-printer library2 bar
- 1 printer disabled
- 0 of 3 printers enabled
- (gdb) info pretty-printer library2
- library1.so:
- foo [disabled]
- library2.so:
- bar [disabled]
- bar1 [disabled]
- bar2
- @end smallexample
- Note that for @code{bar} the entire printer can be disabled,
- as can each individual subprinter.
- Printing values and frame arguments is done by default using
- the enabled pretty printers.
- The print option @code{-raw-values} and @value{GDBN} setting
- @code{set print raw-values} (@pxref{set print raw-values}) can be
- used to print values without applying the enabled pretty printers.
- Similarly, the backtrace option @code{-raw-frame-arguments} and
- @value{GDBN} setting @code{set print raw-frame-arguments}
- (@pxref{set print raw-frame-arguments}) can be used to ignore the
- enabled pretty printers when printing frame argument values.
- @node Value History
- @section Value History
- @cindex value history
- @cindex history of values printed by @value{GDBN}
- Values printed by the @code{print} command are saved in the @value{GDBN}
- @dfn{value history}. This allows you to refer to them in other expressions.
- Values are kept until the symbol table is re-read or discarded
- (for example with the @code{file} or @code{symbol-file} commands).
- When the symbol table changes, the value history is discarded,
- since the values may contain pointers back to the types defined in the
- symbol table.
- @cindex @code{$}
- @cindex @code{$$}
- @cindex history number
- The values printed are given @dfn{history numbers} by which you can
- refer to them. These are successive integers starting with one.
- @code{print} shows you the history number assigned to a value by
- printing @samp{$@var{num} = } before the value; here @var{num} is the
- history number.
- To refer to any previous value, use @samp{$} followed by the value's
- history number. The way @code{print} labels its output is designed to
- remind you of this. Just @code{$} refers to the most recent value in
- the history, and @code{$$} refers to the value before that.
- @code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
- is the value just prior to @code{$$}, @code{$$1} is equivalent to
- @code{$$}, and @code{$$0} is equivalent to @code{$}.
- For example, suppose you have just printed a pointer to a structure and
- want to see the contents of the structure. It suffices to type
- @smallexample
- p *$
- @end smallexample
- If you have a chain of structures where the component @code{next} points
- to the next one, you can print the contents of the next one with this:
- @smallexample
- p *$.next
- @end smallexample
- @noindent
- You can print successive links in the chain by repeating this
- command---which you can do by just typing @key{RET}.
- Note that the history records values, not expressions. If the value of
- @code{x} is 4 and you type these commands:
- @smallexample
- print x
- set x=5
- @end smallexample
- @noindent
- then the value recorded in the value history by the @code{print} command
- remains 4 even though the value of @code{x} has changed.
- @table @code
- @kindex show values
- @item show values
- Print the last ten values in the value history, with their item numbers.
- This is like @samp{p@ $$9} repeated ten times, except that @code{show
- values} does not change the history.
- @item show values @var{n}
- Print ten history values centered on history item number @var{n}.
- @item show values +
- Print ten history values just after the values last printed. If no more
- values are available, @code{show values +} produces no display.
- @end table
- Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
- same effect as @samp{show values +}.
- @node Convenience Vars
- @section Convenience Variables
- @cindex convenience variables
- @cindex user-defined variables
- @value{GDBN} provides @dfn{convenience variables} that you can use within
- @value{GDBN} to hold on to a value and refer to it later. These variables
- exist entirely within @value{GDBN}; they are not part of your program, and
- setting a convenience variable has no direct effect on further execution
- of your program. That is why you can use them freely.
- Convenience variables are prefixed with @samp{$}. Any name preceded by
- @samp{$} can be used for a convenience variable, unless it is one of
- the predefined machine-specific register names (@pxref{Registers, ,Registers}).
- (Value history references, in contrast, are @emph{numbers} preceded
- by @samp{$}. @xref{Value History, ,Value History}.)
- You can save a value in a convenience variable with an assignment
- expression, just as you would set a variable in your program.
- For example:
- @smallexample
- set $foo = *object_ptr
- @end smallexample
- @noindent
- would save in @code{$foo} the value contained in the object pointed to by
- @code{object_ptr}.
- Using a convenience variable for the first time creates it, but its
- value is @code{void} until you assign a new value. You can alter the
- value with another assignment at any time.
- Convenience variables have no fixed types. You can assign a convenience
- variable any type of value, including structures and arrays, even if
- that variable already has a value of a different type. The convenience
- variable, when used as an expression, has the type of its current value.
- @table @code
- @kindex show convenience
- @cindex show all user variables and functions
- @item show convenience
- Print a list of convenience variables used so far, and their values,
- as well as a list of the convenience functions.
- Abbreviated @code{show conv}.
- @kindex init-if-undefined
- @cindex convenience variables, initializing
- @item init-if-undefined $@var{variable} = @var{expression}
- Set a convenience variable if it has not already been set. This is useful
- for user-defined commands that keep some state. It is similar, in concept,
- to using local static variables with initializers in C (except that
- convenience variables are global). It can also be used to allow users to
- override default values used in a command script.
- If the variable is already defined then the expression is not evaluated so
- any side-effects do not occur.
- @end table
- One of the ways to use a convenience variable is as a counter to be
- incremented or a pointer to be advanced. For example, to print
- a field from successive elements of an array of structures:
- @smallexample
- set $i = 0
- print bar[$i++]->contents
- @end smallexample
- @noindent
- Repeat that command by typing @key{RET}.
- Some convenience variables are created automatically by @value{GDBN} and given
- values likely to be useful.
- @table @code
- @vindex $_@r{, convenience variable}
- @item $_
- The variable @code{$_} is automatically set by the @code{x} command to
- the last address examined (@pxref{Memory, ,Examining Memory}). Other
- commands which provide a default address for @code{x} to examine also
- set @code{$_} to that address; these commands include @code{info line}
- and @code{info breakpoint}. The type of @code{$_} is @code{void *}
- except when set by the @code{x} command, in which case it is a pointer
- to the type of @code{$__}.
- @vindex $__@r{, convenience variable}
- @item $__
- The variable @code{$__} is automatically set by the @code{x} command
- to the value found in the last address examined. Its type is chosen
- to match the format in which the data was printed.
- @item $_exitcode
- @vindex $_exitcode@r{, convenience variable}
- When the program being debugged terminates normally, @value{GDBN}
- automatically sets this variable to the exit code of the program, and
- resets @code{$_exitsignal} to @code{void}.
- @item $_exitsignal
- @vindex $_exitsignal@r{, convenience variable}
- When the program being debugged dies due to an uncaught signal,
- @value{GDBN} automatically sets this variable to that signal's number,
- and resets @code{$_exitcode} to @code{void}.
- To distinguish between whether the program being debugged has exited
- (i.e., @code{$_exitcode} is not @code{void}) or signalled (i.e.,
- @code{$_exitsignal} is not @code{void}), the convenience function
- @code{$_isvoid} can be used (@pxref{Convenience Funs,, Convenience
- Functions}). For example, considering the following source code:
- @smallexample
- #include <signal.h>
- int
- main (int argc, char *argv[])
- @{
- raise (SIGALRM);
- return 0;
- @}
- @end smallexample
- A valid way of telling whether the program being debugged has exited
- or signalled would be:
- @smallexample
- (@value{GDBP}) define has_exited_or_signalled
- Type commands for definition of ``has_exited_or_signalled''.
- End with a line saying just ``end''.
- >if $_isvoid ($_exitsignal)
- >echo The program has exited\n
- >else
- >echo The program has signalled\n
- >end
- >end
- (@value{GDBP}) run
- Starting program:
- Program terminated with signal SIGALRM, Alarm clock.
- The program no longer exists.
- (@value{GDBP}) has_exited_or_signalled
- The program has signalled
- @end smallexample
- As can be seen, @value{GDBN} correctly informs that the program being
- debugged has signalled, since it calls @code{raise} and raises a
- @code{SIGALRM} signal. If the program being debugged had not called
- @code{raise}, then @value{GDBN} would report a normal exit:
- @smallexample
- (@value{GDBP}) has_exited_or_signalled
- The program has exited
- @end smallexample
- @item $_exception
- The variable @code{$_exception} is set to the exception object being
- thrown at an exception-related catchpoint. @xref{Set Catchpoints}.
- @item $_ada_exception
- The variable @code{$_ada_exception} is set to the address of the
- exception being caught or thrown at an Ada exception-related
- catchpoint. @xref{Set Catchpoints}.
- @item $_probe_argc
- @itemx $_probe_arg0@dots{}$_probe_arg11
- Arguments to a static probe. @xref{Static Probe Points}.
- @item $_sdata
- @vindex $_sdata@r{, inspect, convenience variable}
- The variable @code{$_sdata} contains extra collected static tracepoint
- data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that
- @code{$_sdata} could be empty, if not inspecting a trace buffer, or
- if extra static tracepoint data has not been collected.
- @item $_siginfo
- @vindex $_siginfo@r{, convenience variable}
- The variable @code{$_siginfo} contains extra signal information
- (@pxref{extra signal information}). Note that @code{$_siginfo}
- could be empty, if the application has not yet received any signals.
- For example, it will be empty before you execute the @code{run} command.
- @item $_tlb
- @vindex $_tlb@r{, convenience variable}
- The variable @code{$_tlb} is automatically set when debugging
- applications running on MS-Windows in native mode or connected to
- gdbserver that supports the @code{qGetTIBAddr} request.
- @xref{General Query Packets}.
- This variable contains the address of the thread information block.
- @item $_inferior
- The number of the current inferior. @xref{Inferiors Connections and
- Programs, ,Debugging Multiple Inferiors Connections and Programs}.
- @item $_thread
- The thread number of the current thread. @xref{thread numbers}.
- @item $_gthread
- The global number of the current thread. @xref{global thread numbers}.
- @item $_gdb_major
- @itemx $_gdb_minor
- @vindex $_gdb_major@r{, convenience variable}
- @vindex $_gdb_minor@r{, convenience variable}
- The major and minor version numbers of the running @value{GDBN}.
- Development snapshots and pretest versions have their minor version
- incremented by one; thus, @value{GDBN} pretest 9.11.90 will produce
- the value 12 for @code{$_gdb_minor}. These variables allow you to
- write scripts that work with different versions of @value{GDBN}
- without errors caused by features unavailable in some of those
- versions.
- @item $_shell_exitcode
- @itemx $_shell_exitsignal
- @vindex $_shell_exitcode@r{, convenience variable}
- @vindex $_shell_exitsignal@r{, convenience variable}
- @cindex shell command, exit code
- @cindex shell command, exit signal
- @cindex exit status of shell commands
- @value{GDBN} commands such as @code{shell} and @code{|} are launching
- shell commands. When a launched command terminates, @value{GDBN}
- automatically maintains the variables @code{$_shell_exitcode}
- and @code{$_shell_exitsignal} according to the exit status of the last
- launched command. These variables are set and used similarly to
- the variables @code{$_exitcode} and @code{$_exitsignal}.
- @end table
- @node Convenience Funs
- @section Convenience Functions
- @cindex convenience functions
- @value{GDBN} also supplies some @dfn{convenience functions}. These
- have a syntax similar to convenience variables. A convenience
- function can be used in an expression just like an ordinary function;
- however, a convenience function is implemented internally to
- @value{GDBN}.
- These functions do not require @value{GDBN} to be configured with
- @code{Python} support, which means that they are always available.
- @table @code
- @item $_isvoid (@var{expr})
- @findex $_isvoid@r{, convenience function}
- Return one if the expression @var{expr} is @code{void}. Otherwise it
- returns zero.
- A @code{void} expression is an expression where the type of the result
- is @code{void}. For example, you can examine a convenience variable
- (see @ref{Convenience Vars,, Convenience Variables}) to check whether
- it is @code{void}:
- @smallexample
- (@value{GDBP}) print $_exitcode
- $1 = void
- (@value{GDBP}) print $_isvoid ($_exitcode)
- $2 = 1
- (@value{GDBP}) run
- Starting program: ./a.out
- [Inferior 1 (process 29572) exited normally]
- (@value{GDBP}) print $_exitcode
- $3 = 0
- (@value{GDBP}) print $_isvoid ($_exitcode)
- $4 = 0
- @end smallexample
- In the example above, we used @code{$_isvoid} to check whether
- @code{$_exitcode} is @code{void} before and after the execution of the
- program being debugged. Before the execution there is no exit code to
- be examined, therefore @code{$_exitcode} is @code{void}. After the
- execution the program being debugged returned zero, therefore
- @code{$_exitcode} is zero, which means that it is not @code{void}
- anymore.
- The @code{void} expression can also be a call of a function from the
- program being debugged. For example, given the following function:
- @smallexample
- void
- foo (void)
- @{
- @}
- @end smallexample
- The result of calling it inside @value{GDBN} is @code{void}:
- @smallexample
- (@value{GDBP}) print foo ()
- $1 = void
- (@value{GDBP}) print $_isvoid (foo ())
- $2 = 1
- (@value{GDBP}) set $v = foo ()
- (@value{GDBP}) print $v
- $3 = void
- (@value{GDBP}) print $_isvoid ($v)
- $4 = 1
- @end smallexample
- @item $_gdb_setting_str (@var{setting})
- @findex $_gdb_setting_str@r{, convenience function}
- Return the value of the @value{GDBN} @var{setting} as a string.
- @var{setting} is any setting that can be used in a @code{set} or
- @code{show} command (@pxref{Controlling GDB}).
- @smallexample
- (@value{GDBP}) show print frame-arguments
- Printing of non-scalar frame arguments is "scalars".
- (@value{GDBP}) p $_gdb_setting_str("print frame-arguments")
- $1 = "scalars"
- (@value{GDBP}) p $_gdb_setting_str("height")
- $2 = "30"
- (@value{GDBP})
- @end smallexample
- @item $_gdb_setting (@var{setting})
- @findex $_gdb_setting@r{, convenience function}
- Return the value of the @value{GDBN} @var{setting}.
- The type of the returned value depends on the setting.
- The value type for boolean and auto boolean settings is @code{int}.
- The boolean values @code{off} and @code{on} are converted to
- the integer values @code{0} and @code{1}. The value @code{auto} is
- converted to the value @code{-1}.
- The value type for integer settings is either @code{unsigned int}
- or @code{int}, depending on the setting.
- Some integer settings accept an @code{unlimited} value.
- Depending on the setting, the @code{set} command also accepts
- the value @code{0} or the value @code{@minus{}1} as a synonym for
- @code{unlimited}.
- For example, @code{set height unlimited} is equivalent to
- @code{set height 0}.
- Some other settings that accept the @code{unlimited} value
- use the value @code{0} to literally mean zero.
- For example, @code{set history size 0} indicates to not
- record any @value{GDBN} commands in the command history.
- For such settings, @code{@minus{}1} is the synonym
- for @code{unlimited}.
- See the documentation of the corresponding @code{set} command for
- the numerical value equivalent to @code{unlimited}.
- The @code{$_gdb_setting} function converts the unlimited value
- to a @code{0} or a @code{@minus{}1} value according to what the
- @code{set} command uses.
- @smallexample
- @group
- (@value{GDBP}) p $_gdb_setting_str("height")
- $1 = "30"
- (@value{GDBP}) p $_gdb_setting("height")
- $2 = 30
- (@value{GDBP}) set height unlimited
- (@value{GDBP}) p $_gdb_setting_str("height")
- $3 = "unlimited"
- (@value{GDBP}) p $_gdb_setting("height")
- $4 = 0
- @end group
- @group
- (@value{GDBP}) p $_gdb_setting_str("history size")
- $5 = "unlimited"
- (@value{GDBP}) p $_gdb_setting("history size")
- $6 = -1
- (@value{GDBP}) p $_gdb_setting_str("disassemble-next-line")
- $7 = "auto"
- (@value{GDBP}) p $_gdb_setting("disassemble-next-line")
- $8 = -1
- (@value{GDBP})
- @end group
- @end smallexample
- Other setting types (enum, filename, optional filename, string, string noescape)
- are returned as string values.
- @item $_gdb_maint_setting_str (@var{setting})
- @findex $_gdb_maint_setting_str@r{, convenience function}
- Like the @code{$_gdb_setting_str} function, but works with
- @code{maintenance set} variables.
- @item $_gdb_maint_setting (@var{setting})
- @findex $_gdb_maint_setting@r{, convenience function}
- Like the @code{$_gdb_setting} function, but works with
- @code{maintenance set} variables.
- @end table
- The following functions require @value{GDBN} to be configured with
- @code{Python} support.
- @table @code
- @item $_memeq(@var{buf1}, @var{buf2}, @var{length})
- @findex $_memeq@r{, convenience function}
- Returns one if the @var{length} bytes at the addresses given by
- @var{buf1} and @var{buf2} are equal.
- Otherwise it returns zero.
- @item $_regex(@var{str}, @var{regex})
- @findex $_regex@r{, convenience function}
- Returns one if the string @var{str} matches the regular expression
- @var{regex}. Otherwise it returns zero.
- The syntax of the regular expression is that specified by @code{Python}'s
- regular expression support.
- @item $_streq(@var{str1}, @var{str2})
- @findex $_streq@r{, convenience function}
- Returns one if the strings @var{str1} and @var{str2} are equal.
- Otherwise it returns zero.
- @item $_strlen(@var{str})
- @findex $_strlen@r{, convenience function}
- Returns the length of string @var{str}.
- @item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
- @findex $_caller_is@r{, convenience function}
- Returns one if the calling function's name is equal to @var{name}.
- Otherwise it returns zero.
- If the optional argument @var{number_of_frames} is provided,
- it is the number of frames up in the stack to look.
- The default is 1.
- Example:
- @smallexample
- (gdb) backtrace
- #0 bottom_func ()
- at testsuite/gdb.python/py-caller-is.c:21
- #1 0x00000000004005a0 in middle_func ()
- at testsuite/gdb.python/py-caller-is.c:27
- #2 0x00000000004005ab in top_func ()
- at testsuite/gdb.python/py-caller-is.c:33
- #3 0x00000000004005b6 in main ()
- at testsuite/gdb.python/py-caller-is.c:39
- (gdb) print $_caller_is ("middle_func")
- $1 = 1
- (gdb) print $_caller_is ("top_func", 2)
- $1 = 1
- @end smallexample
- @item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
- @findex $_caller_matches@r{, convenience function}
- Returns one if the calling function's name matches the regular expression
- @var{regexp}. Otherwise it returns zero.
- If the optional argument @var{number_of_frames} is provided,
- it is the number of frames up in the stack to look.
- The default is 1.
- @item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
- @findex $_any_caller_is@r{, convenience function}
- Returns one if any calling function's name is equal to @var{name}.
- Otherwise it returns zero.
- If the optional argument @var{number_of_frames} is provided,
- it is the number of frames up in the stack to look.
- The default is 1.
- This function differs from @code{$_caller_is} in that this function
- checks all stack frames from the immediate caller to the frame specified
- by @var{number_of_frames}, whereas @code{$_caller_is} only checks the
- frame specified by @var{number_of_frames}.
- @item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
- @findex $_any_caller_matches@r{, convenience function}
- Returns one if any calling function's name matches the regular expression
- @var{regexp}. Otherwise it returns zero.
- If the optional argument @var{number_of_frames} is provided,
- it is the number of frames up in the stack to look.
- The default is 1.
- This function differs from @code{$_caller_matches} in that this function
- checks all stack frames from the immediate caller to the frame specified
- by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the
- frame specified by @var{number_of_frames}.
- @item $_as_string(@var{value})
- @findex $_as_string@r{, convenience function}
- Return the string representation of @var{value}.
- This function is useful to obtain the textual label (enumerator) of an
- enumeration value. For example, assuming the variable @var{node} is of
- an enumerated type:
- @smallexample
- (gdb) printf "Visiting node of type %s\n", $_as_string(node)
- Visiting node of type NODE_INTEGER
- @end smallexample
- @item $_cimag(@var{value})
- @itemx $_creal(@var{value})
- @findex $_cimag@r{, convenience function}
- @findex $_creal@r{, convenience function}
- Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of
- the complex number @var{value}.
- The type of the imaginary or real part depends on the type of the
- complex number, e.g., using @code{$_cimag} on a @code{float complex}
- will return an imaginary part of type @code{float}.
- @end table
- @value{GDBN} provides the ability to list and get help on
- convenience functions.
- @table @code
- @item help function
- @kindex help function
- @cindex show all convenience functions
- Print a list of all convenience functions.
- @end table
- @node Registers
- @section Registers
- @cindex registers
- You can refer to machine register contents, in expressions, as variables
- with names starting with @samp{$}. The names of registers are different
- for each machine; use @code{info registers} to see the names used on
- your machine.
- @table @code
- @kindex info registers
- @item info registers
- Print the names and values of all registers except floating-point
- and vector registers (in the selected stack frame).
- @kindex info all-registers
- @cindex floating point registers
- @item info all-registers
- Print the names and values of all registers, including floating-point
- and vector registers (in the selected stack frame).
- @anchor{info_registers_reggroup}
- @item info registers @var{reggroup} @dots{}
- Print the name and value of the registers in each of the specified
- @var{reggroup}s. The @var{reggroup} can be any of those returned by
- @code{maint print reggroups} (@pxref{Maintenance Commands}).
- @item info registers @var{regname} @dots{}
- Print the @dfn{relativized} value of each specified register @var{regname}.
- As discussed in detail below, register values are normally relative to
- the selected stack frame. The @var{regname} may be any register name valid on
- the machine you are using, with or without the initial @samp{$}.
- @end table
- @anchor{standard registers}
- @cindex stack pointer register
- @cindex program counter register
- @cindex process status register
- @cindex frame pointer register
- @cindex standard registers
- @value{GDBN} has four ``standard'' register names that are available (in
- expressions) on most machines---whenever they do not conflict with an
- architecture's canonical mnemonics for registers. The register names
- @code{$pc} and @code{$sp} are used for the program counter register and
- the stack pointer. @code{$fp} is used for a register that contains a
- pointer to the current stack frame, and @code{$ps} is used for a
- register that contains the processor status. For example,
- you could print the program counter in hex with
- @smallexample
- p/x $pc
- @end smallexample
- @noindent
- or print the instruction to be executed next with
- @smallexample
- x/i $pc
- @end smallexample
- @noindent
- or add four to the stack pointer@footnote{This is a way of removing
- one word from the stack, on machines where stacks grow downward in
- memory (most machines, nowadays). This assumes that the innermost
- stack frame is selected; setting @code{$sp} is not allowed when other
- stack frames are selected. To pop entire frames off the stack,
- regardless of machine architecture, use @code{return};
- see @ref{Returning, ,Returning from a Function}.} with
- @smallexample
- set $sp += 4
- @end smallexample
- Whenever possible, these four standard register names are available on
- your machine even though the machine has different canonical mnemonics,
- so long as there is no conflict. The @code{info registers} command
- shows the canonical names. For example, on the SPARC, @code{info
- registers} displays the processor status register as @code{$psr} but you
- can also refer to it as @code{$ps}; and on x86-based machines @code{$ps}
- is an alias for the @sc{eflags} register.
- @value{GDBN} always considers the contents of an ordinary register as an
- integer when the register is examined in this way. Some machines have
- special registers which can hold nothing but floating point; these
- registers are considered to have floating point values. There is no way
- to refer to the contents of an ordinary register as floating point value
- (although you can @emph{print} it as a floating point value with
- @samp{print/f $@var{regname}}).
- Some registers have distinct ``raw'' and ``virtual'' data formats. This
- means that the data format in which the register contents are saved by
- the operating system is not the same one that your program normally
- sees. For example, the registers of the 68881 floating point
- coprocessor are always saved in ``extended'' (raw) format, but all C
- programs expect to work with ``double'' (virtual) format. In such
- cases, @value{GDBN} normally works with the virtual format only (the format
- that makes sense for your program), but the @code{info registers} command
- prints the data in both formats.
- @cindex SSE registers (x86)
- @cindex MMX registers (x86)
- Some machines have special registers whose contents can be interpreted
- in several different ways. For example, modern x86-based machines
- have SSE and MMX registers that can hold several values packed
- together in several different formats. @value{GDBN} refers to such
- registers in @code{struct} notation:
- @smallexample
- (@value{GDBP}) print $xmm1
- $1 = @{
- v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@},
- v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@},
- v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",
- v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@},
- v4_int32 = @{0, 20657912, 11, 13@},
- v2_int64 = @{88725056443645952, 55834574859@},
- uint128 = 0x0000000d0000000b013b36f800000000
- @}
- @end smallexample
- @noindent
- To set values of such registers, you need to tell @value{GDBN} which
- view of the register you wish to change, as if you were assigning
- value to a @code{struct} member:
- @smallexample
- (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF
- @end smallexample
- Normally, register values are relative to the selected stack frame
- (@pxref{Selection, ,Selecting a Frame}). This means that you get the
- value that the register would contain if all stack frames farther in
- were exited and their saved registers restored. In order to see the
- true contents of hardware registers, you must select the innermost
- frame (with @samp{frame 0}).
- @cindex caller-saved registers
- @cindex call-clobbered registers
- @cindex volatile registers
- @cindex <not saved> values
- Usually ABIs reserve some registers as not needed to be saved by the
- callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile''
- registers). It may therefore not be possible for @value{GDBN} to know
- the value a register had before the call (in other words, in the outer
- frame), if the register value has since been changed by the callee.
- @value{GDBN} tries to deduce where the inner frame saved
- (``callee-saved'') registers, from the debug info, unwind info, or the
- machine code generated by your compiler. If some register is not
- saved, and @value{GDBN} knows the register is ``caller-saved'' (via
- its own knowledge of the ABI, or because the debug/unwind info
- explicitly says the register's value is undefined), @value{GDBN}
- displays @w{@samp{<not saved>}} as the register's value. With targets
- that @value{GDBN} has no knowledge of the register saving convention,
- if a register was not saved by the callee, then its value and location
- in the outer frame are assumed to be the same of the inner frame.
- This is usually harmless, because if the register is call-clobbered,
- the caller either does not care what is in the register after the
- call, or has code to restore the value that it does care about. Note,
- however, that if you change such a register in the outer frame, you
- may also be affecting the inner frame. Also, the more ``outer'' the
- frame is you're looking at, the more likely a call-clobbered
- register's value is to be wrong, in the sense that it doesn't actually
- represent the value the register had just before the call.
- @node Floating Point Hardware
- @section Floating Point Hardware
- @cindex floating point
- Depending on the configuration, @value{GDBN} may be able to give
- you more information about the status of the floating point hardware.
- @table @code
- @kindex info float
- @item info float
- Display hardware-dependent information about the floating
- point unit. The exact contents and layout vary depending on the
- floating point chip. Currently, @samp{info float} is supported on
- the ARM and x86 machines.
- @end table
- @node Vector Unit
- @section Vector Unit
- @cindex vector unit
- Depending on the configuration, @value{GDBN} may be able to give you
- more information about the status of the vector unit.
- @table @code
- @kindex info vector
- @item info vector
- Display information about the vector unit. The exact contents and
- layout vary depending on the hardware.
- @end table
- @node OS Information
- @section Operating System Auxiliary Information
- @cindex OS information
- @value{GDBN} provides interfaces to useful OS facilities that can help
- you debug your program.
- @cindex auxiliary vector
- @cindex vector, auxiliary
- Some operating systems supply an @dfn{auxiliary vector} to programs at
- startup. This is akin to the arguments and environment that you
- specify for a program, but contains a system-dependent variety of
- binary values that tell system libraries important details about the
- hardware, operating system, and process. Each value's purpose is
- identified by an integer tag; the meanings are well-known but system-specific.
- Depending on the configuration and operating system facilities,
- @value{GDBN} may be able to show you this information. For remote
- targets, this functionality may further depend on the remote stub's
- support of the @samp{qXfer:auxv:read} packet, see
- @ref{qXfer auxiliary vector read}.
- @table @code
- @kindex info auxv
- @item info auxv
- Display the auxiliary vector of the inferior, which can be either a
- live process or a core dump file. @value{GDBN} prints each tag value
- numerically, and also shows names and text descriptions for recognized
- tags. Some values in the vector are numbers, some bit masks, and some
- pointers to strings or other data. @value{GDBN} displays each value in the
- most appropriate form for a recognized tag, and in hexadecimal for
- an unrecognized tag.
- @end table
- On some targets, @value{GDBN} can access operating system-specific
- information and show it to you. The types of information available
- will differ depending on the type of operating system running on the
- target. The mechanism used to fetch the data is described in
- @ref{Operating System Information}. For remote targets, this
- functionality depends on the remote stub's support of the
- @samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}.
- @table @code
- @kindex info os
- @item info os @var{infotype}
- Display OS information of the requested type.
- On @sc{gnu}/Linux, the following values of @var{infotype} are valid:
- @anchor{linux info os infotypes}
- @table @code
- @kindex info os cpus
- @item cpus
- Display the list of all CPUs/cores. For each CPU/core, @value{GDBN} prints
- the available fields from /proc/cpuinfo. For each supported architecture
- different fields are available. Two common entries are processor which gives
- CPU number and bogomips; a system constant that is calculated during
- kernel initialization.
- @kindex info os files
- @item files
- Display the list of open file descriptors on the target. For each
- file descriptor, @value{GDBN} prints the identifier of the process
- owning the descriptor, the command of the owning process, the value
- of the descriptor, and the target of the descriptor.
- @kindex info os modules
- @item modules
- Display the list of all loaded kernel modules on the target. For each
- module, @value{GDBN} prints the module name, the size of the module in
- bytes, the number of times the module is used, the dependencies of the
- module, the status of the module, and the address of the loaded module
- in memory.
- @kindex info os msg
- @item msg
- Display the list of all System V message queues on the target. For each
- message queue, @value{GDBN} prints the message queue key, the message
- queue identifier, the access permissions, the current number of bytes
- on the queue, the current number of messages on the queue, the processes
- that last sent and received a message on the queue, the user and group
- of the owner and creator of the message queue, the times at which a
- message was last sent and received on the queue, and the time at which
- the message queue was last changed.
- @kindex info os processes
- @item processes
- Display the list of processes on the target. For each process,
- @value{GDBN} prints the process identifier, the name of the user, the
- command corresponding to the process, and the list of processor cores
- that the process is currently running on. (To understand what these
- properties mean, for this and the following info types, please consult
- the general @sc{gnu}/Linux documentation.)
- @kindex info os procgroups
- @item procgroups
- Display the list of process groups on the target. For each process,
- @value{GDBN} prints the identifier of the process group that it belongs
- to, the command corresponding to the process group leader, the process
- identifier, and the command line of the process. The list is sorted
- first by the process group identifier, then by the process identifier,
- so that processes belonging to the same process group are grouped together
- and the process group leader is listed first.
- @kindex info os semaphores
- @item semaphores
- Display the list of all System V semaphore sets on the target. For each
- semaphore set, @value{GDBN} prints the semaphore set key, the semaphore
- set identifier, the access permissions, the number of semaphores in the
- set, the user and group of the owner and creator of the semaphore set,
- and the times at which the semaphore set was operated upon and changed.
- @kindex info os shm
- @item shm
- Display the list of all System V shared-memory regions on the target.
- For each shared-memory region, @value{GDBN} prints the region key,
- the shared-memory identifier, the access permissions, the size of the
- region, the process that created the region, the process that last
- attached to or detached from the region, the current number of live
- attaches to the region, and the times at which the region was last
- attached to, detach from, and changed.
- @kindex info os sockets
- @item sockets
- Display the list of Internet-domain sockets on the target. For each
- socket, @value{GDBN} prints the address and port of the local and
- remote endpoints, the current state of the connection, the creator of
- the socket, the IP address family of the socket, and the type of the
- connection.
- @kindex info os threads
- @item threads
- Display the list of threads running on the target. For each thread,
- @value{GDBN} prints the identifier of the process that the thread
- belongs to, the command of the process, the thread identifier, and the
- processor core that it is currently running on. The main thread of a
- process is not listed.
- @end table
- @item info os
- If @var{infotype} is omitted, then list the possible values for
- @var{infotype} and the kind of OS information available for each
- @var{infotype}. If the target does not return a list of possible
- types, this command will report an error.
- @end table
- @node Memory Region Attributes
- @section Memory Region Attributes
- @cindex memory region attributes
- @dfn{Memory region attributes} allow you to describe special handling
- required by regions of your target's memory. @value{GDBN} uses
- attributes to determine whether to allow certain types of memory
- accesses; whether to use specific width accesses; and whether to cache
- target memory. By default the description of memory regions is
- fetched from the target (if the current target supports this), but the
- user can override the fetched regions.
- Defined memory regions can be individually enabled and disabled. When a
- memory region is disabled, @value{GDBN} uses the default attributes when
- accessing memory in that region. Similarly, if no memory regions have
- been defined, @value{GDBN} uses the default attributes when accessing
- all memory.
- When a memory region is defined, it is given a number to identify it;
- to enable, disable, or remove a memory region, you specify that number.
- @table @code
- @kindex mem
- @item mem @var{lower} @var{upper} @var{attributes}@dots{}
- Define a memory region bounded by @var{lower} and @var{upper} with
- attributes @var{attributes}@dots{}, and add it to the list of regions
- monitored by @value{GDBN}. Note that @var{upper} == 0 is a special
- case: it is treated as the target's maximum memory address.
- (0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
- @item mem auto
- Discard any user changes to the memory regions and use target-supplied
- regions, if available, or no regions if the target does not support.
- @kindex delete mem
- @item delete mem @var{nums}@dots{}
- Remove memory regions @var{nums}@dots{} from the list of regions
- monitored by @value{GDBN}.
- @kindex disable mem
- @item disable mem @var{nums}@dots{}
- Disable monitoring of memory regions @var{nums}@dots{}.
- A disabled memory region is not forgotten.
- It may be enabled again later.
- @kindex enable mem
- @item enable mem @var{nums}@dots{}
- Enable monitoring of memory regions @var{nums}@dots{}.
- @kindex info mem
- @item info mem
- Print a table of all defined memory regions, with the following columns
- for each region:
- @table @emph
- @item Memory Region Number
- @item Enabled or Disabled.
- Enabled memory regions are marked with @samp{y}.
- Disabled memory regions are marked with @samp{n}.
- @item Lo Address
- The address defining the inclusive lower bound of the memory region.
- @item Hi Address
- The address defining the exclusive upper bound of the memory region.
- @item Attributes
- The list of attributes set for this memory region.
- @end table
- @end table
- @subsection Attributes
- @subsubsection Memory Access Mode
- The access mode attributes set whether @value{GDBN} may make read or
- write accesses to a memory region.
- While these attributes prevent @value{GDBN} from performing invalid
- memory accesses, they do nothing to prevent the target system, I/O DMA,
- etc.@: from accessing memory.
- @table @code
- @item ro
- Memory is read only.
- @item wo
- Memory is write only.
- @item rw
- Memory is read/write. This is the default.
- @end table
- @subsubsection Memory Access Size
- The access size attribute tells @value{GDBN} to use specific sized
- accesses in the memory region. Often memory mapped device registers
- require specific sized accesses. If no access size attribute is
- specified, @value{GDBN} may use accesses of any size.
- @table @code
- @item 8
- Use 8 bit memory accesses.
- @item 16
- Use 16 bit memory accesses.
- @item 32
- Use 32 bit memory accesses.
- @item 64
- Use 64 bit memory accesses.
- @end table
- @c @subsubsection Hardware/Software Breakpoints
- @c The hardware/software breakpoint attributes set whether @value{GDBN}
- @c will use hardware or software breakpoints for the internal breakpoints
- @c used by the step, next, finish, until, etc. commands.
- @c
- @c @table @code
- @c @item hwbreak
- @c Always use hardware breakpoints
- @c @item swbreak (default)
- @c @end table
- @subsubsection Data Cache
- The data cache attributes set whether @value{GDBN} will cache target
- memory. While this generally improves performance by reducing debug
- protocol overhead, it can lead to incorrect results because @value{GDBN}
- does not know about volatile variables or memory mapped device
- registers.
- @table @code
- @item cache
- Enable @value{GDBN} to cache target memory.
- @item nocache
- Disable @value{GDBN} from caching target memory. This is the default.
- @end table
- @subsection Memory Access Checking
- @value{GDBN} can be instructed to refuse accesses to memory that is
- not explicitly described. This can be useful if accessing such
- regions has undesired effects for a specific target, or to provide
- better error checking. The following commands control this behaviour.
- @table @code
- @kindex set mem inaccessible-by-default
- @item set mem inaccessible-by-default [on|off]
- If @code{on} is specified, make @value{GDBN} treat memory not
- explicitly described by the memory ranges as non-existent and refuse accesses
- to such memory. The checks are only performed if there's at least one
- memory range defined. If @code{off} is specified, make @value{GDBN}
- treat the memory not explicitly described by the memory ranges as RAM.
- The default value is @code{on}.
- @kindex show mem inaccessible-by-default
- @item show mem inaccessible-by-default
- Show the current handling of accesses to unknown memory.
- @end table
- @c @subsubsection Memory Write Verification
- @c The memory write verification attributes set whether @value{GDBN}
- @c will re-reads data after each write to verify the write was successful.
- @c
- @c @table @code
- @c @item verify
- @c @item noverify (default)
- @c @end table
- @node Dump/Restore Files
- @section Copy Between Memory and a File
- @cindex dump/restore files
- @cindex append data to a file
- @cindex dump data to a file
- @cindex restore data from a file
- You can use the commands @code{dump}, @code{append}, and
- @code{restore} to copy data between target memory and a file. The
- @code{dump} and @code{append} commands write data to a file, and the
- @code{restore} command reads data from a file back into the inferior's
- memory. Files may be in binary, Motorola S-record, Intel hex,
- Tektronix Hex, or Verilog Hex format; however, @value{GDBN} can only
- append to binary files, and cannot read from Verilog Hex files.
- @table @code
- @kindex dump
- @item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
- @itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr}
- Dump the contents of memory from @var{start_addr} to @var{end_addr},
- or the value of @var{expr}, to @var{filename} in the given format.
- The @var{format} parameter may be any one of:
- @table @code
- @item binary
- Raw binary form.
- @item ihex
- Intel hex format.
- @item srec
- Motorola S-record format.
- @item tekhex
- Tektronix Hex format.
- @item verilog
- Verilog Hex format.
- @end table
- @value{GDBN} uses the same definitions of these formats as the
- @sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If
- @var{format} is omitted, @value{GDBN} dumps the data in raw binary
- form.
- @kindex append
- @item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
- @itemx append @r{[}binary@r{]} value @var{filename} @var{expr}
- Append the contents of memory from @var{start_addr} to @var{end_addr},
- or the value of @var{expr}, to the file @var{filename}, in raw binary form.
- (@value{GDBN} can only append data to files in raw binary form.)
- @kindex restore
- @item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end}
- Restore the contents of file @var{filename} into memory. The
- @code{restore} command can automatically recognize any known @sc{bfd}
- file format, except for raw binary. To restore a raw binary file you
- must specify the optional keyword @code{binary} after the filename.
- If @var{bias} is non-zero, its value will be added to the addresses
- contained in the file. Binary files always start at address zero, so
- they will be restored at address @var{bias}. Other bfd files have
- a built-in location; they will be restored at offset @var{bias}
- from that location.
- If @var{start} and/or @var{end} are non-zero, then only data between
- file offset @var{start} and file offset @var{end} will be restored.
- These offsets are relative to the addresses in the file, before
- the @var{bias} argument is applied.
- @end table
- @node Core File Generation
- @section How to Produce a Core File from Your Program
- @cindex dump core from inferior
- A @dfn{core file} or @dfn{core dump} is a file that records the memory
- image of a running process and its process status (register values
- etc.). Its primary use is post-mortem debugging of a program that
- crashed while it ran outside a debugger. A program that crashes
- automatically produces a core file, unless this feature is disabled by
- the user. @xref{Files}, for information on invoking @value{GDBN} in
- the post-mortem debugging mode.
- Occasionally, you may wish to produce a core file of the program you
- are debugging in order to preserve a snapshot of its state.
- @value{GDBN} has a special command for that.
- @table @code
- @kindex gcore
- @kindex generate-core-file
- @item generate-core-file [@var{file}]
- @itemx gcore [@var{file}]
- Produce a core dump of the inferior process. The optional argument
- @var{file} specifies the file name where to put the core dump. If not
- specified, the file name defaults to @file{core.@var{pid}}, where
- @var{pid} is the inferior process ID.
- Note that this command is implemented only for some systems (as of
- this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390).
- On @sc{gnu}/Linux, this command can take into account the value of the
- file @file{/proc/@var{pid}/coredump_filter} when generating the core
- dump (@pxref{set use-coredump-filter}), and by default honors the
- @code{VM_DONTDUMP} flag for mappings where it is present in the file
- @file{/proc/@var{pid}/smaps} (@pxref{set dump-excluded-mappings}).
- @kindex set use-coredump-filter
- @anchor{set use-coredump-filter}
- @item set use-coredump-filter on
- @itemx set use-coredump-filter off
- Enable or disable the use of the file
- @file{/proc/@var{pid}/coredump_filter} when generating core dump
- files. This file is used by the Linux kernel to decide what types of
- memory mappings will be dumped or ignored when generating a core dump
- file. @var{pid} is the process ID of a currently running process.
- To make use of this feature, you have to write in the
- @file{/proc/@var{pid}/coredump_filter} file a value, in hexadecimal,
- which is a bit mask representing the memory mapping types. If a bit
- is set in the bit mask, then the memory mappings of the corresponding
- types will be dumped; otherwise, they will be ignored. This
- configuration is inherited by child processes. For more information
- about the bits that can be set in the
- @file{/proc/@var{pid}/coredump_filter} file, please refer to the
- manpage of @code{core(5)}.
- By default, this option is @code{on}. If this option is turned
- @code{off}, @value{GDBN} does not read the @file{coredump_filter} file
- and instead uses the same default value as the Linux kernel in order
- to decide which pages will be dumped in the core dump file. This
- value is currently @code{0x33}, which means that bits @code{0}
- (anonymous private mappings), @code{1} (anonymous shared mappings),
- @code{4} (ELF headers) and @code{5} (private huge pages) are active.
- This will cause these memory mappings to be dumped automatically.
- @kindex set dump-excluded-mappings
- @anchor{set dump-excluded-mappings}
- @item set dump-excluded-mappings on
- @itemx set dump-excluded-mappings off
- If @code{on} is specified, @value{GDBN} will dump memory mappings
- marked with the @code{VM_DONTDUMP} flag. This flag is represented in
- the file @file{/proc/@var{pid}/smaps} with the acronym @code{dd}.
- The default value is @code{off}.
- @end table
- @node Character Sets
- @section Character Sets
- @cindex character sets
- @cindex charset
- @cindex translating between character sets
- @cindex host character set
- @cindex target character set
- If the program you are debugging uses a different character set to
- represent characters and strings than the one @value{GDBN} uses itself,
- @value{GDBN} can automatically translate between the character sets for
- you. The character set @value{GDBN} uses we call the @dfn{host
- character set}; the one the inferior program uses we call the
- @dfn{target character set}.
- For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which
- uses the ISO Latin 1 character set, but you are using @value{GDBN}'s
- remote protocol (@pxref{Remote Debugging}) to debug a program
- running on an IBM mainframe, which uses the @sc{ebcdic} character set,
- then the host character set is Latin-1, and the target character set is
- @sc{ebcdic}. If you give @value{GDBN} the command @code{set
- target-charset EBCDIC-US}, then @value{GDBN} translates between
- @sc{ebcdic} and Latin 1 as you print character or string values, or use
- character and string literals in expressions.
- @value{GDBN} has no way to automatically recognize which character set
- the inferior program uses; you must tell it, using the @code{set
- target-charset} command, described below.
- Here are the commands for controlling @value{GDBN}'s character set
- support:
- @table @code
- @item set target-charset @var{charset}
- @kindex set target-charset
- Set the current target character set to @var{charset}. To display the
- list of supported target character sets, type
- @kbd{@w{set target-charset @key{TAB}@key{TAB}}}.
- @item set host-charset @var{charset}
- @kindex set host-charset
- Set the current host character set to @var{charset}.
- By default, @value{GDBN} uses a host character set appropriate to the
- system it is running on; you can override that default using the
- @code{set host-charset} command. On some systems, @value{GDBN} cannot
- automatically determine the appropriate host character set. In this
- case, @value{GDBN} uses @samp{UTF-8}.
- @value{GDBN} can only use certain character sets as its host character
- set. If you type @kbd{@w{set host-charset @key{TAB}@key{TAB}}},
- @value{GDBN} will list the host character sets it supports.
- @item set charset @var{charset}
- @kindex set charset
- Set the current host and target character sets to @var{charset}. As
- above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}},
- @value{GDBN} will list the names of the character sets that can be used
- for both host and target.
- @item show charset
- @kindex show charset
- Show the names of the current host and target character sets.
- @item show host-charset
- @kindex show host-charset
- Show the name of the current host character set.
- @item show target-charset
- @kindex show target-charset
- Show the name of the current target character set.
- @item set target-wide-charset @var{charset}
- @kindex set target-wide-charset
- Set the current target's wide character set to @var{charset}. This is
- the character set used by the target's @code{wchar_t} type. To
- display the list of supported wide character sets, type
- @kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}.
- @item show target-wide-charset
- @kindex show target-wide-charset
- Show the name of the current target's wide character set.
- @end table
- Here is an example of @value{GDBN}'s character set support in action.
- Assume that the following source code has been placed in the file
- @file{charset-test.c}:
- @smallexample
- #include <stdio.h>
- char ascii_hello[]
- = @{72, 101, 108, 108, 111, 44, 32, 119,
- 111, 114, 108, 100, 33, 10, 0@};
- char ibm1047_hello[]
- = @{200, 133, 147, 147, 150, 107, 64, 166,
- 150, 153, 147, 132, 90, 37, 0@};
- main ()
- @{
- printf ("Hello, world!\n");
- @}
- @end smallexample
- In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays
- containing the string @samp{Hello, world!} followed by a newline,
- encoded in the @sc{ascii} and @sc{ibm1047} character sets.
- We compile the program, and invoke the debugger on it:
- @smallexample
- $ gcc -g charset-test.c -o charset-test
- $ gdb -nw charset-test
- GNU gdb 2001-12-19-cvs
- Copyright 2001 Free Software Foundation, Inc.
- @dots{}
- (@value{GDBP})
- @end smallexample
- We can use the @code{show charset} command to see what character sets
- @value{GDBN} is currently using to interpret and display characters and
- strings:
- @smallexample
- (@value{GDBP}) show charset
- The current host and target character set is `ISO-8859-1'.
- (@value{GDBP})
- @end smallexample
- For the sake of printing this manual, let's use @sc{ascii} as our
- initial character set:
- @smallexample
- (@value{GDBP}) set charset ASCII
- (@value{GDBP}) show charset
- The current host and target character set is `ASCII'.
- (@value{GDBP})
- @end smallexample
- Let's assume that @sc{ascii} is indeed the correct character set for our
- host system --- in other words, let's assume that if @value{GDBN} prints
- characters using the @sc{ascii} character set, our terminal will display
- them properly. Since our current target character set is also
- @sc{ascii}, the contents of @code{ascii_hello} print legibly:
- @smallexample
- (@value{GDBP}) print ascii_hello
- $1 = 0x401698 "Hello, world!\n"
- (@value{GDBP}) print ascii_hello[0]
- $2 = 72 'H'
- (@value{GDBP})
- @end smallexample
- @value{GDBN} uses the target character set for character and string
- literals you use in expressions:
- @smallexample
- (@value{GDBP}) print '+'
- $3 = 43 '+'
- (@value{GDBP})
- @end smallexample
- The @sc{ascii} character set uses the number 43 to encode the @samp{+}
- character.
- @value{GDBN} relies on the user to tell it which character set the
- target program uses. If we print @code{ibm1047_hello} while our target
- character set is still @sc{ascii}, we get jibberish:
- @smallexample
- (@value{GDBP}) print ibm1047_hello
- $4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%"
- (@value{GDBP}) print ibm1047_hello[0]
- $5 = 200 '\310'
- (@value{GDBP})
- @end smallexample
- If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB},
- @value{GDBN} tells us the character sets it supports:
- @smallexample
- (@value{GDBP}) set target-charset
- ASCII EBCDIC-US IBM1047 ISO-8859-1
- (@value{GDBP}) set target-charset
- @end smallexample
- We can select @sc{ibm1047} as our target character set, and examine the
- program's strings again. Now the @sc{ascii} string is wrong, but
- @value{GDBN} translates the contents of @code{ibm1047_hello} from the
- target character set, @sc{ibm1047}, to the host character set,
- @sc{ascii}, and they display correctly:
- @smallexample
- (@value{GDBP}) set target-charset IBM1047
- (@value{GDBP}) show charset
- The current host character set is `ASCII'.
- The current target character set is `IBM1047'.
- (@value{GDBP}) print ascii_hello
- $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
- (@value{GDBP}) print ascii_hello[0]
- $7 = 72 '\110'
- (@value{GDBP}) print ibm1047_hello
- $8 = 0x4016a8 "Hello, world!\n"
- (@value{GDBP}) print ibm1047_hello[0]
- $9 = 200 'H'
- (@value{GDBP})
- @end smallexample
- As above, @value{GDBN} uses the target character set for character and
- string literals you use in expressions:
- @smallexample
- (@value{GDBP}) print '+'
- $10 = 78 '+'
- (@value{GDBP})
- @end smallexample
- The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
- character.
- @node Caching Target Data
- @section Caching Data of Targets
- @cindex caching data of targets
- @value{GDBN} caches data exchanged between the debugger and a target.
- Each cache is associated with the address space of the inferior.
- @xref{Inferiors Connections and Programs}, about inferior and address space.
- Such caching generally improves performance in remote debugging
- (@pxref{Remote Debugging}), because it reduces the overhead of the
- remote protocol by bundling memory reads and writes into large chunks.
- Unfortunately, simply caching everything would lead to incorrect results,
- since @value{GDBN} does not necessarily know anything about volatile
- values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode
- (@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command
- is executing.
- Therefore, by default, @value{GDBN} only caches data
- known to be on the stack@footnote{In non-stop mode, it is moderately
- rare for a running thread to modify the stack of a stopped thread
- in a way that would interfere with a backtrace, and caching of
- stack reads provides a significant speed up of remote backtraces.} or
- in the code segment.
- Other regions of memory can be explicitly marked as
- cacheable; @pxref{Memory Region Attributes}.
- @table @code
- @kindex set remotecache
- @item set remotecache on
- @itemx set remotecache off
- This option no longer does anything; it exists for compatibility
- with old scripts.
- @kindex show remotecache
- @item show remotecache
- Show the current state of the obsolete remotecache flag.
- @kindex set stack-cache
- @item set stack-cache on
- @itemx set stack-cache off
- Enable or disable caching of stack accesses. When @code{on}, use
- caching. By default, this option is @code{on}.
- @kindex show stack-cache
- @item show stack-cache
- Show the current state of data caching for memory accesses.
- @kindex set code-cache
- @item set code-cache on
- @itemx set code-cache off
- Enable or disable caching of code segment accesses. When @code{on},
- use caching. By default, this option is @code{on}. This improves
- performance of disassembly in remote debugging.
- @kindex show code-cache
- @item show code-cache
- Show the current state of target memory cache for code segment
- accesses.
- @kindex info dcache
- @item info dcache @r{[}line@r{]}
- Print the information about the performance of data cache of the
- current inferior's address space. The information displayed
- includes the dcache width and depth, and for each cache line, its
- number, address, and how many times it was referenced. This
- command is useful for debugging the data cache operation.
- If a line number is specified, the contents of that line will be
- printed in hex.
- @item set dcache size @var{size}
- @cindex dcache size
- @kindex set dcache size
- Set maximum number of entries in dcache (dcache depth above).
- @item set dcache line-size @var{line-size}
- @cindex dcache line-size
- @kindex set dcache line-size
- Set number of bytes each dcache entry caches (dcache width above).
- Must be a power of 2.
- @item show dcache size
- @kindex show dcache size
- Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}.
- @item show dcache line-size
- @kindex show dcache line-size
- Show default size of dcache lines.
- @item maint flush dcache
- @cindex dcache, flushing
- @kindex maint flush dcache
- Flush the contents (if any) of the dcache. This maintainer command is
- useful when debugging the dcache implementation.
- @end table
- @node Searching Memory
- @section Search Memory
- @cindex searching memory
- Memory can be searched for a particular sequence of bytes with the
- @code{find} command.
- @table @code
- @kindex find
- @item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
- @itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
- Search memory for the sequence of bytes specified by @var{val1}, @var{val2},
- etc. The search begins at address @var{start_addr} and continues for either
- @var{len} bytes or through to @var{end_addr} inclusive.
- @end table
- @var{s} and @var{n} are optional parameters.
- They may be specified in either order, apart or together.
- @table @r
- @item @var{s}, search query size
- The size of each search query value.
- @table @code
- @item b
- bytes
- @item h
- halfwords (two bytes)
- @item w
- words (four bytes)
- @item g
- giant words (eight bytes)
- @end table
- All values are interpreted in the current language.
- This means, for example, that if the current source language is C/C@t{++}
- then searching for the string ``hello'' includes the trailing '\0'.
- The null terminator can be removed from searching by using casts,
- e.g.: @samp{@{char[5]@}"hello"}.
- If the value size is not specified, it is taken from the
- value's type in the current language.
- This is useful when one wants to specify the search
- pattern as a mixture of types.
- Note that this means, for example, that in the case of C-like languages
- a search for an untyped 0x42 will search for @samp{(int) 0x42}
- which is typically four bytes.
- @item @var{n}, maximum number of finds
- The maximum number of matches to print. The default is to print all finds.
- @end table
- You can use strings as search values. Quote them with double-quotes
- (@code{"}).
- The string value is copied into the search pattern byte by byte,
- regardless of the endianness of the target and the size specification.
- The address of each match found is printed as well as a count of the
- number of matches found.
- The address of the last value found is stored in convenience variable
- @samp{$_}.
- A count of the number of matches is stored in @samp{$numfound}.
- For example, if stopped at the @code{printf} in this function:
- @smallexample
- void
- hello ()
- @{
- static char hello[] = "hello-hello";
- static struct @{ char c; short s; int i; @}
- __attribute__ ((packed)) mixed
- = @{ 'c', 0x1234, 0x87654321 @};
- printf ("%s\n", hello);
- @}
- @end smallexample
- @noindent
- you get during debugging:
- @smallexample
- (gdb) find &hello[0], +sizeof(hello), "hello"
- 0x804956d <hello.1620+6>
- 1 pattern found
- (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
- 0x8049567 <hello.1620>
- 0x804956d <hello.1620+6>
- 2 patterns found.
- (gdb) find &hello[0], +sizeof(hello), @{char[5]@}"hello"
- 0x8049567 <hello.1620>
- 0x804956d <hello.1620+6>
- 2 patterns found.
- (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
- 0x8049567 <hello.1620>
- 1 pattern found
- (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
- 0x8049560 <mixed.1625>
- 1 pattern found
- (gdb) print $numfound
- $1 = 1
- (gdb) print $_
- $2 = (void *) 0x8049560
- @end smallexample
- @node Value Sizes
- @section Value Sizes
- Whenever @value{GDBN} prints a value memory will be allocated within
- @value{GDBN} to hold the contents of the value. It is possible in
- some languages with dynamic typing systems, that an invalid program
- may indicate a value that is incorrectly large, this in turn may cause
- @value{GDBN} to try and allocate an overly large amount of memory.
- @table @code
- @kindex set max-value-size
- @item set max-value-size @var{bytes}
- @itemx set max-value-size unlimited
- Set the maximum size of memory that @value{GDBN} will allocate for the
- contents of a value to @var{bytes}, trying to display a value that
- requires more memory than that will result in an error.
- Setting this variable does not effect values that have already been
- allocated within @value{GDBN}, only future allocations.
- There's a minimum size that @code{max-value-size} can be set to in
- order that @value{GDBN} can still operate correctly, this minimum is
- currently 16 bytes.
- The limit applies to the results of some subexpressions as well as to
- complete expressions. For example, an expression denoting a simple
- integer component, such as @code{x.y.z}, may fail if the size of
- @var{x.y} is dynamic and exceeds @var{bytes}. On the other hand,
- @value{GDBN} is sometimes clever; the expression @code{A[i]}, where
- @var{A} is an array variable with non-constant size, will generally
- succeed regardless of the bounds on @var{A}, as long as the component
- size is less than @var{bytes}.
- The default value of @code{max-value-size} is currently 64k.
- @kindex show max-value-size
- @item show max-value-size
- Show the maximum size of memory, in bytes, that @value{GDBN} will
- allocate for the contents of a value.
- @end table
- @node Optimized Code
- @chapter Debugging Optimized Code
- @cindex optimized code, debugging
- @cindex debugging optimized code
- Almost all compilers support optimization. With optimization
- disabled, the compiler generates assembly code that corresponds
- directly to your source code, in a simplistic way. As the compiler
- applies more powerful optimizations, the generated assembly code
- diverges from your original source code. With help from debugging
- information generated by the compiler, @value{GDBN} can map from
- the running program back to constructs from your original source.
- @value{GDBN} is more accurate with optimization disabled. If you
- can recompile without optimization, it is easier to follow the
- progress of your program during debugging. But, there are many cases
- where you may need to debug an optimized version.
- When you debug a program compiled with @samp{-g -O}, remember that the
- optimizer has rearranged your code; the debugger shows you what is
- really there. Do not be too surprised when the execution path does not
- exactly match your source file! An extreme example: if you define a
- variable, but never use it, @value{GDBN} never sees that
- variable---because the compiler optimizes it out of existence.
- Some things do not work as well with @samp{-g -O} as with just
- @samp{-g}, particularly on machines with instruction scheduling. If in
- doubt, recompile with @samp{-g} alone, and if this fixes the problem,
- please report it to us as a bug (including a test case!).
- @xref{Variables}, for more information about debugging optimized code.
- @menu
- * Inline Functions:: How @value{GDBN} presents inlining
- * Tail Call Frames:: @value{GDBN} analysis of jumps to functions
- @end menu
- @node Inline Functions
- @section Inline Functions
- @cindex inline functions, debugging
- @dfn{Inlining} is an optimization that inserts a copy of the function
- body directly at each call site, instead of jumping to a shared
- routine. @value{GDBN} displays inlined functions just like
- non-inlined functions. They appear in backtraces. You can view their
- arguments and local variables, step into them with @code{step}, skip
- them with @code{next}, and escape from them with @code{finish}.
- You can check whether a function was inlined by using the
- @code{info frame} command.
- For @value{GDBN} to support inlined functions, the compiler must
- record information about inlining in the debug information ---
- @value{NGCC} using the @sc{dwarf 2} format does this, and several
- other compilers do also. @value{GDBN} only supports inlined functions
- when using @sc{dwarf 2}. Versions of @value{NGCC} before 4.1
- do not emit two required attributes (@samp{DW_AT_call_file} and
- @samp{DW_AT_call_line}); @value{GDBN} does not display inlined
- function calls with earlier versions of @value{NGCC}. It instead
- displays the arguments and local variables of inlined functions as
- local variables in the caller.
- The body of an inlined function is directly included at its call site;
- unlike a non-inlined function, there are no instructions devoted to
- the call. @value{GDBN} still pretends that the call site and the
- start of the inlined function are different instructions. Stepping to
- the call site shows the call site, and then stepping again shows
- the first line of the inlined function, even though no additional
- instructions are executed.
- This makes source-level debugging much clearer; you can see both the
- context of the call and then the effect of the call. Only stepping by
- a single instruction using @code{stepi} or @code{nexti} does not do
- this; single instruction steps always show the inlined body.
- There are some ways that @value{GDBN} does not pretend that inlined
- function calls are the same as normal calls:
- @itemize @bullet
- @item
- Setting breakpoints at the call site of an inlined function may not
- work, because the call site does not contain any code. @value{GDBN}
- may incorrectly move the breakpoint to the next line of the enclosing
- function, after the call. This limitation will be removed in a future
- version of @value{GDBN}; until then, set a breakpoint on an earlier line
- or inside the inlined function instead.
- @item
- @value{GDBN} cannot locate the return value of inlined calls after
- using the @code{finish} command. This is a limitation of compiler-generated
- debugging information; after @code{finish}, you can step to the next line
- and print a variable where your program stored the return value.
- @end itemize
- @node Tail Call Frames
- @section Tail Call Frames
- @cindex tail call frames, debugging
- Function @code{B} can call function @code{C} in its very last statement. In
- unoptimized compilation the call of @code{C} is immediately followed by return
- instruction at the end of @code{B} code. Optimizing compiler may replace the
- call and return in function @code{B} into one jump to function @code{C}
- instead. Such use of a jump instruction is called @dfn{tail call}.
- During execution of function @code{C}, there will be no indication in the
- function call stack frames that it was tail-called from @code{B}. If function
- @code{A} regularly calls function @code{B} which tail-calls function @code{C},
- then @value{GDBN} will see @code{A} as the caller of @code{C}. However, in
- some cases @value{GDBN} can determine that @code{C} was tail-called from
- @code{B}, and it will then create fictitious call frame for that, with the
- return address set up as if @code{B} called @code{C} normally.
- This functionality is currently supported only by DWARF 2 debugging format and
- the compiler has to produce @samp{DW_TAG_call_site} tags. With
- @value{NGCC}, you need to specify @option{-O -g} during compilation, to get
- this information.
- @kbd{info frame} command (@pxref{Frame Info}) will indicate the tail call frame
- kind by text @code{tail call frame} such as in this sample @value{GDBN} output:
- @smallexample
- (gdb) x/i $pc - 2
- 0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)>
- (gdb) info frame
- Stack level 1, frame at 0x7fffffffda30:
- rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
- tail call frame, caller of frame at 0x7fffffffda30
- source language c++.
- Arglist at unknown address.
- Locals at unknown address, Previous frame's sp is 0x7fffffffda30
- @end smallexample
- The detection of all the possible code path executions can find them ambiguous.
- There is no execution history stored (possible @ref{Reverse Execution} is never
- used for this purpose) and the last known caller could have reached the known
- callee by multiple different jump sequences. In such case @value{GDBN} still
- tries to show at least all the unambiguous top tail callers and all the
- unambiguous bottom tail calees, if any.
- @table @code
- @anchor{set debug entry-values}
- @item set debug entry-values
- @kindex set debug entry-values
- When set to on, enables printing of analysis messages for both frame argument
- values at function entry and tail calls. It will show all the possible valid
- tail calls code paths it has considered. It will also print the intersection
- of them with the final unambiguous (possibly partial or even empty) code path
- result.
- @item show debug entry-values
- @kindex show debug entry-values
- Show the current state of analysis messages printing for both frame argument
- values at function entry and tail calls.
- @end table
- The analysis messages for tail calls can for example show why the virtual tail
- call frame for function @code{c} has not been recognized (due to the indirect
- reference by variable @code{x}):
- @smallexample
- static void __attribute__((noinline, noclone)) c (void);
- void (*x) (void) = c;
- static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
- static void __attribute__((noinline, noclone)) c (void) @{ a (); @}
- int main (void) @{ x (); return 0; @}
- Breakpoint 1, DW_OP_entry_value resolving cannot find
- DW_TAG_call_site 0x40039a in main
- a () at t.c:3
- 3 static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
- (gdb) bt
- #0 a () at t.c:3
- #1 0x000000000040039a in main () at t.c:5
- @end smallexample
- Another possibility is an ambiguous virtual tail call frames resolution:
- @smallexample
- int i;
- static void __attribute__((noinline, noclone)) f (void) @{ i++; @}
- static void __attribute__((noinline, noclone)) e (void) @{ f (); @}
- static void __attribute__((noinline, noclone)) d (void) @{ f (); @}
- static void __attribute__((noinline, noclone)) c (void) @{ d (); @}
- static void __attribute__((noinline, noclone)) b (void)
- @{ if (i) c (); else e (); @}
- static void __attribute__((noinline, noclone)) a (void) @{ b (); @}
- int main (void) @{ a (); return 0; @}
- tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d)
- tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e)
- tailcall: reduced: 0x4004d2(a) |
- (gdb) bt
- #0 f () at t.c:2
- #1 0x00000000004004d2 in a () at t.c:8
- #2 0x0000000000400395 in main () at t.c:9
- @end smallexample
- @set CALLSEQ1A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}c@value{ARROW}d@value{ARROW}f}
- @set CALLSEQ2A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}e@value{ARROW}f}
- @c Convert CALLSEQ#A to CALLSEQ#B depending on HAVE_MAKEINFO_CLICK.
- @ifset HAVE_MAKEINFO_CLICK
- @set ARROW @click{}
- @set CALLSEQ1B @clicksequence{@value{CALLSEQ1A}}
- @set CALLSEQ2B @clicksequence{@value{CALLSEQ2A}}
- @end ifset
- @ifclear HAVE_MAKEINFO_CLICK
- @set ARROW ->
- @set CALLSEQ1B @value{CALLSEQ1A}
- @set CALLSEQ2B @value{CALLSEQ2A}
- @end ifclear
- Frames #0 and #2 are real, #1 is a virtual tail call frame.
- The code can have possible execution paths @value{CALLSEQ1B} or
- @value{CALLSEQ2B}, @value{GDBN} cannot find which one from the inferior state.
- @code{initial:} state shows some random possible calling sequence @value{GDBN}
- has found. It then finds another possible calling sequence - that one is
- prefixed by @code{compare:}. The non-ambiguous intersection of these two is
- printed as the @code{reduced:} calling sequence. That one could have many
- further @code{compare:} and @code{reduced:} statements as long as there remain
- any non-ambiguous sequence entries.
- For the frame of function @code{b} in both cases there are different possible
- @code{$pc} values (@code{0x4004cc} or @code{0x4004ce}), therefore this frame is
- also ambiguous. The only non-ambiguous frame is the one for function @code{a},
- therefore this one is displayed to the user while the ambiguous frames are
- omitted.
- There can be also reasons why printing of frame argument values at function
- entry may fail:
- @smallexample
- int v;
- static void __attribute__((noinline, noclone)) c (int i) @{ v++; @}
- static void __attribute__((noinline, noclone)) a (int i);
- static void __attribute__((noinline, noclone)) b (int i) @{ a (i); @}
- static void __attribute__((noinline, noclone)) a (int i)
- @{ if (i) b (i - 1); else c (0); @}
- int main (void) @{ a (5); return 0; @}
- (gdb) bt
- #0 c (i=i@@entry=0) at t.c:2
- #1 0x0000000000400428 in a (DW_OP_entry_value resolving has found
- function "a" at 0x400420 can call itself via tail calls
- i=<optimized out>) at t.c:6
- #2 0x000000000040036e in main () at t.c:7
- @end smallexample
- @value{GDBN} cannot find out from the inferior state if and how many times did
- function @code{a} call itself (via function @code{b}) as these calls would be
- tail calls. Such tail calls would modify the @code{i} variable, therefore
- @value{GDBN} cannot be sure the value it knows would be right - @value{GDBN}
- prints @code{<optimized out>} instead.
- @node Macros
- @chapter C Preprocessor Macros
- Some languages, such as C and C@t{++}, provide a way to define and invoke
- ``preprocessor macros'' which expand into strings of tokens.
- @value{GDBN} can evaluate expressions containing macro invocations, show
- the result of macro expansion, and show a macro's definition, including
- where it was defined.
- You may need to compile your program specially to provide @value{GDBN}
- with information about preprocessor macros. Most compilers do not
- include macros in their debugging information, even when you compile
- with the @option{-g} flag. @xref{Compilation}.
- A program may define a macro at one point, remove that definition later,
- and then provide a different definition after that. Thus, at different
- points in the program, a macro may have different definitions, or have
- no definition at all. If there is a current stack frame, @value{GDBN}
- uses the macros in scope at that frame's source code line. Otherwise,
- @value{GDBN} uses the macros in scope at the current listing location;
- see @ref{List}.
- Whenever @value{GDBN} evaluates an expression, it always expands any
- macro invocations present in the expression. @value{GDBN} also provides
- the following commands for working with macros explicitly.
- @table @code
- @kindex macro expand
- @cindex macro expansion, showing the results of preprocessor
- @cindex preprocessor macro expansion, showing the results of
- @cindex expanding preprocessor macros
- @item macro expand @var{expression}
- @itemx macro exp @var{expression}
- Show the results of expanding all preprocessor macro invocations in
- @var{expression}. Since @value{GDBN} simply expands macros, but does
- not parse the result, @var{expression} need not be a valid expression;
- it can be any string of tokens.
- @kindex macro exp1
- @item macro expand-once @var{expression}
- @itemx macro exp1 @var{expression}
- @cindex expand macro once
- @i{(This command is not yet implemented.)} Show the results of
- expanding those preprocessor macro invocations that appear explicitly in
- @var{expression}. Macro invocations appearing in that expansion are
- left unchanged. This command allows you to see the effect of a
- particular macro more clearly, without being confused by further
- expansions. Since @value{GDBN} simply expands macros, but does not
- parse the result, @var{expression} need not be a valid expression; it
- can be any string of tokens.
- @kindex info macro
- @cindex macro definition, showing
- @cindex definition of a macro, showing
- @cindex macros, from debug info
- @item info macro [-a|-all] [--] @var{macro}
- Show the current definition or all definitions of the named @var{macro},
- and describe the source location or compiler command-line where that
- definition was established. The optional double dash is to signify the end of
- argument processing and the beginning of @var{macro} for non C-like macros where
- the macro may begin with a hyphen.
- @kindex info macros
- @item info macros @var{location}
- Show all macro definitions that are in effect at the location specified
- by @var{location}, and describe the source location or compiler
- command-line where those definitions were established.
- @kindex macro define
- @cindex user-defined macros
- @cindex defining macros interactively
- @cindex macros, user-defined
- @item macro define @var{macro} @var{replacement-list}
- @itemx macro define @var{macro}(@var{arglist}) @var{replacement-list}
- Introduce a definition for a preprocessor macro named @var{macro},
- invocations of which are replaced by the tokens given in
- @var{replacement-list}. The first form of this command defines an
- ``object-like'' macro, which takes no arguments; the second form
- defines a ``function-like'' macro, which takes the arguments given in
- @var{arglist}.
- A definition introduced by this command is in scope in every
- expression evaluated in @value{GDBN}, until it is removed with the
- @code{macro undef} command, described below. The definition overrides
- all definitions for @var{macro} present in the program being debugged,
- as well as any previous user-supplied definition.
- @kindex macro undef
- @item macro undef @var{macro}
- Remove any user-supplied definition for the macro named @var{macro}.
- This command only affects definitions provided with the @code{macro
- define} command, described above; it cannot remove definitions present
- in the program being debugged.
- @kindex macro list
- @item macro list
- List all the macros defined using the @code{macro define} command.
- @end table
- @cindex macros, example of debugging with
- Here is a transcript showing the above commands in action. First, we
- show our source files:
- @smallexample
- $ cat sample.c
- #include <stdio.h>
- #include "sample.h"
- #define M 42
- #define ADD(x) (M + x)
- main ()
- @{
- #define N 28
- printf ("Hello, world!\n");
- #undef N
- printf ("We're so creative.\n");
- #define N 1729
- printf ("Goodbye, world!\n");
- @}
- $ cat sample.h
- #define Q <
- $
- @end smallexample
- Now, we compile the program using the @sc{gnu} C compiler,
- @value{NGCC}. We pass the @option{-gdwarf-2}@footnote{This is the
- minimum. Recent versions of @value{NGCC} support @option{-gdwarf-3}
- and @option{-gdwarf-4}; we recommend always choosing the most recent
- version of DWARF.} @emph{and} @option{-g3} flags to ensure the compiler
- includes information about preprocessor macros in the debugging
- information.
- @smallexample
- $ gcc -gdwarf-2 -g3 sample.c -o sample
- $
- @end smallexample
- Now, we start @value{GDBN} on our sample program:
- @smallexample
- $ gdb -nw sample
- GNU gdb 2002-05-06-cvs
- Copyright 2002 Free Software Foundation, Inc.
- GDB is free software, @dots{}
- (@value{GDBP})
- @end smallexample
- We can expand macros and examine their definitions, even when the
- program is not running. @value{GDBN} uses the current listing position
- to decide which macro definitions are in scope:
- @smallexample
- (@value{GDBP}) list main
- 3
- 4 #define M 42
- 5 #define ADD(x) (M + x)
- 6
- 7 main ()
- 8 @{
- 9 #define N 28
- 10 printf ("Hello, world!\n");
- 11 #undef N
- 12 printf ("We're so creative.\n");
- (@value{GDBP}) info macro ADD
- Defined at /home/jimb/gdb/macros/play/sample.c:5
- #define ADD(x) (M + x)
- (@value{GDBP}) info macro Q
- Defined at /home/jimb/gdb/macros/play/sample.h:1
- included at /home/jimb/gdb/macros/play/sample.c:2
- #define Q <
- (@value{GDBP}) macro expand ADD(1)
- expands to: (42 + 1)
- (@value{GDBP}) macro expand-once ADD(1)
- expands to: once (M + 1)
- (@value{GDBP})
- @end smallexample
- In the example above, note that @code{macro expand-once} expands only
- the macro invocation explicit in the original text --- the invocation of
- @code{ADD} --- but does not expand the invocation of the macro @code{M},
- which was introduced by @code{ADD}.
- Once the program is running, @value{GDBN} uses the macro definitions in
- force at the source line of the current stack frame:
- @smallexample
- (@value{GDBP}) break main
- Breakpoint 1 at 0x8048370: file sample.c, line 10.
- (@value{GDBP}) run
- Starting program: /home/jimb/gdb/macros/play/sample
- Breakpoint 1, main () at sample.c:10
- 10 printf ("Hello, world!\n");
- (@value{GDBP})
- @end smallexample
- At line 10, the definition of the macro @code{N} at line 9 is in force:
- @smallexample
- (@value{GDBP}) info macro N
- Defined at /home/jimb/gdb/macros/play/sample.c:9
- #define N 28
- (@value{GDBP}) macro expand N Q M
- expands to: 28 < 42
- (@value{GDBP}) print N Q M
- $1 = 1
- (@value{GDBP})
- @end smallexample
- As we step over directives that remove @code{N}'s definition, and then
- give it a new definition, @value{GDBN} finds the definition (or lack
- thereof) in force at each point:
- @smallexample
- (@value{GDBP}) next
- Hello, world!
- 12 printf ("We're so creative.\n");
- (@value{GDBP}) info macro N
- The symbol `N' has no definition as a C/C++ preprocessor macro
- at /home/jimb/gdb/macros/play/sample.c:12
- (@value{GDBP}) next
- We're so creative.
- 14 printf ("Goodbye, world!\n");
- (@value{GDBP}) info macro N
- Defined at /home/jimb/gdb/macros/play/sample.c:13
- #define N 1729
- (@value{GDBP}) macro expand N Q M
- expands to: 1729 < 42
- (@value{GDBP}) print N Q M
- $2 = 0
- (@value{GDBP})
- @end smallexample
- In addition to source files, macros can be defined on the compilation command
- line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in
- such a way, @value{GDBN} displays the location of their definition as line zero
- of the source file submitted to the compiler.
- @smallexample
- (@value{GDBP}) info macro __STDC__
- Defined at /home/jimb/gdb/macros/play/sample.c:0
- -D__STDC__=1
- (@value{GDBP})
- @end smallexample
- @node Tracepoints
- @chapter Tracepoints
- @c This chapter is based on the documentation written by Michael
- @c Snyder, David Taylor, Jim Blandy, and Elena Zannoni.
- @cindex tracepoints
- In some applications, it is not feasible for the debugger to interrupt
- the program's execution long enough for the developer to learn
- anything helpful about its behavior. If the program's correctness
- depends on its real-time behavior, delays introduced by a debugger
- might cause the program to change its behavior drastically, or perhaps
- fail, even when the code itself is correct. It is useful to be able
- to observe the program's behavior without interrupting it.
- Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can
- specify locations in the program, called @dfn{tracepoints}, and
- arbitrary expressions to evaluate when those tracepoints are reached.
- Later, using the @code{tfind} command, you can examine the values
- those expressions had when the program hit the tracepoints. The
- expressions may also denote objects in memory---structures or arrays,
- for example---whose values @value{GDBN} should record; while visiting
- a particular tracepoint, you may inspect those objects as if they were
- in memory at that moment. However, because @value{GDBN} records these
- values without interacting with you, it can do so quickly and
- unobtrusively, hopefully not disturbing the program's behavior.
- The tracepoint facility is currently available only for remote
- targets. @xref{Targets}. In addition, your remote target must know
- how to collect trace data. This functionality is implemented in the
- remote stub; however, none of the stubs distributed with @value{GDBN}
- support tracepoints as of this writing. The format of the remote
- packets used to implement tracepoints are described in @ref{Tracepoint
- Packets}.
- It is also possible to get trace data from a file, in a manner reminiscent
- of corefiles; you specify the filename, and use @code{tfind} to search
- through the file. @xref{Trace Files}, for more details.
- This chapter describes the tracepoint commands and features.
- @menu
- * Set Tracepoints::
- * Analyze Collected Data::
- * Tracepoint Variables::
- * Trace Files::
- @end menu
- @node Set Tracepoints
- @section Commands to Set Tracepoints
- Before running such a @dfn{trace experiment}, an arbitrary number of
- tracepoints can be set. A tracepoint is actually a special type of
- breakpoint (@pxref{Set Breaks}), so you can manipulate it using
- standard breakpoint commands. For instance, as with breakpoints,
- tracepoint numbers are successive integers starting from one, and many
- of the commands associated with tracepoints take the tracepoint number
- as their argument, to identify which tracepoint to work on.
- For each tracepoint, you can specify, in advance, some arbitrary set
- of data that you want the target to collect in the trace buffer when
- it hits that tracepoint. The collected data can include registers,
- local variables, or global data. Later, you can use @value{GDBN}
- commands to examine the values these data had at the time the
- tracepoint was hit.
- Tracepoints do not support every breakpoint feature. Ignore counts on
- tracepoints have no effect, and tracepoints cannot run @value{GDBN}
- commands when they are hit. Tracepoints may not be thread-specific
- either.
- @cindex fast tracepoints
- Some targets may support @dfn{fast tracepoints}, which are inserted in
- a different way (such as with a jump instead of a trap), that is
- faster but possibly restricted in where they may be installed.
- @cindex static tracepoints
- @cindex markers, static tracepoints
- @cindex probing markers, static tracepoints
- Regular and fast tracepoints are dynamic tracing facilities, meaning
- that they can be used to insert tracepoints at (almost) any location
- in the target. Some targets may also support controlling @dfn{static
- tracepoints} from @value{GDBN}. With static tracing, a set of
- instrumentation points, also known as @dfn{markers}, are embedded in
- the target program, and can be activated or deactivated by name or
- address. These are usually placed at locations which facilitate
- investigating what the target is actually doing. @value{GDBN}'s
- support for static tracing includes being able to list instrumentation
- points, and attach them with @value{GDBN} defined high level
- tracepoints that expose the whole range of convenience of
- @value{GDBN}'s tracepoints support. Namely, support for collecting
- registers values and values of global or local (to the instrumentation
- point) variables; tracepoint conditions and trace state variables.
- The act of installing a @value{GDBN} static tracepoint on an
- instrumentation point, or marker, is referred to as @dfn{probing} a
- static tracepoint marker.
- @code{gdbserver} supports tracepoints on some target systems.
- @xref{Server,,Tracepoints support in @code{gdbserver}}.
- This section describes commands to set tracepoints and associated
- conditions and actions.
- @menu
- * Create and Delete Tracepoints::
- * Enable and Disable Tracepoints::
- * Tracepoint Passcounts::
- * Tracepoint Conditions::
- * Trace State Variables::
- * Tracepoint Actions::
- * Listing Tracepoints::
- * Listing Static Tracepoint Markers::
- * Starting and Stopping Trace Experiments::
- * Tracepoint Restrictions::
- @end menu
- @node Create and Delete Tracepoints
- @subsection Create and Delete Tracepoints
- @table @code
- @cindex set tracepoint
- @kindex trace
- @item trace @var{location}
- The @code{trace} command is very similar to the @code{break} command.
- Its argument @var{location} can be any valid location.
- @xref{Specify Location}. The @code{trace} command defines a tracepoint,
- which is a point in the target program where the debugger will briefly stop,
- collect some data, and then allow the program to continue. Setting a tracepoint
- or changing its actions takes effect immediately if the remote stub
- supports the @samp{InstallInTrace} feature (@pxref{install tracepoint
- in tracing}).
- If remote stub doesn't support the @samp{InstallInTrace} feature, all
- these changes don't take effect until the next @code{tstart}
- command, and once a trace experiment is running, further changes will
- not have any effect until the next trace experiment starts. In addition,
- @value{GDBN} supports @dfn{pending tracepoints}---tracepoints whose
- address is not yet resolved. (This is similar to pending breakpoints.)
- Pending tracepoints are not downloaded to the target and not installed
- until they are resolved. The resolution of pending tracepoints requires
- @value{GDBN} support---when debugging with the remote target, and
- @value{GDBN} disconnects from the remote stub (@pxref{disconnected
- tracing}), pending tracepoints can not be resolved (and downloaded to
- the remote stub) while @value{GDBN} is disconnected.
- Here are some examples of using the @code{trace} command:
- @smallexample
- (@value{GDBP}) @b{trace foo.c:121} // a source file and line number
- (@value{GDBP}) @b{trace +2} // 2 lines forward
- (@value{GDBP}) @b{trace my_function} // first source line of function
- (@value{GDBP}) @b{trace *my_function} // EXACT start address of function
- (@value{GDBP}) @b{trace *0x2117c4} // an address
- @end smallexample
- @noindent
- You can abbreviate @code{trace} as @code{tr}.
- @item trace @var{location} if @var{cond}
- Set a tracepoint with condition @var{cond}; evaluate the expression
- @var{cond} each time the tracepoint is reached, and collect data only
- if the value is nonzero---that is, if @var{cond} evaluates as true.
- @xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more
- information on tracepoint conditions.
- @item ftrace @var{location} [ if @var{cond} ]
- @cindex set fast tracepoint
- @cindex fast tracepoints, setting
- @kindex ftrace
- The @code{ftrace} command sets a fast tracepoint. For targets that
- support them, fast tracepoints will use a more efficient but possibly
- less general technique to trigger data collection, such as a jump
- instruction instead of a trap, or some sort of hardware support. It
- may not be possible to create a fast tracepoint at the desired
- location, in which case the command will exit with an explanatory
- message.
- @value{GDBN} handles arguments to @code{ftrace} exactly as for
- @code{trace}.
- On 32-bit x86-architecture systems, fast tracepoints normally need to
- be placed at an instruction that is 5 bytes or longer, but can be
- placed at 4-byte instructions if the low 64K of memory of the target
- program is available to install trampolines. Some Unix-type systems,
- such as @sc{gnu}/Linux, exclude low addresses from the program's
- address space; but for instance with the Linux kernel it is possible
- to let @value{GDBN} use this area by doing a @command{sysctl} command
- to set the @code{mmap_min_addr} kernel parameter, as in
- @example
- sudo sysctl -w vm.mmap_min_addr=32768
- @end example
- @noindent
- which sets the low address to 32K, which leaves plenty of room for
- trampolines. The minimum address should be set to a page boundary.
- @item strace @var{location} [ if @var{cond} ]
- @cindex set static tracepoint
- @cindex static tracepoints, setting
- @cindex probe static tracepoint marker
- @kindex strace
- The @code{strace} command sets a static tracepoint. For targets that
- support it, setting a static tracepoint probes a static
- instrumentation point, or marker, found at @var{location}. It may not
- be possible to set a static tracepoint at the desired location, in
- which case the command will exit with an explanatory message.
- @value{GDBN} handles arguments to @code{strace} exactly as for
- @code{trace}, with the addition that the user can also specify
- @code{-m @var{marker}} as @var{location}. This probes the marker
- identified by the @var{marker} string identifier. This identifier
- depends on the static tracepoint backend library your program is
- using. You can find all the marker identifiers in the @samp{ID} field
- of the @code{info static-tracepoint-markers} command output.
- @xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint
- Markers}. For example, in the following small program using the UST
- tracing engine:
- @smallexample
- main ()
- @{
- trace_mark(ust, bar33, "str %s", "FOOBAZ");
- @}
- @end smallexample
- @noindent
- the marker id is composed of joining the first two arguments to the
- @code{trace_mark} call with a slash, which translates to:
- @smallexample
- (@value{GDBP}) info static-tracepoint-markers
- Cnt Enb ID Address What
- 1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22
- Data: "str %s"
- [etc...]
- @end smallexample
- @noindent
- so you may probe the marker above with:
- @smallexample
- (@value{GDBP}) strace -m ust/bar33
- @end smallexample
- Static tracepoints accept an extra collect action --- @code{collect
- $_sdata}. This collects arbitrary user data passed in the probe point
- call to the tracing library. In the UST example above, you'll see
- that the third argument to @code{trace_mark} is a printf-like format
- string. The user data is then the result of running that formatting
- string against the following arguments. Note that @code{info
- static-tracepoint-markers} command output lists that format string in
- the @samp{Data:} field.
- You can inspect this data when analyzing the trace buffer, by printing
- the $_sdata variable like any other variable available to
- @value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}.
- @vindex $tpnum
- @cindex last tracepoint number
- @cindex recent tracepoint number
- @cindex tracepoint number
- The convenience variable @code{$tpnum} records the tracepoint number
- of the most recently set tracepoint.
- @kindex delete tracepoint
- @cindex tracepoint deletion
- @item delete tracepoint @r{[}@var{num}@r{]}
- Permanently delete one or more tracepoints. With no argument, the
- default is to delete all tracepoints. Note that the regular
- @code{delete} command can remove tracepoints also.
- Examples:
- @smallexample
- (@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints
- (@value{GDBP}) @b{delete trace} // remove all tracepoints
- @end smallexample
- @noindent
- You can abbreviate this command as @code{del tr}.
- @end table
- @node Enable and Disable Tracepoints
- @subsection Enable and Disable Tracepoints
- These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}.
- @table @code
- @kindex disable tracepoint
- @item disable tracepoint @r{[}@var{num}@r{]}
- Disable tracepoint @var{num}, or all tracepoints if no argument
- @var{num} is given. A disabled tracepoint will have no effect during
- a trace experiment, but it is not forgotten. You can re-enable
- a disabled tracepoint using the @code{enable tracepoint} command.
- If the command is issued during a trace experiment and the debug target
- has support for disabling tracepoints during a trace experiment, then the
- change will be effective immediately. Otherwise, it will be applied to the
- next trace experiment.
- @kindex enable tracepoint
- @item enable tracepoint @r{[}@var{num}@r{]}
- Enable tracepoint @var{num}, or all tracepoints. If this command is
- issued during a trace experiment and the debug target supports enabling
- tracepoints during a trace experiment, then the enabled tracepoints will
- become effective immediately. Otherwise, they will become effective the
- next time a trace experiment is run.
- @end table
- @node Tracepoint Passcounts
- @subsection Tracepoint Passcounts
- @table @code
- @kindex passcount
- @cindex tracepoint pass count
- @item passcount @r{[}@var{n} @r{[}@var{num}@r{]]}
- Set the @dfn{passcount} of a tracepoint. The passcount is a way to
- automatically stop a trace experiment. If a tracepoint's passcount is
- @var{n}, then the trace experiment will be automatically stopped on
- the @var{n}'th time that tracepoint is hit. If the tracepoint number
- @var{num} is not specified, the @code{passcount} command sets the
- passcount of the most recently defined tracepoint. If no passcount is
- given, the trace experiment will run until stopped explicitly by the
- user.
- Examples:
- @smallexample
- (@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
- @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
- (@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
- @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.}
- (@value{GDBP}) @b{trace foo}
- (@value{GDBP}) @b{pass 3}
- (@value{GDBP}) @b{trace bar}
- (@value{GDBP}) @b{pass 2}
- (@value{GDBP}) @b{trace baz}
- (@value{GDBP}) @b{pass 1} // Stop tracing when foo has been
- @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has}
- @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times}
- @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.}
- @end smallexample
- @end table
- @node Tracepoint Conditions
- @subsection Tracepoint Conditions
- @cindex conditional tracepoints
- @cindex tracepoint conditions
- The simplest sort of tracepoint collects data every time your program
- reaches a specified place. You can also specify a @dfn{condition} for
- a tracepoint. A condition is just a Boolean expression in your
- programming language (@pxref{Expressions, ,Expressions}). A
- tracepoint with a condition evaluates the expression each time your
- program reaches it, and data collection happens only if the condition
- is true.
- Tracepoint conditions can be specified when a tracepoint is set, by
- using @samp{if} in the arguments to the @code{trace} command.
- @xref{Create and Delete Tracepoints, ,Setting Tracepoints}. They can
- also be set or changed at any time with the @code{condition} command,
- just as with breakpoints.
- Unlike breakpoint conditions, @value{GDBN} does not actually evaluate
- the conditional expression itself. Instead, @value{GDBN} encodes the
- expression into an agent expression (@pxref{Agent Expressions})
- suitable for execution on the target, independently of @value{GDBN}.
- Global variables become raw memory locations, locals become stack
- accesses, and so forth.
- For instance, suppose you have a function that is usually called
- frequently, but should not be called after an error has occurred. You
- could use the following tracepoint command to collect data about calls
- of that function that happen while the error code is propagating
- through the program; an unconditional tracepoint could end up
- collecting thousands of useless trace frames that you would have to
- search through.
- @smallexample
- (@value{GDBP}) @kbd{trace normal_operation if errcode > 0}
- @end smallexample
- @node Trace State Variables
- @subsection Trace State Variables
- @cindex trace state variables
- A @dfn{trace state variable} is a special type of variable that is
- created and managed by target-side code. The syntax is the same as
- that for GDB's convenience variables (a string prefixed with ``$''),
- but they are stored on the target. They must be created explicitly,
- using a @code{tvariable} command. They are always 64-bit signed
- integers.
- Trace state variables are remembered by @value{GDBN}, and downloaded
- to the target along with tracepoint information when the trace
- experiment starts. There are no intrinsic limits on the number of
- trace state variables, beyond memory limitations of the target.
- @cindex convenience variables, and trace state variables
- Although trace state variables are managed by the target, you can use
- them in print commands and expressions as if they were convenience
- variables; @value{GDBN} will get the current value from the target
- while the trace experiment is running. Trace state variables share
- the same namespace as other ``$'' variables, which means that you
- cannot have trace state variables with names like @code{$23} or
- @code{$pc}, nor can you have a trace state variable and a convenience
- variable with the same name.
- @table @code
- @item tvariable $@var{name} [ = @var{expression} ]
- @kindex tvariable
- The @code{tvariable} command creates a new trace state variable named
- @code{$@var{name}}, and optionally gives it an initial value of
- @var{expression}. The @var{expression} is evaluated when this command is
- entered; the result will be converted to an integer if possible,
- otherwise @value{GDBN} will report an error. A subsequent
- @code{tvariable} command specifying the same name does not create a
- variable, but instead assigns the supplied initial value to the
- existing variable of that name, overwriting any previous initial
- value. The default initial value is 0.
- @item info tvariables
- @kindex info tvariables
- List all the trace state variables along with their initial values.
- Their current values may also be displayed, if the trace experiment is
- currently running.
- @item delete tvariable @r{[} $@var{name} @dots{} @r{]}
- @kindex delete tvariable
- Delete the given trace state variables, or all of them if no arguments
- are specified.
- @end table
- @node Tracepoint Actions
- @subsection Tracepoint Action Lists
- @table @code
- @kindex actions
- @cindex tracepoint actions
- @item actions @r{[}@var{num}@r{]}
- This command will prompt for a list of actions to be taken when the
- tracepoint is hit. If the tracepoint number @var{num} is not
- specified, this command sets the actions for the one that was most
- recently defined (so that you can define a tracepoint and then say
- @code{actions} without bothering about its number). You specify the
- actions themselves on the following lines, one action at a time, and
- terminate the actions list with a line containing just @code{end}. So
- far, the only defined actions are @code{collect}, @code{teval}, and
- @code{while-stepping}.
- @code{actions} is actually equivalent to @code{commands} (@pxref{Break
- Commands, ,Breakpoint Command Lists}), except that only the defined
- actions are allowed; any other @value{GDBN} command is rejected.
- @cindex remove actions from a tracepoint
- To remove all actions from a tracepoint, type @samp{actions @var{num}}
- and follow it immediately with @samp{end}.
- @smallexample
- (@value{GDBP}) @b{collect @var{data}} // collect some data
- (@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
- (@value{GDBP}) @b{end} // signals the end of actions.
- @end smallexample
- In the following example, the action list begins with @code{collect}
- commands indicating the things to be collected when the tracepoint is
- hit. Then, in order to single-step and collect additional data
- following the tracepoint, a @code{while-stepping} command is used,
- followed by the list of things to be collected after each step in a
- sequence of single steps. The @code{while-stepping} command is
- terminated by its own separate @code{end} command. Lastly, the action
- list is terminated by an @code{end} command.
- @smallexample
- (@value{GDBP}) @b{trace foo}
- (@value{GDBP}) @b{actions}
- Enter actions for tracepoint 1, one per line:
- > collect bar,baz
- > collect $regs
- > while-stepping 12
- > collect $pc, arr[i]
- > end
- end
- @end smallexample
- @kindex collect @r{(tracepoints)}
- @item collect@r{[}/@var{mods}@r{]} @var{expr1}, @var{expr2}, @dots{}
- Collect values of the given expressions when the tracepoint is hit.
- This command accepts a comma-separated list of any valid expressions.
- In addition to global, static, or local variables, the following
- special arguments are supported:
- @table @code
- @item $regs
- Collect all registers.
- @item $args
- Collect all function arguments.
- @item $locals
- Collect all local variables.
- @item $_ret
- Collect the return address. This is helpful if you want to see more
- of a backtrace.
- @emph{Note:} The return address location can not always be reliably
- determined up front, and the wrong address / registers may end up
- collected instead. On some architectures the reliability is higher
- for tracepoints at function entry, while on others it's the opposite.
- When this happens, backtracing will stop because the return address is
- found unavailable (unless another collect rule happened to match it).
- @item $_probe_argc
- Collects the number of arguments from the static probe at which the
- tracepoint is located.
- @xref{Static Probe Points}.
- @item $_probe_arg@var{n}
- @var{n} is an integer between 0 and 11. Collects the @var{n}th argument
- from the static probe at which the tracepoint is located.
- @xref{Static Probe Points}.
- @item $_sdata
- @vindex $_sdata@r{, collect}
- Collect static tracepoint marker specific data. Only available for
- static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action
- Lists}. On the UST static tracepoints library backend, an
- instrumentation point resembles a @code{printf} function call. The
- tracing library is able to collect user specified data formatted to a
- character string using the format provided by the programmer that
- instrumented the program. Other backends have similar mechanisms.
- Here's an example of a UST marker call:
- @smallexample
- const char master_name[] = "$your_name";
- trace_mark(channel1, marker1, "hello %s", master_name)
- @end smallexample
- In this case, collecting @code{$_sdata} collects the string
- @samp{hello $yourname}. When analyzing the trace buffer, you can
- inspect @samp{$_sdata} like any other variable available to
- @value{GDBN}.
- @end table
- You can give several consecutive @code{collect} commands, each one
- with a single argument, or one @code{collect} command with several
- arguments separated by commas; the effect is the same.
- The optional @var{mods} changes the usual handling of the arguments.
- @code{s} requests that pointers to chars be handled as strings, in
- particular collecting the contents of the memory being pointed at, up
- to the first zero. The upper bound is by default the value of the
- @code{print elements} variable; if @code{s} is followed by a decimal
- number, that is the upper bound instead. So for instance
- @samp{collect/s25 mystr} collects as many as 25 characters at
- @samp{mystr}.
- The command @code{info scope} (@pxref{Symbols, info scope}) is
- particularly useful for figuring out what data to collect.
- @kindex teval @r{(tracepoints)}
- @item teval @var{expr1}, @var{expr2}, @dots{}
- Evaluate the given expressions when the tracepoint is hit. This
- command accepts a comma-separated list of expressions. The results
- are discarded, so this is mainly useful for assigning values to trace
- state variables (@pxref{Trace State Variables}) without adding those
- values to the trace buffer, as would be the case if the @code{collect}
- action were used.
- @kindex while-stepping @r{(tracepoints)}
- @item while-stepping @var{n}
- Perform @var{n} single-step instruction traces after the tracepoint,
- collecting new data after each step. The @code{while-stepping}
- command is followed by the list of what to collect while stepping
- (followed by its own @code{end} command):
- @smallexample
- > while-stepping 12
- > collect $regs, myglobal
- > end
- >
- @end smallexample
- @noindent
- Note that @code{$pc} is not automatically collected by
- @code{while-stepping}; you need to explicitly collect that register if
- you need it. You may abbreviate @code{while-stepping} as @code{ws} or
- @code{stepping}.
- @item set default-collect @var{expr1}, @var{expr2}, @dots{}
- @kindex set default-collect
- @cindex default collection action
- This variable is a list of expressions to collect at each tracepoint
- hit. It is effectively an additional @code{collect} action prepended
- to every tracepoint action list. The expressions are parsed
- individually for each tracepoint, so for instance a variable named
- @code{xyz} may be interpreted as a global for one tracepoint, and a
- local for another, as appropriate to the tracepoint's location.
- @item show default-collect
- @kindex show default-collect
- Show the list of expressions that are collected by default at each
- tracepoint hit.
- @end table
- @node Listing Tracepoints
- @subsection Listing Tracepoints
- @table @code
- @kindex info tracepoints @r{[}@var{n}@dots{}@r{]}
- @kindex info tp @r{[}@var{n}@dots{}@r{]}
- @cindex information about tracepoints
- @item info tracepoints @r{[}@var{num}@dots{}@r{]}
- Display information about the tracepoint @var{num}. If you don't
- specify a tracepoint number, displays information about all the
- tracepoints defined so far. The format is similar to that used for
- @code{info breakpoints}; in fact, @code{info tracepoints} is the same
- command, simply restricting itself to tracepoints.
- A tracepoint's listing may include additional information specific to
- tracing:
- @itemize @bullet
- @item
- its passcount as given by the @code{passcount @var{n}} command
- @item
- the state about installed on target of each location
- @end itemize
- @smallexample
- (@value{GDBP}) @b{info trace}
- Num Type Disp Enb Address What
- 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7
- while-stepping 20
- collect globfoo, $regs
- end
- collect globfoo2
- end
- pass count 1200
- 2 tracepoint keep y <MULTIPLE>
- collect $eip
- 2.1 y 0x0804859c in func4 at change-loc.h:35
- installed on target
- 2.2 y 0xb7ffc480 in func4 at change-loc.h:35
- installed on target
- 2.3 y <PENDING> set_tracepoint
- 3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29
- not installed on target
- (@value{GDBP})
- @end smallexample
- @noindent
- This command can be abbreviated @code{info tp}.
- @end table
- @node Listing Static Tracepoint Markers
- @subsection Listing Static Tracepoint Markers
- @table @code
- @kindex info static-tracepoint-markers
- @cindex information about static tracepoint markers
- @item info static-tracepoint-markers
- Display information about all static tracepoint markers defined in the
- program.
- For each marker, the following columns are printed:
- @table @emph
- @item Count
- An incrementing counter, output to help readability. This is not a
- stable identifier.
- @item ID
- The marker ID, as reported by the target.
- @item Enabled or Disabled
- Probed markers are tagged with @samp{y}. @samp{n} identifies marks
- that are not enabled.
- @item Address
- Where the marker is in your program, as a memory address.
- @item What
- Where the marker is in the source for your program, as a file and line
- number. If the debug information included in the program does not
- allow @value{GDBN} to locate the source of the marker, this column
- will be left blank.
- @end table
- @noindent
- In addition, the following information may be printed for each marker:
- @table @emph
- @item Data
- User data passed to the tracing library by the marker call. In the
- UST backend, this is the format string passed as argument to the
- marker call.
- @item Static tracepoints probing the marker
- The list of static tracepoints attached to the marker.
- @end table
- @smallexample
- (@value{GDBP}) info static-tracepoint-markers
- Cnt ID Enb Address What
- 1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25
- Data: number1 %d number2 %d
- Probed by static tracepoints: #2
- 2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24
- Data: str %s
- (@value{GDBP})
- @end smallexample
- @end table
- @node Starting and Stopping Trace Experiments
- @subsection Starting and Stopping Trace Experiments
- @table @code
- @kindex tstart [ @var{notes} ]
- @cindex start a new trace experiment
- @cindex collected data discarded
- @item tstart
- This command starts the trace experiment, and begins collecting data.
- It has the side effect of discarding all the data collected in the
- trace buffer during the previous trace experiment. If any arguments
- are supplied, they are taken as a note and stored with the trace
- experiment's state. The notes may be arbitrary text, and are
- especially useful with disconnected tracing in a multi-user context;
- the notes can explain what the trace is doing, supply user contact
- information, and so forth.
- @kindex tstop [ @var{notes} ]
- @cindex stop a running trace experiment
- @item tstop
- This command stops the trace experiment. If any arguments are
- supplied, they are recorded with the experiment as a note. This is
- useful if you are stopping a trace started by someone else, for
- instance if the trace is interfering with the system's behavior and
- needs to be stopped quickly.
- @strong{Note}: a trace experiment and data collection may stop
- automatically if any tracepoint's passcount is reached
- (@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
- @kindex tstatus
- @cindex status of trace data collection
- @cindex trace experiment, status of
- @item tstatus
- This command displays the status of the current trace data
- collection.
- @end table
- Here is an example of the commands we described so far:
- @smallexample
- (@value{GDBP}) @b{trace gdb_c_test}
- (@value{GDBP}) @b{actions}
- Enter actions for tracepoint #1, one per line.
- > collect $regs,$locals,$args
- > while-stepping 11
- > collect $regs
- > end
- > end
- (@value{GDBP}) @b{tstart}
- [time passes @dots{}]
- (@value{GDBP}) @b{tstop}
- @end smallexample
- @anchor{disconnected tracing}
- @cindex disconnected tracing
- You can choose to continue running the trace experiment even if
- @value{GDBN} disconnects from the target, voluntarily or
- involuntarily. For commands such as @code{detach}, the debugger will
- ask what you want to do with the trace. But for unexpected
- terminations (@value{GDBN} crash, network outage), it would be
- unfortunate to lose hard-won trace data, so the variable
- @code{disconnected-tracing} lets you decide whether the trace should
- continue running without @value{GDBN}.
- @table @code
- @item set disconnected-tracing on
- @itemx set disconnected-tracing off
- @kindex set disconnected-tracing
- Choose whether a tracing run should continue to run if @value{GDBN}
- has disconnected from the target. Note that @code{detach} or
- @code{quit} will ask you directly what to do about a running trace no
- matter what this variable's setting, so the variable is mainly useful
- for handling unexpected situations, such as loss of the network.
- @item show disconnected-tracing
- @kindex show disconnected-tracing
- Show the current choice for disconnected tracing.
- @end table
- When you reconnect to the target, the trace experiment may or may not
- still be running; it might have filled the trace buffer in the
- meantime, or stopped for one of the other reasons. If it is running,
- it will continue after reconnection.
- Upon reconnection, the target will upload information about the
- tracepoints in effect. @value{GDBN} will then compare that
- information to the set of tracepoints currently defined, and attempt
- to match them up, allowing for the possibility that the numbers may
- have changed due to creation and deletion in the meantime. If one of
- the target's tracepoints does not match any in @value{GDBN}, the
- debugger will create a new tracepoint, so that you have a number with
- which to specify that tracepoint. This matching-up process is
- necessarily heuristic, and it may result in useless tracepoints being
- created; you may simply delete them if they are of no use.
- @cindex circular trace buffer
- If your target agent supports a @dfn{circular trace buffer}, then you
- can run a trace experiment indefinitely without filling the trace
- buffer; when space runs out, the agent deletes already-collected trace
- frames, oldest first, until there is enough room to continue
- collecting. This is especially useful if your tracepoints are being
- hit too often, and your trace gets terminated prematurely because the
- buffer is full. To ask for a circular trace buffer, simply set
- @samp{circular-trace-buffer} to on. You can set this at any time,
- including during tracing; if the agent can do it, it will change
- buffer handling on the fly, otherwise it will not take effect until
- the next run.
- @table @code
- @item set circular-trace-buffer on
- @itemx set circular-trace-buffer off
- @kindex set circular-trace-buffer
- Choose whether a tracing run should use a linear or circular buffer
- for trace data. A linear buffer will not lose any trace data, but may
- fill up prematurely, while a circular buffer will discard old trace
- data, but it will have always room for the latest tracepoint hits.
- @item show circular-trace-buffer
- @kindex show circular-trace-buffer
- Show the current choice for the trace buffer. Note that this may not
- match the agent's current buffer handling, nor is it guaranteed to
- match the setting that might have been in effect during a past run,
- for instance if you are looking at frames from a trace file.
- @end table
- @table @code
- @item set trace-buffer-size @var{n}
- @itemx set trace-buffer-size unlimited
- @kindex set trace-buffer-size
- Request that the target use a trace buffer of @var{n} bytes. Not all
- targets will honor the request; they may have a compiled-in size for
- the trace buffer, or some other limitation. Set to a value of
- @code{unlimited} or @code{-1} to let the target use whatever size it
- likes. This is also the default.
- @item show trace-buffer-size
- @kindex show trace-buffer-size
- Show the current requested size for the trace buffer. Note that this
- will only match the actual size if the target supports size-setting,
- and was able to handle the requested size. For instance, if the
- target can only change buffer size between runs, this variable will
- not reflect the change until the next run starts. Use @code{tstatus}
- to get a report of the actual buffer size.
- @end table
- @table @code
- @item set trace-user @var{text}
- @kindex set trace-user
- @item show trace-user
- @kindex show trace-user
- @item set trace-notes @var{text}
- @kindex set trace-notes
- Set the trace run's notes.
- @item show trace-notes
- @kindex show trace-notes
- Show the trace run's notes.
- @item set trace-stop-notes @var{text}
- @kindex set trace-stop-notes
- Set the trace run's stop notes. The handling of the note is as for
- @code{tstop} arguments; the set command is convenient way to fix a
- stop note that is mistaken or incomplete.
- @item show trace-stop-notes
- @kindex show trace-stop-notes
- Show the trace run's stop notes.
- @end table
- @node Tracepoint Restrictions
- @subsection Tracepoint Restrictions
- @cindex tracepoint restrictions
- There are a number of restrictions on the use of tracepoints. As
- described above, tracepoint data gathering occurs on the target
- without interaction from @value{GDBN}. Thus the full capabilities of
- the debugger are not available during data gathering, and then at data
- examination time, you will be limited by only having what was
- collected. The following items describe some common problems, but it
- is not exhaustive, and you may run into additional difficulties not
- mentioned here.
- @itemize @bullet
- @item
- Tracepoint expressions are intended to gather objects (lvalues). Thus
- the full flexibility of GDB's expression evaluator is not available.
- You cannot call functions, cast objects to aggregate types, access
- convenience variables or modify values (except by assignment to trace
- state variables). Some language features may implicitly call
- functions (for instance Objective-C fields with accessors), and therefore
- cannot be collected either.
- @item
- Collection of local variables, either individually or in bulk with
- @code{$locals} or @code{$args}, during @code{while-stepping} may
- behave erratically. The stepping action may enter a new scope (for
- instance by stepping into a function), or the location of the variable
- may change (for instance it is loaded into a register). The
- tracepoint data recorded uses the location information for the
- variables that is correct for the tracepoint location. When the
- tracepoint is created, it is not possible, in general, to determine
- where the steps of a @code{while-stepping} sequence will advance the
- program---particularly if a conditional branch is stepped.
- @item
- Collection of an incompletely-initialized or partially-destroyed object
- may result in something that @value{GDBN} cannot display, or displays
- in a misleading way.
- @item
- When @value{GDBN} displays a pointer to character it automatically
- dereferences the pointer to also display characters of the string
- being pointed to. However, collecting the pointer during tracing does
- not automatically collect the string. You need to explicitly
- dereference the pointer and provide size information if you want to
- collect not only the pointer, but the memory pointed to. For example,
- @code{*ptr@@50} can be used to collect the 50 element array pointed to
- by @code{ptr}.
- @item
- It is not possible to collect a complete stack backtrace at a
- tracepoint. Instead, you may collect the registers and a few hundred
- bytes from the stack pointer with something like @code{*(unsigned char *)$esp@@300}
- (adjust to use the name of the actual stack pointer register on your
- target architecture, and the amount of stack you wish to capture).
- Then the @code{backtrace} command will show a partial backtrace when
- using a trace frame. The number of stack frames that can be examined
- depends on the sizes of the frames in the collected stack. Note that
- if you ask for a block so large that it goes past the bottom of the
- stack, the target agent may report an error trying to read from an
- invalid address.
- @item
- If you do not collect registers at a tracepoint, @value{GDBN} can
- infer that the value of @code{$pc} must be the same as the address of
- the tracepoint and use that when you are looking at a trace frame
- for that tracepoint. However, this cannot work if the tracepoint has
- multiple locations (for instance if it was set in a function that was
- inlined), or if it has a @code{while-stepping} loop. In those cases
- @value{GDBN} will warn you that it can't infer @code{$pc}, and default
- it to zero.
- @end itemize
- @node Analyze Collected Data
- @section Using the Collected Data
- After the tracepoint experiment ends, you use @value{GDBN} commands
- for examining the trace data. The basic idea is that each tracepoint
- collects a trace @dfn{snapshot} every time it is hit and another
- snapshot every time it single-steps. All these snapshots are
- consecutively numbered from zero and go into a buffer, and you can
- examine them later. The way you examine them is to @dfn{focus} on a
- specific trace snapshot. When the remote stub is focused on a trace
- snapshot, it will respond to all @value{GDBN} requests for memory and
- registers by reading from the buffer which belongs to that snapshot,
- rather than from @emph{real} memory or registers of the program being
- debugged. This means that @strong{all} @value{GDBN} commands
- (@code{print}, @code{info registers}, @code{backtrace}, etc.) will
- behave as if we were currently debugging the program state as it was
- when the tracepoint occurred. Any requests for data that are not in
- the buffer will fail.
- @menu
- * tfind:: How to select a trace snapshot
- * tdump:: How to display all data for a snapshot
- * save tracepoints:: How to save tracepoints for a future run
- @end menu
- @node tfind
- @subsection @code{tfind @var{n}}
- @kindex tfind
- @cindex select trace snapshot
- @cindex find trace snapshot
- The basic command for selecting a trace snapshot from the buffer is
- @code{tfind @var{n}}, which finds trace snapshot number @var{n},
- counting from zero. If no argument @var{n} is given, the next
- snapshot is selected.
- Here are the various forms of using the @code{tfind} command.
- @table @code
- @item tfind start
- Find the first snapshot in the buffer. This is a synonym for
- @code{tfind 0} (since 0 is the number of the first snapshot).
- @item tfind none
- Stop debugging trace snapshots, resume @emph{live} debugging.
- @item tfind end
- Same as @samp{tfind none}.
- @item tfind
- No argument means find the next trace snapshot or find the first
- one if no trace snapshot is selected.
- @item tfind -
- Find the previous trace snapshot before the current one. This permits
- retracing earlier steps.
- @item tfind tracepoint @var{num}
- Find the next snapshot associated with tracepoint @var{num}. Search
- proceeds forward from the last examined trace snapshot. If no
- argument @var{num} is given, it means find the next snapshot collected
- for the same tracepoint as the current snapshot.
- @item tfind pc @var{addr}
- Find the next snapshot associated with the value @var{addr} of the
- program counter. Search proceeds forward from the last examined trace
- snapshot. If no argument @var{addr} is given, it means find the next
- snapshot with the same value of PC as the current snapshot.
- @item tfind outside @var{addr1}, @var{addr2}
- Find the next snapshot whose PC is outside the given range of
- addresses (exclusive).
- @item tfind range @var{addr1}, @var{addr2}
- Find the next snapshot whose PC is between @var{addr1} and
- @var{addr2} (inclusive).
- @item tfind line @r{[}@var{file}:@r{]}@var{n}
- Find the next snapshot associated with the source line @var{n}. If
- the optional argument @var{file} is given, refer to line @var{n} in
- that source file. Search proceeds forward from the last examined
- trace snapshot. If no argument @var{n} is given, it means find the
- next line other than the one currently being examined; thus saying
- @code{tfind line} repeatedly can appear to have the same effect as
- stepping from line to line in a @emph{live} debugging session.
- @end table
- The default arguments for the @code{tfind} commands are specifically
- designed to make it easy to scan through the trace buffer. For
- instance, @code{tfind} with no argument selects the next trace
- snapshot, and @code{tfind -} with no argument selects the previous
- trace snapshot. So, by giving one @code{tfind} command, and then
- simply hitting @key{RET} repeatedly you can examine all the trace
- snapshots in order. Or, by saying @code{tfind -} and then hitting
- @key{RET} repeatedly you can examine the snapshots in reverse order.
- The @code{tfind line} command with no argument selects the snapshot
- for the next source line executed. The @code{tfind pc} command with
- no argument selects the next snapshot with the same program counter
- (PC) as the current frame. The @code{tfind tracepoint} command with
- no argument selects the next trace snapshot collected by the same
- tracepoint as the current one.
- In addition to letting you scan through the trace buffer manually,
- these commands make it easy to construct @value{GDBN} scripts that
- scan through the trace buffer and print out whatever collected data
- you are interested in. Thus, if we want to examine the PC, FP, and SP
- registers from each trace frame in the buffer, we can say this:
- @smallexample
- (@value{GDBP}) @b{tfind start}
- (@value{GDBP}) @b{while ($trace_frame != -1)}
- > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
- $trace_frame, $pc, $sp, $fp
- > tfind
- > end
- Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
- Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
- Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
- Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
- Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
- Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
- Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
- Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
- Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
- Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
- Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
- @end smallexample
- Or, if we want to examine the variable @code{X} at each source line in
- the buffer:
- @smallexample
- (@value{GDBP}) @b{tfind start}
- (@value{GDBP}) @b{while ($trace_frame != -1)}
- > printf "Frame %d, X == %d\n", $trace_frame, X
- > tfind line
- > end
- Frame 0, X = 1
- Frame 7, X = 2
- Frame 13, X = 255
- @end smallexample
- @node tdump
- @subsection @code{tdump}
- @kindex tdump
- @cindex dump all data collected at tracepoint
- @cindex tracepoint data, display
- This command takes no arguments. It prints all the data collected at
- the current trace snapshot.
- @smallexample
- (@value{GDBP}) @b{trace 444}
- (@value{GDBP}) @b{actions}
- Enter actions for tracepoint #2, one per line:
- > collect $regs, $locals, $args, gdb_long_test
- > end
- (@value{GDBP}) @b{tstart}
- (@value{GDBP}) @b{tfind line 444}
- #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
- at gdb_test.c:444
- 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
- (@value{GDBP}) @b{tdump}
- Data collected at tracepoint 2, trace frame 1:
- d0 0xc4aa0085 -995491707
- d1 0x18 24
- d2 0x80 128
- d3 0x33 51
- d4 0x71aea3d 119204413
- d5 0x22 34
- d6 0xe0 224
- d7 0x380035 3670069
- a0 0x19e24a 1696330
- a1 0x3000668 50333288
- a2 0x100 256
- a3 0x322000 3284992
- a4 0x3000698 50333336
- a5 0x1ad3cc 1758156
- fp 0x30bf3c 0x30bf3c
- sp 0x30bf34 0x30bf34
- ps 0x0 0
- pc 0x20b2c8 0x20b2c8
- fpcontrol 0x0 0
- fpstatus 0x0 0
- fpiaddr 0x0 0
- p = 0x20e5b4 "gdb-test"
- p1 = (void *) 0x11
- p2 = (void *) 0x22
- p3 = (void *) 0x33
- p4 = (void *) 0x44
- p5 = (void *) 0x55
- p6 = (void *) 0x66
- gdb_long_test = 17 '\021'
- (@value{GDBP})
- @end smallexample
- @code{tdump} works by scanning the tracepoint's current collection
- actions and printing the value of each expression listed. So
- @code{tdump} can fail, if after a run, you change the tracepoint's
- actions to mention variables that were not collected during the run.
- Also, for tracepoints with @code{while-stepping} loops, @code{tdump}
- uses the collected value of @code{$pc} to distinguish between trace
- frames that were collected at the tracepoint hit, and frames that were
- collected while stepping. This allows it to correctly choose whether
- to display the basic list of collections, or the collections from the
- body of the while-stepping loop. However, if @code{$pc} was not collected,
- then @code{tdump} will always attempt to dump using the basic collection
- list, and may fail if a while-stepping frame does not include all the
- same data that is collected at the tracepoint hit.
- @c This is getting pretty arcane, example would be good.
- @node save tracepoints
- @subsection @code{save tracepoints @var{filename}}
- @kindex save tracepoints
- @kindex save-tracepoints
- @cindex save tracepoints for future sessions
- This command saves all current tracepoint definitions together with
- their actions and passcounts, into a file @file{@var{filename}}
- suitable for use in a later debugging session. To read the saved
- tracepoint definitions, use the @code{source} command (@pxref{Command
- Files}). The @w{@code{save-tracepoints}} command is a deprecated
- alias for @w{@code{save tracepoints}}
- @node Tracepoint Variables
- @section Convenience Variables for Tracepoints
- @cindex tracepoint variables
- @cindex convenience variables for tracepoints
- @table @code
- @vindex $trace_frame
- @item (int) $trace_frame
- The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no
- snapshot is selected.
- @vindex $tracepoint
- @item (int) $tracepoint
- The tracepoint for the current trace snapshot.
- @vindex $trace_line
- @item (int) $trace_line
- The line number for the current trace snapshot.
- @vindex $trace_file
- @item (char []) $trace_file
- The source file for the current trace snapshot.
- @vindex $trace_func
- @item (char []) $trace_func
- The name of the function containing @code{$tracepoint}.
- @end table
- Note: @code{$trace_file} is not suitable for use in @code{printf},
- use @code{output} instead.
- Here's a simple example of using these convenience variables for
- stepping through all the trace snapshots and printing some of their
- data. Note that these are not the same as trace state variables,
- which are managed by the target.
- @smallexample
- (@value{GDBP}) @b{tfind start}
- (@value{GDBP}) @b{while $trace_frame != -1}
- > output $trace_file
- > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
- > tfind
- > end
- @end smallexample
- @node Trace Files
- @section Using Trace Files
- @cindex trace files
- In some situations, the target running a trace experiment may no
- longer be available; perhaps it crashed, or the hardware was needed
- for a different activity. To handle these cases, you can arrange to
- dump the trace data into a file, and later use that file as a source
- of trace data, via the @code{target tfile} command.
- @table @code
- @kindex tsave
- @item tsave [ -r ] @var{filename}
- @itemx tsave [-ctf] @var{dirname}
- Save the trace data to @var{filename}. By default, this command
- assumes that @var{filename} refers to the host filesystem, so if
- necessary @value{GDBN} will copy raw trace data up from the target and
- then save it. If the target supports it, you can also supply the
- optional argument @code{-r} (``remote'') to direct the target to save
- the data directly into @var{filename} in its own filesystem, which may be
- more efficient if the trace buffer is very large. (Note, however, that
- @code{target tfile} can only read from files accessible to the host.)
- By default, this command will save trace frame in tfile format.
- You can supply the optional argument @code{-ctf} to save data in CTF
- format. The @dfn{Common Trace Format} (CTF) is proposed as a trace format
- that can be shared by multiple debugging and tracing tools. Please go to
- @indicateurl{http://www.efficios.com/ctf} to get more information.
- @kindex target tfile
- @kindex tfile
- @kindex target ctf
- @kindex ctf
- @item target tfile @var{filename}
- @itemx target ctf @var{dirname}
- Use the file named @var{filename} or directory named @var{dirname} as
- a source of trace data. Commands that examine data work as they do with
- a live target, but it is not possible to run any new trace experiments.
- @code{tstatus} will report the state of the trace run at the moment
- the data was saved, as well as the current trace frame you are examining.
- Both @var{filename} and @var{dirname} must be on a filesystem accessible to
- the host.
- @smallexample
- (@value{GDBP}) target ctf ctf.ctf
- (@value{GDBP}) tfind
- Found trace frame 0, tracepoint 2
- 39 ++a; /* set tracepoint 1 here */
- (@value{GDBP}) tdump
- Data collected at tracepoint 2, trace frame 0:
- i = 0
- a = 0
- b = 1 '\001'
- c = @{"123", "456", "789", "123", "456", "789"@}
- d = @{@{@{a = 1, b = 2@}, @{a = 3, b = 4@}@}, @{@{a = 5, b = 6@}, @{a = 7, b = 8@}@}@}
- (@value{GDBP}) p b
- $1 = 1
- @end smallexample
- @end table
- @node Overlays
- @chapter Debugging Programs That Use Overlays
- @cindex overlays
- If your program is too large to fit completely in your target system's
- memory, you can sometimes use @dfn{overlays} to work around this
- problem. @value{GDBN} provides some support for debugging programs that
- use overlays.
- @menu
- * How Overlays Work:: A general explanation of overlays.
- * Overlay Commands:: Managing overlays in @value{GDBN}.
- * Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are
- mapped by asking the inferior.
- * Overlay Sample Program:: A sample program using overlays.
- @end menu
- @node How Overlays Work
- @section How Overlays Work
- @cindex mapped overlays
- @cindex unmapped overlays
- @cindex load address, overlay's
- @cindex mapped address
- @cindex overlay area
- Suppose you have a computer whose instruction address space is only 64
- kilobytes long, but which has much more memory which can be accessed by
- other means: special instructions, segment registers, or memory
- management hardware, for example. Suppose further that you want to
- adapt a program which is larger than 64 kilobytes to run on this system.
- One solution is to identify modules of your program which are relatively
- independent, and need not call each other directly; call these modules
- @dfn{overlays}. Separate the overlays from the main program, and place
- their machine code in the larger memory. Place your main program in
- instruction memory, but leave at least enough space there to hold the
- largest overlay as well.
- Now, to call a function located in an overlay, you must first copy that
- overlay's machine code from the large memory into the space set aside
- for it in the instruction memory, and then jump to its entry point
- there.
- @c NB: In the below the mapped area's size is greater or equal to the
- @c size of all overlays. This is intentional to remind the developer
- @c that overlays don't necessarily need to be the same size.
- @smallexample
- @group
- Data Instruction Larger
- Address Space Address Space Address Space
- +-----------+ +-----------+ +-----------+
- | | | | | |
- +-----------+ +-----------+ +-----------+<-- overlay 1
- | program | | main | .----| overlay 1 | load address
- | variables | | program | | +-----------+
- | and heap | | | | | |
- +-----------+ | | | +-----------+<-- overlay 2
- | | +-----------+ | | | load address
- +-----------+ | | | .-| overlay 2 |
- | | | | | |
- mapped --->+-----------+ | | +-----------+
- address | | | | | |
- | overlay | <-' | | |
- | area | <---' +-----------+<-- overlay 3
- | | <---. | | load address
- +-----------+ `--| overlay 3 |
- | | | |
- +-----------+ | |
- +-----------+
- | |
- +-----------+
- @anchor{A code overlay}A code overlay
- @end group
- @end smallexample
- The diagram (@pxref{A code overlay}) shows a system with separate data
- and instruction address spaces. To map an overlay, the program copies
- its code from the larger address space to the instruction address space.
- Since the overlays shown here all use the same mapped address, only one
- may be mapped at a time. For a system with a single address space for
- data and instructions, the diagram would be similar, except that the
- program variables and heap would share an address space with the main
- program and the overlay area.
- An overlay loaded into instruction memory and ready for use is called a
- @dfn{mapped} overlay; its @dfn{mapped address} is its address in the
- instruction memory. An overlay not present (or only partially present)
- in instruction memory is called @dfn{unmapped}; its @dfn{load address}
- is its address in the larger memory. The mapped address is also called
- the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
- called the @dfn{load memory address}, or @dfn{LMA}.
- Unfortunately, overlays are not a completely transparent way to adapt a
- program to limited instruction memory. They introduce a new set of
- global constraints you must keep in mind as you design your program:
- @itemize @bullet
- @item
- Before calling or returning to a function in an overlay, your program
- must make sure that overlay is actually mapped. Otherwise, the call or
- return will transfer control to the right address, but in the wrong
- overlay, and your program will probably crash.
- @item
- If the process of mapping an overlay is expensive on your system, you
- will need to choose your overlays carefully to minimize their effect on
- your program's performance.
- @item
- The executable file you load onto your system must contain each
- overlay's instructions, appearing at the overlay's load address, not its
- mapped address. However, each overlay's instructions must be relocated
- and its symbols defined as if the overlay were at its mapped address.
- You can use GNU linker scripts to specify different load and relocation
- addresses for pieces of your program; see @ref{Overlay Description,,,
- ld.info, Using ld: the GNU linker}.
- @item
- The procedure for loading executable files onto your system must be able
- to load their contents into the larger address space as well as the
- instruction and data spaces.
- @end itemize
- The overlay system described above is rather simple, and could be
- improved in many ways:
- @itemize @bullet
- @item
- If your system has suitable bank switch registers or memory management
- hardware, you could use those facilities to make an overlay's load area
- contents simply appear at their mapped address in instruction space.
- This would probably be faster than copying the overlay to its mapped
- area in the usual way.
- @item
- If your overlays are small enough, you could set aside more than one
- overlay area, and have more than one overlay mapped at a time.
- @item
- You can use overlays to manage data, as well as instructions. In
- general, data overlays are even less transparent to your design than
- code overlays: whereas code overlays only require care when you call or
- return to functions, data overlays require care every time you access
- the data. Also, if you change the contents of a data overlay, you
- must copy its contents back out to its load address before you can copy a
- different data overlay into the same mapped area.
- @end itemize
- @node Overlay Commands
- @section Overlay Commands
- To use @value{GDBN}'s overlay support, each overlay in your program must
- correspond to a separate section of the executable file. The section's
- virtual memory address and load memory address must be the overlay's
- mapped and load addresses. Identifying overlays with sections allows
- @value{GDBN} to determine the appropriate address of a function or
- variable, depending on whether the overlay is mapped or not.
- @value{GDBN}'s overlay commands all start with the word @code{overlay};
- you can abbreviate this as @code{ov} or @code{ovly}. The commands are:
- @table @code
- @item overlay off
- @kindex overlay
- Disable @value{GDBN}'s overlay support. When overlay support is
- disabled, @value{GDBN} assumes that all functions and variables are
- always present at their mapped addresses. By default, @value{GDBN}'s
- overlay support is disabled.
- @item overlay manual
- @cindex manual overlay debugging
- Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
- relies on you to tell it which overlays are mapped, and which are not,
- using the @code{overlay map-overlay} and @code{overlay unmap-overlay}
- commands described below.
- @item overlay map-overlay @var{overlay}
- @itemx overlay map @var{overlay}
- @cindex map an overlay
- Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
- be the name of the object file section containing the overlay. When an
- overlay is mapped, @value{GDBN} assumes it can find the overlay's
- functions and variables at their mapped addresses. @value{GDBN} assumes
- that any other overlays whose mapped ranges overlap that of
- @var{overlay} are now unmapped.
- @item overlay unmap-overlay @var{overlay}
- @itemx overlay unmap @var{overlay}
- @cindex unmap an overlay
- Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
- must be the name of the object file section containing the overlay.
- When an overlay is unmapped, @value{GDBN} assumes it can find the
- overlay's functions and variables at their load addresses.
- @item overlay auto
- Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
- consults a data structure the overlay manager maintains in the inferior
- to see which overlays are mapped. For details, see @ref{Automatic
- Overlay Debugging}.
- @item overlay load-target
- @itemx overlay load
- @cindex reloading the overlay table
- Re-read the overlay table from the inferior. Normally, @value{GDBN}
- re-reads the table @value{GDBN} automatically each time the inferior
- stops, so this command should only be necessary if you have changed the
- overlay mapping yourself using @value{GDBN}. This command is only
- useful when using automatic overlay debugging.
- @item overlay list-overlays
- @itemx overlay list
- @cindex listing mapped overlays
- Display a list of the overlays currently mapped, along with their mapped
- addresses, load addresses, and sizes.
- @end table
- Normally, when @value{GDBN} prints a code address, it includes the name
- of the function the address falls in:
- @smallexample
- (@value{GDBP}) print main
- $3 = @{int ()@} 0x11a0 <main>
- @end smallexample
- @noindent
- When overlay debugging is enabled, @value{GDBN} recognizes code in
- unmapped overlays, and prints the names of unmapped functions with
- asterisks around them. For example, if @code{foo} is a function in an
- unmapped overlay, @value{GDBN} prints it this way:
- @smallexample
- (@value{GDBP}) overlay list
- No sections are mapped.
- (@value{GDBP}) print foo
- $5 = @{int (int)@} 0x100000 <*foo*>
- @end smallexample
- @noindent
- When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
- name normally:
- @smallexample
- (@value{GDBP}) overlay list
- Section .ov.foo.text, loaded at 0x100000 - 0x100034,
- mapped at 0x1016 - 0x104a
- (@value{GDBP}) print foo
- $6 = @{int (int)@} 0x1016 <foo>
- @end smallexample
- When overlay debugging is enabled, @value{GDBN} can find the correct
- address for functions and variables in an overlay, whether or not the
- overlay is mapped. This allows most @value{GDBN} commands, like
- @code{break} and @code{disassemble}, to work normally, even on unmapped
- code. However, @value{GDBN}'s breakpoint support has some limitations:
- @itemize @bullet
- @item
- @cindex breakpoints in overlays
- @cindex overlays, setting breakpoints in
- You can set breakpoints in functions in unmapped overlays, as long as
- @value{GDBN} can write to the overlay at its load address.
- @item
- @value{GDBN} can not set hardware or simulator-based breakpoints in
- unmapped overlays. However, if you set a breakpoint at the end of your
- overlay manager (and tell @value{GDBN} which overlays are now mapped, if
- you are using manual overlay management), @value{GDBN} will re-set its
- breakpoints properly.
- @end itemize
- @node Automatic Overlay Debugging
- @section Automatic Overlay Debugging
- @cindex automatic overlay debugging
- @value{GDBN} can automatically track which overlays are mapped and which
- are not, given some simple co-operation from the overlay manager in the
- inferior. If you enable automatic overlay debugging with the
- @code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN}
- looks in the inferior's memory for certain variables describing the
- current state of the overlays.
- Here are the variables your overlay manager must define to support
- @value{GDBN}'s automatic overlay debugging:
- @table @asis
- @item @code{_ovly_table}:
- This variable must be an array of the following structures:
- @smallexample
- struct
- @{
- /* The overlay's mapped address. */
- unsigned long vma;
- /* The size of the overlay, in bytes. */
- unsigned long size;
- /* The overlay's load address. */
- unsigned long lma;
- /* Non-zero if the overlay is currently mapped;
- zero otherwise. */
- unsigned long mapped;
- @}
- @end smallexample
- @item @code{_novlys}:
- This variable must be a four-byte signed integer, holding the total
- number of elements in @code{_ovly_table}.
- @end table
- To decide whether a particular overlay is mapped or not, @value{GDBN}
- looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and
- @code{lma} members equal the VMA and LMA of the overlay's section in the
- executable file. When @value{GDBN} finds a matching entry, it consults
- the entry's @code{mapped} member to determine whether the overlay is
- currently mapped.
- In addition, your overlay manager may define a function called
- @code{_ovly_debug_event}. If this function is defined, @value{GDBN}
- will silently set a breakpoint there. If the overlay manager then
- calls this function whenever it has changed the overlay table, this
- will enable @value{GDBN} to accurately keep track of which overlays
- are in program memory, and update any breakpoints that may be set
- in overlays. This will allow breakpoints to work even if the
- overlays are kept in ROM or other non-writable memory while they
- are not being executed.
- @node Overlay Sample Program
- @section Overlay Sample Program
- @cindex overlay example program
- When linking a program which uses overlays, you must place the overlays
- at their load addresses, while relocating them to run at their mapped
- addresses. To do this, you must write a linker script (@pxref{Overlay
- Description,,, ld.info, Using ld: the GNU linker}). Unfortunately,
- since linker scripts are specific to a particular host system, target
- architecture, and target memory layout, this manual cannot provide
- portable sample code demonstrating @value{GDBN}'s overlay support.
- However, the @value{GDBN} source distribution does contain an overlaid
- program, with linker scripts for a few systems, as part of its test
- suite. The program consists of the following files from
- @file{gdb/testsuite/gdb.base}:
- @table @file
- @item overlays.c
- The main program file.
- @item ovlymgr.c
- A simple overlay manager, used by @file{overlays.c}.
- @item foo.c
- @itemx bar.c
- @itemx baz.c
- @itemx grbx.c
- Overlay modules, loaded and used by @file{overlays.c}.
- @item d10v.ld
- @itemx m32r.ld
- Linker scripts for linking the test program on the @code{d10v-elf}
- and @code{m32r-elf} targets.
- @end table
- You can build the test program using the @code{d10v-elf} GCC
- cross-compiler like this:
- @smallexample
- $ d10v-elf-gcc -g -c overlays.c
- $ d10v-elf-gcc -g -c ovlymgr.c
- $ d10v-elf-gcc -g -c foo.c
- $ d10v-elf-gcc -g -c bar.c
- $ d10v-elf-gcc -g -c baz.c
- $ d10v-elf-gcc -g -c grbx.c
- $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
- baz.o grbx.o -Wl,-Td10v.ld -o overlays
- @end smallexample
- The build process is identical for any other architecture, except that
- you must substitute the appropriate compiler and linker script for the
- target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
- @node Languages
- @chapter Using @value{GDBN} with Different Languages
- @cindex languages
- Although programming languages generally have common aspects, they are
- rarely expressed in the same manner. For instance, in ANSI C,
- dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
- Modula-2, it is accomplished by @code{p^}. Values can also be
- represented (and displayed) differently. Hex numbers in C appear as
- @samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
- @cindex working language
- Language-specific information is built into @value{GDBN} for some languages,
- allowing you to express operations like the above in your program's
- native language, and allowing @value{GDBN} to output values in a manner
- consistent with the syntax of your program's native language. The
- language you use to build expressions is called the @dfn{working
- language}.
- @menu
- * Setting:: Switching between source languages
- * Show:: Displaying the language
- * Checks:: Type and range checks
- * Supported Languages:: Supported languages
- * Unsupported Languages:: Unsupported languages
- @end menu
- @node Setting
- @section Switching Between Source Languages
- There are two ways to control the working language---either have @value{GDBN}
- set it automatically, or select it manually yourself. You can use the
- @code{set language} command for either purpose. On startup, @value{GDBN}
- defaults to setting the language automatically. The working language is
- used to determine how expressions you type are interpreted, how values
- are printed, etc.
- In addition to the working language, every source file that
- @value{GDBN} knows about has its own working language. For some object
- file formats, the compiler might indicate which language a particular
- source file is in. However, most of the time @value{GDBN} infers the
- language from the name of the file. The language of a source file
- controls whether C@t{++} names are demangled---this way @code{backtrace} can
- show each frame appropriately for its own language. There is no way to
- set the language of a source file from within @value{GDBN}, but you can
- set the language associated with a filename extension. @xref{Show, ,
- Displaying the Language}.
- This is most commonly a problem when you use a program, such
- as @code{cfront} or @code{f2c}, that generates C but is written in
- another language. In that case, make the
- program use @code{#line} directives in its C output; that way
- @value{GDBN} will know the correct language of the source code of the original
- program, and will display that source code, not the generated C code.
- @menu
- * Filenames:: Filename extensions and languages.
- * Manually:: Setting the working language manually
- * Automatically:: Having @value{GDBN} infer the source language
- @end menu
- @node Filenames
- @subsection List of Filename Extensions and Languages
- If a source file name ends in one of the following extensions, then
- @value{GDBN} infers that its language is the one indicated.
- @table @file
- @item .ada
- @itemx .ads
- @itemx .adb
- @itemx .a
- Ada source file.
- @item .c
- C source file
- @item .C
- @itemx .cc
- @itemx .cp
- @itemx .cpp
- @itemx .cxx
- @itemx .c++
- C@t{++} source file
- @item .d
- D source file
- @item .m
- Objective-C source file
- @item .f
- @itemx .F
- Fortran source file
- @item .mod
- Modula-2 source file
- @item .s
- @itemx .S
- Assembler source file. This actually behaves almost like C, but
- @value{GDBN} does not skip over function prologues when stepping.
- @end table
- In addition, you may set the language associated with a filename
- extension. @xref{Show, , Displaying the Language}.
- @node Manually
- @subsection Setting the Working Language
- If you allow @value{GDBN} to set the language automatically,
- expressions are interpreted the same way in your debugging session and
- your program.
- @kindex set language
- If you wish, you may set the language manually. To do this, issue the
- command @samp{set language @var{lang}}, where @var{lang} is the name of
- a language, such as
- @code{c} or @code{modula-2}.
- For a list of the supported languages, type @samp{set language}.
- Setting the language manually prevents @value{GDBN} from updating the working
- language automatically. This can lead to confusion if you try
- to debug a program when the working language is not the same as the
- source language, when an expression is acceptable to both
- languages---but means different things. For instance, if the current
- source file were written in C, and @value{GDBN} was parsing Modula-2, a
- command such as:
- @smallexample
- print a = b + c
- @end smallexample
- @noindent
- might not have the effect you intended. In C, this means to add
- @code{b} and @code{c} and place the result in @code{a}. The result
- printed would be the value of @code{a}. In Modula-2, this means to compare
- @code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
- @node Automatically
- @subsection Having @value{GDBN} Infer the Source Language
- To have @value{GDBN} set the working language automatically, use
- @samp{set language local} or @samp{set language auto}. @value{GDBN}
- then infers the working language. That is, when your program stops in a
- frame (usually by encountering a breakpoint), @value{GDBN} sets the
- working language to the language recorded for the function in that
- frame. If the language for a frame is unknown (that is, if the function
- or block corresponding to the frame was defined in a source file that
- does not have a recognized extension), the current working language is
- not changed, and @value{GDBN} issues a warning.
- This may not seem necessary for most programs, which are written
- entirely in one source language. However, program modules and libraries
- written in one source language can be used by a main program written in
- a different source language. Using @samp{set language auto} in this
- case frees you from having to set the working language manually.
- @node Show
- @section Displaying the Language
- The following commands help you find out which language is the
- working language, and also what language source files were written in.
- @table @code
- @item show language
- @anchor{show language}
- @kindex show language
- Display the current working language. This is the
- language you can use with commands such as @code{print} to
- build and compute expressions that may involve variables in your program.
- @item info frame
- @kindex info frame@r{, show the source language}
- Display the source language for this frame. This language becomes the
- working language if you use an identifier from this frame.
- @xref{Frame Info, ,Information about a Frame}, to identify the other
- information listed here.
- @item info source
- @kindex info source@r{, show the source language}
- Display the source language of this source file.
- @xref{Symbols, ,Examining the Symbol Table}, to identify the other
- information listed here.
- @end table
- In unusual circumstances, you may have source files with extensions
- not in the standard list. You can then set the extension associated
- with a language explicitly:
- @table @code
- @item set extension-language @var{ext} @var{language}
- @kindex set extension-language
- Tell @value{GDBN} that source files with extension @var{ext} are to be
- assumed as written in the source language @var{language}.
- @item info extensions
- @kindex info extensions
- List all the filename extensions and the associated languages.
- @end table
- @node Checks
- @section Type and Range Checking
- Some languages are designed to guard you against making seemingly common
- errors through a series of compile- and run-time checks. These include
- checking the type of arguments to functions and operators and making
- sure mathematical overflows are caught at run time. Checks such as
- these help to ensure a program's correctness once it has been compiled
- by eliminating type mismatches and providing active checks for range
- errors when your program is running.
- By default @value{GDBN} checks for these errors according to the
- rules of the current source language. Although @value{GDBN} does not check
- the statements in your program, it can check expressions entered directly
- into @value{GDBN} for evaluation via the @code{print} command, for example.
- @menu
- * Type Checking:: An overview of type checking
- * Range Checking:: An overview of range checking
- @end menu
- @cindex type checking
- @cindex checks, type
- @node Type Checking
- @subsection An Overview of Type Checking
- Some languages, such as C and C@t{++}, are strongly typed, meaning that the
- arguments to operators and functions have to be of the correct type,
- otherwise an error occurs. These checks prevent type mismatch
- errors from ever causing any run-time problems. For example,
- @smallexample
- int klass::my_method(char *b) @{ return b ? 1 : 2; @}
- (@value{GDBP}) print obj.my_method (0)
- $1 = 2
- @exdent but
- (@value{GDBP}) print obj.my_method (0x1234)
- Cannot resolve method klass::my_method to any overloaded instance
- @end smallexample
- The second example fails because in C@t{++} the integer constant
- @samp{0x1234} is not type-compatible with the pointer parameter type.
- For the expressions you use in @value{GDBN} commands, you can tell
- @value{GDBN} to not enforce strict type checking or
- to treat any mismatches as errors and abandon the expression;
- When type checking is disabled, @value{GDBN} successfully evaluates
- expressions like the second example above.
- Even if type checking is off, there may be other reasons
- related to type that prevent @value{GDBN} from evaluating an expression.
- For instance, @value{GDBN} does not know how to add an @code{int} and
- a @code{struct foo}. These particular type errors have nothing to do
- with the language in use and usually arise from expressions which make
- little sense to evaluate anyway.
- @value{GDBN} provides some additional commands for controlling type checking:
- @kindex set check type
- @kindex show check type
- @table @code
- @item set check type on
- @itemx set check type off
- Set strict type checking on or off. If any type mismatches occur in
- evaluating an expression while type checking is on, @value{GDBN} prints a
- message and aborts evaluation of the expression.
- @item show check type
- Show the current setting of type checking and whether @value{GDBN}
- is enforcing strict type checking rules.
- @end table
- @cindex range checking
- @cindex checks, range
- @node Range Checking
- @subsection An Overview of Range Checking
- In some languages (such as Modula-2), it is an error to exceed the
- bounds of a type; this is enforced with run-time checks. Such range
- checking is meant to ensure program correctness by making sure
- computations do not overflow, or indices on an array element access do
- not exceed the bounds of the array.
- For expressions you use in @value{GDBN} commands, you can tell
- @value{GDBN} to treat range errors in one of three ways: ignore them,
- always treat them as errors and abandon the expression, or issue
- warnings but evaluate the expression anyway.
- A range error can result from numerical overflow, from exceeding an
- array index bound, or when you type a constant that is not a member
- of any type. Some languages, however, do not treat overflows as an
- error. In many implementations of C, mathematical overflow causes the
- result to ``wrap around'' to lower values---for example, if @var{m} is
- the largest integer value, and @var{s} is the smallest, then
- @smallexample
- @var{m} + 1 @result{} @var{s}
- @end smallexample
- This, too, is specific to individual languages, and in some cases
- specific to individual compilers or machines. @xref{Supported Languages, ,
- Supported Languages}, for further details on specific languages.
- @value{GDBN} provides some additional commands for controlling the range checker:
- @kindex set check range
- @kindex show check range
- @table @code
- @item set check range auto
- Set range checking on or off based on the current working language.
- @xref{Supported Languages, ,Supported Languages}, for the default settings for
- each language.
- @item set check range on
- @itemx set check range off
- Set range checking on or off, overriding the default setting for the
- current working language. A warning is issued if the setting does not
- match the language default. If a range error occurs and range checking is on,
- then a message is printed and evaluation of the expression is aborted.
- @item set check range warn
- Output messages when the @value{GDBN} range checker detects a range error,
- but attempt to evaluate the expression anyway. Evaluating the
- expression may still be impossible for other reasons, such as accessing
- memory that the process does not own (a typical example from many Unix
- systems).
- @item show check range
- Show the current setting of the range checker, and whether or not it is
- being set automatically by @value{GDBN}.
- @end table
- @node Supported Languages
- @section Supported Languages
- @value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran,
- OpenCL C, Pascal, Rust, assembly, Modula-2, and Ada.
- @c This is false ...
- Some @value{GDBN} features may be used in expressions regardless of the
- language you use: the @value{GDBN} @code{@@} and @code{::} operators,
- and the @samp{@{type@}addr} construct (@pxref{Expressions,
- ,Expressions}) can be used with the constructs of any supported
- language.
- The following sections detail to what degree each source language is
- supported by @value{GDBN}. These sections are not meant to be language
- tutorials or references, but serve only as a reference guide to what the
- @value{GDBN} expression parser accepts, and what input and output
- formats should look like for different languages. There are many good
- books written on each of these languages; please look to these for a
- language reference or tutorial.
- @menu
- * C:: C and C@t{++}
- * D:: D
- * Go:: Go
- * Objective-C:: Objective-C
- * OpenCL C:: OpenCL C
- * Fortran:: Fortran
- * Pascal:: Pascal
- * Rust:: Rust
- * Modula-2:: Modula-2
- * Ada:: Ada
- @end menu
- @node C
- @subsection C and C@t{++}
- @cindex C and C@t{++}
- @cindex expressions in C or C@t{++}
- Since C and C@t{++} are so closely related, many features of @value{GDBN} apply
- to both languages. Whenever this is the case, we discuss those languages
- together.
- @cindex C@t{++}
- @cindex @code{g++}, @sc{gnu} C@t{++} compiler
- @cindex @sc{gnu} C@t{++}
- The C@t{++} debugging facilities are jointly implemented by the C@t{++}
- compiler and @value{GDBN}. Therefore, to debug your C@t{++} code
- effectively, you must compile your C@t{++} programs with a supported
- C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
- compiler (@code{aCC}).
- @menu
- * C Operators:: C and C@t{++} operators
- * C Constants:: C and C@t{++} constants
- * C Plus Plus Expressions:: C@t{++} expressions
- * C Defaults:: Default settings for C and C@t{++}
- * C Checks:: C and C@t{++} type and range checks
- * Debugging C:: @value{GDBN} and C
- * Debugging C Plus Plus:: @value{GDBN} features for C@t{++}
- * Decimal Floating Point:: Numbers in Decimal Floating Point format
- @end menu
- @node C Operators
- @subsubsection C and C@t{++} Operators
- @cindex C and C@t{++} operators
- Operators must be defined on values of specific types. For instance,
- @code{+} is defined on numbers, but not on structures. Operators are
- often defined on groups of types.
- For the purposes of C and C@t{++}, the following definitions hold:
- @itemize @bullet
- @item
- @emph{Integral types} include @code{int} with any of its storage-class
- specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
- @item
- @emph{Floating-point types} include @code{float}, @code{double}, and
- @code{long double} (if supported by the target platform).
- @item
- @emph{Pointer types} include all types defined as @code{(@var{type} *)}.
- @item
- @emph{Scalar types} include all of the above.
- @end itemize
- @noindent
- The following operators are supported. They are listed here
- in order of increasing precedence:
- @table @code
- @item ,
- The comma or sequencing operator. Expressions in a comma-separated list
- are evaluated from left to right, with the result of the entire
- expression being the last expression evaluated.
- @item =
- Assignment. The value of an assignment expression is the value
- assigned. Defined on scalar types.
- @item @var{op}=
- Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
- and translated to @w{@code{@var{a} = @var{a op b}}}.
- @w{@code{@var{op}=}} and @code{=} have the same precedence. The operator
- @var{op} is any one of the operators @code{|}, @code{^}, @code{&},
- @code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
- @item ?:
- The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
- of as: if @var{a} then @var{b} else @var{c}. The argument @var{a}
- should be of an integral type.
- @item ||
- Logical @sc{or}. Defined on integral types.
- @item &&
- Logical @sc{and}. Defined on integral types.
- @item |
- Bitwise @sc{or}. Defined on integral types.
- @item ^
- Bitwise exclusive-@sc{or}. Defined on integral types.
- @item &
- Bitwise @sc{and}. Defined on integral types.
- @item ==@r{, }!=
- Equality and inequality. Defined on scalar types. The value of these
- expressions is 0 for false and non-zero for true.
- @item <@r{, }>@r{, }<=@r{, }>=
- Less than, greater than, less than or equal, greater than or equal.
- Defined on scalar types. The value of these expressions is 0 for false
- and non-zero for true.
- @item <<@r{, }>>
- left shift, and right shift. Defined on integral types.
- @item @@
- The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
- @item +@r{, }-
- Addition and subtraction. Defined on integral types, floating-point types and
- pointer types.
- @item *@r{, }/@r{, }%
- Multiplication, division, and modulus. Multiplication and division are
- defined on integral and floating-point types. Modulus is defined on
- integral types.
- @item ++@r{, }--
- Increment and decrement. When appearing before a variable, the
- operation is performed before the variable is used in an expression;
- when appearing after it, the variable's value is used before the
- operation takes place.
- @item *
- Pointer dereferencing. Defined on pointer types. Same precedence as
- @code{++}.
- @item &
- Address operator. Defined on variables. Same precedence as @code{++}.
- For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
- allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
- to examine the address
- where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
- stored.
- @item -
- Negative. Defined on integral and floating-point types. Same
- precedence as @code{++}.
- @item !
- Logical negation. Defined on integral types. Same precedence as
- @code{++}.
- @item ~
- Bitwise complement operator. Defined on integral types. Same precedence as
- @code{++}.
- @item .@r{, }->
- Structure member, and pointer-to-structure member. For convenience,
- @value{GDBN} regards the two as equivalent, choosing whether to dereference a
- pointer based on the stored type information.
- Defined on @code{struct} and @code{union} data.
- @item .*@r{, }->*
- Dereferences of pointers to members.
- @item []
- Array indexing. @code{@var{a}[@var{i}]} is defined as
- @code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
- @item ()
- Function parameter list. Same precedence as @code{->}.
- @item ::
- C@t{++} scope resolution operator. Defined on @code{struct}, @code{union},
- and @code{class} types.
- @item ::
- Doubled colons also represent the @value{GDBN} scope operator
- (@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
- above.
- @end table
- If an operator is redefined in the user code, @value{GDBN} usually
- attempts to invoke the redefined version instead of using the operator's
- predefined meaning.
- @node C Constants
- @subsubsection C and C@t{++} Constants
- @cindex C and C@t{++} constants
- @value{GDBN} allows you to express the constants of C and C@t{++} in the
- following ways:
- @itemize @bullet
- @item
- Integer constants are a sequence of digits. Octal constants are
- specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants
- by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
- @samp{l}, specifying that the constant should be treated as a
- @code{long} value.
- @item
- Floating point constants are a sequence of digits, followed by a decimal
- point, followed by a sequence of digits, and optionally followed by an
- exponent. An exponent is of the form:
- @samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
- sequence of digits. The @samp{+} is optional for positive exponents.
- A floating-point constant may also end with a letter @samp{f} or
- @samp{F}, specifying that the constant should be treated as being of
- the @code{float} (as opposed to the default @code{double}) type; or with
- a letter @samp{l} or @samp{L}, which specifies a @code{long double}
- constant.
- @item
- Enumerated constants consist of enumerated identifiers, or their
- integral equivalents.
- @item
- Character constants are a single character surrounded by single quotes
- (@code{'}), or a number---the ordinal value of the corresponding character
- (usually its @sc{ascii} value). Within quotes, the single character may
- be represented by a letter or by @dfn{escape sequences}, which are of
- the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
- of the character's ordinal value; or of the form @samp{\@var{x}}, where
- @samp{@var{x}} is a predefined special character---for example,
- @samp{\n} for newline.
- Wide character constants can be written by prefixing a character
- constant with @samp{L}, as in C. For example, @samp{L'x'} is the wide
- form of @samp{x}. The target wide character set is used when
- computing the value of this constant (@pxref{Character Sets}).
- @item
- String constants are a sequence of character constants surrounded by
- double quotes (@code{"}). Any valid character constant (as described
- above) may appear. Double quotes within the string must be preceded by
- a backslash, so for instance @samp{"a\"b'c"} is a string of five
- characters.
- Wide string constants can be written by prefixing a string constant
- with @samp{L}, as in C. The target wide character set is used when
- computing the value of this constant (@pxref{Character Sets}).
- @item
- Pointer constants are an integral value. You can also write pointers
- to constants using the C operator @samp{&}.
- @item
- Array constants are comma-separated lists surrounded by braces @samp{@{}
- and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
- integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
- and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
- @end itemize
- @node C Plus Plus Expressions
- @subsubsection C@t{++} Expressions
- @cindex expressions in C@t{++}
- @value{GDBN} expression handling can interpret most C@t{++} expressions.
- @cindex debugging C@t{++} programs
- @cindex C@t{++} compilers
- @cindex debug formats and C@t{++}
- @cindex @value{NGCC} and C@t{++}
- @quotation
- @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use
- the proper compiler and the proper debug format. Currently,
- @value{GDBN} works best when debugging C@t{++} code that is compiled
- with the most recent version of @value{NGCC} possible. The DWARF
- debugging format is preferred; @value{NGCC} defaults to this on most
- popular platforms. Other compilers and/or debug formats are likely to
- work badly or not at all when using @value{GDBN} to debug C@t{++}
- code. @xref{Compilation}.
- @end quotation
- @enumerate
- @cindex member functions
- @item
- Member function calls are allowed; you can use expressions like
- @smallexample
- count = aml->GetOriginal(x, y)
- @end smallexample
- @vindex this@r{, inside C@t{++} member functions}
- @cindex namespace in C@t{++}
- @item
- While a member function is active (in the selected stack frame), your
- expressions have the same namespace available as the member function;
- that is, @value{GDBN} allows implicit references to the class instance
- pointer @code{this} following the same rules as C@t{++}. @code{using}
- declarations in the current scope are also respected by @value{GDBN}.
- @cindex call overloaded functions
- @cindex overloaded functions, calling
- @cindex type conversions in C@t{++}
- @item
- You can call overloaded functions; @value{GDBN} resolves the function
- call to the right definition, with some restrictions. @value{GDBN} does not
- perform overload resolution involving user-defined type conversions,
- calls to constructors, or instantiations of templates that do not exist
- in the program. It also cannot handle ellipsis argument lists or
- default arguments.
- It does perform integral conversions and promotions, floating-point
- promotions, arithmetic conversions, pointer conversions, conversions of
- class objects to base classes, and standard conversions such as those of
- functions or arrays to pointers; it requires an exact match on the
- number of function arguments.
- Overload resolution is always performed, unless you have specified
- @code{set overload-resolution off}. @xref{Debugging C Plus Plus,
- ,@value{GDBN} Features for C@t{++}}.
- You must specify @code{set overload-resolution off} in order to use an
- explicit function signature to call an overloaded function, as in
- @smallexample
- p 'foo(char,int)'('x', 13)
- @end smallexample
- The @value{GDBN} command-completion facility can simplify this;
- see @ref{Completion, ,Command Completion}.
- @cindex reference declarations
- @item
- @value{GDBN} understands variables declared as C@t{++} lvalue or rvalue
- references; you can use them in expressions just as you do in C@t{++}
- source---they are automatically dereferenced.
- In the parameter list shown when @value{GDBN} displays a frame, the values of
- reference variables are not displayed (unlike other variables); this
- avoids clutter, since references are often used for large structures.
- The @emph{address} of a reference variable is always shown, unless
- you have specified @samp{set print address off}.
- @item
- @value{GDBN} supports the C@t{++} name resolution operator @code{::}---your
- expressions can use it just as expressions in your program do. Since
- one scope may be defined in another, you can use @code{::} repeatedly if
- necessary, for example in an expression like
- @samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
- resolving name scope by reference to source files, in both C and C@t{++}
- debugging (@pxref{Variables, ,Program Variables}).
- @item
- @value{GDBN} performs argument-dependent lookup, following the C@t{++}
- specification.
- @end enumerate
- @node C Defaults
- @subsubsection C and C@t{++} Defaults
- @cindex C and C@t{++} defaults
- If you allow @value{GDBN} to set range checking automatically, it
- defaults to @code{off} whenever the working language changes to
- C or C@t{++}. This happens regardless of whether you or @value{GDBN}
- selects the working language.
- If you allow @value{GDBN} to set the language automatically, it
- recognizes source files whose names end with @file{.c}, @file{.C}, or
- @file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
- these files, it sets the working language to C or C@t{++}.
- @xref{Automatically, ,Having @value{GDBN} Infer the Source Language},
- for further details.
- @node C Checks
- @subsubsection C and C@t{++} Type and Range Checks
- @cindex C and C@t{++} checks
- By default, when @value{GDBN} parses C or C@t{++} expressions, strict type
- checking is used. However, if you turn type checking off, @value{GDBN}
- will allow certain non-standard conversions, such as promoting integer
- constants to pointers.
- Range checking, if turned on, is done on mathematical operations. Array
- indices are not checked, since they are often used to index a pointer
- that is not itself an array.
- @node Debugging C
- @subsubsection @value{GDBN} and C
- The @code{set print union} and @code{show print union} commands apply to
- the @code{union} type. When set to @samp{on}, any @code{union} that is
- inside a @code{struct} or @code{class} is also printed. Otherwise, it
- appears as @samp{@{...@}}.
- The @code{@@} operator aids in the debugging of dynamic arrays, formed
- with pointers and a memory allocation function. @xref{Expressions,
- ,Expressions}.
- @node Debugging C Plus Plus
- @subsubsection @value{GDBN} Features for C@t{++}
- @cindex commands for C@t{++}
- Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
- designed specifically for use with C@t{++}. Here is a summary:
- @table @code
- @cindex break in overloaded functions
- @item @r{breakpoint menus}
- When you want a breakpoint in a function whose name is overloaded,
- @value{GDBN} has the capability to display a menu of possible breakpoint
- locations to help you specify which function definition you want.
- @xref{Ambiguous Expressions,,Ambiguous Expressions}.
- @cindex overloading in C@t{++}
- @item rbreak @var{regex}
- Setting breakpoints using regular expressions is helpful for setting
- breakpoints on overloaded functions that are not members of any special
- classes.
- @xref{Set Breaks, ,Setting Breakpoints}.
- @cindex C@t{++} exception handling
- @item catch throw
- @itemx catch rethrow
- @itemx catch catch
- Debug C@t{++} exception handling using these commands. @xref{Set
- Catchpoints, , Setting Catchpoints}.
- @cindex inheritance
- @item ptype @var{typename}
- Print inheritance relationships as well as other information for type
- @var{typename}.
- @xref{Symbols, ,Examining the Symbol Table}.
- @item info vtbl @var{expression}.
- The @code{info vtbl} command can be used to display the virtual
- method tables of the object computed by @var{expression}. This shows
- one entry per virtual table; there may be multiple virtual tables when
- multiple inheritance is in use.
- @cindex C@t{++} demangling
- @item demangle @var{name}
- Demangle @var{name}.
- @xref{Symbols}, for a more complete description of the @code{demangle} command.
- @cindex C@t{++} symbol display
- @item set print demangle
- @itemx show print demangle
- @itemx set print asm-demangle
- @itemx show print asm-demangle
- Control whether C@t{++} symbols display in their source form, both when
- displaying code as C@t{++} source and when displaying disassemblies.
- @xref{Print Settings, ,Print Settings}.
- @item set print object
- @itemx show print object
- Choose whether to print derived (actual) or declared types of objects.
- @xref{Print Settings, ,Print Settings}.
- @item set print vtbl
- @itemx show print vtbl
- Control the format for printing virtual function tables.
- @xref{Print Settings, ,Print Settings}.
- (The @code{vtbl} commands do not work on programs compiled with the HP
- ANSI C@t{++} compiler (@code{aCC}).)
- @kindex set overload-resolution
- @cindex overloaded functions, overload resolution
- @item set overload-resolution on
- Enable overload resolution for C@t{++} expression evaluation. The default
- is on. For overloaded functions, @value{GDBN} evaluates the arguments
- and searches for a function whose signature matches the argument types,
- using the standard C@t{++} conversion rules (see @ref{C Plus Plus
- Expressions, ,C@t{++} Expressions}, for details).
- If it cannot find a match, it emits a message.
- @item set overload-resolution off
- Disable overload resolution for C@t{++} expression evaluation. For
- overloaded functions that are not class member functions, @value{GDBN}
- chooses the first function of the specified name that it finds in the
- symbol table, whether or not its arguments are of the correct type. For
- overloaded functions that are class member functions, @value{GDBN}
- searches for a function whose signature @emph{exactly} matches the
- argument types.
- @kindex show overload-resolution
- @item show overload-resolution
- Show the current setting of overload resolution.
- @item @r{Overloaded symbol names}
- You can specify a particular definition of an overloaded symbol, using
- the same notation that is used to declare such symbols in C@t{++}: type
- @code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
- also use the @value{GDBN} command-line word completion facilities to list the
- available choices, or to finish the type list for you.
- @xref{Completion,, Command Completion}, for details on how to do this.
- @item @r{Breakpoints in template functions}
- Similar to how overloaded symbols are handled, @value{GDBN} will ignore
- template parameter lists when it encounters a symbol which includes a
- C@t{++} template. This permits setting breakpoints on families of template functions
- or functions whose parameters include template types.
- The @kbd{-qualified} flag may be used to override this behavior, causing
- @value{GDBN} to search for a specific function or type.
- The @value{GDBN} command-line word completion facility also understands
- template parameters and may be used to list available choices or finish
- template parameter lists for you. @xref{Completion,, Command Completion}, for
- details on how to do this.
- @item @r{Breakpoints in functions with ABI tags}
- The GNU C@t{++} compiler introduced the notion of ABI ``tags'', which
- correspond to changes in the ABI of a type, function, or variable that
- would not otherwise be reflected in a mangled name. See
- @url{https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/}
- for more detail.
- The ABI tags are visible in C@t{++} demangled names. For example, a
- function that returns a std::string:
- @smallexample
- std::string function(int);
- @end smallexample
- @noindent
- when compiled for the C++11 ABI is marked with the @code{cxx11} ABI
- tag, and @value{GDBN} displays the symbol like this:
- @smallexample
- function[abi:cxx11](int)
- @end smallexample
- You can set a breakpoint on such functions simply as if they had no
- tag. For example:
- @smallexample
- (gdb) b function(int)
- Breakpoint 2 at 0x40060d: file main.cc, line 10.
- (gdb) info breakpoints
- Num Type Disp Enb Address What
- 1 breakpoint keep y 0x0040060d in function[abi:cxx11](int)
- at main.cc:10
- @end smallexample
- On the rare occasion you need to disambiguate between different ABI
- tags, you can do so by simply including the ABI tag in the function
- name, like:
- @smallexample
- (@value{GDBP}) b ambiguous[abi:other_tag](int)
- @end smallexample
- @end table
- @node Decimal Floating Point
- @subsubsection Decimal Floating Point format
- @cindex decimal floating point format
- @value{GDBN} can examine, set and perform computations with numbers in
- decimal floating point format, which in the C language correspond to the
- @code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as
- specified by the extension to support decimal floating-point arithmetic.
- There are two encodings in use, depending on the architecture: BID (Binary
- Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
- PowerPC and S/390. @value{GDBN} will use the appropriate encoding for the
- configured target.
- Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
- to manipulate decimal floating point numbers, it is not possible to convert
- (using a cast, for example) integers wider than 32-bit to decimal float.
- In addition, in order to imitate @value{GDBN}'s behaviour with binary floating
- point computations, error checking in decimal float operations ignores
- underflow, overflow and divide by zero exceptions.
- In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers
- to inspect @code{_Decimal128} values stored in floating point registers.
- See @ref{PowerPC,,PowerPC} for more details.
- @node D
- @subsection D
- @cindex D
- @value{GDBN} can be used to debug programs written in D and compiled with
- GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D
- specific feature --- dynamic arrays.
- @node Go
- @subsection Go
- @cindex Go (programming language)
- @value{GDBN} can be used to debug programs written in Go and compiled with
- @file{gccgo} or @file{6g} compilers.
- Here is a summary of the Go-specific features and restrictions:
- @table @code
- @cindex current Go package
- @item The current Go package
- The name of the current package does not need to be specified when
- specifying global variables and functions.
- For example, given the program:
- @example
- package main
- var myglob = "Shall we?"
- func main () @{
- // ...
- @}
- @end example
- When stopped inside @code{main} either of these work:
- @example
- (gdb) p myglob
- (gdb) p main.myglob
- @end example
- @cindex builtin Go types
- @item Builtin Go types
- The @code{string} type is recognized by @value{GDBN} and is printed
- as a string.
- @cindex builtin Go functions
- @item Builtin Go functions
- The @value{GDBN} expression parser recognizes the @code{unsafe.Sizeof}
- function and handles it internally.
- @cindex restrictions on Go expressions
- @item Restrictions on Go expressions
- All Go operators are supported except @code{&^}.
- The Go @code{_} ``blank identifier'' is not supported.
- Automatic dereferencing of pointers is not supported.
- @end table
- @node Objective-C
- @subsection Objective-C
- @cindex Objective-C
- This section provides information about some commands and command
- options that are useful for debugging Objective-C code. See also
- @ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a
- few more commands specific to Objective-C support.
- @menu
- * Method Names in Commands::
- * The Print Command with Objective-C::
- @end menu
- @node Method Names in Commands
- @subsubsection Method Names in Commands
- The following commands have been extended to accept Objective-C method
- names as line specifications:
- @kindex clear@r{, and Objective-C}
- @kindex break@r{, and Objective-C}
- @kindex info line@r{, and Objective-C}
- @kindex jump@r{, and Objective-C}
- @kindex list@r{, and Objective-C}
- @itemize
- @item @code{clear}
- @item @code{break}
- @item @code{info line}
- @item @code{jump}
- @item @code{list}
- @end itemize
- A fully qualified Objective-C method name is specified as
- @smallexample
- -[@var{Class} @var{methodName}]
- @end smallexample
- where the minus sign is used to indicate an instance method and a
- plus sign (not shown) is used to indicate a class method. The class
- name @var{Class} and method name @var{methodName} are enclosed in
- brackets, similar to the way messages are specified in Objective-C
- source code. For example, to set a breakpoint at the @code{create}
- instance method of class @code{Fruit} in the program currently being
- debugged, enter:
- @smallexample
- break -[Fruit create]
- @end smallexample
- To list ten program lines around the @code{initialize} class method,
- enter:
- @smallexample
- list +[NSText initialize]
- @end smallexample
- In the current version of @value{GDBN}, the plus or minus sign is
- required. In future versions of @value{GDBN}, the plus or minus
- sign will be optional, but you can use it to narrow the search. It
- is also possible to specify just a method name:
- @smallexample
- break create
- @end smallexample
- You must specify the complete method name, including any colons. If
- your program's source files contain more than one @code{create} method,
- you'll be presented with a numbered list of classes that implement that
- method. Indicate your choice by number, or type @samp{0} to exit if
- none apply.
- As another example, to clear a breakpoint established at the
- @code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter:
- @smallexample
- clear -[NSWindow makeKeyAndOrderFront:]
- @end smallexample
- @node The Print Command with Objective-C
- @subsubsection The Print Command With Objective-C
- @cindex Objective-C, print objects
- @kindex print-object
- @kindex po @r{(@code{print-object})}
- The print command has also been extended to accept methods. For example:
- @smallexample
- print -[@var{object} hash]
- @end smallexample
- @cindex print an Objective-C object description
- @cindex @code{_NSPrintForDebugger}, and printing Objective-C objects
- @noindent
- will tell @value{GDBN} to send the @code{hash} message to @var{object}
- and print the result. Also, an additional command has been added,
- @code{print-object} or @code{po} for short, which is meant to print
- the description of an object. However, this command may only work
- with certain Objective-C libraries that have a particular hook
- function, @code{_NSPrintForDebugger}, defined.
- @node OpenCL C
- @subsection OpenCL C
- @cindex OpenCL C
- This section provides information about @value{GDBN}s OpenCL C support.
- @menu
- * OpenCL C Datatypes::
- * OpenCL C Expressions::
- * OpenCL C Operators::
- @end menu
- @node OpenCL C Datatypes
- @subsubsection OpenCL C Datatypes
- @cindex OpenCL C Datatypes
- @value{GDBN} supports the builtin scalar and vector datatypes specified
- by OpenCL 1.1. In addition the half- and double-precision floating point
- data types of the @code{cl_khr_fp16} and @code{cl_khr_fp64} OpenCL
- extensions are also known to @value{GDBN}.
- @node OpenCL C Expressions
- @subsubsection OpenCL C Expressions
- @cindex OpenCL C Expressions
- @value{GDBN} supports accesses to vector components including the access as
- lvalue where possible. Since OpenCL C is based on C99 most C expressions
- supported by @value{GDBN} can be used as well.
- @node OpenCL C Operators
- @subsubsection OpenCL C Operators
- @cindex OpenCL C Operators
- @value{GDBN} supports the operators specified by OpenCL 1.1 for scalar and
- vector data types.
- @node Fortran
- @subsection Fortran
- @cindex Fortran-specific support in @value{GDBN}
- @value{GDBN} can be used to debug programs written in Fortran, but it
- currently supports only the features of Fortran 77 language.
- @cindex trailing underscore, in Fortran symbols
- Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
- among them) append an underscore to the names of variables and
- functions. When you debug programs compiled by those compilers, you
- will need to refer to variables and functions with a trailing
- underscore.
- @menu
- * Fortran Operators:: Fortran operators and expressions
- * Fortran Defaults:: Default settings for Fortran
- * Special Fortran Commands:: Special @value{GDBN} commands for Fortran
- @end menu
- @node Fortran Operators
- @subsubsection Fortran Operators and Expressions
- @cindex Fortran operators and expressions
- Operators must be defined on values of specific types. For instance,
- @code{+} is defined on numbers, but not on characters or other non-
- arithmetic types. Operators are often defined on groups of types.
- @table @code
- @item **
- The exponentiation operator. It raises the first operand to the power
- of the second one.
- @item :
- The range operator. Normally used in the form of array(low:high) to
- represent a section of array.
- @item %
- The access component operator. Normally used to access elements in derived
- types. Also suitable for unions. As unions aren't part of regular Fortran,
- this can only happen when accessing a register that uses a gdbarch-defined
- union type.
- @item ::
- The scope operator. Normally used to access variables in modules or
- to set breakpoints on subroutines nested in modules or in other
- subroutines (internal subroutines).
- @end table
- @node Fortran Defaults
- @subsubsection Fortran Defaults
- @cindex Fortran Defaults
- Fortran symbols are usually case-insensitive, so @value{GDBN} by
- default uses case-insensitive matches for Fortran symbols. You can
- change that with the @samp{set case-insensitive} command, see
- @ref{Symbols}, for the details.
- @node Special Fortran Commands
- @subsubsection Special Fortran Commands
- @cindex Special Fortran commands
- @value{GDBN} has some commands to support Fortran-specific features,
- such as displaying common blocks.
- @table @code
- @cindex @code{COMMON} blocks, Fortran
- @kindex info common
- @item info common @r{[}@var{common-name}@r{]}
- This command prints the values contained in the Fortran @code{COMMON}
- block whose name is @var{common-name}. With no argument, the names of
- all @code{COMMON} blocks visible at the current program location are
- printed.
- @cindex arrays slices (Fortran)
- @kindex set fortran repack-array-slices
- @kindex show fortran repack-array-slices
- @item set fortran repack-array-slices [on|off]
- @item show fortran repack-array-slices
- When taking a slice from an array, a Fortran compiler can choose to
- either produce an array descriptor that describes the slice in place,
- or it may repack the slice, copying the elements of the slice into a
- new region of memory.
- When this setting is on, then @value{GDBN} will also repack array
- slices in some situations. When this setting is off, then
- @value{GDBN} will create array descriptors for slices that reference
- the original data in place.
- @value{GDBN} will never repack an array slice if the data for the
- slice is contiguous within the original array.
- @value{GDBN} will always repack string slices if the data for the
- slice is non-contiguous within the original string as @value{GDBN}
- does not support printing non-contiguous strings.
- The default for this setting is @code{off}.
- @end table
- @node Pascal
- @subsection Pascal
- @cindex Pascal support in @value{GDBN}, limitations
- Debugging Pascal programs which use sets, subranges, file variables, or
- nested functions does not currently work. @value{GDBN} does not support
- entering expressions, printing values, or similar features using Pascal
- syntax.
- The Pascal-specific command @code{set print pascal_static-members}
- controls whether static members of Pascal objects are displayed.
- @xref{Print Settings, pascal_static-members}.
- @node Rust
- @subsection Rust
- @value{GDBN} supports the @url{https://www.rust-lang.org/, Rust
- Programming Language}. Type- and value-printing, and expression
- parsing, are reasonably complete. However, there are a few
- peculiarities and holes to be aware of.
- @itemize @bullet
- @item
- Linespecs (@pxref{Specify Location}) are never relative to the current
- crate. Instead, they act as if there were a global namespace of
- crates, somewhat similar to the way @code{extern crate} behaves.
- That is, if @value{GDBN} is stopped at a breakpoint in a function in
- crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt
- to set a breakpoint in a function named @samp{f} in a crate named
- @samp{B}.
- As a consequence of this approach, linespecs also cannot refer to
- items using @samp{self::} or @samp{super::}.
- @item
- Because @value{GDBN} implements Rust name-lookup semantics in
- expressions, it will sometimes prepend the current crate to a name.
- For example, if @value{GDBN} is stopped at a breakpoint in the crate
- @samp{K}, then @code{print ::x::y} will try to find the symbol
- @samp{K::x::y}.
- However, since it is useful to be able to refer to other crates when
- debugging, @value{GDBN} provides the @code{extern} extension to
- circumvent this. To use the extension, just put @code{extern} before
- a path expression to refer to the otherwise unavailable ``global''
- scope.
- In the above example, if you wanted to refer to the symbol @samp{y} in
- the crate @samp{x}, you would use @code{print extern x::y}.
- @item
- The Rust expression evaluator does not support ``statement-like''
- expressions such as @code{if} or @code{match}, or lambda expressions.
- @item
- Tuple expressions are not implemented.
- @item
- The Rust expression evaluator does not currently implement the
- @code{Drop} trait. Objects that may be created by the evaluator will
- never be destroyed.
- @item
- @value{GDBN} does not implement type inference for generics. In order
- to call generic functions or otherwise refer to generic items, you
- will have to specify the type parameters manually.
- @item
- @value{GDBN} currently uses the C@t{++} demangler for Rust. In most
- cases this does not cause any problems. However, in an expression
- context, completing a generic function name will give syntactically
- invalid results. This happens because Rust requires the @samp{::}
- operator between the function name and its generic arguments. For
- example, @value{GDBN} might provide a completion like
- @code{crate::f<u32>}, where the parser would require
- @code{crate::f::<u32>}.
- @item
- As of this writing, the Rust compiler (version 1.8) has a few holes in
- the debugging information it generates. These holes prevent certain
- features from being implemented by @value{GDBN}:
- @itemize @bullet
- @item
- Method calls cannot be made via traits.
- @item
- Operator overloading is not implemented.
- @item
- When debugging in a monomorphized function, you cannot use the generic
- type names.
- @item
- The type @code{Self} is not available.
- @item
- @code{use} statements are not available, so some names may not be
- available in the crate.
- @end itemize
- @end itemize
- @node Modula-2
- @subsection Modula-2
- @cindex Modula-2, @value{GDBN} support
- The extensions made to @value{GDBN} to support Modula-2 only support
- output from the @sc{gnu} Modula-2 compiler (which is currently being
- developed). Other Modula-2 compilers are not currently supported, and
- attempting to debug executables produced by them is most likely
- to give an error as @value{GDBN} reads in the executable's symbol
- table.
- @cindex expressions in Modula-2
- @menu
- * M2 Operators:: Built-in operators
- * Built-In Func/Proc:: Built-in functions and procedures
- * M2 Constants:: Modula-2 constants
- * M2 Types:: Modula-2 types
- * M2 Defaults:: Default settings for Modula-2
- * Deviations:: Deviations from standard Modula-2
- * M2 Checks:: Modula-2 type and range checks
- * M2 Scope:: The scope operators @code{::} and @code{.}
- * GDB/M2:: @value{GDBN} and Modula-2
- @end menu
- @node M2 Operators
- @subsubsection Operators
- @cindex Modula-2 operators
- Operators must be defined on values of specific types. For instance,
- @code{+} is defined on numbers, but not on structures. Operators are
- often defined on groups of types. For the purposes of Modula-2, the
- following definitions hold:
- @itemize @bullet
- @item
- @emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
- their subranges.
- @item
- @emph{Character types} consist of @code{CHAR} and its subranges.
- @item
- @emph{Floating-point types} consist of @code{REAL}.
- @item
- @emph{Pointer types} consist of anything declared as @code{POINTER TO
- @var{type}}.
- @item
- @emph{Scalar types} consist of all of the above.
- @item
- @emph{Set types} consist of @code{SET} and @code{BITSET} types.
- @item
- @emph{Boolean types} consist of @code{BOOLEAN}.
- @end itemize
- @noindent
- The following operators are supported, and appear in order of
- increasing precedence:
- @table @code
- @item ,
- Function argument or array index separator.
- @item :=
- Assignment. The value of @var{var} @code{:=} @var{value} is
- @var{value}.
- @item <@r{, }>
- Less than, greater than on integral, floating-point, or enumerated
- types.
- @item <=@r{, }>=
- Less than or equal to, greater than or equal to
- on integral, floating-point and enumerated types, or set inclusion on
- set types. Same precedence as @code{<}.
- @item =@r{, }<>@r{, }#
- Equality and two ways of expressing inequality, valid on scalar types.
- Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
- available for inequality, since @code{#} conflicts with the script
- comment character.
- @item IN
- Set membership. Defined on set types and the types of their members.
- Same precedence as @code{<}.
- @item OR
- Boolean disjunction. Defined on boolean types.
- @item AND@r{, }&
- Boolean conjunction. Defined on boolean types.
- @item @@
- The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
- @item +@r{, }-
- Addition and subtraction on integral and floating-point types, or union
- and difference on set types.
- @item *
- Multiplication on integral and floating-point types, or set intersection
- on set types.
- @item /
- Division on floating-point types, or symmetric set difference on set
- types. Same precedence as @code{*}.
- @item DIV@r{, }MOD
- Integer division and remainder. Defined on integral types. Same
- precedence as @code{*}.
- @item -
- Negative. Defined on @code{INTEGER} and @code{REAL} data.
- @item ^
- Pointer dereferencing. Defined on pointer types.
- @item NOT
- Boolean negation. Defined on boolean types. Same precedence as
- @code{^}.
- @item .
- @code{RECORD} field selector. Defined on @code{RECORD} data. Same
- precedence as @code{^}.
- @item []
- Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
- @item ()
- Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
- as @code{^}.
- @item ::@r{, }.
- @value{GDBN} and Modula-2 scope operators.
- @end table
- @quotation
- @emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN}
- treats the use of the operator @code{IN}, or the use of operators
- @code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
- @code{<=}, and @code{>=} on sets as an error.
- @end quotation
- @node Built-In Func/Proc
- @subsubsection Built-in Functions and Procedures
- @cindex Modula-2 built-ins
- Modula-2 also makes available several built-in procedures and functions.
- In describing these, the following metavariables are used:
- @table @var
- @item a
- represents an @code{ARRAY} variable.
- @item c
- represents a @code{CHAR} constant or variable.
- @item i
- represents a variable or constant of integral type.
- @item m
- represents an identifier that belongs to a set. Generally used in the
- same function with the metavariable @var{s}. The type of @var{s} should
- be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
- @item n
- represents a variable or constant of integral or floating-point type.
- @item r
- represents a variable or constant of floating-point type.
- @item t
- represents a type.
- @item v
- represents a variable.
- @item x
- represents a variable or constant of one of many types. See the
- explanation of the function for details.
- @end table
- All Modula-2 built-in procedures also return a result, described below.
- @table @code
- @item ABS(@var{n})
- Returns the absolute value of @var{n}.
- @item CAP(@var{c})
- If @var{c} is a lower case letter, it returns its upper case
- equivalent, otherwise it returns its argument.
- @item CHR(@var{i})
- Returns the character whose ordinal value is @var{i}.
- @item DEC(@var{v})
- Decrements the value in the variable @var{v} by one. Returns the new value.
- @item DEC(@var{v},@var{i})
- Decrements the value in the variable @var{v} by @var{i}. Returns the
- new value.
- @item EXCL(@var{m},@var{s})
- Removes the element @var{m} from the set @var{s}. Returns the new
- set.
- @item FLOAT(@var{i})
- Returns the floating point equivalent of the integer @var{i}.
- @item HIGH(@var{a})
- Returns the index of the last member of @var{a}.
- @item INC(@var{v})
- Increments the value in the variable @var{v} by one. Returns the new value.
- @item INC(@var{v},@var{i})
- Increments the value in the variable @var{v} by @var{i}. Returns the
- new value.
- @item INCL(@var{m},@var{s})
- Adds the element @var{m} to the set @var{s} if it is not already
- there. Returns the new set.
- @item MAX(@var{t})
- Returns the maximum value of the type @var{t}.
- @item MIN(@var{t})
- Returns the minimum value of the type @var{t}.
- @item ODD(@var{i})
- Returns boolean TRUE if @var{i} is an odd number.
- @item ORD(@var{x})
- Returns the ordinal value of its argument. For example, the ordinal
- value of a character is its @sc{ascii} value (on machines supporting
- the @sc{ascii} character set). The argument @var{x} must be of an
- ordered type, which include integral, character and enumerated types.
- @item SIZE(@var{x})
- Returns the size of its argument. The argument @var{x} can be a
- variable or a type.
- @item TRUNC(@var{r})
- Returns the integral part of @var{r}.
- @item TSIZE(@var{x})
- Returns the size of its argument. The argument @var{x} can be a
- variable or a type.
- @item VAL(@var{t},@var{i})
- Returns the member of the type @var{t} whose ordinal value is @var{i}.
- @end table
- @quotation
- @emph{Warning:} Sets and their operations are not yet supported, so
- @value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
- an error.
- @end quotation
- @cindex Modula-2 constants
- @node M2 Constants
- @subsubsection Constants
- @value{GDBN} allows you to express the constants of Modula-2 in the following
- ways:
- @itemize @bullet
- @item
- Integer constants are simply a sequence of digits. When used in an
- expression, a constant is interpreted to be type-compatible with the
- rest of the expression. Hexadecimal integers are specified by a
- trailing @samp{H}, and octal integers by a trailing @samp{B}.
- @item
- Floating point constants appear as a sequence of digits, followed by a
- decimal point and another sequence of digits. An optional exponent can
- then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
- @samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
- digits of the floating point constant must be valid decimal (base 10)
- digits.
- @item
- Character constants consist of a single character enclosed by a pair of
- like quotes, either single (@code{'}) or double (@code{"}). They may
- also be expressed by their ordinal value (their @sc{ascii} value, usually)
- followed by a @samp{C}.
- @item
- String constants consist of a sequence of characters enclosed by a
- pair of like quotes, either single (@code{'}) or double (@code{"}).
- Escape sequences in the style of C are also allowed. @xref{C
- Constants, ,C and C@t{++} Constants}, for a brief explanation of escape
- sequences.
- @item
- Enumerated constants consist of an enumerated identifier.
- @item
- Boolean constants consist of the identifiers @code{TRUE} and
- @code{FALSE}.
- @item
- Pointer constants consist of integral values only.
- @item
- Set constants are not yet supported.
- @end itemize
- @node M2 Types
- @subsubsection Modula-2 Types
- @cindex Modula-2 types
- Currently @value{GDBN} can print the following data types in Modula-2
- syntax: array types, record types, set types, pointer types, procedure
- types, enumerated types, subrange types and base types. You can also
- print the contents of variables declared using these type.
- This section gives a number of simple source code examples together with
- sample @value{GDBN} sessions.
- The first example contains the following section of code:
- @smallexample
- VAR
- s: SET OF CHAR ;
- r: [20..40] ;
- @end smallexample
- @noindent
- and you can request @value{GDBN} to interrogate the type and value of
- @code{r} and @code{s}.
- @smallexample
- (@value{GDBP}) print s
- @{'A'..'C', 'Z'@}
- (@value{GDBP}) ptype s
- SET OF CHAR
- (@value{GDBP}) print r
- 21
- (@value{GDBP}) ptype r
- [20..40]
- @end smallexample
- @noindent
- Likewise if your source code declares @code{s} as:
- @smallexample
- VAR
- s: SET ['A'..'Z'] ;
- @end smallexample
- @noindent
- then you may query the type of @code{s} by:
- @smallexample
- (@value{GDBP}) ptype s
- type = SET ['A'..'Z']
- @end smallexample
- @noindent
- Note that at present you cannot interactively manipulate set
- expressions using the debugger.
- The following example shows how you might declare an array in Modula-2
- and how you can interact with @value{GDBN} to print its type and contents:
- @smallexample
- VAR
- s: ARRAY [-10..10] OF CHAR ;
- @end smallexample
- @smallexample
- (@value{GDBP}) ptype s
- ARRAY [-10..10] OF CHAR
- @end smallexample
- Note that the array handling is not yet complete and although the type
- is printed correctly, expression handling still assumes that all
- arrays have a lower bound of zero and not @code{-10} as in the example
- above.
- Here are some more type related Modula-2 examples:
- @smallexample
- TYPE
- colour = (blue, red, yellow, green) ;
- t = [blue..yellow] ;
- VAR
- s: t ;
- BEGIN
- s := blue ;
- @end smallexample
- @noindent
- The @value{GDBN} interaction shows how you can query the data type
- and value of a variable.
- @smallexample
- (@value{GDBP}) print s
- $1 = blue
- (@value{GDBP}) ptype t
- type = [blue..yellow]
- @end smallexample
- @noindent
- In this example a Modula-2 array is declared and its contents
- displayed. Observe that the contents are written in the same way as
- their @code{C} counterparts.
- @smallexample
- VAR
- s: ARRAY [1..5] OF CARDINAL ;
- BEGIN
- s[1] := 1 ;
- @end smallexample
- @smallexample
- (@value{GDBP}) print s
- $1 = @{1, 0, 0, 0, 0@}
- (@value{GDBP}) ptype s
- type = ARRAY [1..5] OF CARDINAL
- @end smallexample
- The Modula-2 language interface to @value{GDBN} also understands
- pointer types as shown in this example:
- @smallexample
- VAR
- s: POINTER TO ARRAY [1..5] OF CARDINAL ;
- BEGIN
- NEW(s) ;
- s^[1] := 1 ;
- @end smallexample
- @noindent
- and you can request that @value{GDBN} describes the type of @code{s}.
- @smallexample
- (@value{GDBP}) ptype s
- type = POINTER TO ARRAY [1..5] OF CARDINAL
- @end smallexample
- @value{GDBN} handles compound types as we can see in this example.
- Here we combine array types, record types, pointer types and subrange
- types:
- @smallexample
- TYPE
- foo = RECORD
- f1: CARDINAL ;
- f2: CHAR ;
- f3: myarray ;
- END ;
- myarray = ARRAY myrange OF CARDINAL ;
- myrange = [-2..2] ;
- VAR
- s: POINTER TO ARRAY myrange OF foo ;
- @end smallexample
- @noindent
- and you can ask @value{GDBN} to describe the type of @code{s} as shown
- below.
- @smallexample
- (@value{GDBP}) ptype s
- type = POINTER TO ARRAY [-2..2] OF foo = RECORD
- f1 : CARDINAL;
- f2 : CHAR;
- f3 : ARRAY [-2..2] OF CARDINAL;
- END
- @end smallexample
- @node M2 Defaults
- @subsubsection Modula-2 Defaults
- @cindex Modula-2 defaults
- If type and range checking are set automatically by @value{GDBN}, they
- both default to @code{on} whenever the working language changes to
- Modula-2. This happens regardless of whether you or @value{GDBN}
- selected the working language.
- If you allow @value{GDBN} to set the language automatically, then entering
- code compiled from a file whose name ends with @file{.mod} sets the
- working language to Modula-2. @xref{Automatically, ,Having @value{GDBN}
- Infer the Source Language}, for further details.
- @node Deviations
- @subsubsection Deviations from Standard Modula-2
- @cindex Modula-2, deviations from
- A few changes have been made to make Modula-2 programs easier to debug.
- This is done primarily via loosening its type strictness:
- @itemize @bullet
- @item
- Unlike in standard Modula-2, pointer constants can be formed by
- integers. This allows you to modify pointer variables during
- debugging. (In standard Modula-2, the actual address contained in a
- pointer variable is hidden from you; it can only be modified
- through direct assignment to another pointer variable or expression that
- returned a pointer.)
- @item
- C escape sequences can be used in strings and characters to represent
- non-printable characters. @value{GDBN} prints out strings with these
- escape sequences embedded. Single non-printable characters are
- printed using the @samp{CHR(@var{nnn})} format.
- @item
- The assignment operator (@code{:=}) returns the value of its right-hand
- argument.
- @item
- All built-in procedures both modify @emph{and} return their argument.
- @end itemize
- @node M2 Checks
- @subsubsection Modula-2 Type and Range Checks
- @cindex Modula-2 checks
- @quotation
- @emph{Warning:} in this release, @value{GDBN} does not yet perform type or
- range checking.
- @end quotation
- @c FIXME remove warning when type/range checks added
- @value{GDBN} considers two Modula-2 variables type equivalent if:
- @itemize @bullet
- @item
- They are of types that have been declared equivalent via a @code{TYPE
- @var{t1} = @var{t2}} statement
- @item
- They have been declared on the same line. (Note: This is true of the
- @sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
- @end itemize
- As long as type checking is enabled, any attempt to combine variables
- whose types are not equivalent is an error.
- Range checking is done on all mathematical operations, assignment, array
- index bounds, and all built-in functions and procedures.
- @node M2 Scope
- @subsubsection The Scope Operators @code{::} and @code{.}
- @cindex scope
- @cindex @code{.}, Modula-2 scope operator
- @cindex colon, doubled as scope operator
- @ifinfo
- @vindex colon-colon@r{, in Modula-2}
- @c Info cannot handle :: but TeX can.
- @end ifinfo
- @ifnotinfo
- @vindex ::@r{, in Modula-2}
- @end ifnotinfo
- There are a few subtle differences between the Modula-2 scope operator
- (@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
- similar syntax:
- @smallexample
- @var{module} . @var{id}
- @var{scope} :: @var{id}
- @end smallexample
- @noindent
- where @var{scope} is the name of a module or a procedure,
- @var{module} the name of a module, and @var{id} is any declared
- identifier within your program, except another module.
- Using the @code{::} operator makes @value{GDBN} search the scope
- specified by @var{scope} for the identifier @var{id}. If it is not
- found in the specified scope, then @value{GDBN} searches all scopes
- enclosing the one specified by @var{scope}.
- Using the @code{.} operator makes @value{GDBN} search the current scope for
- the identifier specified by @var{id} that was imported from the
- definition module specified by @var{module}. With this operator, it is
- an error if the identifier @var{id} was not imported from definition
- module @var{module}, or if @var{id} is not an identifier in
- @var{module}.
- @node GDB/M2
- @subsubsection @value{GDBN} and Modula-2
- Some @value{GDBN} commands have little use when debugging Modula-2 programs.
- Five subcommands of @code{set print} and @code{show print} apply
- specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle},
- @samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
- apply to C@t{++}, and the last to the C @code{union} type, which has no direct
- analogue in Modula-2.
- The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
- with any language, is not useful with Modula-2. Its
- intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
- created in Modula-2 as they can in C or C@t{++}. However, because an
- address can be specified by an integral constant, the construct
- @samp{@{@var{type}@}@var{adrexp}} is still useful.
- @cindex @code{#} in Modula-2
- In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
- interpreted as the beginning of a comment. Use @code{<>} instead.
- @node Ada
- @subsection Ada
- @cindex Ada
- The extensions made to @value{GDBN} for Ada only support
- output from the @sc{gnu} Ada (GNAT) compiler.
- Other Ada compilers are not currently supported, and
- attempting to debug executables produced by them is most likely
- to be difficult.
- @cindex expressions in Ada
- @menu
- * Ada Mode Intro:: General remarks on the Ada syntax
- and semantics supported by Ada mode
- in @value{GDBN}.
- * Omissions from Ada:: Restrictions on the Ada expression syntax.
- * Additions to Ada:: Extensions of the Ada expression syntax.
- * Overloading support for Ada:: Support for expressions involving overloaded
- subprograms.
- * Stopping Before Main Program:: Debugging the program during elaboration.
- * Ada Exceptions:: Ada Exceptions
- * Ada Tasks:: Listing and setting breakpoints in tasks.
- * Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
- * Ravenscar Profile:: Tasking Support when using the Ravenscar
- Profile
- * Ada Settings:: New settable GDB parameters for Ada.
- * Ada Source Character Set:: Character set of Ada source files.
- * Ada Glitches:: Known peculiarities of Ada mode.
- @end menu
- @node Ada Mode Intro
- @subsubsection Introduction
- @cindex Ada mode, general
- The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression
- syntax, with some extensions.
- The philosophy behind the design of this subset is
- @itemize @bullet
- @item
- That @value{GDBN} should provide basic literals and access to operations for
- arithmetic, dereferencing, field selection, indexing, and subprogram calls,
- leaving more sophisticated computations to subprograms written into the
- program (which therefore may be called from @value{GDBN}).
- @item
- That type safety and strict adherence to Ada language restrictions
- are not particularly important to the @value{GDBN} user.
- @item
- That brevity is important to the @value{GDBN} user.
- @end itemize
- Thus, for brevity, the debugger acts as if all names declared in
- user-written packages are directly visible, even if they are not visible
- according to Ada rules, thus making it unnecessary to fully qualify most
- names with their packages, regardless of context. Where this causes
- ambiguity, @value{GDBN} asks the user's intent.
- The debugger will start in Ada mode if it detects an Ada main program.
- As for other languages, it will enter Ada mode when stopped in a program that
- was translated from an Ada source file.
- While in Ada mode, you may use `@t{--}' for comments. This is useful
- mostly for documenting command files. The standard @value{GDBN} comment
- (@samp{#}) still works at the beginning of a line in Ada mode, but not in the
- middle (to allow based literals).
- @node Omissions from Ada
- @subsubsection Omissions from Ada
- @cindex Ada, omissions from
- Here are the notable omissions from the subset:
- @itemize @bullet
- @item
- Only a subset of the attributes are supported:
- @itemize @minus
- @item
- @t{'First}, @t{'Last}, and @t{'Length}
- on array objects (not on types and subtypes).
- @item
- @t{'Min} and @t{'Max}.
- @item
- @t{'Pos} and @t{'Val}.
- @item
- @t{'Tag}.
- @item
- @t{'Range} on array objects (not subtypes), but only as the right
- operand of the membership (@code{in}) operator.
- @item
- @t{'Access}, @t{'Unchecked_Access}, and
- @t{'Unrestricted_Access} (a GNAT extension).
- @item
- @t{'Address}.
- @end itemize
- @item
- The names in @code{Characters.Latin_1} are not available.
- @item
- Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
- equality of representations. They will generally work correctly
- for strings and arrays whose elements have integer or enumeration types.
- They may not work correctly for arrays whose element
- types have user-defined equality, for arrays of real values
- (in particular, IEEE-conformant floating point, because of negative
- zeroes and NaNs), and for arrays whose elements contain unused bits with
- indeterminate values.
- @item
- The other component-by-component array operations (@code{and}, @code{or},
- @code{xor}, @code{not}, and relational tests other than equality)
- are not implemented.
- @item
- @cindex array aggregates (Ada)
- @cindex record aggregates (Ada)
- @cindex aggregates (Ada)
- There is limited support for array and record aggregates. They are
- permitted only on the right sides of assignments, as in these examples:
- @smallexample
- (@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6)
- (@value{GDBP}) set An_Array := (1, others => 0)
- (@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
- (@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
- (@value{GDBP}) set A_Record := (1, "Peter", True);
- (@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True)
- @end smallexample
- Changing a
- discriminant's value by assigning an aggregate has an
- undefined effect if that discriminant is used within the record.
- However, you can first modify discriminants by directly assigning to
- them (which normally would not be allowed in Ada), and then performing an
- aggregate assignment. For example, given a variable @code{A_Rec}
- declared to have a type such as:
- @smallexample
- type Rec (Len : Small_Integer := 0) is record
- Id : Integer;
- Vals : IntArray (1 .. Len);
- end record;
- @end smallexample
- you can assign a value with a different size of @code{Vals} with two
- assignments:
- @smallexample
- (@value{GDBP}) set A_Rec.Len := 4
- (@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
- @end smallexample
- As this example also illustrates, @value{GDBN} is very loose about the usual
- rules concerning aggregates. You may leave out some of the
- components of an array or record aggregate (such as the @code{Len}
- component in the assignment to @code{A_Rec} above); they will retain their
- original values upon assignment. You may freely use dynamic values as
- indices in component associations. You may even use overlapping or
- redundant component associations, although which component values are
- assigned in such cases is not defined.
- @item
- Calls to dispatching subprograms are not implemented.
- @item
- The overloading algorithm is much more limited (i.e., less selective)
- than that of real Ada. It makes only limited use of the context in
- which a subexpression appears to resolve its meaning, and it is much
- looser in its rules for allowing type matches. As a result, some
- function calls will be ambiguous, and the user will be asked to choose
- the proper resolution.
- @item
- The @code{new} operator is not implemented.
- @item
- Entry calls are not implemented.
- @item
- Aside from printing, arithmetic operations on the native VAX floating-point
- formats are not supported.
- @item
- It is not possible to slice a packed array.
- @item
- The names @code{True} and @code{False}, when not part of a qualified name,
- are interpreted as if implicitly prefixed by @code{Standard}, regardless of
- context.
- Should your program
- redefine these names in a package or procedure (at best a dubious practice),
- you will have to use fully qualified names to access their new definitions.
- @item
- Based real literals are not implemented.
- @end itemize
- @node Additions to Ada
- @subsubsection Additions to Ada
- @cindex Ada, deviations from
- As it does for other languages, @value{GDBN} makes certain generic
- extensions to Ada (@pxref{Expressions}):
- @itemize @bullet
- @item
- If the expression @var{E} is a variable residing in memory (typically
- a local variable or array element) and @var{N} is a positive integer,
- then @code{@var{E}@@@var{N}} displays the values of @var{E} and the
- @var{N}-1 adjacent variables following it in memory as an array. In
- Ada, this operator is generally not necessary, since its prime use is
- in displaying parts of an array, and slicing will usually do this in
- Ada. However, there are occasional uses when debugging programs in
- which certain debugging information has been optimized away.
- @item
- @code{@var{B}::@var{var}} means ``the variable named @var{var} that
- appears in function or file @var{B}.'' When @var{B} is a file name,
- you must typically surround it in single quotes.
- @item
- The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
- @var{type} that appears at address @var{addr}.''
- @item
- A name starting with @samp{$} is a convenience variable
- (@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
- @end itemize
- In addition, @value{GDBN} provides a few other shortcuts and outright
- additions specific to Ada:
- @itemize @bullet
- @item
- The assignment statement is allowed as an expression, returning
- its right-hand operand as its value. Thus, you may enter
- @smallexample
- (@value{GDBP}) set x := y + 3
- (@value{GDBP}) print A(tmp := y + 1)
- @end smallexample
- @item
- The semicolon is allowed as an ``operator,'' returning as its value
- the value of its right-hand operand.
- This allows, for example,
- complex conditional breaks:
- @smallexample
- (@value{GDBP}) break f
- (@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100)
- @end smallexample
- @item
- An extension to based literals can be used to specify the exact byte
- contents of a floating-point literal. After the base, you can use
- from zero to two @samp{l} characters, followed by an @samp{f}. The
- number of @samp{l} characters controls the width of the resulting real
- constant: zero means @code{Float} is used, one means
- @code{Long_Float}, and two means @code{Long_Long_Float}.
- @smallexample
- (@value{GDBP}) print 16f#41b80000#
- $1 = 23.0
- @end smallexample
- @item
- Rather than use catenation and symbolic character names to introduce special
- characters into strings, one may instead use a special bracket notation,
- which is also used to print strings. A sequence of characters of the form
- @samp{["@var{XX}"]} within a string or character literal denotes the
- (single) character whose numeric encoding is @var{XX} in hexadecimal. The
- sequence of characters @samp{["""]} also denotes a single quotation mark
- in strings. For example,
- @smallexample
- "One line.["0a"]Next line.["0a"]"
- @end smallexample
- @noindent
- contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF})
- after each period.
- @item
- The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
- @t{'Max} is optional (and is ignored in any case). For example, it is valid
- to write
- @smallexample
- (@value{GDBP}) print 'max(x, y)
- @end smallexample
- @item
- When printing arrays, @value{GDBN} uses positional notation when the
- array has a lower bound of 1, and uses a modified named notation otherwise.
- For example, a one-dimensional array of three integers with a lower bound
- of 3 might print as
- @smallexample
- (3 => 10, 17, 1)
- @end smallexample
- @noindent
- That is, in contrast to valid Ada, only the first component has a @code{=>}
- clause.
- @item
- You may abbreviate attributes in expressions with any unique,
- multi-character subsequence of
- their names (an exact match gets preference).
- For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh}
- in place of @t{a'length}.
- @item
- @cindex quoting Ada internal identifiers
- Since Ada is case-insensitive, the debugger normally maps identifiers you type
- to lower case. The GNAT compiler uses upper-case characters for
- some of its internal identifiers, which are normally of no interest to users.
- For the rare occasions when you actually have to look at them,
- enclose them in angle brackets to avoid the lower-case mapping.
- For example,
- @smallexample
- (@value{GDBP}) print <JMPBUF_SAVE>[0]
- @end smallexample
- @item
- Printing an object of class-wide type or dereferencing an
- access-to-class-wide value will display all the components of the object's
- specific type (as indicated by its run-time tag). Likewise, component
- selection on such a value will operate on the specific type of the
- object.
- @end itemize
- @node Overloading support for Ada
- @subsubsection Overloading support for Ada
- @cindex overloading, Ada
- The debugger supports limited overloading. Given a subprogram call in which
- the function symbol has multiple definitions, it will use the number of
- actual parameters and some information about their types to attempt to narrow
- the set of definitions. It also makes very limited use of context, preferring
- procedures to functions in the context of the @code{call} command, and
- functions to procedures elsewhere.
- If, after narrowing, the set of matching definitions still contains more than
- one definition, @value{GDBN} will display a menu to query which one it should
- use, for instance:
- @smallexample
- (@value{GDBP}) print f(1)
- Multiple matches for f
- [0] cancel
- [1] foo.f (integer) return boolean at foo.adb:23
- [2] foo.f (foo.new_integer) return boolean at foo.adb:28
- >
- @end smallexample
- In this case, just select one menu entry either to cancel expression evaluation
- (type @kbd{0} and press @key{RET}) or to continue evaluation with a specific
- instance (type the corresponding number and press @key{RET}).
- Here are a couple of commands to customize @value{GDBN}'s behavior in this
- case:
- @table @code
- @kindex set ada print-signatures
- @item set ada print-signatures
- Control whether parameter types and return types are displayed in overloads
- selection menus. It is @code{on} by default.
- @xref{Overloading support for Ada}.
- @kindex show ada print-signatures
- @item show ada print-signatures
- Show the current setting for displaying parameter types and return types in
- overloads selection menu.
- @xref{Overloading support for Ada}.
- @end table
- @node Stopping Before Main Program
- @subsubsection Stopping at the Very Beginning
- @cindex breakpointing Ada elaboration code
- It is sometimes necessary to debug the program during elaboration, and
- before reaching the main procedure.
- As defined in the Ada Reference
- Manual, the elaboration code is invoked from a procedure called
- @code{adainit}. To run your program up to the beginning of
- elaboration, simply use the following two commands:
- @code{tbreak adainit} and @code{run}.
- @node Ada Exceptions
- @subsubsection Ada Exceptions
- A command is provided to list all Ada exceptions:
- @table @code
- @kindex info exceptions
- @item info exceptions
- @itemx info exceptions @var{regexp}
- The @code{info exceptions} command allows you to list all Ada exceptions
- defined within the program being debugged, as well as their addresses.
- With a regular expression, @var{regexp}, as argument, only those exceptions
- whose names match @var{regexp} are listed.
- @end table
- Below is a small example, showing how the command can be used, first
- without argument, and next with a regular expression passed as an
- argument.
- @smallexample
- (@value{GDBP}) info exceptions
- All defined Ada exceptions:
- constraint_error: 0x613da0
- program_error: 0x613d20
- storage_error: 0x613ce0
- tasking_error: 0x613ca0
- const.aint_global_e: 0x613b00
- (@value{GDBP}) info exceptions const.aint
- All Ada exceptions matching regular expression "const.aint":
- constraint_error: 0x613da0
- const.aint_global_e: 0x613b00
- @end smallexample
- It is also possible to ask @value{GDBN} to stop your program's execution
- when an exception is raised. For more details, see @ref{Set Catchpoints}.
- @node Ada Tasks
- @subsubsection Extensions for Ada Tasks
- @cindex Ada, tasking
- Support for Ada tasks is analogous to that for threads (@pxref{Threads}).
- @value{GDBN} provides the following task-related commands:
- @table @code
- @kindex info tasks
- @item info tasks
- This command shows a list of current Ada tasks, as in the following example:
- @smallexample
- @iftex
- @leftskip=0.5cm
- @end iftex
- (@value{GDBP}) info tasks
- ID TID P-ID Pri State Name
- 1 8088000 0 15 Child Activation Wait main_task
- 2 80a4000 1 15 Accept Statement b
- 3 809a800 1 15 Child Activation Wait a
- * 4 80ae800 3 15 Runnable c
- @end smallexample
- @noindent
- In this listing, the asterisk before the last task indicates it to be the
- task currently being inspected.
- @table @asis
- @item ID
- Represents @value{GDBN}'s internal task number.
- @item TID
- The Ada task ID.
- @item P-ID
- The parent's task ID (@value{GDBN}'s internal task number).
- @item Pri
- The base priority of the task.
- @item State
- Current state of the task.
- @table @code
- @item Unactivated
- The task has been created but has not been activated. It cannot be
- executing.
- @item Runnable
- The task is not blocked for any reason known to Ada. (It may be waiting
- for a mutex, though.) It is conceptually "executing" in normal mode.
- @item Terminated
- The task is terminated, in the sense of ARM 9.3 (5). Any dependents
- that were waiting on terminate alternatives have been awakened and have
- terminated themselves.
- @item Child Activation Wait
- The task is waiting for created tasks to complete activation.
- @item Accept Statement
- The task is waiting on an accept or selective wait statement.
- @item Waiting on entry call
- The task is waiting on an entry call.
- @item Async Select Wait
- The task is waiting to start the abortable part of an asynchronous
- select statement.
- @item Delay Sleep
- The task is waiting on a select statement with only a delay
- alternative open.
- @item Child Termination Wait
- The task is sleeping having completed a master within itself, and is
- waiting for the tasks dependent on that master to become terminated or
- waiting on a terminate Phase.
- @item Wait Child in Term Alt
- The task is sleeping waiting for tasks on terminate alternatives to
- finish terminating.
- @item Accepting RV with @var{taskno}
- The task is accepting a rendez-vous with the task @var{taskno}.
- @end table
- @item Name
- Name of the task in the program.
- @end table
- @kindex info task @var{taskno}
- @item info task @var{taskno}
- This command shows detailed informations on the specified task, as in
- the following example:
- @smallexample
- @iftex
- @leftskip=0.5cm
- @end iftex
- (@value{GDBP}) info tasks
- ID TID P-ID Pri State Name
- 1 8077880 0 15 Child Activation Wait main_task
- * 2 807c468 1 15 Runnable task_1
- (@value{GDBP}) info task 2
- Ada Task: 0x807c468
- Name: "task_1"
- Thread: 0
- LWP: 0x1fac
- Parent: 1 ("main_task")
- Base Priority: 15
- State: Runnable
- @end smallexample
- @item task
- @kindex task@r{ (Ada)}
- @cindex current Ada task ID
- This command prints the ID and name of the current task.
- @smallexample
- @iftex
- @leftskip=0.5cm
- @end iftex
- (@value{GDBP}) info tasks
- ID TID P-ID Pri State Name
- 1 8077870 0 15 Child Activation Wait main_task
- * 2 807c458 1 15 Runnable some_task
- (@value{GDBP}) task
- [Current task is 2 "some_task"]
- @end smallexample
- @item task @var{taskno}
- @cindex Ada task switching
- This command is like the @code{thread @var{thread-id}}
- command (@pxref{Threads}). It switches the context of debugging
- from the current task to the given task.
- @smallexample
- @iftex
- @leftskip=0.5cm
- @end iftex
- (@value{GDBP}) info tasks
- ID TID P-ID Pri State Name
- 1 8077870 0 15 Child Activation Wait main_task
- * 2 807c458 1 15 Runnable some_task
- (@value{GDBP}) task 1
- [Switching to task 1 "main_task"]
- #0 0x8067726 in pthread_cond_wait ()
- (@value{GDBP}) bt
- #0 0x8067726 in pthread_cond_wait ()
- #1 0x8056714 in system.os_interface.pthread_cond_wait ()
- #2 0x805cb63 in system.task_primitives.operations.sleep ()
- #3 0x806153e in system.tasking.stages.activate_tasks ()
- #4 0x804aacc in un () at un.adb:5
- @end smallexample
- @item task apply [@var{task-id-list} | all] [@var{flag}]@dots{} @var{command}
- The @code{task apply} command is the Ada tasking analogue of
- @code{thread apply} (@pxref{Threads}). It allows you to apply the
- named @var{command} to one or more tasks. Specify the tasks that you
- want affected using a list of task IDs, or specify @code{all} to apply
- to all tasks.
- The @var{flag} arguments control what output to produce and how to
- handle errors raised when applying @var{command} to a task.
- @var{flag} must start with a @code{-} directly followed by one letter
- in @code{qcs}. If several flags are provided, they must be given
- individually, such as @code{-c -q}.
- By default, @value{GDBN} displays some task information before the
- output produced by @var{command}, and an error raised during the
- execution of a @var{command} will abort @code{task apply}. The
- following flags can be used to fine-tune this behavior:
- @table @code
- @item -c
- The flag @code{-c}, which stands for @samp{continue}, causes any
- errors in @var{command} to be displayed, and the execution of
- @code{task apply} then continues.
- @item -s
- The flag @code{-s}, which stands for @samp{silent}, causes any errors
- or empty output produced by a @var{command} to be silently ignored.
- That is, the execution continues, but the task information and errors
- are not printed.
- @item -q
- The flag @code{-q} (@samp{quiet}) disables printing the task
- information.
- @end table
- Flags @code{-c} and @code{-s} cannot be used together.
- @item break @var{location} task @var{taskno}
- @itemx break @var{location} task @var{taskno} if @dots{}
- @cindex breakpoints and tasks, in Ada
- @cindex task breakpoints, in Ada
- @kindex break @dots{} task @var{taskno}@r{ (Ada)}
- These commands are like the @code{break @dots{} thread @dots{}}
- command (@pxref{Thread Stops}). The
- @var{location} argument specifies source lines, as described
- in @ref{Specify Location}.
- Use the qualifier @samp{task @var{taskno}} with a breakpoint command
- to specify that you only want @value{GDBN} to stop the program when a
- particular Ada task reaches this breakpoint. The @var{taskno} is one of the
- numeric task identifiers assigned by @value{GDBN}, shown in the first
- column of the @samp{info tasks} display.
- If you do not specify @samp{task @var{taskno}} when you set a
- breakpoint, the breakpoint applies to @emph{all} tasks of your
- program.
- You can use the @code{task} qualifier on conditional breakpoints as
- well; in this case, place @samp{task @var{taskno}} before the
- breakpoint condition (before the @code{if}).
- For example,
- @smallexample
- @iftex
- @leftskip=0.5cm
- @end iftex
- (@value{GDBP}) info tasks
- ID TID P-ID Pri State Name
- 1 140022020 0 15 Child Activation Wait main_task
- 2 140045060 1 15 Accept/Select Wait t2
- 3 140044840 1 15 Runnable t1
- * 4 140056040 1 15 Runnable t3
- (@value{GDBP}) b 15 task 2
- Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
- (@value{GDBP}) cont
- Continuing.
- task # 1 running
- task # 2 running
- Breakpoint 5, test_task_debug () at test_task_debug.adb:15
- 15 flush;
- (@value{GDBP}) info tasks
- ID TID P-ID Pri State Name
- 1 140022020 0 15 Child Activation Wait main_task
- * 2 140045060 1 15 Runnable t2
- 3 140044840 1 15 Runnable t1
- 4 140056040 1 15 Delay Sleep t3
- @end smallexample
- @end table
- @node Ada Tasks and Core Files
- @subsubsection Tasking Support when Debugging Core Files
- @cindex Ada tasking and core file debugging
- When inspecting a core file, as opposed to debugging a live program,
- tasking support may be limited or even unavailable, depending on
- the platform being used.
- For instance, on x86-linux, the list of tasks is available, but task
- switching is not supported.
- On certain platforms, the debugger needs to perform some
- memory writes in order to provide Ada tasking support. When inspecting
- a core file, this means that the core file must be opened with read-write
- privileges, using the command @samp{"set write on"} (@pxref{Patching}).
- Under these circumstances, you should make a backup copy of the core
- file before inspecting it with @value{GDBN}.
- @node Ravenscar Profile
- @subsubsection Tasking Support when using the Ravenscar Profile
- @cindex Ravenscar Profile
- The @dfn{Ravenscar Profile} is a subset of the Ada tasking features,
- specifically designed for systems with safety-critical real-time
- requirements.
- @table @code
- @kindex set ravenscar task-switching on
- @cindex task switching with program using Ravenscar Profile
- @item set ravenscar task-switching on
- Allows task switching when debugging a program that uses the Ravenscar
- Profile. This is the default.
- @kindex set ravenscar task-switching off
- @item set ravenscar task-switching off
- Turn off task switching when debugging a program that uses the Ravenscar
- Profile. This is mostly intended to disable the code that adds support
- for the Ravenscar Profile, in case a bug in either @value{GDBN} or in
- the Ravenscar runtime is preventing @value{GDBN} from working properly.
- To be effective, this command should be run before the program is started.
- @kindex show ravenscar task-switching
- @item show ravenscar task-switching
- Show whether it is possible to switch from task to task in a program
- using the Ravenscar Profile.
- @end table
- @cindex Ravenscar thread
- When Ravenscar task-switching is enabled, Ravenscar tasks are
- announced by @value{GDBN} as if they were threads:
- @smallexample
- (gdb) continue
- [New Ravenscar Thread 0x2b8f0]
- @end smallexample
- Both Ravenscar tasks and the underlying CPU threads will show up in
- the output of @code{info threads}:
- @smallexample
- (gdb) info threads
- Id Target Id Frame
- 1 Thread 1 (CPU#0 [running]) simple () at simple.adb:10
- 2 Thread 2 (CPU#1 [running]) 0x0000000000003d34 in __gnat_initialize_cpu_devices ()
- 3 Thread 3 (CPU#2 [running]) 0x0000000000003d28 in __gnat_initialize_cpu_devices ()
- 4 Thread 4 (CPU#3 [halted ]) 0x000000000000c6ec in system.task_primitives.operations.idle ()
- * 5 Ravenscar Thread 0x2b8f0 simple () at simple.adb:10
- 6 Ravenscar Thread 0x2f150 0x000000000000c6ec in system.task_primitives.operations.idle ()
- @end smallexample
- One known limitation of the Ravenscar support in @value{GDBN} is that
- it isn't currently possible to single-step through the runtime
- initialization sequence. If you need to debug this code, you should
- use @code{set ravenscar task-switching off}.
- @node Ada Settings
- @subsubsection Ada Settings
- @cindex Ada settings
- @table @code
- @kindex set varsize-limit
- @item set varsize-limit @var{size}
- Prevent @value{GDBN} from attempting to evaluate objects whose size
- is above the given limit (@var{size}) when those sizes are computed
- from run-time quantities. This is typically the case when the object
- has a variable size, such as an array whose bounds are not known at
- compile time for example. Setting @var{size} to @code{unlimited}
- removes the size limitation. By default, the limit is about 65KB.
- The purpose of having such a limit is to prevent @value{GDBN} from
- trying to grab enormous chunks of virtual memory when asked to evaluate
- a quantity whose bounds have been corrupted or have not yet been fully
- initialized. The limit applies to the results of some subexpressions
- as well as to complete expressions. For example, an expression denoting
- a simple integer component, such as @code{x.y.z}, may fail if the size of
- @code{x.y} is variable and exceeds @code{size}. On the other hand,
- @value{GDBN} is sometimes clever; the expression @code{A(i)}, where
- @code{A} is an array variable with non-constant size, will generally
- succeed regardless of the bounds on @code{A}, as long as the component
- size is less than @var{size}.
- @kindex show varsize-limit
- @item show varsize-limit
- Show the limit on types whose size is determined by run-time quantities.
- @end table
- @node Ada Source Character Set
- @subsubsection Ada Source Character Set
- @cindex Ada, source character set
- The GNAT compiler supports a number of character sets for source
- files. @xref{Character Set Control, , Character Set Control,
- gnat_ugn}. @value{GDBN} includes support for this as well.
- @table @code
- @item set ada source-charset @var{charset}
- @kindex set ada source-charset
- Set the source character set for Ada. The character set must be
- supported by GNAT. Because this setting affects the decoding of
- symbols coming from the debug information in your program, the setting
- should be set as early as possible. The default is @code{ISO-8859-1},
- because that is also GNAT's default.
- @item show ada source-charset
- @kindex show ada source-charset
- Show the current source character set for Ada.
- @end table
- @node Ada Glitches
- @subsubsection Known Peculiarities of Ada Mode
- @cindex Ada, problems
- Besides the omissions listed previously (@pxref{Omissions from Ada}),
- we know of several problems with and limitations of Ada mode in
- @value{GDBN},
- some of which will be fixed with planned future releases of the debugger
- and the GNU Ada compiler.
- @itemize @bullet
- @item
- Static constants that the compiler chooses not to materialize as objects in
- storage are invisible to the debugger.
- @item
- Named parameter associations in function argument lists are ignored (the
- argument lists are treated as positional).
- @item
- Many useful library packages are currently invisible to the debugger.
- @item
- Fixed-point arithmetic, conversions, input, and output is carried out using
- floating-point arithmetic, and may give results that only approximate those on
- the host machine.
- @item
- The GNAT compiler never generates the prefix @code{Standard} for any of
- the standard symbols defined by the Ada language. @value{GDBN} knows about
- this: it will strip the prefix from names when you use it, and will never
- look for a name you have so qualified among local symbols, nor match against
- symbols in other packages or subprograms. If you have
- defined entities anywhere in your program other than parameters and
- local variables whose simple names match names in @code{Standard},
- GNAT's lack of qualification here can cause confusion. When this happens,
- you can usually resolve the confusion
- by qualifying the problematic names with package
- @code{Standard} explicitly.
- @end itemize
- Older versions of the compiler sometimes generate erroneous debugging
- information, resulting in the debugger incorrectly printing the value
- of affected entities. In some cases, the debugger is able to work
- around an issue automatically. In other cases, the debugger is able
- to work around the issue, but the work-around has to be specifically
- enabled.
- @kindex set ada trust-PAD-over-XVS
- @kindex show ada trust-PAD-over-XVS
- @table @code
- @item set ada trust-PAD-over-XVS on
- Configure GDB to strictly follow the GNAT encoding when computing the
- value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS}
- types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for
- a complete description of the encoding used by the GNAT compiler).
- This is the default.
- @item set ada trust-PAD-over-XVS off
- This is related to the encoding using by the GNAT compiler. If @value{GDBN}
- sometimes prints the wrong value for certain entities, changing @code{ada
- trust-PAD-over-XVS} to @code{off} activates a work-around which may fix
- the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to
- @code{off}, but this incurs a slight performance penalty, so it is
- recommended to leave this setting to @code{on} unless necessary.
- @end table
- @cindex GNAT descriptive types
- @cindex GNAT encoding
- Internally, the debugger also relies on the compiler following a number
- of conventions known as the @samp{GNAT Encoding}, all documented in
- @file{gcc/ada/exp_dbug.ads} in the GCC sources. This encoding describes
- how the debugging information should be generated for certain types.
- In particular, this convention makes use of @dfn{descriptive types},
- which are artificial types generated purely to help the debugger.
- These encodings were defined at a time when the debugging information
- format used was not powerful enough to describe some of the more complex
- types available in Ada. Since DWARF allows us to express nearly all
- Ada features, the long-term goal is to slowly replace these descriptive
- types by their pure DWARF equivalent. To facilitate that transition,
- a new maintenance option is available to force the debugger to ignore
- those descriptive types. It allows the user to quickly evaluate how
- well @value{GDBN} works without them.
- @table @code
- @kindex maint ada set ignore-descriptive-types
- @item maintenance ada set ignore-descriptive-types [on|off]
- Control whether the debugger should ignore descriptive types.
- The default is not to ignore descriptives types (@code{off}).
- @kindex maint ada show ignore-descriptive-types
- @item maintenance ada show ignore-descriptive-types
- Show if descriptive types are ignored by @value{GDBN}.
- @end table
- @node Unsupported Languages
- @section Unsupported Languages
- @cindex unsupported languages
- @cindex minimal language
- In addition to the other fully-supported programming languages,
- @value{GDBN} also provides a pseudo-language, called @code{minimal}.
- It does not represent a real programming language, but provides a set
- of capabilities close to what the C or assembly languages provide.
- This should allow most simple operations to be performed while debugging
- an application that uses a language currently not supported by @value{GDBN}.
- If the language is set to @code{auto}, @value{GDBN} will automatically
- select this language if the current frame corresponds to an unsupported
- language.
- @node Symbols
- @chapter Examining the Symbol Table
- The commands described in this chapter allow you to inquire about the
- symbols (names of variables, functions and types) defined in your
- program. This information is inherent in the text of your program and
- does not change as your program executes. @value{GDBN} finds it in your
- program's symbol table, in the file indicated when you started @value{GDBN}
- (@pxref{File Options, ,Choosing Files}), or by one of the
- file-management commands (@pxref{Files, ,Commands to Specify Files}).
- @cindex symbol names
- @cindex names of symbols
- @cindex quoting names
- @anchor{quoting names}
- Occasionally, you may need to refer to symbols that contain unusual
- characters, which @value{GDBN} ordinarily treats as word delimiters. The
- most frequent case is in referring to static variables in other
- source files (@pxref{Variables,,Program Variables}). File names
- are recorded in object files as debugging symbols, but @value{GDBN} would
- ordinarily parse a typical file name, like @file{foo.c}, as the three words
- @samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
- @samp{foo.c} as a single symbol, enclose it in single quotes; for example,
- @smallexample
- p 'foo.c'::x
- @end smallexample
- @noindent
- looks up the value of @code{x} in the scope of the file @file{foo.c}.
- @table @code
- @cindex case-insensitive symbol names
- @cindex case sensitivity in symbol names
- @kindex set case-sensitive
- @item set case-sensitive on
- @itemx set case-sensitive off
- @itemx set case-sensitive auto
- Normally, when @value{GDBN} looks up symbols, it matches their names
- with case sensitivity determined by the current source language.
- Occasionally, you may wish to control that. The command @code{set
- case-sensitive} lets you do that by specifying @code{on} for
- case-sensitive matches or @code{off} for case-insensitive ones. If
- you specify @code{auto}, case sensitivity is reset to the default
- suitable for the source language. The default is case-sensitive
- matches for all languages except for Fortran, for which the default is
- case-insensitive matches.
- @kindex show case-sensitive
- @item show case-sensitive
- This command shows the current setting of case sensitivity for symbols
- lookups.
- @kindex set print type methods
- @item set print type methods
- @itemx set print type methods on
- @itemx set print type methods off
- Normally, when @value{GDBN} prints a class, it displays any methods
- declared in that class. You can control this behavior either by
- passing the appropriate flag to @code{ptype}, or using @command{set
- print type methods}. Specifying @code{on} will cause @value{GDBN} to
- display the methods; this is the default. Specifying @code{off} will
- cause @value{GDBN} to omit the methods.
- @kindex show print type methods
- @item show print type methods
- This command shows the current setting of method display when printing
- classes.
- @kindex set print type nested-type-limit
- @item set print type nested-type-limit @var{limit}
- @itemx set print type nested-type-limit unlimited
- Set the limit of displayed nested types that the type printer will
- show. A @var{limit} of @code{unlimited} or @code{-1} will show all
- nested definitions. By default, the type printer will not show any nested
- types defined in classes.
- @kindex show print type nested-type-limit
- @item show print type nested-type-limit
- This command shows the current display limit of nested types when
- printing classes.
- @kindex set print type typedefs
- @item set print type typedefs
- @itemx set print type typedefs on
- @itemx set print type typedefs off
- Normally, when @value{GDBN} prints a class, it displays any typedefs
- defined in that class. You can control this behavior either by
- passing the appropriate flag to @code{ptype}, or using @command{set
- print type typedefs}. Specifying @code{on} will cause @value{GDBN} to
- display the typedef definitions; this is the default. Specifying
- @code{off} will cause @value{GDBN} to omit the typedef definitions.
- Note that this controls whether the typedef definition itself is
- printed, not whether typedef names are substituted when printing other
- types.
- @kindex show print type typedefs
- @item show print type typedefs
- This command shows the current setting of typedef display when
- printing classes.
- @kindex set print type hex
- @item set print type hex
- @itemx set print type hex on
- @itemx set print type hex off
- When @value{GDBN} prints sizes and offsets of struct members, it can use
- either the decimal or hexadecimal notation. You can select one or the
- other either by passing the appropriate flag to @code{ptype}, or by using
- the @command{set print type hex} command.
- @kindex show print type hex
- @item show print type hex
- This command shows whether the sizes and offsets of struct members are
- printed in decimal or hexadecimal notation.
- @kindex info address
- @cindex address of a symbol
- @item info address @var{symbol}
- Describe where the data for @var{symbol} is stored. For a register
- variable, this says which register it is kept in. For a non-register
- local variable, this prints the stack-frame offset at which the variable
- is always stored.
- Note the contrast with @samp{print &@var{symbol}}, which does not work
- at all for a register variable, and for a stack local variable prints
- the exact address of the current instantiation of the variable.
- @kindex info symbol
- @cindex symbol from address
- @cindex closest symbol and offset for an address
- @item info symbol @var{addr}
- Print the name of a symbol which is stored at the address @var{addr}.
- If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
- nearest symbol and an offset from it:
- @smallexample
- (@value{GDBP}) info symbol 0x54320
- _initialize_vx + 396 in section .text
- @end smallexample
- @noindent
- This is the opposite of the @code{info address} command. You can use
- it to find out the name of a variable or a function given its address.
- For dynamically linked executables, the name of executable or shared
- library containing the symbol is also printed:
- @smallexample
- (@value{GDBP}) info symbol 0x400225
- _start + 5 in section .text of /tmp/a.out
- (@value{GDBP}) info symbol 0x2aaaac2811cf
- __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
- @end smallexample
- @kindex demangle
- @cindex demangle
- @item demangle @r{[}-l @var{language}@r{]} @r{[}@var{--}@r{]} @var{name}
- Demangle @var{name}.
- If @var{language} is provided it is the name of the language to demangle
- @var{name} in. Otherwise @var{name} is demangled in the current language.
- The @samp{--} option specifies the end of options,
- and is useful when @var{name} begins with a dash.
- The parameter @code{demangle-style} specifies how to interpret the kind
- of mangling used. @xref{Print Settings}.
- @kindex whatis
- @item whatis[/@var{flags}] [@var{arg}]
- Print the data type of @var{arg}, which can be either an expression
- or a name of a data type. With no argument, print the data type of
- @code{$}, the last value in the value history.
- If @var{arg} is an expression (@pxref{Expressions, ,Expressions}), it
- is not actually evaluated, and any side-effecting operations (such as
- assignments or function calls) inside it do not take place.
- If @var{arg} is a variable or an expression, @code{whatis} prints its
- literal type as it is used in the source code. If the type was
- defined using a @code{typedef}, @code{whatis} will @emph{not} print
- the data type underlying the @code{typedef}. If the type of the
- variable or the expression is a compound data type, such as
- @code{struct} or @code{class}, @code{whatis} never prints their
- fields or methods. It just prints the @code{struct}/@code{class}
- name (a.k.a.@: its @dfn{tag}). If you want to see the members of
- such a compound data type, use @code{ptype}.
- If @var{arg} is a type name that was defined using @code{typedef},
- @code{whatis} @dfn{unrolls} only one level of that @code{typedef}.
- Unrolling means that @code{whatis} will show the underlying type used
- in the @code{typedef} declaration of @var{arg}. However, if that
- underlying type is also a @code{typedef}, @code{whatis} will not
- unroll it.
- For C code, the type names may also have the form @samp{class
- @var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
- @var{union-tag}} or @samp{enum @var{enum-tag}}.
- @var{flags} can be used to modify how the type is displayed.
- Available flags are:
- @table @code
- @item r
- Display in ``raw'' form. Normally, @value{GDBN} substitutes template
- parameters and typedefs defined in a class when printing the class'
- members. The @code{/r} flag disables this.
- @item m
- Do not print methods defined in the class.
- @item M
- Print methods defined in the class. This is the default, but the flag
- exists in case you change the default with @command{set print type methods}.
- @item t
- Do not print typedefs defined in the class. Note that this controls
- whether the typedef definition itself is printed, not whether typedef
- names are substituted when printing other types.
- @item T
- Print typedefs defined in the class. This is the default, but the flag
- exists in case you change the default with @command{set print type typedefs}.
- @item o
- Print the offsets and sizes of fields in a struct, similar to what the
- @command{pahole} tool does. This option implies the @code{/tm} flags.
- @item x
- Use hexadecimal notation when printing offsets and sizes of fields in a
- struct.
- @item d
- Use decimal notation when printing offsets and sizes of fields in a
- struct.
- For example, given the following declarations:
- @smallexample
- struct tuv
- @{
- int a1;
- char *a2;
- int a3;
- @};
- struct xyz
- @{
- int f1;
- char f2;
- void *f3;
- struct tuv f4;
- @};
- union qwe
- @{
- struct tuv fff1;
- struct xyz fff2;
- @};
- struct tyu
- @{
- int a1 : 1;
- int a2 : 3;
- int a3 : 23;
- char a4 : 2;
- int64_t a5;
- int a6 : 5;
- int64_t a7 : 3;
- @};
- @end smallexample
- Issuing a @kbd{ptype /o struct tuv} command would print:
- @smallexample
- (@value{GDBP}) ptype /o struct tuv
- /* offset | size */ type = struct tuv @{
- /* 0 | 4 */ int a1;
- /* XXX 4-byte hole */
- /* 8 | 8 */ char *a2;
- /* 16 | 4 */ int a3;
- /* total size (bytes): 24 */
- @}
- @end smallexample
- Notice the format of the first column of comments. There, you can
- find two parts separated by the @samp{|} character: the @emph{offset},
- which indicates where the field is located inside the struct, in
- bytes, and the @emph{size} of the field. Another interesting line is
- the marker of a @emph{hole} in the struct, indicating that it may be
- possible to pack the struct and make it use less space by reorganizing
- its fields.
- It is also possible to print offsets inside an union:
- @smallexample
- (@value{GDBP}) ptype /o union qwe
- /* offset | size */ type = union qwe @{
- /* 24 */ struct tuv @{
- /* 0 | 4 */ int a1;
- /* XXX 4-byte hole */
- /* 8 | 8 */ char *a2;
- /* 16 | 4 */ int a3;
- /* total size (bytes): 24 */
- @} fff1;
- /* 40 */ struct xyz @{
- /* 0 | 4 */ int f1;
- /* 4 | 1 */ char f2;
- /* XXX 3-byte hole */
- /* 8 | 8 */ void *f3;
- /* 16 | 24 */ struct tuv @{
- /* 16 | 4 */ int a1;
- /* XXX 4-byte hole */
- /* 24 | 8 */ char *a2;
- /* 32 | 4 */ int a3;
- /* total size (bytes): 24 */
- @} f4;
- /* total size (bytes): 40 */
- @} fff2;
- /* total size (bytes): 40 */
- @}
- @end smallexample
- In this case, since @code{struct tuv} and @code{struct xyz} occupy the
- same space (because we are dealing with an union), the offset is not
- printed for them. However, you can still examine the offset of each
- of these structures' fields.
- Another useful scenario is printing the offsets of a struct containing
- bitfields:
- @smallexample
- (@value{GDBP}) ptype /o struct tyu
- /* offset | size */ type = struct tyu @{
- /* 0:31 | 4 */ int a1 : 1;
- /* 0:28 | 4 */ int a2 : 3;
- /* 0: 5 | 4 */ int a3 : 23;
- /* 3: 3 | 1 */ signed char a4 : 2;
- /* XXX 3-bit hole */
- /* XXX 4-byte hole */
- /* 8 | 8 */ int64_t a5;
- /* 16: 0 | 4 */ int a6 : 5;
- /* 16: 5 | 8 */ int64_t a7 : 3;
- /* XXX 7-byte padding */
- /* total size (bytes): 24 */
- @}
- @end smallexample
- Note how the offset information is now extended to also include the
- first bit of the bitfield.
- @end table
- @kindex ptype
- @item ptype[/@var{flags}] [@var{arg}]
- @code{ptype} accepts the same arguments as @code{whatis}, but prints a
- detailed description of the type, instead of just the name of the type.
- @xref{Expressions, ,Expressions}.
- Contrary to @code{whatis}, @code{ptype} always unrolls any
- @code{typedef}s in its argument declaration, whether the argument is
- a variable, expression, or a data type. This means that @code{ptype}
- of a variable or an expression will not print literally its type as
- present in the source code---use @code{whatis} for that. @code{typedef}s at
- the pointer or reference targets are also unrolled. Only @code{typedef}s of
- fields, methods and inner @code{class typedef}s of @code{struct}s,
- @code{class}es and @code{union}s are not unrolled even with @code{ptype}.
- For example, for this variable declaration:
- @smallexample
- typedef double real_t;
- struct complex @{ real_t real; double imag; @};
- typedef struct complex complex_t;
- complex_t var;
- real_t *real_pointer_var;
- @end smallexample
- @noindent
- the two commands give this output:
- @smallexample
- @group
- (@value{GDBP}) whatis var
- type = complex_t
- (@value{GDBP}) ptype var
- type = struct complex @{
- real_t real;
- double imag;
- @}
- (@value{GDBP}) whatis complex_t
- type = struct complex
- (@value{GDBP}) whatis struct complex
- type = struct complex
- (@value{GDBP}) ptype struct complex
- type = struct complex @{
- real_t real;
- double imag;
- @}
- (@value{GDBP}) whatis real_pointer_var
- type = real_t *
- (@value{GDBP}) ptype real_pointer_var
- type = double *
- @end group
- @end smallexample
- @noindent
- As with @code{whatis}, using @code{ptype} without an argument refers to
- the type of @code{$}, the last value in the value history.
- @cindex incomplete type
- Sometimes, programs use opaque data types or incomplete specifications
- of complex data structure. If the debug information included in the
- program does not allow @value{GDBN} to display a full declaration of
- the data type, it will say @samp{<incomplete type>}. For example,
- given these declarations:
- @smallexample
- struct foo;
- struct foo *fooptr;
- @end smallexample
- @noindent
- but no definition for @code{struct foo} itself, @value{GDBN} will say:
- @smallexample
- (@value{GDBP}) ptype foo
- $1 = <incomplete type>
- @end smallexample
- @noindent
- ``Incomplete type'' is C terminology for data types that are not
- completely specified.
- @cindex unknown type
- Othertimes, information about a variable's type is completely absent
- from the debug information included in the program. This most often
- happens when the program or library where the variable is defined
- includes no debug information at all. @value{GDBN} knows the variable
- exists from inspecting the linker/loader symbol table (e.g., the ELF
- dynamic symbol table), but such symbols do not contain type
- information. Inspecting the type of a (global) variable for which
- @value{GDBN} has no type information shows:
- @smallexample
- (@value{GDBP}) ptype var
- type = <data variable, no debug info>
- @end smallexample
- @xref{Variables, no debug info variables}, for how to print the values
- of such variables.
- @kindex info types
- @item info types [-q] [@var{regexp}]
- Print a brief description of all types whose names match the regular
- expression @var{regexp} (or all types in your program, if you supply
- no argument). Each complete typename is matched as though it were a
- complete line; thus, @samp{i type value} gives information on all
- types in your program whose names include the string @code{value}, but
- @samp{i type ^value$} gives information only on types whose complete
- name is @code{value}.
- In programs using different languages, @value{GDBN} chooses the syntax
- to print the type description according to the
- @samp{set language} value: using @samp{set language auto}
- (see @ref{Automatically, ,Set Language Automatically}) means to use the
- language of the type, other values mean to use
- the manually specified language (see @ref{Manually, ,Set Language Manually}).
- This command differs from @code{ptype} in two ways: first, like
- @code{whatis}, it does not print a detailed description; second, it
- lists all source files and line numbers where a type is defined.
- The output from @samp{into types} is proceeded with a header line
- describing what types are being listed. The optional flag @samp{-q},
- which stands for @samp{quiet}, disables printing this header
- information.
- @kindex info type-printers
- @item info type-printers
- Versions of @value{GDBN} that ship with Python scripting enabled may
- have ``type printers'' available. When using @command{ptype} or
- @command{whatis}, these printers are consulted when the name of a type
- is needed. @xref{Type Printing API}, for more information on writing
- type printers.
- @code{info type-printers} displays all the available type printers.
- @kindex enable type-printer
- @kindex disable type-printer
- @item enable type-printer @var{name}@dots{}
- @item disable type-printer @var{name}@dots{}
- These commands can be used to enable or disable type printers.
- @kindex info scope
- @cindex local variables
- @item info scope @var{location}
- List all the variables local to a particular scope. This command
- accepts a @var{location} argument---a function name, a source line, or
- an address preceded by a @samp{*}, and prints all the variables local
- to the scope defined by that location. (@xref{Specify Location}, for
- details about supported forms of @var{location}.) For example:
- @smallexample
- (@value{GDBP}) @b{info scope command_line_handler}
- Scope for command_line_handler:
- Symbol rl is an argument at stack/frame offset 8, length 4.
- Symbol linebuffer is in static storage at address 0x150a18, length 4.
- Symbol linelength is in static storage at address 0x150a1c, length 4.
- Symbol p is a local variable in register $esi, length 4.
- Symbol p1 is a local variable in register $ebx, length 4.
- Symbol nline is a local variable in register $edx, length 4.
- Symbol repeat is a local variable at frame offset -8, length 4.
- @end smallexample
- @noindent
- This command is especially useful for determining what data to collect
- during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
- collect}.
- @kindex info source
- @item info source
- Show information about the current source file---that is, the source file for
- the function containing the current point of execution:
- @itemize @bullet
- @item
- the name of the source file, and the directory containing it,
- @item
- the directory it was compiled in,
- @item
- its length, in lines,
- @item
- which programming language it is written in,
- @item
- if the debug information provides it, the program that compiled the file
- (which may include, e.g., the compiler version and command line arguments),
- @item
- whether the executable includes debugging information for that file, and
- if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
- @item
- whether the debugging information includes information about
- preprocessor macros.
- @end itemize
- @kindex info sources
- @item info sources @r{[}-dirname | -basename@r{]} @r{[}--@r{]} @r{[}@var{regexp}@r{]}
- With no options @samp{info sources} prints the names of all source
- files in your program for which there is debugging information. The
- source files are presented based on a list of object files
- (executables and libraries) currently loaded into @value{GDBN}. For
- each object file all of the associated source files are listed.
- Each source file will only be printed once for each object file, but a
- single source file can be repeated in the output if it is part of
- multiple object files.
- If the optional @var{regexp} is provided, then only source files that
- match the regular expression will be printed. The matching is
- case-sensitive, except on operating systems that have case-insensitive
- filesystem (e.g., MS-Windows). @samp{--} can be used before
- @var{regexp} to prevent @value{GDBN} interpreting @var{regexp} as a
- command option (e.g. if @var{regexp} starts with @samp{-}).
- By default, the @var{regexp} is used to match anywhere in the
- filename. If @code{-dirname}, only files having a dirname matching
- @var{regexp} are shown. If @code{-basename}, only files having a
- basename matching @var{regexp} are shown.
- It is possible that an object file may be printed in the list with no
- associated source files. This can happen when either no source files
- match @var{regexp}, or, the object file was compiled without debug
- information and so @value{GDBN} is unable to find any source file
- names.
- @kindex info functions
- @item info functions [-q] [-n]
- Print the names and data types of all defined functions.
- Similarly to @samp{info types}, this command groups its output by source
- files and annotates each function definition with its source line
- number.
- In programs using different languages, @value{GDBN} chooses the syntax
- to print the function name and type according to the
- @samp{set language} value: using @samp{set language auto}
- (see @ref{Automatically, ,Set Language Automatically}) means to use the
- language of the function, other values mean to use
- the manually specified language (see @ref{Manually, ,Set Language Manually}).
- The @samp{-n} flag excludes @dfn{non-debugging symbols} from the
- results. A non-debugging symbol is a symbol that comes from the
- executable's symbol table, not from the debug information (for
- example, DWARF) associated with the executable.
- The optional flag @samp{-q}, which stands for @samp{quiet}, disables
- printing header information and messages explaining why no functions
- have been printed.
- @item info functions [-q] [-n] [-t @var{type_regexp}] [@var{regexp}]
- Like @samp{info functions}, but only print the names and data types
- of the functions selected with the provided regexp(s).
- If @var{regexp} is provided, print only the functions whose names
- match the regular expression @var{regexp}.
- Thus, @samp{info fun step} finds all functions whose
- names include @code{step}; @samp{info fun ^step} finds those whose names
- start with @code{step}. If a function name contains characters that
- conflict with the regular expression language (e.g.@:
- @samp{operator*()}), they may be quoted with a backslash.
- If @var{type_regexp} is provided, print only the functions whose
- types, as printed by the @code{whatis} command, match
- the regular expression @var{type_regexp}.
- If @var{type_regexp} contains space(s), it should be enclosed in
- quote characters. If needed, use backslash to escape the meaning
- of special characters or quotes.
- Thus, @samp{info fun -t '^int ('} finds the functions that return
- an integer; @samp{info fun -t '(.*int.*'} finds the functions that
- have an argument type containing int; @samp{info fun -t '^int (' ^step}
- finds the functions whose names start with @code{step} and that return
- int.
- If both @var{regexp} and @var{type_regexp} are provided, a function
- is printed only if its name matches @var{regexp} and its type matches
- @var{type_regexp}.
- @kindex info variables
- @item info variables [-q] [-n]
- Print the names and data types of all variables that are defined
- outside of functions (i.e.@: excluding local variables).
- The printed variables are grouped by source files and annotated with
- their respective source line numbers.
- In programs using different languages, @value{GDBN} chooses the syntax
- to print the variable name and type according to the
- @samp{set language} value: using @samp{set language auto}
- (see @ref{Automatically, ,Set Language Automatically}) means to use the
- language of the variable, other values mean to use
- the manually specified language (see @ref{Manually, ,Set Language Manually}).
- The @samp{-n} flag excludes non-debugging symbols from the results.
- The optional flag @samp{-q}, which stands for @samp{quiet}, disables
- printing header information and messages explaining why no variables
- have been printed.
- @item info variables [-q] [-n] [-t @var{type_regexp}] [@var{regexp}]
- Like @kbd{info variables}, but only print the variables selected
- with the provided regexp(s).
- If @var{regexp} is provided, print only the variables whose names
- match the regular expression @var{regexp}.
- If @var{type_regexp} is provided, print only the variables whose
- types, as printed by the @code{whatis} command, match
- the regular expression @var{type_regexp}.
- If @var{type_regexp} contains space(s), it should be enclosed in
- quote characters. If needed, use backslash to escape the meaning
- of special characters or quotes.
- If both @var{regexp} and @var{type_regexp} are provided, an argument
- is printed only if its name matches @var{regexp} and its type matches
- @var{type_regexp}.
- @kindex info modules
- @cindex modules
- @item info modules @r{[}-q@r{]} @r{[}@var{regexp}@r{]}
- List all Fortran modules in the program, or all modules matching the
- optional regular expression @var{regexp}.
- The optional flag @samp{-q}, which stands for @samp{quiet}, disables
- printing header information and messages explaining why no modules
- have been printed.
- @kindex info module
- @cindex Fortran modules, information about
- @cindex functions and variables by Fortran module
- @cindex module functions and variables
- @item info module functions @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]}
- @itemx info module variables @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]}
- List all functions or variables within all Fortran modules. The set
- of functions or variables listed can be limited by providing some or
- all of the optional regular expressions. If @var{module-regexp} is
- provided, then only Fortran modules matching @var{module-regexp} will
- be searched. Only functions or variables whose type matches the
- optional regular expression @var{type-regexp} will be listed. And
- only functions or variables whose name matches the optional regular
- expression @var{regexp} will be listed.
- The optional flag @samp{-q}, which stands for @samp{quiet}, disables
- printing header information and messages explaining why no functions
- or variables have been printed.
- @kindex info classes
- @cindex Objective-C, classes and selectors
- @item info classes
- @itemx info classes @var{regexp}
- Display all Objective-C classes in your program, or
- (with the @var{regexp} argument) all those matching a particular regular
- expression.
- @kindex info selectors
- @item info selectors
- @itemx info selectors @var{regexp}
- Display all Objective-C selectors in your program, or
- (with the @var{regexp} argument) all those matching a particular regular
- expression.
- @ignore
- This was never implemented.
- @kindex info methods
- @item info methods
- @itemx info methods @var{regexp}
- The @code{info methods} command permits the user to examine all defined
- methods within C@t{++} program, or (with the @var{regexp} argument) a
- specific set of methods found in the various C@t{++} classes. Many
- C@t{++} classes provide a large number of methods. Thus, the output
- from the @code{ptype} command can be overwhelming and hard to use. The
- @code{info-methods} command filters the methods, printing only those
- which match the regular-expression @var{regexp}.
- @end ignore
- @cindex opaque data types
- @kindex set opaque-type-resolution
- @item set opaque-type-resolution on
- Tell @value{GDBN} to resolve opaque types. An opaque type is a type
- declared as a pointer to a @code{struct}, @code{class}, or
- @code{union}---for example, @code{struct MyType *}---that is used in one
- source file although the full declaration of @code{struct MyType} is in
- another source file. The default is on.
- A change in the setting of this subcommand will not take effect until
- the next time symbols for a file are loaded.
- @item set opaque-type-resolution off
- Tell @value{GDBN} not to resolve opaque types. In this case, the type
- is printed as follows:
- @smallexample
- @{<no data fields>@}
- @end smallexample
- @kindex show opaque-type-resolution
- @item show opaque-type-resolution
- Show whether opaque types are resolved or not.
- @kindex set print symbol-loading
- @cindex print messages when symbols are loaded
- @item set print symbol-loading
- @itemx set print symbol-loading full
- @itemx set print symbol-loading brief
- @itemx set print symbol-loading off
- The @code{set print symbol-loading} command allows you to control the
- printing of messages when @value{GDBN} loads symbol information.
- By default a message is printed for the executable and one for each
- shared library, and normally this is what you want. However, when
- debugging apps with large numbers of shared libraries these messages
- can be annoying.
- When set to @code{brief} a message is printed for each executable,
- and when @value{GDBN} loads a collection of shared libraries at once
- it will only print one message regardless of the number of shared
- libraries. When set to @code{off} no messages are printed.
- @kindex show print symbol-loading
- @item show print symbol-loading
- Show whether messages will be printed when a @value{GDBN} command
- entered from the keyboard causes symbol information to be loaded.
- @kindex maint print symbols
- @cindex symbol dump
- @kindex maint print psymbols
- @cindex partial symbol dump
- @kindex maint print msymbols
- @cindex minimal symbol dump
- @item maint print symbols @r{[}-pc @var{address}@r{]} @r{[}@var{filename}@r{]}
- @itemx maint print symbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
- @itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-pc @var{address}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
- @itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
- @itemx maint print msymbols @r{[}-objfile @var{objfile}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
- Write a dump of debugging symbol data into the file @var{filename} or
- the terminal if @var{filename} is unspecified.
- If @code{-objfile @var{objfile}} is specified, only dump symbols for
- that objfile.
- If @code{-pc @var{address}} is specified, only dump symbols for the file
- with code at that address. Note that @var{address} may be a symbol like
- @code{main}.
- If @code{-source @var{source}} is specified, only dump symbols for that
- source file.
- These commands are used to debug the @value{GDBN} symbol-reading code.
- These commands do not modify internal @value{GDBN} state, therefore
- @samp{maint print symbols} will only print symbols for already expanded symbol
- tables.
- You can use the command @code{info sources} to find out which files these are.
- If you use @samp{maint print psymbols} instead, the dump shows information
- about symbols that @value{GDBN} only knows partially---that is, symbols
- defined in files that @value{GDBN} has skimmed, but not yet read completely.
- Finally, @samp{maint print msymbols} just dumps ``minimal symbols'', e.g.,
- ``ELF symbols''.
- @xref{Files, ,Commands to Specify Files}, for a discussion of how
- @value{GDBN} reads symbols (in the description of @code{symbol-file}).
- @kindex maint info symtabs
- @kindex maint info psymtabs
- @cindex listing @value{GDBN}'s internal symbol tables
- @cindex symbol tables, listing @value{GDBN}'s internal
- @cindex full symbol tables, listing @value{GDBN}'s internal
- @cindex partial symbol tables, listing @value{GDBN}'s internal
- @item maint info symtabs @r{[} @var{regexp} @r{]}
- @itemx maint info psymtabs @r{[} @var{regexp} @r{]}
- List the @code{struct symtab} or @code{struct partial_symtab}
- structures whose names match @var{regexp}. If @var{regexp} is not
- given, list them all. The output includes expressions which you can
- copy into a @value{GDBN} debugging this one to examine a particular
- structure in more detail. For example:
- @smallexample
- (@value{GDBP}) maint info psymtabs dwarf2read
- @{ objfile /home/gnu/build/gdb/gdb
- ((struct objfile *) 0x82e69d0)
- @{ psymtab /home/gnu/src/gdb/dwarf2read.c
- ((struct partial_symtab *) 0x8474b10)
- readin no
- fullname (null)
- text addresses 0x814d3c8 -- 0x8158074
- globals (* (struct partial_symbol **) 0x8507a08 @@ 9)
- statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882)
- dependencies (none)
- @}
- @}
- (@value{GDBP}) maint info symtabs
- (@value{GDBP})
- @end smallexample
- @noindent
- We see that there is one partial symbol table whose filename contains
- the string @samp{dwarf2read}, belonging to the @samp{gdb} executable;
- and we see that @value{GDBN} has not read in any symtabs yet at all.
- If we set a breakpoint on a function, that will cause @value{GDBN} to
- read the symtab for the compilation unit containing that function:
- @smallexample
- (@value{GDBP}) break dwarf2_psymtab_to_symtab
- Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
- line 1574.
- (@value{GDBP}) maint info symtabs
- @{ objfile /home/gnu/build/gdb/gdb
- ((struct objfile *) 0x82e69d0)
- @{ symtab /home/gnu/src/gdb/dwarf2read.c
- ((struct symtab *) 0x86c1f38)
- dirname (null)
- fullname (null)
- blockvector ((struct blockvector *) 0x86c1bd0) (primary)
- linetable ((struct linetable *) 0x8370fa0)
- debugformat DWARF 2
- @}
- @}
- (@value{GDBP})
- @end smallexample
- @kindex maint info line-table
- @cindex listing @value{GDBN}'s internal line tables
- @cindex line tables, listing @value{GDBN}'s internal
- @item maint info line-table @r{[} @var{regexp} @r{]}
- List the @code{struct linetable} from all @code{struct symtab}
- instances whose name matches @var{regexp}. If @var{regexp} is not
- given, list the @code{struct linetable} from all @code{struct symtab}.
- For example:
- @smallexample
- (@value{GDBP}) maint info line-table
- objfile: /home/gnu/build/a.out ((struct objfile *) 0x6120000e0d40)
- compunit_symtab: simple.cpp ((struct compunit_symtab *) 0x6210000ff450)
- symtab: /home/gnu/src/simple.cpp ((struct symtab *) 0x6210000ff4d0)
- linetable: ((struct linetable *) 0x62100012b760):
- INDEX LINE ADDRESS IS-STMT PROLOGUE-END
- 0 3 0x0000000000401110 Y
- 1 4 0x0000000000401114 Y Y
- 2 9 0x0000000000401120 Y
- 3 10 0x0000000000401124 Y Y
- 4 10 0x0000000000401129
- 5 15 0x0000000000401130 Y
- 6 16 0x0000000000401134 Y Y
- 7 16 0x0000000000401139
- 8 21 0x0000000000401140 Y
- 9 22 0x000000000040114f Y Y
- 10 22 0x0000000000401154
- 11 END 0x000000000040115a Y
- @end smallexample
- @noindent
- The @samp{IS-STMT} column indicates if the address is a recommended breakpoint
- location to represent a line or a statement. The @samp{PROLOGUE-END} column
- indicates that a given address is an adequate place to set a breakpoint at the
- first instruction following a function prologue.
- @kindex maint set symbol-cache-size
- @cindex symbol cache size
- @item maint set symbol-cache-size @var{size}
- Set the size of the symbol cache to @var{size}.
- The default size is intended to be good enough for debugging
- most applications. This option exists to allow for experimenting
- with different sizes.
- @kindex maint show symbol-cache-size
- @item maint show symbol-cache-size
- Show the size of the symbol cache.
- @kindex maint print symbol-cache
- @cindex symbol cache, printing its contents
- @item maint print symbol-cache
- Print the contents of the symbol cache.
- This is useful when debugging symbol cache issues.
- @kindex maint print symbol-cache-statistics
- @cindex symbol cache, printing usage statistics
- @item maint print symbol-cache-statistics
- Print symbol cache usage statistics.
- This helps determine how well the cache is being utilized.
- @kindex maint flush symbol-cache
- @kindex maint flush-symbol-cache
- @cindex symbol cache, flushing
- @item maint flush symbol-cache
- @itemx maint flush-symbol-cache
- Flush the contents of the symbol cache, all entries are removed. This
- command is useful when debugging the symbol cache. It is also useful
- when collecting performance data. The command @code{maint
- flush-symbol-cache} is deprecated in favor of @code{maint flush
- symbol-cache}..
- @kindex maint set ignore-prologue-end-flag
- @cindex prologue-end
- @item maint set ignore-prologue-end-flag [on|off]
- Enable or disable the use of the @samp{PROLOGUE-END} flag from the line-table.
- When @samp{off} (the default), @value{GDBN} uses the @samp{PROLOGUE-END} flag
- to place breakpoints past the end of a function prologue. When @samp{on},
- @value{GDBN} ignores the flag and relies on prologue analyzers to skip function
- prologues.
- @kindex maint show ignore-prologue-end-flag
- @item maint show ignore-prologue-end-flag
- Show whether @value{GDBN} will ignore the @samp{PROLOGUE-END} flag.
- @end table
- @node Altering
- @chapter Altering Execution
- Once you think you have found an error in your program, you might want to
- find out for certain whether correcting the apparent error would lead to
- correct results in the rest of the run. You can find the answer by
- experiment, using the @value{GDBN} features for altering execution of the
- program.
- For example, you can store new values into variables or memory
- locations, give your program a signal, restart it at a different
- address, or even return prematurely from a function.
- @menu
- * Assignment:: Assignment to variables
- * Jumping:: Continuing at a different address
- * Signaling:: Giving your program a signal
- * Returning:: Returning from a function
- * Calling:: Calling your program's functions
- * Patching:: Patching your program
- * Compiling and Injecting Code:: Compiling and injecting code in @value{GDBN}
- @end menu
- @node Assignment
- @section Assignment to Variables
- @cindex assignment
- @cindex setting variables
- To alter the value of a variable, evaluate an assignment expression.
- @xref{Expressions, ,Expressions}. For example,
- @smallexample
- print x=4
- @end smallexample
- @noindent
- stores the value 4 into the variable @code{x}, and then prints the
- value of the assignment expression (which is 4).
- @xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
- information on operators in supported languages.
- @kindex set variable
- @cindex variables, setting
- If you are not interested in seeing the value of the assignment, use the
- @code{set} command instead of the @code{print} command. @code{set} is
- really the same as @code{print} except that the expression's value is
- not printed and is not put in the value history (@pxref{Value History,
- ,Value History}). The expression is evaluated only for its effects.
- If the beginning of the argument string of the @code{set} command
- appears identical to a @code{set} subcommand, use the @code{set
- variable} command instead of just @code{set}. This command is identical
- to @code{set} except for its lack of subcommands. For example, if your
- program has a variable @code{width}, you get an error if you try to set
- a new value with just @samp{set width=13}, because @value{GDBN} has the
- command @code{set width}:
- @smallexample
- (@value{GDBP}) whatis width
- type = double
- (@value{GDBP}) p width
- $4 = 13
- (@value{GDBP}) set width=47
- Invalid syntax in expression.
- @end smallexample
- @noindent
- The invalid expression, of course, is @samp{=47}. In
- order to actually set the program's variable @code{width}, use
- @smallexample
- (@value{GDBP}) set var width=47
- @end smallexample
- Because the @code{set} command has many subcommands that can conflict
- with the names of program variables, it is a good idea to use the
- @code{set variable} command instead of just @code{set}. For example, if
- your program has a variable @code{g}, you run into problems if you try
- to set a new value with just @samp{set g=4}, because @value{GDBN} has
- the command @code{set gnutarget}, abbreviated @code{set g}:
- @smallexample
- @group
- (@value{GDBP}) whatis g
- type = double
- (@value{GDBP}) p g
- $1 = 1
- (@value{GDBP}) set g=4
- (@value{GDBP}) p g
- $2 = 1
- (@value{GDBP}) r
- The program being debugged has been started already.
- Start it from the beginning? (y or n) y
- Starting program: /home/smith/cc_progs/a.out
- "/home/smith/cc_progs/a.out": can't open to read symbols:
- Invalid bfd target.
- (@value{GDBP}) show g
- The current BFD target is "=4".
- @end group
- @end smallexample
- @noindent
- The program variable @code{g} did not change, and you silently set the
- @code{gnutarget} to an invalid value. In order to set the variable
- @code{g}, use
- @smallexample
- (@value{GDBP}) set var g=4
- @end smallexample
- @value{GDBN} allows more implicit conversions in assignments than C; you can
- freely store an integer value into a pointer variable or vice versa,
- and you can convert any structure to any other structure that is the
- same length or shorter.
- @comment FIXME: how do structs align/pad in these conversions?
- @comment /doc@cygnus.com 18dec1990
- To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
- construct to generate a value of specified type at a specified address
- (@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
- to memory location @code{0x83040} as an integer (which implies a certain size
- and representation in memory), and
- @smallexample
- set @{int@}0x83040 = 4
- @end smallexample
- @noindent
- stores the value 4 into that memory location.
- @node Jumping
- @section Continuing at a Different Address
- Ordinarily, when you continue your program, you do so at the place where
- it stopped, with the @code{continue} command. You can instead continue at
- an address of your own choosing, with the following commands:
- @table @code
- @kindex jump
- @kindex j @r{(@code{jump})}
- @item jump @var{location}
- @itemx j @var{location}
- Resume execution at @var{location}. Execution stops again immediately
- if there is a breakpoint there. @xref{Specify Location}, for a description
- of the different forms of @var{location}. It is common
- practice to use the @code{tbreak} command in conjunction with
- @code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
- The @code{jump} command does not change the current stack frame, or
- the stack pointer, or the contents of any memory location or any
- register other than the program counter. If @var{location} is in
- a different function from the one currently executing, the results may
- be bizarre if the two functions expect different patterns of arguments or
- of local variables. For this reason, the @code{jump} command requests
- confirmation if the specified line is not in the function currently
- executing. However, even bizarre results are predictable if you are
- well acquainted with the machine-language code of your program.
- @end table
- On many systems, you can get much the same effect as the @code{jump}
- command by storing a new value into the register @code{$pc}. The
- difference is that this does not start your program running; it only
- changes the address of where it @emph{will} run when you continue. For
- example,
- @smallexample
- set $pc = 0x485
- @end smallexample
- @noindent
- makes the next @code{continue} command or stepping command execute at
- address @code{0x485}, rather than at the address where your program stopped.
- @xref{Continuing and Stepping, ,Continuing and Stepping}.
- The most common occasion to use the @code{jump} command is to back
- up---perhaps with more breakpoints set---over a portion of a program
- that has already executed, in order to examine its execution in more
- detail.
- @c @group
- @node Signaling
- @section Giving your Program a Signal
- @cindex deliver a signal to a program
- @table @code
- @kindex signal
- @item signal @var{signal}
- Resume execution where your program is stopped, but immediately give it the
- signal @var{signal}. The @var{signal} can be the name or the number of a
- signal. For example, on many systems @code{signal 2} and @code{signal
- SIGINT} are both ways of sending an interrupt signal.
- Alternatively, if @var{signal} is zero, continue execution without
- giving a signal. This is useful when your program stopped on account of
- a signal and would ordinarily see the signal when resumed with the
- @code{continue} command; @samp{signal 0} causes it to resume without a
- signal.
- @emph{Note:} When resuming a multi-threaded program, @var{signal} is
- delivered to the currently selected thread, not the thread that last
- reported a stop. This includes the situation where a thread was
- stopped due to a signal. So if you want to continue execution
- suppressing the signal that stopped a thread, you should select that
- same thread before issuing the @samp{signal 0} command. If you issue
- the @samp{signal 0} command with another thread as the selected one,
- @value{GDBN} detects that and asks for confirmation.
- Invoking the @code{signal} command is not the same as invoking the
- @code{kill} utility from the shell. Sending a signal with @code{kill}
- causes @value{GDBN} to decide what to do with the signal depending on
- the signal handling tables (@pxref{Signals}). The @code{signal} command
- passes the signal directly to your program.
- @code{signal} does not repeat when you press @key{RET} a second time
- after executing the command.
- @kindex queue-signal
- @item queue-signal @var{signal}
- Queue @var{signal} to be delivered immediately to the current thread
- when execution of the thread resumes. The @var{signal} can be the name or
- the number of a signal. For example, on many systems @code{signal 2} and
- @code{signal SIGINT} are both ways of sending an interrupt signal.
- The handling of the signal must be set to pass the signal to the program,
- otherwise @value{GDBN} will report an error.
- You can control the handling of signals from @value{GDBN} with the
- @code{handle} command (@pxref{Signals}).
- Alternatively, if @var{signal} is zero, any currently queued signal
- for the current thread is discarded and when execution resumes no signal
- will be delivered. This is useful when your program stopped on account
- of a signal and would ordinarily see the signal when resumed with the
- @code{continue} command.
- This command differs from the @code{signal} command in that the signal
- is just queued, execution is not resumed. And @code{queue-signal} cannot
- be used to pass a signal whose handling state has been set to @code{nopass}
- (@pxref{Signals}).
- @end table
- @c @end group
- @xref{stepping into signal handlers}, for information on how stepping
- commands behave when the thread has a signal queued.
- @node Returning
- @section Returning from a Function
- @table @code
- @cindex returning from a function
- @kindex return
- @item return
- @itemx return @var{expression}
- You can cancel execution of a function call with the @code{return}
- command. If you give an
- @var{expression} argument, its value is used as the function's return
- value.
- @end table
- When you use @code{return}, @value{GDBN} discards the selected stack frame
- (and all frames within it). You can think of this as making the
- discarded frame return prematurely. If you wish to specify a value to
- be returned, give that value as the argument to @code{return}.
- This pops the selected stack frame (@pxref{Selection, ,Selecting a
- Frame}), and any other frames inside of it, leaving its caller as the
- innermost remaining frame. That frame becomes selected. The
- specified value is stored in the registers used for returning values
- of functions.
- The @code{return} command does not resume execution; it leaves the
- program stopped in the state that would exist if the function had just
- returned. In contrast, the @code{finish} command (@pxref{Continuing
- and Stepping, ,Continuing and Stepping}) resumes execution until the
- selected stack frame returns naturally.
- @value{GDBN} needs to know how the @var{expression} argument should be set for
- the inferior. The concrete registers assignment depends on the OS ABI and the
- type being returned by the selected stack frame. For example it is common for
- OS ABI to return floating point values in FPU registers while integer values in
- CPU registers. Still some ABIs return even floating point values in CPU
- registers. Larger integer widths (such as @code{long long int}) also have
- specific placement rules. @value{GDBN} already knows the OS ABI from its
- current target so it needs to find out also the type being returned to make the
- assignment into the right register(s).
- Normally, the selected stack frame has debug info. @value{GDBN} will always
- use the debug info instead of the implicit type of @var{expression} when the
- debug info is available. For example, if you type @kbd{return -1}, and the
- function in the current stack frame is declared to return a @code{long long
- int}, @value{GDBN} transparently converts the implicit @code{int} value of -1
- into a @code{long long int}:
- @smallexample
- Breakpoint 1, func () at gdb.base/return-nodebug.c:29
- 29 return 31;
- (@value{GDBP}) return -1
- Make func return now? (y or n) y
- #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43
- 43 printf ("result=%lld\n", func ());
- (@value{GDBP})
- @end smallexample
- However, if the selected stack frame does not have a debug info, e.g., if the
- function was compiled without debug info, @value{GDBN} has to find out the type
- to return from user. Specifying a different type by mistake may set the value
- in different inferior registers than the caller code expects. For example,
- typing @kbd{return -1} with its implicit type @code{int} would set only a part
- of a @code{long long int} result for a debug info less function (on 32-bit
- architectures). Therefore the user is required to specify the return type by
- an appropriate cast explicitly:
- @smallexample
- Breakpoint 2, 0x0040050b in func ()
- (@value{GDBP}) return -1
- Return value type not available for selected stack frame.
- Please use an explicit cast of the value to return.
- (@value{GDBP}) return (long long int) -1
- Make selected stack frame return now? (y or n) y
- #0 0x00400526 in main ()
- (@value{GDBP})
- @end smallexample
- @node Calling
- @section Calling Program Functions
- @table @code
- @cindex calling functions
- @cindex inferior functions, calling
- @item print @var{expr}
- Evaluate the expression @var{expr} and display the resulting value.
- The expression may include calls to functions in the program being
- debugged.
- @kindex call
- @item call @var{expr}
- Evaluate the expression @var{expr} without displaying @code{void}
- returned values.
- You can use this variant of the @code{print} command if you want to
- execute a function from your program that does not return anything
- (a.k.a.@: @dfn{a void function}), but without cluttering the output
- with @code{void} returned values that @value{GDBN} will otherwise
- print. If the result is not void, it is printed and saved in the
- value history.
- @end table
- It is possible for the function you call via the @code{print} or
- @code{call} command to generate a signal (e.g., if there's a bug in
- the function, or if you passed it incorrect arguments). What happens
- in that case is controlled by the @code{set unwindonsignal} command.
- Similarly, with a C@t{++} program it is possible for the function you
- call via the @code{print} or @code{call} command to generate an
- exception that is not handled due to the constraints of the dummy
- frame. In this case, any exception that is raised in the frame, but has
- an out-of-frame exception handler will not be found. GDB builds a
- dummy-frame for the inferior function call, and the unwinder cannot
- seek for exception handlers outside of this dummy-frame. What happens
- in that case is controlled by the
- @code{set unwind-on-terminating-exception} command.
- @table @code
- @item set unwindonsignal
- @kindex set unwindonsignal
- @cindex unwind stack in called functions
- @cindex call dummy stack unwinding
- Set unwinding of the stack if a signal is received while in a function
- that @value{GDBN} called in the program being debugged. If set to on,
- @value{GDBN} unwinds the stack it created for the call and restores
- the context to what it was before the call. If set to off (the
- default), @value{GDBN} stops in the frame where the signal was
- received.
- @item show unwindonsignal
- @kindex show unwindonsignal
- Show the current setting of stack unwinding in the functions called by
- @value{GDBN}.
- @item set unwind-on-terminating-exception
- @kindex set unwind-on-terminating-exception
- @cindex unwind stack in called functions with unhandled exceptions
- @cindex call dummy stack unwinding on unhandled exception.
- Set unwinding of the stack if a C@t{++} exception is raised, but left
- unhandled while in a function that @value{GDBN} called in the program being
- debugged. If set to on (the default), @value{GDBN} unwinds the stack
- it created for the call and restores the context to what it was before
- the call. If set to off, @value{GDBN} the exception is delivered to
- the default C@t{++} exception handler and the inferior terminated.
- @item show unwind-on-terminating-exception
- @kindex show unwind-on-terminating-exception
- Show the current setting of stack unwinding in the functions called by
- @value{GDBN}.
- @item set may-call-functions
- @kindex set may-call-functions
- @cindex disabling calling functions in the program
- @cindex calling functions in the program, disabling
- Set permission to call functions in the program.
- This controls whether @value{GDBN} will attempt to call functions in
- the program, such as with expressions in the @code{print} command. It
- defaults to @code{on}.
- To call a function in the program, @value{GDBN} has to temporarily
- modify the state of the inferior. This has potentially undesired side
- effects. Also, having @value{GDBN} call nested functions is likely to
- be erroneous and may even crash the program being debugged. You can
- avoid such hazards by forbidding @value{GDBN} from calling functions
- in the program being debugged. If calling functions in the program
- is forbidden, GDB will throw an error when a command (such as printing
- an expression) starts a function call in the program.
- @item show may-call-functions
- @kindex show may-call-functions
- Show permission to call functions in the program.
- @end table
- @subsection Calling functions with no debug info
- @cindex no debug info functions
- Sometimes, a function you wish to call is missing debug information.
- In such case, @value{GDBN} does not know the type of the function,
- including the types of the function's parameters. To avoid calling
- the inferior function incorrectly, which could result in the called
- function functioning erroneously and even crash, @value{GDBN} refuses
- to call the function unless you tell it the type of the function.
- For prototyped (i.e.@: ANSI/ISO style) functions, there are two ways
- to do that. The simplest is to cast the call to the function's
- declared return type. For example:
- @smallexample
- (@value{GDBP}) p getenv ("PATH")
- 'getenv' has unknown return type; cast the call to its declared return type
- (@value{GDBP}) p (char *) getenv ("PATH")
- $1 = 0x7fffffffe7ba "/usr/local/bin:/"...
- @end smallexample
- Casting the return type of a no-debug function is equivalent to
- casting the function to a pointer to a prototyped function that has a
- prototype that matches the types of the passed-in arguments, and
- calling that. I.e., the call above is equivalent to:
- @smallexample
- (@value{GDBP}) p ((char * (*) (const char *)) getenv) ("PATH")
- @end smallexample
- @noindent
- and given this prototyped C or C++ function with float parameters:
- @smallexample
- float multiply (float v1, float v2) @{ return v1 * v2; @}
- @end smallexample
- @noindent
- these calls are equivalent:
- @smallexample
- (@value{GDBP}) p (float) multiply (2.0f, 3.0f)
- (@value{GDBP}) p ((float (*) (float, float)) multiply) (2.0f, 3.0f)
- @end smallexample
- If the function you wish to call is declared as unprototyped (i.e.@:
- old K&R style), you must use the cast-to-function-pointer syntax, so
- that @value{GDBN} knows that it needs to apply default argument
- promotions (promote float arguments to double). @xref{ABI, float
- promotion}. For example, given this unprototyped C function with
- float parameters, and no debug info:
- @smallexample
- float
- multiply_noproto (v1, v2)
- float v1, v2;
- @{
- return v1 * v2;
- @}
- @end smallexample
- @noindent
- you call it like this:
- @smallexample
- (@value{GDBP}) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f)
- @end smallexample
- @node Patching
- @section Patching Programs
- @cindex patching binaries
- @cindex writing into executables
- @cindex writing into corefiles
- By default, @value{GDBN} opens the file containing your program's
- executable code (or the corefile) read-only. This prevents accidental
- alterations to machine code; but it also prevents you from intentionally
- patching your program's binary.
- If you'd like to be able to patch the binary, you can specify that
- explicitly with the @code{set write} command. For example, you might
- want to turn on internal debugging flags, or even to make emergency
- repairs.
- @table @code
- @kindex set write
- @item set write on
- @itemx set write off
- If you specify @samp{set write on}, @value{GDBN} opens executable and
- core files for both reading and writing; if you specify @kbd{set write
- off} (the default), @value{GDBN} opens them read-only.
- If you have already loaded a file, you must load it again (using the
- @code{exec-file} or @code{core-file} command) after changing @code{set
- write}, for your new setting to take effect.
- @item show write
- @kindex show write
- Display whether executable files and core files are opened for writing
- as well as reading.
- @end table
- @node Compiling and Injecting Code
- @section Compiling and injecting code in @value{GDBN}
- @cindex injecting code
- @cindex writing into executables
- @cindex compiling code
- @value{GDBN} supports on-demand compilation and code injection into
- programs running under @value{GDBN}. GCC 5.0 or higher built with
- @file{libcc1.so} must be installed for this functionality to be enabled.
- This functionality is implemented with the following commands.
- @table @code
- @kindex compile code
- @item compile code @var{source-code}
- @itemx compile code -raw @var{--} @var{source-code}
- Compile @var{source-code} with the compiler language found as the current
- language in @value{GDBN} (@pxref{Languages}). If compilation and
- injection is not supported with the current language specified in
- @value{GDBN}, or the compiler does not support this feature, an error
- message will be printed. If @var{source-code} compiles and links
- successfully, @value{GDBN} will load the object-code emitted,
- and execute it within the context of the currently selected inferior.
- It is important to note that the compiled code is executed immediately.
- After execution, the compiled code is removed from @value{GDBN} and any
- new types or variables you have defined will be deleted.
- The command allows you to specify @var{source-code} in two ways.
- The simplest method is to provide a single line of code to the command.
- E.g.:
- @smallexample
- compile code printf ("hello world\n");
- @end smallexample
- If you specify options on the command line as well as source code, they
- may conflict. The @samp{--} delimiter can be used to separate options
- from actual source code. E.g.:
- @smallexample
- compile code -r -- printf ("hello world\n");
- @end smallexample
- Alternatively you can enter source code as multiple lines of text. To
- enter this mode, invoke the @samp{compile code} command without any text
- following the command. This will start the multiple-line editor and
- allow you to type as many lines of source code as required. When you
- have completed typing, enter @samp{end} on its own line to exit the
- editor.
- @smallexample
- compile code
- >printf ("hello\n");
- >printf ("world\n");
- >end
- @end smallexample
- Specifying @samp{-raw}, prohibits @value{GDBN} from wrapping the
- provided @var{source-code} in a callable scope. In this case, you must
- specify the entry point of the code by defining a function named
- @code{_gdb_expr_}. The @samp{-raw} code cannot access variables of the
- inferior. Using @samp{-raw} option may be needed for example when
- @var{source-code} requires @samp{#include} lines which may conflict with
- inferior symbols otherwise.
- @kindex compile file
- @item compile file @var{filename}
- @itemx compile file -raw @var{filename}
- Like @code{compile code}, but take the source code from @var{filename}.
- @smallexample
- compile file /home/user/example.c
- @end smallexample
- @end table
- @table @code
- @item compile print [[@var{options}] --] @var{expr}
- @itemx compile print [[@var{options}] --] /@var{f} @var{expr}
- Compile and execute @var{expr} with the compiler language found as the
- current language in @value{GDBN} (@pxref{Languages}). By default the
- value of @var{expr} is printed in a format appropriate to its data type;
- you can choose a different format by specifying @samp{/@var{f}}, where
- @var{f} is a letter specifying the format; see @ref{Output Formats,,Output
- Formats}. The @code{compile print} command accepts the same options
- as the @code{print} command; see @ref{print options}.
- @item compile print [[@var{options}] --]
- @itemx compile print [[@var{options}] --] /@var{f}
- @cindex reprint the last value
- Alternatively you can enter the expression (source code producing it) as
- multiple lines of text. To enter this mode, invoke the @samp{compile print}
- command without any text following the command. This will start the
- multiple-line editor.
- @end table
- @noindent
- The process of compiling and injecting the code can be inspected using:
- @table @code
- @anchor{set debug compile}
- @item set debug compile
- @cindex compile command debugging info
- Turns on or off display of @value{GDBN} process of compiling and
- injecting the code. The default is off.
- @item show debug compile
- Displays the current state of displaying @value{GDBN} process of
- compiling and injecting the code.
- @anchor{set debug compile-cplus-types}
- @item set debug compile-cplus-types
- @cindex compile C@t{++} type conversion
- Turns on or off the display of C@t{++} type conversion debugging information.
- The default is off.
- @item show debug compile-cplus-types
- Displays the current state of displaying debugging information for
- C@t{++} type conversion.
- @end table
- @subsection Compilation options for the @code{compile} command
- @value{GDBN} needs to specify the right compilation options for the code
- to be injected, in part to make its ABI compatible with the inferior
- and in part to make the injected code compatible with @value{GDBN}'s
- injecting process.
- @noindent
- The options used, in increasing precedence:
- @table @asis
- @item target architecture and OS options (@code{gdbarch})
- These options depend on target processor type and target operating
- system, usually they specify at least 32-bit (@code{-m32}) or 64-bit
- (@code{-m64}) compilation option.
- @item compilation options recorded in the target
- @value{NGCC} (since version 4.7) stores the options used for compilation
- into @code{DW_AT_producer} part of DWARF debugging information according
- to the @value{NGCC} option @code{-grecord-gcc-switches}. One has to
- explicitly specify @code{-g} during inferior compilation otherwise
- @value{NGCC} produces no DWARF. This feature is only relevant for
- platforms where @code{-g} produces DWARF by default, otherwise one may
- try to enforce DWARF by using @code{-gdwarf-4}.
- @item compilation options set by @code{set compile-args}
- @end table
- @noindent
- You can override compilation options using the following command:
- @table @code
- @item set compile-args
- @cindex compile command options override
- Set compilation options used for compiling and injecting code with the
- @code{compile} commands. These options override any conflicting ones
- from the target architecture and/or options stored during inferior
- compilation.
- @item show compile-args
- Displays the current state of compilation options override.
- This does not show all the options actually used during compilation,
- use @ref{set debug compile} for that.
- @end table
- @subsection Caveats when using the @code{compile} command
- There are a few caveats to keep in mind when using the @code{compile}
- command. As the caveats are different per language, the table below
- highlights specific issues on a per language basis.
- @table @asis
- @item C code examples and caveats
- When the language in @value{GDBN} is set to @samp{C}, the compiler will
- attempt to compile the source code with a @samp{C} compiler. The source
- code provided to the @code{compile} command will have much the same
- access to variables and types as it normally would if it were part of
- the program currently being debugged in @value{GDBN}.
- Below is a sample program that forms the basis of the examples that
- follow. This program has been compiled and loaded into @value{GDBN},
- much like any other normal debugging session.
- @smallexample
- void function1 (void)
- @{
- int i = 42;
- printf ("function 1\n");
- @}
- void function2 (void)
- @{
- int j = 12;
- function1 ();
- @}
- int main(void)
- @{
- int k = 6;
- int *p;
- function2 ();
- return 0;
- @}
- @end smallexample
- For the purposes of the examples in this section, the program above has
- been compiled, loaded into @value{GDBN}, stopped at the function
- @code{main}, and @value{GDBN} is awaiting input from the user.
- To access variables and types for any program in @value{GDBN}, the
- program must be compiled and packaged with debug information. The
- @code{compile} command is not an exception to this rule. Without debug
- information, you can still use the @code{compile} command, but you will
- be very limited in what variables and types you can access.
- So with that in mind, the example above has been compiled with debug
- information enabled. The @code{compile} command will have access to
- all variables and types (except those that may have been optimized
- out). Currently, as @value{GDBN} has stopped the program in the
- @code{main} function, the @code{compile} command would have access to
- the variable @code{k}. You could invoke the @code{compile} command
- and type some source code to set the value of @code{k}. You can also
- read it, or do anything with that variable you would normally do in
- @code{C}. Be aware that changes to inferior variables in the
- @code{compile} command are persistent. In the following example:
- @smallexample
- compile code k = 3;
- @end smallexample
- @noindent
- the variable @code{k} is now 3. It will retain that value until
- something else in the example program changes it, or another
- @code{compile} command changes it.
- Normal scope and access rules apply to source code compiled and
- injected by the @code{compile} command. In the example, the variables
- @code{j} and @code{k} are not accessible yet, because the program is
- currently stopped in the @code{main} function, where these variables
- are not in scope. Therefore, the following command
- @smallexample
- compile code j = 3;
- @end smallexample
- @noindent
- will result in a compilation error message.
- Once the program is continued, execution will bring these variables in
- scope, and they will become accessible; then the code you specify via
- the @code{compile} command will be able to access them.
- You can create variables and types with the @code{compile} command as
- part of your source code. Variables and types that are created as part
- of the @code{compile} command are not visible to the rest of the program for
- the duration of its run. This example is valid:
- @smallexample
- compile code int ff = 5; printf ("ff is %d\n", ff);
- @end smallexample
- However, if you were to type the following into @value{GDBN} after that
- command has completed:
- @smallexample
- compile code printf ("ff is %d\n'', ff);
- @end smallexample
- @noindent
- a compiler error would be raised as the variable @code{ff} no longer
- exists. Object code generated and injected by the @code{compile}
- command is removed when its execution ends. Caution is advised
- when assigning to program variables values of variables created by the
- code submitted to the @code{compile} command. This example is valid:
- @smallexample
- compile code int ff = 5; k = ff;
- @end smallexample
- The value of the variable @code{ff} is assigned to @code{k}. The variable
- @code{k} does not require the existence of @code{ff} to maintain the value
- it has been assigned. However, pointers require particular care in
- assignment. If the source code compiled with the @code{compile} command
- changed the address of a pointer in the example program, perhaps to a
- variable created in the @code{compile} command, that pointer would point
- to an invalid location when the command exits. The following example
- would likely cause issues with your debugged program:
- @smallexample
- compile code int ff = 5; p = &ff;
- @end smallexample
- In this example, @code{p} would point to @code{ff} when the
- @code{compile} command is executing the source code provided to it.
- However, as variables in the (example) program persist with their
- assigned values, the variable @code{p} would point to an invalid
- location when the command exists. A general rule should be followed
- in that you should either assign @code{NULL} to any assigned pointers,
- or restore a valid location to the pointer before the command exits.
- Similar caution must be exercised with any structs, unions, and typedefs
- defined in @code{compile} command. Types defined in the @code{compile}
- command will no longer be available in the next @code{compile} command.
- Therefore, if you cast a variable to a type defined in the
- @code{compile} command, care must be taken to ensure that any future
- need to resolve the type can be achieved.
- @smallexample
- (gdb) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v;
- (gdb) compile code printf ("%d\n", ((struct a *) argv)->a);
- gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’
- Compilation failed.
- (gdb) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a);
- 42
- @end smallexample
- Variables that have been optimized away by the compiler are not
- accessible to the code submitted to the @code{compile} command.
- Access to those variables will generate a compiler error which @value{GDBN}
- will print to the console.
- @end table
- @subsection Compiler search for the @code{compile} command
- @value{GDBN} needs to find @value{NGCC} for the inferior being debugged
- which may not be obvious for remote targets of different architecture
- than where @value{GDBN} is running. Environment variable @env{PATH} on
- @value{GDBN} host is searched for @value{NGCC} binary matching the
- target architecture and operating system. This search can be overriden
- by @code{set compile-gcc} @value{GDBN} command below. @env{PATH} is
- taken from shell that executed @value{GDBN}, it is not the value set by
- @value{GDBN} command @code{set environment}). @xref{Environment}.
- Specifically @env{PATH} is searched for binaries matching regular expression
- @code{@var{arch}(-[^-]*)?-@var{os}-gcc} according to the inferior target being
- debugged. @var{arch} is processor name --- multiarch is supported, so for
- example both @code{i386} and @code{x86_64} targets look for pattern
- @code{(x86_64|i.86)} and both @code{s390} and @code{s390x} targets look
- for pattern @code{s390x?}. @var{os} is currently supported only for
- pattern @code{linux(-gnu)?}.
- On Posix hosts the compiler driver @value{GDBN} needs to find also
- shared library @file{libcc1.so} from the compiler. It is searched in
- default shared library search path (overridable with usual environment
- variable @env{LD_LIBRARY_PATH}), unrelated to @env{PATH} or @code{set
- compile-gcc} settings. Contrary to it @file{libcc1plugin.so} is found
- according to the installation of the found compiler --- as possibly
- specified by the @code{set compile-gcc} command.
- @table @code
- @item set compile-gcc
- @cindex compile command driver filename override
- Set compilation command used for compiling and injecting code with the
- @code{compile} commands. If this option is not set (it is set to
- an empty string), the search described above will occur --- that is the
- default.
- @item show compile-gcc
- Displays the current compile command @value{NGCC} driver filename.
- If set, it is the main command @command{gcc}, found usually for example
- under name @file{x86_64-linux-gnu-gcc}.
- @end table
- @node GDB Files
- @chapter @value{GDBN} Files
- @value{GDBN} needs to know the file name of the program to be debugged,
- both in order to read its symbol table and in order to start your
- program. To debug a core dump of a previous run, you must also tell
- @value{GDBN} the name of the core dump file.
- @menu
- * Files:: Commands to specify files
- * File Caching:: Information about @value{GDBN}'s file caching
- * Separate Debug Files:: Debugging information in separate files
- * MiniDebugInfo:: Debugging information in a special section
- * Index Files:: Index files speed up GDB
- * Symbol Errors:: Errors reading symbol files
- * Data Files:: GDB data files
- @end menu
- @node Files
- @section Commands to Specify Files
- @cindex symbol table
- @cindex core dump file
- You may want to specify executable and core dump file names. The usual
- way to do this is at start-up time, using the arguments to
- @value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
- Out of @value{GDBN}}).
- Occasionally it is necessary to change to a different file during a
- @value{GDBN} session. Or you may run @value{GDBN} and forget to
- specify a file you want to use. Or you are debugging a remote target
- via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver}
- Program}). In these situations the @value{GDBN} commands to specify
- new files are useful.
- @table @code
- @cindex executable file
- @kindex file
- @item file @var{filename}
- Use @var{filename} as the program to be debugged. It is read for its
- symbols and for the contents of pure memory. It is also the program
- executed when you use the @code{run} command. If you do not specify a
- directory and the file is not found in the @value{GDBN} working directory,
- @value{GDBN} uses the environment variable @env{PATH} as a list of
- directories to search, just as the shell does when looking for a program
- to run. You can change the value of this variable, for both @value{GDBN}
- and your program, using the @code{path} command.
- @cindex unlinked object files
- @cindex patching object files
- You can load unlinked object @file{.o} files into @value{GDBN} using
- the @code{file} command. You will not be able to ``run'' an object
- file, but you can disassemble functions and inspect variables. Also,
- if the underlying BFD functionality supports it, you could use
- @kbd{gdb -write} to patch object files using this technique. Note
- that @value{GDBN} can neither interpret nor modify relocations in this
- case, so branches and some initialized variables will appear to go to
- the wrong place. But this feature is still handy from time to time.
- @item file
- @code{file} with no argument makes @value{GDBN} discard any information it
- has on both executable file and the symbol table.
- @kindex exec-file
- @item exec-file @r{[} @var{filename} @r{]}
- Specify that the program to be run (but not the symbol table) is found
- in @var{filename}. @value{GDBN} searches the environment variable @env{PATH}
- if necessary to locate your program. Omitting @var{filename} means to
- discard information on the executable file.
- @kindex symbol-file
- @item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]}
- Read symbol table information from file @var{filename}. @env{PATH} is
- searched when necessary. Use the @code{file} command to get both symbol
- table and program to run from the same file.
- If an optional @var{offset} is specified, it is added to the start
- address of each section in the symbol file. This is useful if the
- program is relocated at runtime, such as the Linux kernel with kASLR
- enabled.
- @code{symbol-file} with no argument clears out @value{GDBN} information on your
- program's symbol table.
- The @code{symbol-file} command causes @value{GDBN} to forget the contents of
- some breakpoints and auto-display expressions. This is because they may
- contain pointers to the internal data recording symbols and data types,
- which are part of the old symbol table data being discarded inside
- @value{GDBN}.
- @code{symbol-file} does not repeat if you press @key{RET} again after
- executing it once.
- When @value{GDBN} is configured for a particular environment, it
- understands debugging information in whatever format is the standard
- generated for that environment; you may use either a @sc{gnu} compiler, or
- other compilers that adhere to the local conventions.
- Best results are usually obtained from @sc{gnu} compilers; for example,
- using @code{@value{NGCC}} you can generate debugging information for
- optimized code.
- For most kinds of object files, with the exception of old SVR3 systems
- using COFF, the @code{symbol-file} command does not normally read the
- symbol table in full right away. Instead, it scans the symbol table
- quickly to find which source files and which symbols are present. The
- details are read later, one source file at a time, as they are needed.
- The purpose of this two-stage reading strategy is to make @value{GDBN}
- start up faster. For the most part, it is invisible except for
- occasional pauses while the symbol table details for a particular source
- file are being read. (The @code{set verbose} command can turn these
- pauses into messages if desired. @xref{Messages/Warnings, ,Optional
- Warnings and Messages}.)
- We have not implemented the two-stage strategy for COFF yet. When the
- symbol table is stored in COFF format, @code{symbol-file} reads the
- symbol table data in full right away. Note that ``stabs-in-COFF''
- still does the two-stage strategy, since the debug info is actually
- in stabs format.
- @kindex readnow
- @cindex reading symbols immediately
- @cindex symbols, reading immediately
- @item symbol-file @r{[} -readnow @r{]} @var{filename}
- @itemx file @r{[} -readnow @r{]} @var{filename}
- You can override the @value{GDBN} two-stage strategy for reading symbol
- tables by using the @samp{-readnow} option with any of the commands that
- load symbol table information, if you want to be sure @value{GDBN} has the
- entire symbol table available.
- @cindex @code{-readnever}, option for symbol-file command
- @cindex never read symbols
- @cindex symbols, never read
- @item symbol-file @r{[} -readnever @r{]} @var{filename}
- @itemx file @r{[} -readnever @r{]} @var{filename}
- You can instruct @value{GDBN} to never read the symbolic information
- contained in @var{filename} by using the @samp{-readnever} option.
- @xref{--readnever}.
- @c FIXME: for now no mention of directories, since this seems to be in
- @c flux. 13mar1992 status is that in theory GDB would look either in
- @c current dir or in same dir as myprog; but issues like competing
- @c GDB's, or clutter in system dirs, mean that in practice right now
- @c only current dir is used. FFish says maybe a special GDB hierarchy
- @c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
- @c files.
- @kindex core-file
- @item core-file @r{[}@var{filename}@r{]}
- @itemx core
- Specify the whereabouts of a core dump file to be used as the ``contents
- of memory''. Traditionally, core files contain only some parts of the
- address space of the process that generated them; @value{GDBN} can access the
- executable file itself for other parts.
- @code{core-file} with no argument specifies that no core file is
- to be used.
- Note that the core file is ignored when your program is actually running
- under @value{GDBN}. So, if you have been running your program and you
- wish to debug a core file instead, you must kill the subprocess in which
- the program is running. To do this, use the @code{kill} command
- (@pxref{Kill Process, ,Killing the Child Process}).
- @kindex add-symbol-file
- @cindex dynamic linking
- @item add-symbol-file @var{filename} @r{[} -readnow @r{|} -readnever @r{]} @r{[} -o @var{offset} @r{]} @r{[} @var{textaddress} @r{]} @r{[} -s @var{section} @var{address} @dots{} @r{]}
- The @code{add-symbol-file} command reads additional symbol table
- information from the file @var{filename}. You would use this command
- when @var{filename} has been dynamically loaded (by some other means)
- into the program that is running. The @var{textaddress} parameter gives
- the memory address at which the file's text section has been loaded.
- You can additionally specify the base address of other sections using
- an arbitrary number of @samp{-s @var{section} @var{address}} pairs.
- If a section is omitted, @value{GDBN} will use its default addresses
- as found in @var{filename}. Any @var{address} or @var{textaddress}
- can be given as an expression.
- If an optional @var{offset} is specified, it is added to the start
- address of each section, except those for which the address was
- specified explicitly.
- The symbol table of the file @var{filename} is added to the symbol table
- originally read with the @code{symbol-file} command. You can use the
- @code{add-symbol-file} command any number of times; the new symbol data
- thus read is kept in addition to the old.
- Changes can be reverted using the command @code{remove-symbol-file}.
- @cindex relocatable object files, reading symbols from
- @cindex object files, relocatable, reading symbols from
- @cindex reading symbols from relocatable object files
- @cindex symbols, reading from relocatable object files
- @cindex @file{.o} files, reading symbols from
- Although @var{filename} is typically a shared library file, an
- executable file, or some other object file which has been fully
- relocated for loading into a process, you can also load symbolic
- information from relocatable @file{.o} files, as long as:
- @itemize @bullet
- @item
- the file's symbolic information refers only to linker symbols defined in
- that file, not to symbols defined by other object files,
- @item
- every section the file's symbolic information refers to has actually
- been loaded into the inferior, as it appears in the file, and
- @item
- you can determine the address at which every section was loaded, and
- provide these to the @code{add-symbol-file} command.
- @end itemize
- @noindent
- Some embedded operating systems, like Sun Chorus and VxWorks, can load
- relocatable files into an already running program; such systems
- typically make the requirements above easy to meet. However, it's
- important to recognize that many native systems use complex link
- procedures (@code{.linkonce} section factoring and C@t{++} constructor table
- assembly, for example) that make the requirements difficult to meet. In
- general, one cannot assume that using @code{add-symbol-file} to read a
- relocatable object file's symbolic information will have the same effect
- as linking the relocatable object file into the program in the normal
- way.
- @code{add-symbol-file} does not repeat if you press @key{RET} after using it.
- @kindex remove-symbol-file
- @item remove-symbol-file @var{filename}
- @item remove-symbol-file -a @var{address}
- Remove a symbol file added via the @code{add-symbol-file} command. The
- file to remove can be identified by its @var{filename} or by an @var{address}
- that lies within the boundaries of this symbol file in memory. Example:
- @smallexample
- (gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
- add symbol table from file "/home/user/gdb/mylib.so" at
- .text_addr = 0x7ffff7ff9480
- (y or n) y
- Reading symbols from /home/user/gdb/mylib.so...
- (gdb) remove-symbol-file -a 0x7ffff7ff9480
- Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
- (gdb)
- @end smallexample
- @code{remove-symbol-file} does not repeat if you press @key{RET} after using it.
- @kindex add-symbol-file-from-memory
- @cindex @code{syscall DSO}
- @cindex load symbols from memory
- @item add-symbol-file-from-memory @var{address}
- Load symbols from the given @var{address} in a dynamically loaded
- object file whose image is mapped directly into the inferior's memory.
- For example, the Linux kernel maps a @code{syscall DSO} into each
- process's address space; this DSO provides kernel-specific code for
- some system calls. The argument can be any expression whose
- evaluation yields the address of the file's shared object file header.
- For this command to work, you must have used @code{symbol-file} or
- @code{exec-file} commands in advance.
- @kindex section
- @item section @var{section} @var{addr}
- The @code{section} command changes the base address of the named
- @var{section} of the exec file to @var{addr}. This can be used if the
- exec file does not contain section addresses, (such as in the
- @code{a.out} format), or when the addresses specified in the file
- itself are wrong. Each section must be changed separately. The
- @code{info files} command, described below, lists all the sections and
- their addresses.
- @kindex info files
- @kindex info target
- @item info files
- @itemx info target
- @code{info files} and @code{info target} are synonymous; both print the
- current target (@pxref{Targets, ,Specifying a Debugging Target}),
- including the names of the executable and core dump files currently in
- use by @value{GDBN}, and the files from which symbols were loaded. The
- command @code{help target} lists all possible targets rather than
- current ones.
- @kindex maint info sections
- @item maint info sections @r{[}-all-objects@r{]} @r{[}@var{filter-list}@r{]}
- Another command that can give you extra information about program sections
- is @code{maint info sections}. In addition to the section information
- displayed by @code{info files}, this command displays the flags and file
- offset of each section in the executable and core dump files.
- When @samp{-all-objects} is passed then sections from all loaded object
- files, including shared libraries, are printed.
- The optional @var{filter-list} is a space separated list of filter
- keywords. Sections that match any one of the filter criteria will be
- printed. There are two types of filter:
- @table @code
- @item @var{section-name}
- Display information about any section named @var{section-name}.
- @item @var{section-flag}
- Display information for any section with @var{section-flag}. The
- section flags that @value{GDBN} currently knows about are:
- @table @code
- @item ALLOC
- Section will have space allocated in the process when loaded.
- Set for all sections except those containing debug information.
- @item LOAD
- Section will be loaded from the file into the child process memory.
- Set for pre-initialized code and data, clear for @code{.bss} sections.
- @item RELOC
- Section needs to be relocated before loading.
- @item READONLY
- Section cannot be modified by the child process.
- @item CODE
- Section contains executable code only.
- @item DATA
- Section contains data only (no executable code).
- @item ROM
- Section will reside in ROM.
- @item CONSTRUCTOR
- Section contains data for constructor/destructor lists.
- @item HAS_CONTENTS
- Section is not empty.
- @item NEVER_LOAD
- An instruction to the linker to not output the section.
- @item COFF_SHARED_LIBRARY
- A notification to the linker that the section contains
- COFF shared library information.
- @item IS_COMMON
- Section contains common symbols.
- @end table
- @end table
- @kindex maint info target-sections
- @item maint info target-sections
- This command prints @value{GDBN}'s internal section table. For each
- target @value{GDBN} maintains a table containing the allocatable
- sections from all currently mapped objects, along with information
- about where the section is mapped.
- @kindex set trust-readonly-sections
- @cindex read-only sections
- @item set trust-readonly-sections on
- Tell @value{GDBN} that readonly sections in your object file
- really are read-only (i.e.@: that their contents will not change).
- In that case, @value{GDBN} can fetch values from these sections
- out of the object file, rather than from the target program.
- For some targets (notably embedded ones), this can be a significant
- enhancement to debugging performance.
- The default is off.
- @item set trust-readonly-sections off
- Tell @value{GDBN} not to trust readonly sections. This means that
- the contents of the section might change while the program is running,
- and must therefore be fetched from the target when needed.
- @item show trust-readonly-sections
- Show the current setting of trusting readonly sections.
- @end table
- All file-specifying commands allow both absolute and relative file names
- as arguments. @value{GDBN} always converts the file name to an absolute file
- name and remembers it that way.
- @cindex shared libraries
- @anchor{Shared Libraries}
- @value{GDBN} supports @sc{gnu}/Linux, MS-Windows, SunOS,
- Darwin/Mach-O, SVr4, IBM RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and
- DSBT (TIC6X) shared libraries.
- On MS-Windows @value{GDBN} must be linked with the Expat library to support
- shared libraries. @xref{Expat}.
- @value{GDBN} automatically loads symbol definitions from shared libraries
- when you use the @code{run} command, or when you examine a core file.
- (Before you issue the @code{run} command, @value{GDBN} does not understand
- references to a function in a shared library, however---unless you are
- debugging a core file).
- @c FIXME: some @value{GDBN} release may permit some refs to undef
- @c FIXME...symbols---eg in a break cmd---assuming they are from a shared
- @c FIXME...lib; check this from time to time when updating manual
- There are times, however, when you may wish to not automatically load
- symbol definitions from shared libraries, such as when they are
- particularly large or there are many of them.
- To control the automatic loading of shared library symbols, use the
- commands:
- @table @code
- @kindex set auto-solib-add
- @item set auto-solib-add @var{mode}
- If @var{mode} is @code{on}, symbols from all shared object libraries
- will be loaded automatically when the inferior begins execution, you
- attach to an independently started inferior, or when the dynamic linker
- informs @value{GDBN} that a new library has been loaded. If @var{mode}
- is @code{off}, symbols must be loaded manually, using the
- @code{sharedlibrary} command. The default value is @code{on}.
- @cindex memory used for symbol tables
- If your program uses lots of shared libraries with debug info that
- takes large amounts of memory, you can decrease the @value{GDBN}
- memory footprint by preventing it from automatically loading the
- symbols from shared libraries. To that end, type @kbd{set
- auto-solib-add off} before running the inferior, then load each
- library whose debug symbols you do need with @kbd{sharedlibrary
- @var{regexp}}, where @var{regexp} is a regular expression that matches
- the libraries whose symbols you want to be loaded.
- @kindex show auto-solib-add
- @item show auto-solib-add
- Display the current autoloading mode.
- @end table
- @cindex load shared library
- To explicitly load shared library symbols, use the @code{sharedlibrary}
- command:
- @table @code
- @kindex info sharedlibrary
- @kindex info share
- @item info share @var{regex}
- @itemx info sharedlibrary @var{regex}
- Print the names of the shared libraries which are currently loaded
- that match @var{regex}. If @var{regex} is omitted then print
- all shared libraries that are loaded.
- @kindex info dll
- @item info dll @var{regex}
- This is an alias of @code{info sharedlibrary}.
- @kindex sharedlibrary
- @kindex share
- @item sharedlibrary @var{regex}
- @itemx share @var{regex}
- Load shared object library symbols for files matching a
- Unix regular expression.
- As with files loaded automatically, it only loads shared libraries
- required by your program for a core file or after typing @code{run}. If
- @var{regex} is omitted all shared libraries required by your program are
- loaded.
- @item nosharedlibrary
- @kindex nosharedlibrary
- @cindex unload symbols from shared libraries
- Unload all shared object library symbols. This discards all symbols
- that have been loaded from all shared libraries. Symbols from shared
- libraries that were loaded by explicit user requests are not
- discarded.
- @end table
- Sometimes you may wish that @value{GDBN} stops and gives you control
- when any of shared library events happen. The best way to do this is
- to use @code{catch load} and @code{catch unload} (@pxref{Set
- Catchpoints}).
- @value{GDBN} also supports the @code{set stop-on-solib-events}
- command for this. This command exists for historical reasons. It is
- less useful than setting a catchpoint, because it does not allow for
- conditions or commands as a catchpoint does.
- @table @code
- @item set stop-on-solib-events
- @kindex set stop-on-solib-events
- This command controls whether @value{GDBN} should give you control
- when the dynamic linker notifies it about some shared library event.
- The most common event of interest is loading or unloading of a new
- shared library.
- @item show stop-on-solib-events
- @kindex show stop-on-solib-events
- Show whether @value{GDBN} stops and gives you control when shared
- library events happen.
- @end table
- Shared libraries are also supported in many cross or remote debugging
- configurations. @value{GDBN} needs to have access to the target's libraries;
- this can be accomplished either by providing copies of the libraries
- on the host system, or by asking @value{GDBN} to automatically retrieve the
- libraries from the target. If copies of the target libraries are
- provided, they need to be the same as the target libraries, although the
- copies on the target can be stripped as long as the copies on the host are
- not.
- @cindex where to look for shared libraries
- For remote debugging, you need to tell @value{GDBN} where the target
- libraries are, so that it can load the correct copies---otherwise, it
- may try to load the host's libraries. @value{GDBN} has two variables
- to specify the search directories for target libraries.
- @table @code
- @cindex prefix for executable and shared library file names
- @cindex system root, alternate
- @kindex set solib-absolute-prefix
- @kindex set sysroot
- @item set sysroot @var{path}
- Use @var{path} as the system root for the program being debugged. Any
- absolute shared library paths will be prefixed with @var{path}; many
- runtime loaders store the absolute paths to the shared library in the
- target program's memory. When starting processes remotely, and when
- attaching to already-running processes (local or remote), their
- executable filenames will be prefixed with @var{path} if reported to
- @value{GDBN} as absolute by the operating system. If you use
- @code{set sysroot} to find executables and shared libraries, they need
- to be laid out in the same way that they are on the target, with
- e.g.@: a @file{/bin}, @file{/lib} and @file{/usr/lib} hierarchy under
- @var{path}.
- If @var{path} starts with the sequence @file{target:} and the target
- system is remote then @value{GDBN} will retrieve the target binaries
- from the remote system. This is only supported when using a remote
- target that supports the @code{remote get} command (@pxref{File
- Transfer,,Sending files to a remote system}). The part of @var{path}
- following the initial @file{target:} (if present) is used as system
- root prefix on the remote file system. If @var{path} starts with the
- sequence @file{remote:} this is converted to the sequence
- @file{target:} by @code{set sysroot}@footnote{Historically the
- functionality to retrieve binaries from the remote system was
- provided by prefixing @var{path} with @file{remote:}}. If you want
- to specify a local system root using a directory that happens to be
- named @file{target:} or @file{remote:}, you need to use some
- equivalent variant of the name like @file{./target:}.
- For targets with an MS-DOS based filesystem, such as MS-Windows,
- @value{GDBN} tries prefixing a few variants of the target
- absolute file name with @var{path}. But first, on Unix hosts,
- @value{GDBN} converts all backslash directory separators into forward
- slashes, because the backslash is not a directory separator on Unix:
- @smallexample
- c:\foo\bar.dll @result{} c:/foo/bar.dll
- @end smallexample
- Then, @value{GDBN} attempts prefixing the target file name with
- @var{path}, and looks for the resulting file name in the host file
- system:
- @smallexample
- c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll
- @end smallexample
- If that does not find the binary, @value{GDBN} tries removing
- the @samp{:} character from the drive spec, both for convenience, and,
- for the case of the host file system not supporting file names with
- colons:
- @smallexample
- c:/foo/bar.dll @result{} /path/to/sysroot/c/foo/bar.dll
- @end smallexample
- This makes it possible to have a system root that mirrors a target
- with more than one drive. E.g., you may want to setup your local
- copies of the target system shared libraries like so (note @samp{c} vs
- @samp{z}):
- @smallexample
- @file{/path/to/sysroot/c/sys/bin/foo.dll}
- @file{/path/to/sysroot/c/sys/bin/bar.dll}
- @file{/path/to/sysroot/z/sys/bin/bar.dll}
- @end smallexample
- @noindent
- and point the system root at @file{/path/to/sysroot}, so that
- @value{GDBN} can find the correct copies of both
- @file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}.
- If that still does not find the binary, @value{GDBN} tries
- removing the whole drive spec from the target file name:
- @smallexample
- c:/foo/bar.dll @result{} /path/to/sysroot/foo/bar.dll
- @end smallexample
- This last lookup makes it possible to not care about the drive name,
- if you don't want or need to.
- The @code{set solib-absolute-prefix} command is an alias for @code{set
- sysroot}.
- @cindex default system root
- @cindex @samp{--with-sysroot}
- You can set the default system root by using the configure-time
- @samp{--with-sysroot} option. If the system root is inside
- @value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
- @samp{--exec-prefix}), then the default system root will be updated
- automatically if the installed @value{GDBN} is moved to a new
- location.
- @kindex show sysroot
- @item show sysroot
- Display the current executable and shared library prefix.
- @kindex set solib-search-path
- @item set solib-search-path @var{path}
- If this variable is set, @var{path} is a colon-separated list of
- directories to search for shared libraries. @samp{solib-search-path}
- is used after @samp{sysroot} fails to locate the library, or if the
- path to the library is relative instead of absolute. If you want to
- use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set
- @samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from
- finding your host's libraries. @samp{sysroot} is preferred; setting
- it to a nonexistent directory may interfere with automatic loading
- of shared library symbols.
- @kindex show solib-search-path
- @item show solib-search-path
- Display the current shared library search path.
- @cindex DOS file-name semantics of file names.
- @kindex set target-file-system-kind (unix|dos-based|auto)
- @kindex show target-file-system-kind
- @item set target-file-system-kind @var{kind}
- Set assumed file system kind for target reported file names.
- Shared library file names as reported by the target system may not
- make sense as is on the system @value{GDBN} is running on. For
- example, when remote debugging a target that has MS-DOS based file
- system semantics, from a Unix host, the target may be reporting to
- @value{GDBN} a list of loaded shared libraries with file names such as
- @file{c:\Windows\kernel32.dll}. On Unix hosts, there's no concept of
- drive letters, so the @samp{c:\} prefix is not normally understood as
- indicating an absolute file name, and neither is the backslash
- normally considered a directory separator character. In that case,
- the native file system would interpret this whole absolute file name
- as a relative file name with no directory components. This would make
- it impossible to point @value{GDBN} at a copy of the remote target's
- shared libraries on the host using @code{set sysroot}, and impractical
- with @code{set solib-search-path}. Setting
- @code{target-file-system-kind} to @code{dos-based} tells @value{GDBN}
- to interpret such file names similarly to how the target would, and to
- map them to file names valid on @value{GDBN}'s native file system
- semantics. The value of @var{kind} can be @code{"auto"}, in addition
- to one of the supported file system kinds. In that case, @value{GDBN}
- tries to determine the appropriate file system variant based on the
- current target's operating system (@pxref{ABI, ,Configuring the
- Current ABI}). The supported file system settings are:
- @table @code
- @item unix
- Instruct @value{GDBN} to assume the target file system is of Unix
- kind. Only file names starting the forward slash (@samp{/}) character
- are considered absolute, and the directory separator character is also
- the forward slash.
- @item dos-based
- Instruct @value{GDBN} to assume the target file system is DOS based.
- File names starting with either a forward slash, or a drive letter
- followed by a colon (e.g., @samp{c:}), are considered absolute, and
- both the slash (@samp{/}) and the backslash (@samp{\\}) characters are
- considered directory separators.
- @item auto
- Instruct @value{GDBN} to use the file system kind associated with the
- target operating system (@pxref{ABI, ,Configuring the Current ABI}).
- This is the default.
- @end table
- @end table
- @cindex file name canonicalization
- @cindex base name differences
- When processing file names provided by the user, @value{GDBN}
- frequently needs to compare them to the file names recorded in the
- program's debug info. Normally, @value{GDBN} compares just the
- @dfn{base names} of the files as strings, which is reasonably fast
- even for very large programs. (The base name of a file is the last
- portion of its name, after stripping all the leading directories.)
- This shortcut in comparison is based upon the assumption that files
- cannot have more than one base name. This is usually true, but
- references to files that use symlinks or similar filesystem
- facilities violate that assumption. If your program records files
- using such facilities, or if you provide file names to @value{GDBN}
- using symlinks etc., you can set @code{basenames-may-differ} to
- @code{true} to instruct @value{GDBN} to completely canonicalize each
- pair of file names it needs to compare. This will make file-name
- comparisons accurate, but at a price of a significant slowdown.
- @table @code
- @item set basenames-may-differ
- @kindex set basenames-may-differ
- Set whether a source file may have multiple base names.
- @item show basenames-may-differ
- @kindex show basenames-may-differ
- Show whether a source file may have multiple base names.
- @end table
- @node File Caching
- @section File Caching
- @cindex caching of opened files
- @cindex caching of bfd objects
- To speed up file loading, and reduce memory usage, @value{GDBN} will
- reuse the @code{bfd} objects used to track open files. @xref{Top, ,
- BFD, bfd, The Binary File Descriptor Library}. The following commands
- allow visibility and control of the caching behavior.
- @table @code
- @kindex maint info bfds
- @item maint info bfds
- This prints information about each @code{bfd} object that is known to
- @value{GDBN}.
- @kindex maint set bfd-sharing
- @kindex maint show bfd-sharing
- @kindex bfd caching
- @item maint set bfd-sharing
- @item maint show bfd-sharing
- Control whether @code{bfd} objects can be shared. When sharing is
- enabled @value{GDBN} reuses already open @code{bfd} objects rather
- than reopening the same file. Turning sharing off does not cause
- already shared @code{bfd} objects to be unshared, but all future files
- that are opened will create a new @code{bfd} object. Similarly,
- re-enabling sharing does not cause multiple existing @code{bfd}
- objects to be collapsed into a single shared @code{bfd} object.
- @kindex set debug bfd-cache @var{level}
- @kindex bfd caching
- @item set debug bfd-cache @var{level}
- Turns on debugging of the bfd cache, setting the level to @var{level}.
- @kindex show debug bfd-cache
- @kindex bfd caching
- @item show debug bfd-cache
- Show the current debugging level of the bfd cache.
- @end table
- @node Separate Debug Files
- @section Debugging Information in Separate Files
- @cindex separate debugging information files
- @cindex debugging information in separate files
- @cindex @file{.debug} subdirectories
- @cindex debugging information directory, global
- @cindex global debugging information directories
- @cindex build ID, and separate debugging files
- @cindex @file{.build-id} directory
- @value{GDBN} allows you to put a program's debugging information in a
- file separate from the executable itself, in a way that allows
- @value{GDBN} to find and load the debugging information automatically.
- Since debugging information can be very large---sometimes larger
- than the executable code itself---some systems distribute debugging
- information for their executables in separate files, which users can
- install only when they need to debug a problem.
- @value{GDBN} supports two ways of specifying the separate debug info
- file:
- @itemize @bullet
- @item
- The executable contains a @dfn{debug link} that specifies the name of
- the separate debug info file. The separate debug file's name is
- usually @file{@var{executable}.debug}, where @var{executable} is the
- name of the corresponding executable file without leading directories
- (e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the
- debug link specifies a 32-bit @dfn{Cyclic Redundancy Check} (CRC)
- checksum for the debug file, which @value{GDBN} uses to validate that
- the executable and the debug file came from the same build.
- @item
- @anchor{build ID}
- The executable contains a @dfn{build ID}, a unique bit string that is
- also present in the corresponding debug info file. (This is supported
- only on some operating systems, when using the ELF or PE file formats
- for binary files and the @sc{gnu} Binutils.) For more details about
- this feature, see the description of the @option{--build-id}
- command-line option in @ref{Options, , Command Line Options, ld,
- The GNU Linker}. The debug info file's name is not specified
- explicitly by the build ID, but can be computed from the build ID, see
- below.
- @end itemize
- Depending on the way the debug info file is specified, @value{GDBN}
- uses two different methods of looking for the debug file:
- @itemize @bullet
- @item
- For the ``debug link'' method, @value{GDBN} looks up the named file in
- the directory of the executable file, then in a subdirectory of that
- directory named @file{.debug}, and finally under each one of the
- global debug directories, in a subdirectory whose name is identical to
- the leading directories of the executable's absolute file name. (On
- MS-Windows/MS-DOS, the drive letter of the executable's leading
- directories is converted to a one-letter subdirectory, i.e.@:
- @file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows
- filesystems disallow colons in file names.)
- @item
- For the ``build ID'' method, @value{GDBN} looks in the
- @file{.build-id} subdirectory of each one of the global debug directories for
- a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
- first 2 hex characters of the build ID bit string, and @var{nnnnnnnn}
- are the rest of the bit string. (Real build ID strings are 32 or more
- hex characters, not 10.) @value{GDBN} can automatically query
- @code{debuginfod} servers using build IDs in order to download separate debug
- files that cannot be found locally. For more information see @ref{Debuginfod}.
- @end itemize
- So, for example, suppose you ask @value{GDBN} to debug
- @file{/usr/bin/ls}, which has a debug link that specifies the
- file @file{ls.debug}, and a build ID whose value in hex is
- @code{abcdef1234}. If the list of the global debug directories includes
- @file{/usr/lib/debug}, then @value{GDBN} will look for the following
- debug information files, in the indicated order:
- @itemize @minus
- @item
- @file{/usr/lib/debug/.build-id/ab/cdef1234.debug}
- @item
- @file{/usr/bin/ls.debug}
- @item
- @file{/usr/bin/.debug/ls.debug}
- @item
- @file{/usr/lib/debug/usr/bin/ls.debug}.
- @end itemize
- If the debug file still has not been found and @code{debuginfod}
- (@pxref{Debuginfod}) is enabled, @value{GDBN} will attempt to download the
- file from @code{debuginfod} servers.
- @anchor{debug-file-directory}
- Global debugging info directories default to what is set by @value{GDBN}
- configure option @option{--with-separate-debug-dir}. During @value{GDBN} run
- you can also set the global debugging info directories, and view the list
- @value{GDBN} is currently using.
- @table @code
- @kindex set debug-file-directory
- @item set debug-file-directory @var{directories}
- Set the directories which @value{GDBN} searches for separate debugging
- information files to @var{directory}. Multiple path components can be set
- concatenating them by a path separator.
- @kindex show debug-file-directory
- @item show debug-file-directory
- Show the directories @value{GDBN} searches for separate debugging
- information files.
- @end table
- @cindex @code{.gnu_debuglink} sections
- @cindex debug link sections
- A debug link is a special section of the executable file named
- @code{.gnu_debuglink}. The section must contain:
- @itemize
- @item
- A filename, with any leading directory components removed, followed by
- a zero byte,
- @item
- zero to three bytes of padding, as needed to reach the next four-byte
- boundary within the section, and
- @item
- a four-byte CRC checksum, stored in the same endianness used for the
- executable file itself. The checksum is computed on the debugging
- information file's full contents by the function given below, passing
- zero as the @var{crc} argument.
- @end itemize
- Any executable file format can carry a debug link, as long as it can
- contain a section named @code{.gnu_debuglink} with the contents
- described above.
- @cindex @code{.note.gnu.build-id} sections
- @cindex build ID sections
- The build ID is a special section in the executable file (and in other
- ELF binary files that @value{GDBN} may consider). This section is
- often named @code{.note.gnu.build-id}, but that name is not mandatory.
- It contains unique identification for the built files---the ID remains
- the same across multiple builds of the same build tree. The default
- algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
- content for the build ID string. The same section with an identical
- value is present in the original built binary with symbols, in its
- stripped variant, and in the separate debugging information file.
- The debugging information file itself should be an ordinary
- executable, containing a full set of linker symbols, sections, and
- debugging information. The sections of the debugging information file
- should have the same names, addresses, and sizes as the original file,
- but they need not contain any data---much like a @code{.bss} section
- in an ordinary executable.
- The @sc{gnu} binary utilities (Binutils) package includes the
- @samp{objcopy} utility that can produce
- the separated executable / debugging information file pairs using the
- following commands:
- @smallexample
- @kbd{objcopy --only-keep-debug foo foo.debug}
- @kbd{strip -g foo}
- @end smallexample
- @noindent
- These commands remove the debugging
- information from the executable file @file{foo} and place it in the file
- @file{foo.debug}. You can use the first, second or both methods to link the
- two files:
- @itemize @bullet
- @item
- The debug link method needs the following additional command to also leave
- behind a debug link in @file{foo}:
- @smallexample
- @kbd{objcopy --add-gnu-debuglink=foo.debug foo}
- @end smallexample
- Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains
- a version of the @code{strip} command such that the command @kbd{strip foo -f
- foo.debug} has the same functionality as the two @code{objcopy} commands and
- the @code{ln -s} command above, together.
- @item
- Build ID gets embedded into the main executable using @code{ld --build-id} or
- the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus
- compatibility fixes for debug files separation are present in @sc{gnu} binary
- utilities (Binutils) package since version 2.18.
- @end itemize
- @noindent
- @cindex CRC algorithm definition
- The CRC used in @code{.gnu_debuglink} is the CRC-32 defined in
- IEEE 802.3 using the polynomial:
- @c TexInfo requires naked braces for multi-digit exponents for Tex
- @c output, but this causes HTML output to barf. HTML has to be set using
- @c raw commands. So we end up having to specify this equation in 2
- @c different ways!
- @ifhtml
- @display
- @html
- <em>x</em><sup>32</sup> + <em>x</em><sup>26</sup> + <em>x</em><sup>23</sup> + <em>x</em><sup>22</sup> + <em>x</em><sup>16</sup> + <em>x</em><sup>12</sup> + <em>x</em><sup>11</sup>
- + <em>x</em><sup>10</sup> + <em>x</em><sup>8</sup> + <em>x</em><sup>7</sup> + <em>x</em><sup>5</sup> + <em>x</em><sup>4</sup> + <em>x</em><sup>2</sup> + <em>x</em> + 1
- @end html
- @end display
- @end ifhtml
- @ifnothtml
- @display
- @math{x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}}
- @math{+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1}
- @end display
- @end ifnothtml
- The function is computed byte at a time, taking the least
- significant bit of each byte first. The initial pattern
- @code{0xffffffff} is used, to ensure leading zeros affect the CRC and
- the final result is inverted to ensure trailing zeros also affect the
- CRC.
- @emph{Note:} This is the same CRC polynomial as used in handling the
- @dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{qCRC packet}).
- However in the case of the Remote Serial Protocol, the CRC is computed
- @emph{most} significant bit first, and the result is not inverted, so
- trailing zeros have no effect on the CRC value.
- To complete the description, we show below the code of the function
- which produces the CRC used in @code{.gnu_debuglink}. Inverting the
- initially supplied @code{crc} argument means that an initial call to
- this function passing in zero will start computing the CRC using
- @code{0xffffffff}.
- @kindex gnu_debuglink_crc32
- @smallexample
- unsigned long
- gnu_debuglink_crc32 (unsigned long crc,
- unsigned char *buf, size_t len)
- @{
- static const unsigned long crc32_table[256] =
- @{
- 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
- 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
- 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
- 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
- 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
- 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
- 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
- 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
- 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
- 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
- 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
- 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
- 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
- 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
- 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
- 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
- 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
- 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
- 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
- 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
- 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
- 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
- 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
- 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
- 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
- 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
- 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
- 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
- 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
- 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
- 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
- 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
- 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
- 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
- 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
- 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
- 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
- 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
- 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
- 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
- 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
- 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
- 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
- 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
- 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
- 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
- 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
- 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
- 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
- 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
- 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
- 0x2d02ef8d
- @};
- unsigned char *end;
- crc = ~crc & 0xffffffff;
- for (end = buf + len; buf < end; ++buf)
- crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
- return ~crc & 0xffffffff;
- @}
- @end smallexample
- @noindent
- This computation does not apply to the ``build ID'' method.
- @node MiniDebugInfo
- @section Debugging information in a special section
- @cindex separate debug sections
- @cindex @samp{.gnu_debugdata} section
- Some systems ship pre-built executables and libraries that have a
- special @samp{.gnu_debugdata} section. This feature is called
- @dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and
- is used to supply extra symbols for backtraces.
- The intent of this section is to provide extra minimal debugging
- information for use in simple backtraces. It is not intended to be a
- replacement for full separate debugging information (@pxref{Separate
- Debug Files}). The example below shows the intended use; however,
- @value{GDBN} does not currently put restrictions on what sort of
- debugging information might be included in the section.
- @value{GDBN} has support for this extension. If the section exists,
- then it is used provided that no other source of debugging information
- can be found, and that @value{GDBN} was configured with LZMA support.
- This section can be easily created using @command{objcopy} and other
- standard utilities:
- @smallexample
- # Extract the dynamic symbols from the main binary, there is no need
- # to also have these in the normal symbol table.
- nm -D @var{binary} --format=posix --defined-only \
- | awk '@{ print $1 @}' | sort > dynsyms
- # Extract all the text (i.e. function) symbols from the debuginfo.
- # (Note that we actually also accept "D" symbols, for the benefit
- # of platforms like PowerPC64 that use function descriptors.)
- nm @var{binary} --format=posix --defined-only \
- | awk '@{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 @}' \
- | sort > funcsyms
- # Keep all the function symbols not already in the dynamic symbol
- # table.
- comm -13 dynsyms funcsyms > keep_symbols
- # Separate full debug info into debug binary.
- objcopy --only-keep-debug @var{binary} debug
- # Copy the full debuginfo, keeping only a minimal set of symbols and
- # removing some unnecessary sections.
- objcopy -S --remove-section .gdb_index --remove-section .comment \
- --keep-symbols=keep_symbols debug mini_debuginfo
- # Drop the full debug info from the original binary.
- strip --strip-all -R .comment @var{binary}
- # Inject the compressed data into the .gnu_debugdata section of the
- # original binary.
- xz mini_debuginfo
- objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary}
- @end smallexample
- @node Index Files
- @section Index Files Speed Up @value{GDBN}
- @cindex index files
- @cindex @samp{.gdb_index} section
- When @value{GDBN} finds a symbol file, it scans the symbols in the
- file in order to construct an internal symbol table. This lets most
- @value{GDBN} operations work quickly---at the cost of a delay early
- on. For large programs, this delay can be quite lengthy, so
- @value{GDBN} provides a way to build an index, which speeds up
- startup.
- For convenience, @value{GDBN} comes with a program,
- @command{gdb-add-index}, which can be used to add the index to a
- symbol file. It takes the symbol file as its only argument:
- @smallexample
- $ gdb-add-index symfile
- @end smallexample
- @xref{gdb-add-index}.
- It is also possible to do the work manually. Here is what
- @command{gdb-add-index} does behind the curtains.
- The index is stored as a section in the symbol file. @value{GDBN} can
- write the index to a file, then you can put it into the symbol file
- using @command{objcopy}.
- To create an index file, use the @code{save gdb-index} command:
- @table @code
- @item save gdb-index [-dwarf-5] @var{directory}
- @kindex save gdb-index
- Create index files for all symbol files currently known by
- @value{GDBN}. For each known @var{symbol-file}, this command by
- default creates it produces a single file
- @file{@var{symbol-file}.gdb-index}. If you invoke this command with
- the @option{-dwarf-5} option, it produces 2 files:
- @file{@var{symbol-file}.debug_names} and
- @file{@var{symbol-file}.debug_str}. The files are created in the
- given @var{directory}.
- @end table
- Once you have created an index file you can merge it into your symbol
- file, here named @file{symfile}, using @command{objcopy}:
- @smallexample
- $ objcopy --add-section .gdb_index=symfile.gdb-index \
- --set-section-flags .gdb_index=readonly symfile symfile
- @end smallexample
- Or for @code{-dwarf-5}:
- @smallexample
- $ objcopy --dump-section .debug_str=symfile.debug_str.new symfile
- $ cat symfile.debug_str >>symfile.debug_str.new
- $ objcopy --add-section .debug_names=symfile.gdb-index \
- --set-section-flags .debug_names=readonly \
- --update-section .debug_str=symfile.debug_str.new symfile symfile
- @end smallexample
- @value{GDBN} will normally ignore older versions of @file{.gdb_index}
- sections that have been deprecated. Usually they are deprecated because
- they are missing a new feature or have performance issues.
- To tell @value{GDBN} to use a deprecated index section anyway
- specify @code{set use-deprecated-index-sections on}.
- The default is @code{off}.
- This can speed up startup, but may result in some functionality being lost.
- @xref{Index Section Format}.
- @emph{Warning:} Setting @code{use-deprecated-index-sections} to @code{on}
- must be done before gdb reads the file. The following will not work:
- @smallexample
- $ gdb -ex "set use-deprecated-index-sections on" <program>
- @end smallexample
- Instead you must do, for example,
- @smallexample
- $ gdb -iex "set use-deprecated-index-sections on" <program>
- @end smallexample
- Indices only work when using DWARF debugging information, not stabs.
- @subsection Automatic symbol index cache
- @cindex automatic symbol index cache
- It is possible for @value{GDBN} to automatically save a copy of this index in a
- cache on disk and retrieve it from there when loading the same binary in the
- future. This feature can be turned on with @kbd{set index-cache enabled on}.
- The following commands can be used to tweak the behavior of the index cache.
- @table @code
- @kindex set index-cache
- @item set index-cache enabled on
- @itemx set index-cache enabled off
- Enable or disable the use of the symbol index cache.
- @item set index-cache directory @var{directory}
- @kindex show index-cache
- @itemx show index-cache directory
- Set/show the directory where index files will be saved.
- The default value for this directory depends on the host platform. On
- most systems, the index is cached in the @file{gdb} subdirectory of
- the directory pointed to by the @env{XDG_CACHE_HOME} environment
- variable, if it is defined, else in the @file{.cache/gdb} subdirectory
- of your home directory. However, on some systems, the default may
- differ according to local convention.
- There is no limit on the disk space used by index cache. It is perfectly safe
- to delete the content of that directory to free up disk space.
- @item show index-cache stats
- Print the number of cache hits and misses since the launch of @value{GDBN}.
- @end table
- @node Symbol Errors
- @section Errors Reading Symbol Files
- While reading a symbol file, @value{GDBN} occasionally encounters problems,
- such as symbol types it does not recognize, or known bugs in compiler
- output. By default, @value{GDBN} does not notify you of such problems, since
- they are relatively common and primarily of interest to people
- debugging compilers. If you are interested in seeing information
- about ill-constructed symbol tables, you can either ask @value{GDBN} to print
- only one message about each such type of problem, no matter how many
- times the problem occurs; or you can ask @value{GDBN} to print more messages,
- to see how many times the problems occur, with the @code{set
- complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and
- Messages}).
- The messages currently printed, and their meanings, include:
- @table @code
- @item inner block not inside outer block in @var{symbol}
- The symbol information shows where symbol scopes begin and end
- (such as at the start of a function or a block of statements). This
- error indicates that an inner scope block is not fully contained
- in its outer scope blocks.
- @value{GDBN} circumvents the problem by treating the inner block as if it had
- the same scope as the outer block. In the error message, @var{symbol}
- may be shown as ``@code{(don't know)}'' if the outer block is not a
- function.
- @item block at @var{address} out of order
- The symbol information for symbol scope blocks should occur in
- order of increasing addresses. This error indicates that it does not
- do so.
- @value{GDBN} does not circumvent this problem, and has trouble
- locating symbols in the source file whose symbols it is reading. (You
- can often determine what source file is affected by specifying
- @code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and
- Messages}.)
- @item bad block start address patched
- The symbol information for a symbol scope block has a start address
- smaller than the address of the preceding source line. This is known
- to occur in the SunOS 4.1.1 (and earlier) C compiler.
- @value{GDBN} circumvents the problem by treating the symbol scope block as
- starting on the previous source line.
- @item bad string table offset in symbol @var{n}
- @cindex foo
- Symbol number @var{n} contains a pointer into the string table which is
- larger than the size of the string table.
- @value{GDBN} circumvents the problem by considering the symbol to have the
- name @code{foo}, which may cause other problems if many symbols end up
- with this name.
- @item unknown symbol type @code{0x@var{nn}}
- The symbol information contains new data types that @value{GDBN} does
- not yet know how to read. @code{0x@var{nn}} is the symbol type of the
- uncomprehended information, in hexadecimal.
- @value{GDBN} circumvents the error by ignoring this symbol information.
- This usually allows you to debug your program, though certain symbols
- are not accessible. If you encounter such a problem and feel like
- debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
- on @code{complain}, then go up to the function @code{read_dbx_symtab}
- and examine @code{*bufp} to see the symbol.
- @item stub type has NULL name
- @value{GDBN} could not find the full definition for a struct or class.
- @item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
- The symbol information for a C@t{++} member function is missing some
- information that recent versions of the compiler should have output for
- it.
- @item info mismatch between compiler and debugger
- @value{GDBN} could not parse a type specification output by the compiler.
- @end table
- @node Data Files
- @section GDB Data Files
- @cindex prefix for data files
- @value{GDBN} will sometimes read an auxiliary data file. These files
- are kept in a directory known as the @dfn{data directory}.
- You can set the data directory's name, and view the name @value{GDBN}
- is currently using.
- @table @code
- @kindex set data-directory
- @item set data-directory @var{directory}
- Set the directory which @value{GDBN} searches for auxiliary data files
- to @var{directory}.
- @kindex show data-directory
- @item show data-directory
- Show the directory @value{GDBN} searches for auxiliary data files.
- @end table
- @cindex default data directory
- @cindex @samp{--with-gdb-datadir}
- You can set the default data directory by using the configure-time
- @samp{--with-gdb-datadir} option. If the data directory is inside
- @value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
- @samp{--exec-prefix}), then the default data directory will be updated
- automatically if the installed @value{GDBN} is moved to a new
- location.
- The data directory may also be specified with the
- @code{--data-directory} command line option.
- @xref{Mode Options}.
- @node Targets
- @chapter Specifying a Debugging Target
- @cindex debugging target
- A @dfn{target} is the execution environment occupied by your program.
- Often, @value{GDBN} runs in the same host environment as your program;
- in that case, the debugging target is specified as a side effect when
- you use the @code{file} or @code{core} commands. When you need more
- flexibility---for example, running @value{GDBN} on a physically separate
- host, or controlling a standalone system over a serial port or a
- realtime system over a TCP/IP connection---you can use the @code{target}
- command to specify one of the target types configured for @value{GDBN}
- (@pxref{Target Commands, ,Commands for Managing Targets}).
- @cindex target architecture
- It is possible to build @value{GDBN} for several different @dfn{target
- architectures}. When @value{GDBN} is built like that, you can choose
- one of the available architectures with the @kbd{set architecture}
- command.
- @table @code
- @kindex set architecture
- @kindex show architecture
- @item set architecture @var{arch}
- This command sets the current target architecture to @var{arch}. The
- value of @var{arch} can be @code{"auto"}, in addition to one of the
- supported architectures.
- @item show architecture
- Show the current target architecture.
- @item set processor
- @itemx processor
- @kindex set processor
- @kindex show processor
- These are alias commands for, respectively, @code{set architecture}
- and @code{show architecture}.
- @end table
- @menu
- * Active Targets:: Active targets
- * Target Commands:: Commands for managing targets
- * Byte Order:: Choosing target byte order
- @end menu
- @node Active Targets
- @section Active Targets
- @cindex stacking targets
- @cindex active targets
- @cindex multiple targets
- There are multiple classes of targets such as: processes, executable files or
- recording sessions. Core files belong to the process class, making core file
- and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently
- on multiple active targets, one in each class. This allows you to (for
- example) start a process and inspect its activity, while still having access to
- the executable file after the process finishes. Or if you start process
- recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are
- presented a virtual layer of the recording target, while the process target
- remains stopped at the chronologically last point of the process execution.
- Use the @code{core-file} and @code{exec-file} commands to select a new core
- file or executable target (@pxref{Files, ,Commands to Specify Files}). To
- specify as a target a process that is already running, use the @code{attach}
- command (@pxref{Attach, ,Debugging an Already-running Process}).
- @node Target Commands
- @section Commands for Managing Targets
- @table @code
- @item target @var{type} @var{parameters}
- Connects the @value{GDBN} host environment to a target machine or
- process. A target is typically a protocol for talking to debugging
- facilities. You use the argument @var{type} to specify the type or
- protocol of the target machine.
- Further @var{parameters} are interpreted by the target protocol, but
- typically include things like device names or host names to connect
- with, process numbers, and baud rates.
- The @code{target} command does not repeat if you press @key{RET} again
- after executing the command.
- @kindex help target
- @item help target
- Displays the names of all targets available. To display targets
- currently selected, use either @code{info target} or @code{info files}
- (@pxref{Files, ,Commands to Specify Files}).
- @item help target @var{name}
- Describe a particular target, including any parameters necessary to
- select it.
- @kindex set gnutarget
- @item set gnutarget @var{args}
- @value{GDBN} uses its own library BFD to read your files. @value{GDBN}
- knows whether it is reading an @dfn{executable},
- a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
- with the @code{set gnutarget} command. Unlike most @code{target} commands,
- with @code{gnutarget} the @code{target} refers to a program, not a machine.
- @quotation
- @emph{Warning:} To specify a file format with @code{set gnutarget},
- you must know the actual BFD name.
- @end quotation
- @noindent
- @xref{Files, , Commands to Specify Files}.
- @kindex show gnutarget
- @item show gnutarget
- Use the @code{show gnutarget} command to display what file format
- @code{gnutarget} is set to read. If you have not set @code{gnutarget},
- @value{GDBN} will determine the file format for each file automatically,
- and @code{show gnutarget} displays @samp{The current BFD target is "auto"}.
- @end table
- @cindex common targets
- Here are some common targets (available, or not, depending on the GDB
- configuration):
- @table @code
- @kindex target
- @item target exec @var{program}
- @cindex executable file target
- An executable file. @samp{target exec @var{program}} is the same as
- @samp{exec-file @var{program}}.
- @item target core @var{filename}
- @cindex core dump file target
- A core dump file. @samp{target core @var{filename}} is the same as
- @samp{core-file @var{filename}}.
- @item target remote @var{medium}
- @cindex remote target
- A remote system connected to @value{GDBN} via a serial line or network
- connection. This command tells @value{GDBN} to use its own remote
- protocol over @var{medium} for debugging. @xref{Remote Debugging}.
- For example, if you have a board connected to @file{/dev/ttya} on the
- machine running @value{GDBN}, you could say:
- @smallexample
- target remote /dev/ttya
- @end smallexample
- @code{target remote} supports the @code{load} command. This is only
- useful if you have some other way of getting the stub to the target
- system, and you can put it somewhere in memory where it won't get
- clobbered by the download.
- @item target sim @r{[}@var{simargs}@r{]} @dots{}
- @cindex built-in simulator target
- Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
- In general,
- @smallexample
- target sim
- load
- run
- @end smallexample
- @noindent
- works; however, you cannot assume that a specific memory map, device
- drivers, or even basic I/O is available, although some simulators do
- provide these. For info about any processor-specific simulator details,
- see the appropriate section in @ref{Embedded Processors, ,Embedded
- Processors}.
- @item target native
- @cindex native target
- Setup for local/native process debugging. Useful to make the
- @code{run} command spawn native processes (likewise @code{attach},
- etc.@:) even when @code{set auto-connect-native-target} is @code{off}
- (@pxref{set auto-connect-native-target}).
- @end table
- Different targets are available on different configurations of @value{GDBN};
- your configuration may have more or fewer targets.
- Many remote targets require you to download the executable's code once
- you've successfully established a connection. You may wish to control
- various aspects of this process.
- @table @code
- @item set hash
- @kindex set hash@r{, for remote monitors}
- @cindex hash mark while downloading
- This command controls whether a hash mark @samp{#} is displayed while
- downloading a file to the remote monitor. If on, a hash mark is
- displayed after each S-record is successfully downloaded to the
- monitor.
- @item show hash
- @kindex show hash@r{, for remote monitors}
- Show the current status of displaying the hash mark.
- @item set debug monitor
- @kindex set debug monitor
- @cindex display remote monitor communications
- Enable or disable display of communications messages between
- @value{GDBN} and the remote monitor.
- @item show debug monitor
- @kindex show debug monitor
- Show the current status of displaying communications between
- @value{GDBN} and the remote monitor.
- @end table
- @table @code
- @kindex load @var{filename} @var{offset}
- @item load @var{filename} @var{offset}
- @anchor{load}
- Depending on what remote debugging facilities are configured into
- @value{GDBN}, the @code{load} command may be available. Where it exists, it
- is meant to make @var{filename} (an executable) available for debugging
- on the remote system---by downloading, or dynamic linking, for example.
- @code{load} also records the @var{filename} symbol table in @value{GDBN}, like
- the @code{add-symbol-file} command.
- If your @value{GDBN} does not have a @code{load} command, attempting to
- execute it gets the error message ``@code{You can't do that when your
- target is @dots{}}''
- The file is loaded at whatever address is specified in the executable.
- For some object file formats, you can specify the load address when you
- link the program; for other formats, like a.out, the object file format
- specifies a fixed address.
- @c FIXME! This would be a good place for an xref to the GNU linker doc.
- It is also possible to tell @value{GDBN} to load the executable file at a
- specific offset described by the optional argument @var{offset}. When
- @var{offset} is provided, @var{filename} must also be provided.
- Depending on the remote side capabilities, @value{GDBN} may be able to
- load programs into flash memory.
- @code{load} does not repeat if you press @key{RET} again after using it.
- @end table
- @table @code
- @kindex flash-erase
- @item flash-erase
- @anchor{flash-erase}
- Erases all known flash memory regions on the target.
- @end table
- @node Byte Order
- @section Choosing Target Byte Order
- @cindex choosing target byte order
- @cindex target byte order
- Some types of processors, such as the @acronym{MIPS}, PowerPC, and Renesas SH,
- offer the ability to run either big-endian or little-endian byte
- orders. Usually the executable or symbol will include a bit to
- designate the endian-ness, and you will not need to worry about
- which to use. However, you may still find it useful to adjust
- @value{GDBN}'s idea of processor endian-ness manually.
- @table @code
- @kindex set endian
- @item set endian big
- Instruct @value{GDBN} to assume the target is big-endian.
- @item set endian little
- Instruct @value{GDBN} to assume the target is little-endian.
- @item set endian auto
- Instruct @value{GDBN} to use the byte order associated with the
- executable.
- @item show endian
- Display @value{GDBN}'s current idea of the target byte order.
- @end table
- If the @code{set endian auto} mode is in effect and no executable has
- been selected, then the endianness used is the last one chosen either
- by one of the @code{set endian big} and @code{set endian little}
- commands or by inferring from the last executable used. If no
- endianness has been previously chosen, then the default for this mode
- is inferred from the target @value{GDBN} has been built for, and is
- @code{little} if the name of the target CPU has an @code{el} suffix
- and @code{big} otherwise.
- Note that these commands merely adjust interpretation of symbolic
- data on the host, and that they have absolutely no effect on the
- target system.
- @node Remote Debugging
- @chapter Debugging Remote Programs
- @cindex remote debugging
- If you are trying to debug a program running on a machine that cannot run
- @value{GDBN} in the usual way, it is often useful to use remote debugging.
- For example, you might use remote debugging on an operating system kernel,
- or on a small system which does not have a general purpose operating system
- powerful enough to run a full-featured debugger.
- Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
- to make this work with particular debugging targets. In addition,
- @value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
- but not specific to any particular target system) which you can use if you
- write the remote stubs---the code that runs on the remote system to
- communicate with @value{GDBN}.
- Other remote targets may be available in your
- configuration of @value{GDBN}; use @code{help target} to list them.
- @menu
- * Connecting:: Connecting to a remote target
- * File Transfer:: Sending files to a remote system
- * Server:: Using the gdbserver program
- * Remote Configuration:: Remote configuration
- * Remote Stub:: Implementing a remote stub
- @end menu
- @node Connecting
- @section Connecting to a Remote Target
- @cindex remote debugging, connecting
- @cindex @code{gdbserver}, connecting
- @cindex remote debugging, types of connections
- @cindex @code{gdbserver}, types of connections
- @cindex @code{gdbserver}, @code{target remote} mode
- @cindex @code{gdbserver}, @code{target extended-remote} mode
- This section describes how to connect to a remote target, including the
- types of connections and their differences, how to set up executable and
- symbol files on the host and target, and the commands used for
- connecting to and disconnecting from the remote target.
- @subsection Types of Remote Connections
- @value{GDBN} supports two types of remote connections, @code{target remote}
- mode and @code{target extended-remote} mode. Note that many remote targets
- support only @code{target remote} mode. There are several major
- differences between the two types of connections, enumerated here:
- @table @asis
- @cindex remote debugging, detach and program exit
- @item Result of detach or program exit
- @strong{With target remote mode:} When the debugged program exits or you
- detach from it, @value{GDBN} disconnects from the target. When using
- @code{gdbserver}, @code{gdbserver} will exit.
- @strong{With target extended-remote mode:} When the debugged program exits or
- you detach from it, @value{GDBN} remains connected to the target, even
- though no program is running. You can rerun the program, attach to a
- running program, or use @code{monitor} commands specific to the target.
- When using @code{gdbserver} in this case, it does not exit unless it was
- invoked using the @option{--once} option. If the @option{--once} option
- was not used, you can ask @code{gdbserver} to exit using the
- @code{monitor exit} command (@pxref{Monitor Commands for gdbserver}).
- @item Specifying the program to debug
- For both connection types you use the @code{file} command to specify the
- program on the host system. If you are using @code{gdbserver} there are
- some differences in how to specify the location of the program on the
- target.
- @strong{With target remote mode:} You must either specify the program to debug
- on the @code{gdbserver} command line or use the @option{--attach} option
- (@pxref{Attaching to a program,,Attaching to a Running Program}).
- @cindex @option{--multi}, @code{gdbserver} option
- @strong{With target extended-remote mode:} You may specify the program to debug
- on the @code{gdbserver} command line, or you can load the program or attach
- to it using @value{GDBN} commands after connecting to @code{gdbserver}.
- @anchor{--multi Option in Types of Remote Connnections}
- You can start @code{gdbserver} without supplying an initial command to run
- or process ID to attach. To do this, use the @option{--multi} command line
- option. Then you can connect using @code{target extended-remote} and start
- the program you want to debug (see below for details on using the
- @code{run} command in this scenario). Note that the conditions under which
- @code{gdbserver} terminates depend on how @value{GDBN} connects to it
- (@code{target remote} or @code{target extended-remote}). The
- @option{--multi} option to @code{gdbserver} has no influence on that.
- @item The @code{run} command
- @strong{With target remote mode:} The @code{run} command is not
- supported. Once a connection has been established, you can use all
- the usual @value{GDBN} commands to examine and change data. The
- remote program is already running, so you can use commands like
- @kbd{step} and @kbd{continue}.
- @strong{With target extended-remote mode:} The @code{run} command is
- supported. The @code{run} command uses the value set by
- @code{set remote exec-file} (@pxref{set remote exec-file}) to select
- the program to run. Command line arguments are supported, except for
- wildcard expansion and I/O redirection (@pxref{Arguments}).
- If you specify the program to debug on the command line, then the
- @code{run} command is not required to start execution, and you can
- resume using commands like @kbd{step} and @kbd{continue} as with
- @code{target remote} mode.
- @anchor{Attaching in Types of Remote Connections}
- @item Attaching
- @strong{With target remote mode:} The @value{GDBN} command @code{attach} is
- not supported. To attach to a running program using @code{gdbserver}, you
- must use the @option{--attach} option (@pxref{Running gdbserver}).
- @strong{With target extended-remote mode:} To attach to a running program,
- you may use the @code{attach} command after the connection has been
- established. If you are using @code{gdbserver}, you may also invoke
- @code{gdbserver} using the @option{--attach} option
- (@pxref{Running gdbserver}).
- Some remote targets allow @value{GDBN} to determine the executable file running
- in the process the debugger is attaching to. In such a case, @value{GDBN}
- uses the value of @code{exec-file-mismatch} to handle a possible mismatch
- between the executable file name running in the process and the name of the
- current exec-file loaded by @value{GDBN} (@pxref{set exec-file-mismatch}).
- @end table
- @anchor{Host and target files}
- @subsection Host and Target Files
- @cindex remote debugging, symbol files
- @cindex symbol files, remote debugging
- @value{GDBN}, running on the host, needs access to symbol and debugging
- information for your program running on the target. This requires
- access to an unstripped copy of your program, and possibly any associated
- symbol files. Note that this section applies equally to both @code{target
- remote} mode and @code{target extended-remote} mode.
- Some remote targets (@pxref{qXfer executable filename read}, and
- @pxref{Host I/O Packets}) allow @value{GDBN} to access program files over
- the same connection used to communicate with @value{GDBN}. With such a
- target, if the remote program is unstripped, the only command you need is
- @code{target remote} (or @code{target extended-remote}).
- If the remote program is stripped, or the target does not support remote
- program file access, start up @value{GDBN} using the name of the local
- unstripped copy of your program as the first argument, or use the
- @code{file} command. Use @code{set sysroot} to specify the location (on
- the host) of target libraries (unless your @value{GDBN} was compiled with
- the correct sysroot using @code{--with-sysroot}). Alternatively, you
- may use @code{set solib-search-path} to specify how @value{GDBN} locates
- target libraries.
- The symbol file and target libraries must exactly match the executable
- and libraries on the target, with one exception: the files on the host
- system should not be stripped, even if the files on the target system
- are. Mismatched or missing files will lead to confusing results
- during debugging. On @sc{gnu}/Linux targets, mismatched or missing
- files may also prevent @code{gdbserver} from debugging multi-threaded
- programs.
- @subsection Remote Connection Commands
- @cindex remote connection commands
- @value{GDBN} can communicate with the target over a serial line, a
- local Unix domain socket, or
- over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
- each case, @value{GDBN} uses the same protocol for debugging your
- program; only the medium carrying the debugging packets varies. The
- @code{target remote} and @code{target extended-remote} commands
- establish a connection to the target. Both commands accept the same
- arguments, which indicate the medium to use:
- @table @code
- @item target remote @var{serial-device}
- @itemx target extended-remote @var{serial-device}
- @cindex serial line, @code{target remote}
- Use @var{serial-device} to communicate with the target. For example,
- to use a serial line connected to the device named @file{/dev/ttyb}:
- @smallexample
- target remote /dev/ttyb
- @end smallexample
- If you're using a serial line, you may want to give @value{GDBN} the
- @samp{--baud} option, or use the @code{set serial baud} command
- (@pxref{Remote Configuration, set serial baud}) before the
- @code{target} command.
- @item target remote @var{local-socket}
- @itemx target extended-remote @var{local-socket}
- @cindex local socket, @code{target remote}
- @cindex Unix domain socket
- Use @var{local-socket} to communicate with the target. For example,
- to use a local Unix domain socket bound to the file system entry @file{/tmp/gdb-socket0}:
- @smallexample
- target remote /tmp/gdb-socket0
- @end smallexample
- Note that this command has the same form as the command to connect
- to a serial line. @value{GDBN} will automatically determine which
- kind of file you have specified and will make the appropriate kind
- of connection.
- This feature is not available if the host system does not support
- Unix domain sockets.
- @item target remote @code{@var{host}:@var{port}}
- @itemx target remote @code{[@var{host}]:@var{port}}
- @itemx target remote @code{tcp:@var{host}:@var{port}}
- @itemx target remote @code{tcp:[@var{host}]:@var{port}}
- @itemx target remote @code{tcp4:@var{host}:@var{port}}
- @itemx target remote @code{tcp6:@var{host}:@var{port}}
- @itemx target remote @code{tcp6:[@var{host}]:@var{port}}
- @itemx target extended-remote @code{@var{host}:@var{port}}
- @itemx target extended-remote @code{[@var{host}]:@var{port}}
- @itemx target extended-remote @code{tcp:@var{host}:@var{port}}
- @itemx target extended-remote @code{tcp:[@var{host}]:@var{port}}
- @itemx target extended-remote @code{tcp4:@var{host}:@var{port}}
- @itemx target extended-remote @code{tcp6:@var{host}:@var{port}}
- @itemx target extended-remote @code{tcp6:[@var{host}]:@var{port}}
- @cindex @acronym{TCP} port, @code{target remote}
- Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
- The @var{host} may be either a host name, a numeric @acronym{IPv4}
- address, or a numeric @acronym{IPv6} address (with or without the
- square brackets to separate the address from the port); @var{port}
- must be a decimal number. The @var{host} could be the target machine
- itself, if it is directly connected to the net, or it might be a
- terminal server which in turn has a serial line to the target.
- For example, to connect to port 2828 on a terminal server named
- @code{manyfarms}:
- @smallexample
- target remote manyfarms:2828
- @end smallexample
- To connect to port 2828 on a terminal server whose address is
- @code{2001:0db8:85a3:0000:0000:8a2e:0370:7334}, you can either use the
- square bracket syntax:
- @smallexample
- target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828
- @end smallexample
- @noindent
- or explicitly specify the @acronym{IPv6} protocol:
- @smallexample
- target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828
- @end smallexample
- This last example may be confusing to the reader, because there is no
- visible separation between the hostname and the port number.
- Therefore, we recommend the user to provide @acronym{IPv6} addresses
- using square brackets for clarity. However, it is important to
- mention that for @value{GDBN} there is no ambiguity: the number after
- the last colon is considered to be the port number.
- If your remote target is actually running on the same machine as your
- debugger session (e.g.@: a simulator for your target running on the
- same host), you can omit the hostname. For example, to connect to
- port 1234 on your local machine:
- @smallexample
- target remote :1234
- @end smallexample
- @noindent
- Note that the colon is still required here.
- @item target remote @code{udp:@var{host}:@var{port}}
- @itemx target remote @code{udp:[@var{host}]:@var{port}}
- @itemx target remote @code{udp4:@var{host}:@var{port}}
- @itemx target remote @code{udp6:[@var{host}]:@var{port}}
- @itemx target extended-remote @code{udp:@var{host}:@var{port}}
- @itemx target extended-remote @code{udp:@var{host}:@var{port}}
- @itemx target extended-remote @code{udp:[@var{host}]:@var{port}}
- @itemx target extended-remote @code{udp4:@var{host}:@var{port}}
- @itemx target extended-remote @code{udp6:@var{host}:@var{port}}
- @itemx target extended-remote @code{udp6:[@var{host}]:@var{port}}
- @cindex @acronym{UDP} port, @code{target remote}
- Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
- connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
- @smallexample
- target remote udp:manyfarms:2828
- @end smallexample
- When using a @acronym{UDP} connection for remote debugging, you should
- keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP}
- can silently drop packets on busy or unreliable networks, which will
- cause havoc with your debugging session.
- @item target remote | @var{command}
- @itemx target extended-remote | @var{command}
- @cindex pipe, @code{target remote} to
- Run @var{command} in the background and communicate with it using a
- pipe. The @var{command} is a shell command, to be parsed and expanded
- by the system's command shell, @code{/bin/sh}; it should expect remote
- protocol packets on its standard input, and send replies on its
- standard output. You could use this to run a stand-alone simulator
- that speaks the remote debugging protocol, to make net connections
- using programs like @code{ssh}, or for other similar tricks.
- If @var{command} closes its standard output (perhaps by exiting),
- @value{GDBN} will try to send it a @code{SIGTERM} signal. (If the
- program has already exited, this will have no effect.)
- @end table
- @cindex interrupting remote programs
- @cindex remote programs, interrupting
- Whenever @value{GDBN} is waiting for the remote program, if you type the
- interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the
- program. This may or may not succeed, depending in part on the hardware
- and the serial drivers the remote system uses. If you type the
- interrupt character once again, @value{GDBN} displays this prompt:
- @smallexample
- Interrupted while waiting for the program.
- Give up (and stop debugging it)? (y or n)
- @end smallexample
- In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons
- the remote debugging session. (If you decide you want to try again later,
- you can use @kbd{target remote} again to connect once more.) If you type
- @kbd{n}, @value{GDBN} goes back to waiting.
- In @code{target extended-remote} mode, typing @kbd{n} will leave
- @value{GDBN} connected to the target.
- @table @code
- @kindex detach (remote)
- @item detach
- When you have finished debugging the remote program, you can use the
- @code{detach} command to release it from @value{GDBN} control.
- Detaching from the target normally resumes its execution, but the results
- will depend on your particular remote stub. After the @code{detach}
- command in @code{target remote} mode, @value{GDBN} is free to connect to
- another target. In @code{target extended-remote} mode, @value{GDBN} is
- still connected to the target.
- @kindex disconnect
- @item disconnect
- The @code{disconnect} command closes the connection to the target, and
- the target is generally not resumed. It will wait for @value{GDBN}
- (this instance or another one) to connect and continue debugging. After
- the @code{disconnect} command, @value{GDBN} is again free to connect to
- another target.
- @cindex send command to remote monitor
- @cindex extend @value{GDBN} for remote targets
- @cindex add new commands for external monitor
- @kindex monitor
- @item monitor @var{cmd}
- This command allows you to send arbitrary commands directly to the
- remote monitor. Since @value{GDBN} doesn't care about the commands it
- sends like this, this command is the way to extend @value{GDBN}---you
- can add new commands that only the external monitor will understand
- and implement.
- @end table
- @node File Transfer
- @section Sending files to a remote system
- @cindex remote target, file transfer
- @cindex file transfer
- @cindex sending files to remote systems
- Some remote targets offer the ability to transfer files over the same
- connection used to communicate with @value{GDBN}. This is convenient
- for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems
- running @code{gdbserver} over a network interface. For other targets,
- e.g.@: embedded devices with only a single serial port, this may be
- the only way to upload or download files.
- Not all remote targets support these commands.
- @table @code
- @kindex remote put
- @item remote put @var{hostfile} @var{targetfile}
- Copy file @var{hostfile} from the host system (the machine running
- @value{GDBN}) to @var{targetfile} on the target system.
- @kindex remote get
- @item remote get @var{targetfile} @var{hostfile}
- Copy file @var{targetfile} from the target system to @var{hostfile}
- on the host system.
- @kindex remote delete
- @item remote delete @var{targetfile}
- Delete @var{targetfile} from the target system.
- @end table
- @node Server
- @section Using the @code{gdbserver} Program
- @kindex gdbserver
- @cindex remote connection without stubs
- @code{gdbserver} is a control program for Unix-like systems, which
- allows you to connect your program with a remote @value{GDBN} via
- @code{target remote} or @code{target extended-remote}---but without
- linking in the usual debugging stub.
- @code{gdbserver} is not a complete replacement for the debugging stubs,
- because it requires essentially the same operating-system facilities
- that @value{GDBN} itself does. In fact, a system that can run
- @code{gdbserver} to connect to a remote @value{GDBN} could also run
- @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
- because it is a much smaller program than @value{GDBN} itself. It is
- also easier to port than all of @value{GDBN}, so you may be able to get
- started more quickly on a new system by using @code{gdbserver}.
- Finally, if you develop code for real-time systems, you may find that
- the tradeoffs involved in real-time operation make it more convenient to
- do as much development work as possible on another system, for example
- by cross-compiling. You can use @code{gdbserver} to make a similar
- choice for debugging.
- @value{GDBN} and @code{gdbserver} communicate via either a serial line
- or a TCP connection, using the standard @value{GDBN} remote serial
- protocol.
- @quotation
- @emph{Warning:} @code{gdbserver} does not have any built-in security.
- Do not run @code{gdbserver} connected to any public network; a
- @value{GDBN} connection to @code{gdbserver} provides access to the
- target system with the same privileges as the user running
- @code{gdbserver}.
- @end quotation
- @anchor{Running gdbserver}
- @subsection Running @code{gdbserver}
- @cindex arguments, to @code{gdbserver}
- @cindex @code{gdbserver}, command-line arguments
- Run @code{gdbserver} on the target system. You need a copy of the
- program you want to debug, including any libraries it requires.
- @code{gdbserver} does not need your program's symbol table, so you can
- strip the program if necessary to save space. @value{GDBN} on the host
- system does all the symbol handling.
- To use the server, you must tell it how to communicate with @value{GDBN};
- the name of your program; and the arguments for your program. The usual
- syntax is:
- @smallexample
- target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
- @end smallexample
- @var{comm} is either a device name (to use a serial line), or a TCP
- hostname and portnumber, or @code{-} or @code{stdio} to use
- stdin/stdout of @code{gdbserver}.
- For example, to debug Emacs with the argument
- @samp{foo.txt} and communicate with @value{GDBN} over the serial port
- @file{/dev/com1}:
- @smallexample
- target> gdbserver /dev/com1 emacs foo.txt
- @end smallexample
- @code{gdbserver} waits passively for the host @value{GDBN} to communicate
- with it.
- To use a TCP connection instead of a serial line:
- @smallexample
- target> gdbserver host:2345 emacs foo.txt
- @end smallexample
- The only difference from the previous example is the first argument,
- specifying that you are communicating with the host @value{GDBN} via
- TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
- expect a TCP connection from machine @samp{host} to local TCP port 2345.
- (Currently, the @samp{host} part is ignored.) You can choose any number
- you want for the port number as long as it does not conflict with any
- TCP ports already in use on the target system (for example, @code{23} is
- reserved for @code{telnet}).@footnote{If you choose a port number that
- conflicts with another service, @code{gdbserver} prints an error message
- and exits.} You must use the same port number with the host @value{GDBN}
- @code{target remote} command.
- The @code{stdio} connection is useful when starting @code{gdbserver}
- with ssh:
- @smallexample
- (gdb) target remote | ssh -T hostname gdbserver - hello
- @end smallexample
- The @samp{-T} option to ssh is provided because we don't need a remote pty,
- and we don't want escape-character handling. Ssh does this by default when
- a command is provided, the flag is provided to make it explicit.
- You could elide it if you want to.
- Programs started with stdio-connected gdbserver have @file{/dev/null} for
- @code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for
- display through a pipe connected to gdbserver.
- Both @code{stdout} and @code{stderr} use the same pipe.
- @anchor{Attaching to a program}
- @subsubsection Attaching to a Running Program
- @cindex attach to a program, @code{gdbserver}
- @cindex @option{--attach}, @code{gdbserver} option
- On some targets, @code{gdbserver} can also attach to running programs.
- This is accomplished via the @code{--attach} argument. The syntax is:
- @smallexample
- target> gdbserver --attach @var{comm} @var{pid}
- @end smallexample
- @var{pid} is the process ID of a currently running process. It isn't
- necessary to point @code{gdbserver} at a binary for the running process.
- In @code{target extended-remote} mode, you can also attach using the
- @value{GDBN} attach command
- (@pxref{Attaching in Types of Remote Connections}).
- @pindex pidof
- You can debug processes by name instead of process ID if your target has the
- @code{pidof} utility:
- @smallexample
- target> gdbserver --attach @var{comm} `pidof @var{program}`
- @end smallexample
- In case more than one copy of @var{program} is running, or @var{program}
- has multiple threads, most versions of @code{pidof} support the
- @code{-s} option to only return the first process ID.
- @subsubsection TCP port allocation lifecycle of @code{gdbserver}
- This section applies only when @code{gdbserver} is run to listen on a TCP
- port.
- @code{gdbserver} normally terminates after all of its debugged processes have
- terminated in @kbd{target remote} mode. On the other hand, for @kbd{target
- extended-remote}, @code{gdbserver} stays running even with no processes left.
- @value{GDBN} normally terminates the spawned debugged process on its exit,
- which normally also terminates @code{gdbserver} in the @kbd{target remote}
- mode. Therefore, when the connection drops unexpectedly, and @value{GDBN}
- cannot ask @code{gdbserver} to kill its debugged processes, @code{gdbserver}
- stays running even in the @kbd{target remote} mode.
- When @code{gdbserver} stays running, @value{GDBN} can connect to it again later.
- Such reconnecting is useful for features like @ref{disconnected tracing}. For
- completeness, at most one @value{GDBN} can be connected at a time.
- @cindex @option{--once}, @code{gdbserver} option
- By default, @code{gdbserver} keeps the listening TCP port open, so that
- subsequent connections are possible. However, if you start @code{gdbserver}
- with the @option{--once} option, it will stop listening for any further
- connection attempts after connecting to the first @value{GDBN} session. This
- means no further connections to @code{gdbserver} will be possible after the
- first one. It also means @code{gdbserver} will terminate after the first
- connection with remote @value{GDBN} has closed, even for unexpectedly closed
- connections and even in the @kbd{target extended-remote} mode. The
- @option{--once} option allows reusing the same port number for connecting to
- multiple instances of @code{gdbserver} running on the same host, since each
- instance closes its port after the first connection.
- @anchor{Other Command-Line Arguments for gdbserver}
- @subsubsection Other Command-Line Arguments for @code{gdbserver}
- You can use the @option{--multi} option to start @code{gdbserver} without
- specifying a program to debug or a process to attach to. Then you can
- attach in @code{target extended-remote} mode and run or attach to a
- program. For more information,
- @pxref{--multi Option in Types of Remote Connnections}.
- @cindex @option{--debug}, @code{gdbserver} option
- The @option{--debug} option tells @code{gdbserver} to display extra
- status information about the debugging process.
- @cindex @option{--remote-debug}, @code{gdbserver} option
- The @option{--remote-debug} option tells @code{gdbserver} to display
- remote protocol debug output.
- @cindex @option{--debug-file}, @code{gdbserver} option
- @cindex @code{gdbserver}, send all debug output to a single file
- The @option{--debug-file=@var{filename}} option tells @code{gdbserver} to
- write any debug output to the given @var{filename}. These options are intended
- for @code{gdbserver} development and for bug reports to the developers.
- @cindex @option{--debug-format}, @code{gdbserver} option
- The @option{--debug-format=option1[,option2,...]} option tells
- @code{gdbserver} to include additional information in each output.
- Possible options are:
- @table @code
- @item none
- Turn off all extra information in debugging output.
- @item all
- Turn on all extra information in debugging output.
- @item timestamps
- Include a timestamp in each line of debugging output.
- @end table
- Options are processed in order. Thus, for example, if @option{none}
- appears last then no additional information is added to debugging output.
- @cindex @option{--wrapper}, @code{gdbserver} option
- The @option{--wrapper} option specifies a wrapper to launch programs
- for debugging. The option should be followed by the name of the
- wrapper, then any command-line arguments to pass to the wrapper, then
- @kbd{--} indicating the end of the wrapper arguments.
- @code{gdbserver} runs the specified wrapper program with a combined
- command line including the wrapper arguments, then the name of the
- program to debug, then any arguments to the program. The wrapper
- runs until it executes your program, and then @value{GDBN} gains control.
- You can use any program that eventually calls @code{execve} with
- its arguments as a wrapper. Several standard Unix utilities do
- this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
- with @code{exec "$@@"} will also work.
- For example, you can use @code{env} to pass an environment variable to
- the debugged program, without setting the variable in @code{gdbserver}'s
- environment:
- @smallexample
- $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
- @end smallexample
- @cindex @option{--selftest}
- The @option{--selftest} option runs the self tests in @code{gdbserver}:
- @smallexample
- $ gdbserver --selftest
- Ran 2 unit tests, 0 failed
- @end smallexample
- These tests are disabled in release.
- @subsection Connecting to @code{gdbserver}
- The basic procedure for connecting to the remote target is:
- @itemize
- @item
- Run @value{GDBN} on the host system.
- @item
- Make sure you have the necessary symbol files
- (@pxref{Host and target files}).
- Load symbols for your application using the @code{file} command before you
- connect. Use @code{set sysroot} to locate target libraries (unless your
- @value{GDBN} was compiled with the correct sysroot using
- @code{--with-sysroot}).
- @item
- Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}).
- For TCP connections, you must start up @code{gdbserver} prior to using
- the @code{target} command. Otherwise you may get an error whose
- text depends on the host system, but which usually looks something like
- @samp{Connection refused}. Don't use the @code{load}
- command in @value{GDBN} when using @code{target remote} mode, since the
- program is already on the target.
- @end itemize
- @anchor{Monitor Commands for gdbserver}
- @subsection Monitor Commands for @code{gdbserver}
- @cindex monitor commands, for @code{gdbserver}
- During a @value{GDBN} session using @code{gdbserver}, you can use the
- @code{monitor} command to send special requests to @code{gdbserver}.
- Here are the available commands.
- @table @code
- @item monitor help
- List the available monitor commands.
- @item monitor set debug 0
- @itemx monitor set debug 1
- Disable or enable general debugging messages.
- @item monitor set remote-debug 0
- @itemx monitor set remote-debug 1
- Disable or enable specific debugging messages associated with the remote
- protocol (@pxref{Remote Protocol}).
- @item monitor set debug-file filename
- @itemx monitor set debug-file
- Send any debug output to the given file, or to stderr.
- @item monitor set debug-format option1@r{[},option2,...@r{]}
- Specify additional text to add to debugging messages.
- Possible options are:
- @table @code
- @item none
- Turn off all extra information in debugging output.
- @item all
- Turn on all extra information in debugging output.
- @item timestamps
- Include a timestamp in each line of debugging output.
- @end table
- Options are processed in order. Thus, for example, if @option{none}
- appears last then no additional information is added to debugging output.
- @item monitor set libthread-db-search-path [PATH]
- @cindex gdbserver, search path for @code{libthread_db}
- When this command is issued, @var{path} is a colon-separated list of
- directories to search for @code{libthread_db} (@pxref{Threads,,set
- libthread-db-search-path}). If you omit @var{path},
- @samp{libthread-db-search-path} will be reset to its default value.
- The special entry @samp{$pdir} for @samp{libthread-db-search-path} is
- not supported in @code{gdbserver}.
- @item monitor exit
- Tell gdbserver to exit immediately. This command should be followed by
- @code{disconnect} to close the debugging session. @code{gdbserver} will
- detach from any attached processes and kill any processes it created.
- Use @code{monitor exit} to terminate @code{gdbserver} at the end
- of a multi-process mode debug session.
- @end table
- @subsection Tracepoints support in @code{gdbserver}
- @cindex tracepoints support in @code{gdbserver}
- On some targets, @code{gdbserver} supports tracepoints, fast
- tracepoints and static tracepoints.
- For fast or static tracepoints to work, a special library called the
- @dfn{in-process agent} (IPA), must be loaded in the inferior process.
- This library is built and distributed as an integral part of
- @code{gdbserver}. In addition, support for static tracepoints
- requires building the in-process agent library with static tracepoints
- support. At present, the UST (LTTng Userspace Tracer,
- @url{http://lttng.org/ust}) tracing engine is supported. This support
- is automatically available if UST development headers are found in the
- standard include path when @code{gdbserver} is built, or if
- @code{gdbserver} was explicitly configured using @option{--with-ust}
- to point at such headers. You can explicitly disable the support
- using @option{--with-ust=no}.
- There are several ways to load the in-process agent in your program:
- @table @code
- @item Specifying it as dependency at link time
- You can link your program dynamically with the in-process agent
- library. On most systems, this is accomplished by adding
- @code{-linproctrace} to the link command.
- @item Using the system's preloading mechanisms
- You can force loading the in-process agent at startup time by using
- your system's support for preloading shared libraries. Many Unixes
- support the concept of preloading user defined libraries. In most
- cases, you do that by specifying @code{LD_PRELOAD=libinproctrace.so}
- in the environment. See also the description of @code{gdbserver}'s
- @option{--wrapper} command line option.
- @item Using @value{GDBN} to force loading the agent at run time
- On some systems, you can force the inferior to load a shared library,
- by calling a dynamic loader function in the inferior that takes care
- of dynamically looking up and loading a shared library. On most Unix
- systems, the function is @code{dlopen}. You'll use the @code{call}
- command for that. For example:
- @smallexample
- (@value{GDBP}) call dlopen ("libinproctrace.so", ...)
- @end smallexample
- Note that on most Unix systems, for the @code{dlopen} function to be
- available, the program needs to be linked with @code{-ldl}.
- @end table
- On systems that have a userspace dynamic loader, like most Unix
- systems, when you connect to @code{gdbserver} using @code{target
- remote}, you'll find that the program is stopped at the dynamic
- loader's entry point, and no shared library has been loaded in the
- program's address space yet, including the in-process agent. In that
- case, before being able to use any of the fast or static tracepoints
- features, you need to let the loader run and load the shared
- libraries. The simplest way to do that is to run the program to the
- main procedure. E.g., if debugging a C or C@t{++} program, start
- @code{gdbserver} like so:
- @smallexample
- $ gdbserver :9999 myprogram
- @end smallexample
- Start GDB and connect to @code{gdbserver} like so, and run to main:
- @smallexample
- $ gdb myprogram
- (@value{GDBP}) target remote myhost:9999
- 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2
- (@value{GDBP}) b main
- (@value{GDBP}) continue
- @end smallexample
- The in-process tracing agent library should now be loaded into the
- process; you can confirm it with the @code{info sharedlibrary}
- command, which will list @file{libinproctrace.so} as loaded in the
- process. You are now ready to install fast tracepoints, list static
- tracepoint markers, probe static tracepoints markers, and start
- tracing.
- @node Remote Configuration
- @section Remote Configuration
- @kindex set remote
- @kindex show remote
- This section documents the configuration options available when
- debugging remote programs. For the options related to the File I/O
- extensions of the remote protocol, see @ref{system,
- system-call-allowed}.
- @table @code
- @item set remoteaddresssize @var{bits}
- @cindex address size for remote targets
- @cindex bits in remote address
- Set the maximum size of address in a memory packet to the specified
- number of bits. @value{GDBN} will mask off the address bits above
- that number, when it passes addresses to the remote target. The
- default value is the number of bits in the target's address.
- @item show remoteaddresssize
- Show the current value of remote address size in bits.
- @item set serial baud @var{n}
- @cindex baud rate for remote targets
- Set the baud rate for the remote serial I/O to @var{n} baud. The
- value is used to set the speed of the serial port used for debugging
- remote targets.
- @item show serial baud
- Show the current speed of the remote connection.
- @item set serial parity @var{parity}
- Set the parity for the remote serial I/O. Supported values of @var{parity} are:
- @code{even}, @code{none}, and @code{odd}. The default is @code{none}.
- @item show serial parity
- Show the current parity of the serial port.
- @item set remotebreak
- @cindex interrupt remote programs
- @cindex BREAK signal instead of Ctrl-C
- @anchor{set remotebreak}
- If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
- when you type @kbd{Ctrl-c} to interrupt the program running
- on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C}
- character instead. The default is off, since most remote systems
- expect to see @samp{Ctrl-C} as the interrupt signal.
- @item show remotebreak
- Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
- interrupt the remote program.
- @item set remoteflow on
- @itemx set remoteflow off
- @kindex set remoteflow
- Enable or disable hardware flow control (@code{RTS}/@code{CTS})
- on the serial port used to communicate to the remote target.
- @item show remoteflow
- @kindex show remoteflow
- Show the current setting of hardware flow control.
- @item set remotelogbase @var{base}
- Set the base (a.k.a.@: radix) of logging serial protocol
- communications to @var{base}. Supported values of @var{base} are:
- @code{ascii}, @code{octal}, and @code{hex}. The default is
- @code{ascii}.
- @item show remotelogbase
- Show the current setting of the radix for logging remote serial
- protocol.
- @item set remotelogfile @var{file}
- @cindex record serial communications on file
- Record remote serial communications on the named @var{file}. The
- default is not to record at all.
- @item show remotelogfile
- Show the current setting of the file name on which to record the
- serial communications.
- @item set remotetimeout @var{num}
- @cindex timeout for serial communications
- @cindex remote timeout
- Set the timeout limit to wait for the remote target to respond to
- @var{num} seconds. The default is 2 seconds.
- @item show remotetimeout
- Show the current number of seconds to wait for the remote target
- responses.
- @cindex limit hardware breakpoints and watchpoints
- @cindex remote target, limit break- and watchpoints
- @anchor{set remote hardware-watchpoint-limit}
- @anchor{set remote hardware-breakpoint-limit}
- @item set remote hardware-watchpoint-limit @var{limit}
- @itemx set remote hardware-breakpoint-limit @var{limit}
- Restrict @value{GDBN} to using @var{limit} remote hardware watchpoints
- or breakpoints. The @var{limit} can be set to 0 to disable hardware
- watchpoints or breakpoints, and @code{unlimited} for unlimited
- watchpoints or breakpoints.
- @item show remote hardware-watchpoint-limit
- @itemx show remote hardware-breakpoint-limit
- Show the current limit for the number of hardware watchpoints or
- breakpoints that @value{GDBN} can use.
- @cindex limit hardware watchpoints length
- @cindex remote target, limit watchpoints length
- @anchor{set remote hardware-watchpoint-length-limit}
- @item set remote hardware-watchpoint-length-limit @var{limit}
- Restrict @value{GDBN} to using @var{limit} bytes for the maximum
- length of a remote hardware watchpoint. A @var{limit} of 0 disables
- hardware watchpoints and @code{unlimited} allows watchpoints of any
- length.
- @item show remote hardware-watchpoint-length-limit
- Show the current limit (in bytes) of the maximum length of
- a remote hardware watchpoint.
- @item set remote exec-file @var{filename}
- @itemx show remote exec-file
- @anchor{set remote exec-file}
- @cindex executable file, for remote target
- Select the file used for @code{run} with @code{target
- extended-remote}. This should be set to a filename valid on the
- target system. If it is not set, the target will use a default
- filename (e.g.@: the last program run).
- @item set remote interrupt-sequence
- @cindex interrupt remote programs
- @cindex select Ctrl-C, BREAK or BREAK-g
- Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or
- @samp{BREAK-g} as the
- sequence to the remote target in order to interrupt the execution.
- @samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which
- is high level of serial line for some certain time.
- Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g.
- It is @code{BREAK} signal followed by character @code{g}.
- @item show remote interrupt-sequence
- Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g}
- is sent by @value{GDBN} to interrupt the remote program.
- @code{BREAK-g} is BREAK signal followed by @code{g} and
- also known as Magic SysRq g.
- @item set remote interrupt-on-connect
- @cindex send interrupt-sequence on start
- Specify whether interrupt-sequence is sent to remote target when
- @value{GDBN} connects to it. This is mostly needed when you debug
- Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g}
- which is known as Magic SysRq g in order to connect @value{GDBN}.
- @item show remote interrupt-on-connect
- Show whether interrupt-sequence is sent
- to remote target when @value{GDBN} connects to it.
- @kindex set tcp
- @kindex show tcp
- @item set tcp auto-retry on
- @cindex auto-retry, for remote TCP target
- Enable auto-retry for remote TCP connections. This is useful if the remote
- debugging agent is launched in parallel with @value{GDBN}; there is a race
- condition because the agent may not become ready to accept the connection
- before @value{GDBN} attempts to connect. When auto-retry is
- enabled, if the initial attempt to connect fails, @value{GDBN} reattempts
- to establish the connection using the timeout specified by
- @code{set tcp connect-timeout}.
- @item set tcp auto-retry off
- Do not auto-retry failed TCP connections.
- @item show tcp auto-retry
- Show the current auto-retry setting.
- @item set tcp connect-timeout @var{seconds}
- @itemx set tcp connect-timeout unlimited
- @cindex connection timeout, for remote TCP target
- @cindex timeout, for remote target connection
- Set the timeout for establishing a TCP connection to the remote target to
- @var{seconds}. The timeout affects both polling to retry failed connections
- (enabled by @code{set tcp auto-retry on}) and waiting for connections
- that are merely slow to complete, and represents an approximate cumulative
- value. If @var{seconds} is @code{unlimited}, there is no timeout and
- @value{GDBN} will keep attempting to establish a connection forever,
- unless interrupted with @kbd{Ctrl-c}. The default is 15 seconds.
- @item show tcp connect-timeout
- Show the current connection timeout setting.
- @end table
- @cindex remote packets, enabling and disabling
- The @value{GDBN} remote protocol autodetects the packets supported by
- your debugging stub. If you need to override the autodetection, you
- can use these commands to enable or disable individual packets. Each
- packet can be set to @samp{on} (the remote target supports this
- packet), @samp{off} (the remote target does not support this packet),
- or @samp{auto} (detect remote target support for this packet). They
- all default to @samp{auto}. For more information about each packet,
- see @ref{Remote Protocol}.
- During normal use, you should not have to use any of these commands.
- If you do, that may be a bug in your remote debugging stub, or a bug
- in @value{GDBN}. You may want to report the problem to the
- @value{GDBN} developers.
- For each packet @var{name}, the command to enable or disable the
- packet is @code{set remote @var{name}-packet}. The available settings
- are:
- @multitable @columnfractions 0.28 0.32 0.25
- @item Command Name
- @tab Remote Packet
- @tab Related Features
- @item @code{fetch-register}
- @tab @code{p}
- @tab @code{info registers}
- @item @code{set-register}
- @tab @code{P}
- @tab @code{set}
- @item @code{binary-download}
- @tab @code{X}
- @tab @code{load}, @code{set}
- @item @code{read-aux-vector}
- @tab @code{qXfer:auxv:read}
- @tab @code{info auxv}
- @item @code{symbol-lookup}
- @tab @code{qSymbol}
- @tab Detecting multiple threads
- @item @code{attach}
- @tab @code{vAttach}
- @tab @code{attach}
- @item @code{verbose-resume}
- @tab @code{vCont}
- @tab Stepping or resuming multiple threads
- @item @code{run}
- @tab @code{vRun}
- @tab @code{run}
- @item @code{software-breakpoint}
- @tab @code{Z0}
- @tab @code{break}
- @item @code{hardware-breakpoint}
- @tab @code{Z1}
- @tab @code{hbreak}
- @item @code{write-watchpoint}
- @tab @code{Z2}
- @tab @code{watch}
- @item @code{read-watchpoint}
- @tab @code{Z3}
- @tab @code{rwatch}
- @item @code{access-watchpoint}
- @tab @code{Z4}
- @tab @code{awatch}
- @item @code{pid-to-exec-file}
- @tab @code{qXfer:exec-file:read}
- @tab @code{attach}, @code{run}
- @item @code{target-features}
- @tab @code{qXfer:features:read}
- @tab @code{set architecture}
- @item @code{library-info}
- @tab @code{qXfer:libraries:read}
- @tab @code{info sharedlibrary}
- @item @code{memory-map}
- @tab @code{qXfer:memory-map:read}
- @tab @code{info mem}
- @item @code{read-sdata-object}
- @tab @code{qXfer:sdata:read}
- @tab @code{print $_sdata}
- @item @code{read-siginfo-object}
- @tab @code{qXfer:siginfo:read}
- @tab @code{print $_siginfo}
- @item @code{write-siginfo-object}
- @tab @code{qXfer:siginfo:write}
- @tab @code{set $_siginfo}
- @item @code{threads}
- @tab @code{qXfer:threads:read}
- @tab @code{info threads}
- @item @code{get-thread-local-@*storage-address}
- @tab @code{qGetTLSAddr}
- @tab Displaying @code{__thread} variables
- @item @code{get-thread-information-block-address}
- @tab @code{qGetTIBAddr}
- @tab Display MS-Windows Thread Information Block.
- @item @code{search-memory}
- @tab @code{qSearch:memory}
- @tab @code{find}
- @item @code{supported-packets}
- @tab @code{qSupported}
- @tab Remote communications parameters
- @item @code{catch-syscalls}
- @tab @code{QCatchSyscalls}
- @tab @code{catch syscall}
- @item @code{pass-signals}
- @tab @code{QPassSignals}
- @tab @code{handle @var{signal}}
- @item @code{program-signals}
- @tab @code{QProgramSignals}
- @tab @code{handle @var{signal}}
- @item @code{hostio-close-packet}
- @tab @code{vFile:close}
- @tab @code{remote get}, @code{remote put}
- @item @code{hostio-open-packet}
- @tab @code{vFile:open}
- @tab @code{remote get}, @code{remote put}
- @item @code{hostio-pread-packet}
- @tab @code{vFile:pread}
- @tab @code{remote get}, @code{remote put}
- @item @code{hostio-pwrite-packet}
- @tab @code{vFile:pwrite}
- @tab @code{remote get}, @code{remote put}
- @item @code{hostio-unlink-packet}
- @tab @code{vFile:unlink}
- @tab @code{remote delete}
- @item @code{hostio-readlink-packet}
- @tab @code{vFile:readlink}
- @tab Host I/O
- @item @code{hostio-fstat-packet}
- @tab @code{vFile:fstat}
- @tab Host I/O
- @item @code{hostio-setfs-packet}
- @tab @code{vFile:setfs}
- @tab Host I/O
- @item @code{noack-packet}
- @tab @code{QStartNoAckMode}
- @tab Packet acknowledgment
- @item @code{osdata}
- @tab @code{qXfer:osdata:read}
- @tab @code{info os}
- @item @code{query-attached}
- @tab @code{qAttached}
- @tab Querying remote process attach state.
- @item @code{trace-buffer-size}
- @tab @code{QTBuffer:size}
- @tab @code{set trace-buffer-size}
- @item @code{trace-status}
- @tab @code{qTStatus}
- @tab @code{tstatus}
- @item @code{traceframe-info}
- @tab @code{qXfer:traceframe-info:read}
- @tab Traceframe info
- @item @code{install-in-trace}
- @tab @code{InstallInTrace}
- @tab Install tracepoint in tracing
- @item @code{disable-randomization}
- @tab @code{QDisableRandomization}
- @tab @code{set disable-randomization}
- @item @code{startup-with-shell}
- @tab @code{QStartupWithShell}
- @tab @code{set startup-with-shell}
- @item @code{environment-hex-encoded}
- @tab @code{QEnvironmentHexEncoded}
- @tab @code{set environment}
- @item @code{environment-unset}
- @tab @code{QEnvironmentUnset}
- @tab @code{unset environment}
- @item @code{environment-reset}
- @tab @code{QEnvironmentReset}
- @tab @code{Reset the inferior environment (i.e., unset user-set variables)}
- @item @code{set-working-dir}
- @tab @code{QSetWorkingDir}
- @tab @code{set cwd}
- @item @code{conditional-breakpoints-packet}
- @tab @code{Z0 and Z1}
- @tab @code{Support for target-side breakpoint condition evaluation}
- @item @code{multiprocess-extensions}
- @tab @code{multiprocess extensions}
- @tab Debug multiple processes and remote process PID awareness
- @item @code{swbreak-feature}
- @tab @code{swbreak stop reason}
- @tab @code{break}
- @item @code{hwbreak-feature}
- @tab @code{hwbreak stop reason}
- @tab @code{hbreak}
- @item @code{fork-event-feature}
- @tab @code{fork stop reason}
- @tab @code{fork}
- @item @code{vfork-event-feature}
- @tab @code{vfork stop reason}
- @tab @code{vfork}
- @item @code{exec-event-feature}
- @tab @code{exec stop reason}
- @tab @code{exec}
- @item @code{thread-events}
- @tab @code{QThreadEvents}
- @tab Tracking thread lifetime.
- @item @code{no-resumed-stop-reply}
- @tab @code{no resumed thread left stop reply}
- @tab Tracking thread lifetime.
- @end multitable
- @node Remote Stub
- @section Implementing a Remote Stub
- @cindex debugging stub, example
- @cindex remote stub, example
- @cindex stub example, remote debugging
- The stub files provided with @value{GDBN} implement the target side of the
- communication protocol, and the @value{GDBN} side is implemented in the
- @value{GDBN} source file @file{remote.c}. Normally, you can simply allow
- these subroutines to communicate, and ignore the details. (If you're
- implementing your own stub file, you can still ignore the details: start
- with one of the existing stub files. @file{sparc-stub.c} is the best
- organized, and therefore the easiest to read.)
- @cindex remote serial debugging, overview
- To debug a program running on another machine (the debugging
- @dfn{target} machine), you must first arrange for all the usual
- prerequisites for the program to run by itself. For example, for a C
- program, you need:
- @enumerate
- @item
- A startup routine to set up the C runtime environment; these usually
- have a name like @file{crt0}. The startup routine may be supplied by
- your hardware supplier, or you may have to write your own.
- @item
- A C subroutine library to support your program's
- subroutine calls, notably managing input and output.
- @item
- A way of getting your program to the other machine---for example, a
- download program. These are often supplied by the hardware
- manufacturer, but you may have to write your own from hardware
- documentation.
- @end enumerate
- The next step is to arrange for your program to use a serial port to
- communicate with the machine where @value{GDBN} is running (the @dfn{host}
- machine). In general terms, the scheme looks like this:
- @table @emph
- @item On the host,
- @value{GDBN} already understands how to use this protocol; when everything
- else is set up, you can simply use the @samp{target remote} command
- (@pxref{Targets,,Specifying a Debugging Target}).
- @item On the target,
- you must link with your program a few special-purpose subroutines that
- implement the @value{GDBN} remote serial protocol. The file containing these
- subroutines is called a @dfn{debugging stub}.
- On certain remote targets, you can use an auxiliary program
- @code{gdbserver} instead of linking a stub into your program.
- @xref{Server,,Using the @code{gdbserver} Program}, for details.
- @end table
- The debugging stub is specific to the architecture of the remote
- machine; for example, use @file{sparc-stub.c} to debug programs on
- @sc{sparc} boards.
- @cindex remote serial stub list
- These working remote stubs are distributed with @value{GDBN}:
- @table @code
- @item i386-stub.c
- @cindex @file{i386-stub.c}
- @cindex Intel
- @cindex i386
- For Intel 386 and compatible architectures.
- @item m68k-stub.c
- @cindex @file{m68k-stub.c}
- @cindex Motorola 680x0
- @cindex m680x0
- For Motorola 680x0 architectures.
- @item sh-stub.c
- @cindex @file{sh-stub.c}
- @cindex Renesas
- @cindex SH
- For Renesas SH architectures.
- @item sparc-stub.c
- @cindex @file{sparc-stub.c}
- @cindex Sparc
- For @sc{sparc} architectures.
- @item sparcl-stub.c
- @cindex @file{sparcl-stub.c}
- @cindex Fujitsu
- @cindex SparcLite
- For Fujitsu @sc{sparclite} architectures.
- @end table
- The @file{README} file in the @value{GDBN} distribution may list other
- recently added stubs.
- @menu
- * Stub Contents:: What the stub can do for you
- * Bootstrapping:: What you must do for the stub
- * Debug Session:: Putting it all together
- @end menu
- @node Stub Contents
- @subsection What the Stub Can Do for You
- @cindex remote serial stub
- The debugging stub for your architecture supplies these three
- subroutines:
- @table @code
- @item set_debug_traps
- @findex set_debug_traps
- @cindex remote serial stub, initialization
- This routine arranges for @code{handle_exception} to run when your
- program stops. You must call this subroutine explicitly in your
- program's startup code.
- @item handle_exception
- @findex handle_exception
- @cindex remote serial stub, main routine
- This is the central workhorse, but your program never calls it
- explicitly---the setup code arranges for @code{handle_exception} to
- run when a trap is triggered.
- @code{handle_exception} takes control when your program stops during
- execution (for example, on a breakpoint), and mediates communications
- with @value{GDBN} on the host machine. This is where the communications
- protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
- representative on the target machine. It begins by sending summary
- information on the state of your program, then continues to execute,
- retrieving and transmitting any information @value{GDBN} needs, until you
- execute a @value{GDBN} command that makes your program resume; at that point,
- @code{handle_exception} returns control to your own code on the target
- machine.
- @item breakpoint
- @cindex @code{breakpoint} subroutine, remote
- Use this auxiliary subroutine to make your program contain a
- breakpoint. Depending on the particular situation, this may be the only
- way for @value{GDBN} to get control. For instance, if your target
- machine has some sort of interrupt button, you won't need to call this;
- pressing the interrupt button transfers control to
- @code{handle_exception}---in effect, to @value{GDBN}. On some machines,
- simply receiving characters on the serial port may also trigger a trap;
- again, in that situation, you don't need to call @code{breakpoint} from
- your own program---simply running @samp{target remote} from the host
- @value{GDBN} session gets control.
- Call @code{breakpoint} if none of these is true, or if you simply want
- to make certain your program stops at a predetermined point for the
- start of your debugging session.
- @end table
- @node Bootstrapping
- @subsection What You Must Do for the Stub
- @cindex remote stub, support routines
- The debugging stubs that come with @value{GDBN} are set up for a particular
- chip architecture, but they have no information about the rest of your
- debugging target machine.
- First of all you need to tell the stub how to communicate with the
- serial port.
- @table @code
- @item int getDebugChar()
- @findex getDebugChar
- Write this subroutine to read a single character from the serial port.
- It may be identical to @code{getchar} for your target system; a
- different name is used to allow you to distinguish the two if you wish.
- @item void putDebugChar(int)
- @findex putDebugChar
- Write this subroutine to write a single character to the serial port.
- It may be identical to @code{putchar} for your target system; a
- different name is used to allow you to distinguish the two if you wish.
- @end table
- @cindex control C, and remote debugging
- @cindex interrupting remote targets
- If you want @value{GDBN} to be able to stop your program while it is
- running, you need to use an interrupt-driven serial driver, and arrange
- for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
- character). That is the character which @value{GDBN} uses to tell the
- remote system to stop.
- Getting the debugging target to return the proper status to @value{GDBN}
- probably requires changes to the standard stub; one quick and dirty way
- is to just execute a breakpoint instruction (the ``dirty'' part is that
- @value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
- Other routines you need to supply are:
- @table @code
- @item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
- @findex exceptionHandler
- Write this function to install @var{exception_address} in the exception
- handling tables. You need to do this because the stub does not have any
- way of knowing what the exception handling tables on your target system
- are like (for example, the processor's table might be in @sc{rom},
- containing entries which point to a table in @sc{ram}).
- The @var{exception_number} specifies the exception which should be changed;
- its meaning is architecture-dependent (for example, different numbers
- might represent divide by zero, misaligned access, etc). When this
- exception occurs, control should be transferred directly to
- @var{exception_address}, and the processor state (stack, registers,
- and so on) should be just as it is when a processor exception occurs. So if
- you want to use a jump instruction to reach @var{exception_address}, it
- should be a simple jump, not a jump to subroutine.
- For the 386, @var{exception_address} should be installed as an interrupt
- gate so that interrupts are masked while the handler runs. The gate
- should be at privilege level 0 (the most privileged level). The
- @sc{sparc} and 68k stubs are able to mask interrupts themselves without
- help from @code{exceptionHandler}.
- @item void flush_i_cache()
- @findex flush_i_cache
- On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
- instruction cache, if any, on your target machine. If there is no
- instruction cache, this subroutine may be a no-op.
- On target machines that have instruction caches, @value{GDBN} requires this
- function to make certain that the state of your program is stable.
- @end table
- @noindent
- You must also make sure this library routine is available:
- @table @code
- @item void *memset(void *, int, int)
- @findex memset
- This is the standard library function @code{memset} that sets an area of
- memory to a known value. If you have one of the free versions of
- @code{libc.a}, @code{memset} can be found there; otherwise, you must
- either obtain it from your hardware manufacturer, or write your own.
- @end table
- If you do not use the GNU C compiler, you may need other standard
- library subroutines as well; this varies from one stub to another,
- but in general the stubs are likely to use any of the common library
- subroutines which @code{@value{NGCC}} generates as inline code.
- @node Debug Session
- @subsection Putting it All Together
- @cindex remote serial debugging summary
- In summary, when your program is ready to debug, you must follow these
- steps.
- @enumerate
- @item
- Make sure you have defined the supporting low-level routines
- (@pxref{Bootstrapping,,What You Must Do for the Stub}):
- @display
- @code{getDebugChar}, @code{putDebugChar},
- @code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
- @end display
- @item
- Insert these lines in your program's startup code, before the main
- procedure is called:
- @smallexample
- set_debug_traps();
- breakpoint();
- @end smallexample
- On some machines, when a breakpoint trap is raised, the hardware
- automatically makes the PC point to the instruction after the
- breakpoint. If your machine doesn't do that, you may need to adjust
- @code{handle_exception} to arrange for it to return to the instruction
- after the breakpoint on this first invocation, so that your program
- doesn't keep hitting the initial breakpoint instead of making
- progress.
- @item
- For the 680x0 stub only, you need to provide a variable called
- @code{exceptionHook}. Normally you just use:
- @smallexample
- void (*exceptionHook)() = 0;
- @end smallexample
- @noindent
- but if before calling @code{set_debug_traps}, you set it to point to a
- function in your program, that function is called when
- @code{@value{GDBN}} continues after stopping on a trap (for example, bus
- error). The function indicated by @code{exceptionHook} is called with
- one parameter: an @code{int} which is the exception number.
- @item
- Compile and link together: your program, the @value{GDBN} debugging stub for
- your target architecture, and the supporting subroutines.
- @item
- Make sure you have a serial connection between your target machine and
- the @value{GDBN} host, and identify the serial port on the host.
- @item
- @c The "remote" target now provides a `load' command, so we should
- @c document that. FIXME.
- Download your program to your target machine (or get it there by
- whatever means the manufacturer provides), and start it.
- @item
- Start @value{GDBN} on the host, and connect to the target
- (@pxref{Connecting,,Connecting to a Remote Target}).
- @end enumerate
- @node Configurations
- @chapter Configuration-Specific Information
- While nearly all @value{GDBN} commands are available for all native and
- cross versions of the debugger, there are some exceptions. This chapter
- describes things that are only available in certain configurations.
- There are three major categories of configurations: native
- configurations, where the host and target are the same, embedded
- operating system configurations, which are usually the same for several
- different processor architectures, and bare embedded processors, which
- are quite different from each other.
- @menu
- * Native::
- * Embedded OS::
- * Embedded Processors::
- * Architectures::
- @end menu
- @node Native
- @section Native
- This section describes details specific to particular native
- configurations.
- @menu
- * BSD libkvm Interface:: Debugging BSD kernel memory images
- * Process Information:: Process information
- * DJGPP Native:: Features specific to the DJGPP port
- * Cygwin Native:: Features specific to the Cygwin port
- * Hurd Native:: Features specific to @sc{gnu} Hurd
- * Darwin:: Features specific to Darwin
- * FreeBSD:: Features specific to FreeBSD
- @end menu
- @node BSD libkvm Interface
- @subsection BSD libkvm Interface
- @cindex libkvm
- @cindex kernel memory image
- @cindex kernel crash dump
- BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
- interface that provides a uniform interface for accessing kernel virtual
- memory images, including live systems and crash dumps. @value{GDBN}
- uses this interface to allow you to debug live kernels and kernel crash
- dumps on many native BSD configurations. This is implemented as a
- special @code{kvm} debugging target. For debugging a live system, load
- the currently running kernel into @value{GDBN} and connect to the
- @code{kvm} target:
- @smallexample
- (@value{GDBP}) @b{target kvm}
- @end smallexample
- For debugging crash dumps, provide the file name of the crash dump as an
- argument:
- @smallexample
- (@value{GDBP}) @b{target kvm /var/crash/bsd.0}
- @end smallexample
- Once connected to the @code{kvm} target, the following commands are
- available:
- @table @code
- @kindex kvm
- @item kvm pcb
- Set current context from the @dfn{Process Control Block} (PCB) address.
- @item kvm proc
- Set current context from proc address. This command isn't available on
- modern FreeBSD systems.
- @end table
- @node Process Information
- @subsection Process Information
- @cindex /proc
- @cindex examine process image
- @cindex process info via @file{/proc}
- Some operating systems provide interfaces to fetch additional
- information about running processes beyond memory and per-thread
- register state. If @value{GDBN} is configured for an operating system
- with a supported interface, the command @code{info proc} is available
- to report information about the process running your program, or about
- any process running on your system.
- One supported interface is a facility called @samp{/proc} that can be
- used to examine the image of a running process using file-system
- subroutines. This facility is supported on @sc{gnu}/Linux and Solaris
- systems.
- On FreeBSD and NetBSD systems, system control nodes are used to query
- process information.
- In addition, some systems may provide additional process information
- in core files. Note that a core file may include a subset of the
- information available from a live process. Process information is
- currently available from cores created on @sc{gnu}/Linux and FreeBSD
- systems.
- @table @code
- @kindex info proc
- @cindex process ID
- @item info proc
- @itemx info proc @var{process-id}
- Summarize available information about a process. If a
- process ID is specified by @var{process-id}, display information about
- that process; otherwise display information about the program being
- debugged. The summary includes the debugged process ID, the command
- line used to invoke it, its current working directory, and its
- executable file's absolute file name.
- On some systems, @var{process-id} can be of the form
- @samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID
- within a process. If the optional @var{pid} part is missing, it means
- a thread from the process being debugged (the leading @samp{/} still
- needs to be present, or else @value{GDBN} will interpret the number as
- a process ID rather than a thread ID).
- @item info proc cmdline
- @cindex info proc cmdline
- Show the original command line of the process. This command is
- supported on @sc{gnu}/Linux, FreeBSD and NetBSD.
- @item info proc cwd
- @cindex info proc cwd
- Show the current working directory of the process. This command is
- supported on @sc{gnu}/Linux, FreeBSD and NetBSD.
- @item info proc exe
- @cindex info proc exe
- Show the name of executable of the process. This command is supported
- on @sc{gnu}/Linux, FreeBSD and NetBSD.
- @item info proc files
- @cindex info proc files
- Show the file descriptors open by the process. For each open file
- descriptor, @value{GDBN} shows its number, type (file, directory,
- character device, socket), file pointer offset, and the name of the
- resource open on the descriptor. The resource name can be a file name
- (for files, directories, and devices) or a protocol followed by socket
- address (for network connections). This command is supported on
- FreeBSD.
- This example shows the open file descriptors for a process using a
- tty for standard input and output as well as two network sockets:
- @smallexample
- (gdb) info proc files 22136
- process 22136
- Open files:
- FD Type Offset Flags Name
- text file - r-------- /usr/bin/ssh
- ctty chr - rw------- /dev/pts/20
- cwd dir - r-------- /usr/home/john
- root dir - r-------- /
- 0 chr 0x32933a4 rw------- /dev/pts/20
- 1 chr 0x32933a4 rw------- /dev/pts/20
- 2 chr 0x32933a4 rw------- /dev/pts/20
- 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22
- 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456
- @end smallexample
- @item info proc mappings
- @cindex memory address space mappings
- Report the memory address space ranges accessible in a process. On
- Solaris, FreeBSD and NetBSD systems, each memory range includes information
- on whether the process has read, write, or execute access rights to each
- range. On @sc{gnu}/Linux, FreeBSD and NetBSD systems, each memory range
- includes the object file which is mapped to that range.
- @item info proc stat
- @itemx info proc status
- @cindex process detailed status information
- Show additional process-related information, including the user ID and
- group ID; virtual memory usage; the signals that are pending, blocked,
- and ignored; its TTY; its consumption of system and user time; its
- stack size; its @samp{nice} value; etc. These commands are supported
- on @sc{gnu}/Linux, FreeBSD and NetBSD.
- For @sc{gnu}/Linux systems, see the @samp{proc} man page for more
- information (type @kbd{man 5 proc} from your shell prompt).
- For FreeBSD and NetBSD systems, @code{info proc stat} is an alias for
- @code{info proc status}.
- @item info proc all
- Show all the information about the process described under all of the
- above @code{info proc} subcommands.
- @ignore
- @comment These sub-options of 'info proc' were not included when
- @comment procfs.c was re-written. Keep their descriptions around
- @comment against the day when someone finds the time to put them back in.
- @kindex info proc times
- @item info proc times
- Starting time, user CPU time, and system CPU time for your program and
- its children.
- @kindex info proc id
- @item info proc id
- Report on the process IDs related to your program: its own process ID,
- the ID of its parent, the process group ID, and the session ID.
- @end ignore
- @item set procfs-trace
- @kindex set procfs-trace
- @cindex @code{procfs} API calls
- This command enables and disables tracing of @code{procfs} API calls.
- @item show procfs-trace
- @kindex show procfs-trace
- Show the current state of @code{procfs} API call tracing.
- @item set procfs-file @var{file}
- @kindex set procfs-file
- Tell @value{GDBN} to write @code{procfs} API trace to the named
- @var{file}. @value{GDBN} appends the trace info to the previous
- contents of the file. The default is to display the trace on the
- standard output.
- @item show procfs-file
- @kindex show procfs-file
- Show the file to which @code{procfs} API trace is written.
- @item proc-trace-entry
- @itemx proc-trace-exit
- @itemx proc-untrace-entry
- @itemx proc-untrace-exit
- @kindex proc-trace-entry
- @kindex proc-trace-exit
- @kindex proc-untrace-entry
- @kindex proc-untrace-exit
- These commands enable and disable tracing of entries into and exits
- from the @code{syscall} interface.
- @item info pidlist
- @kindex info pidlist
- @cindex process list, QNX Neutrino
- For QNX Neutrino only, this command displays the list of all the
- processes and all the threads within each process.
- @item info meminfo
- @kindex info meminfo
- @cindex mapinfo list, QNX Neutrino
- For QNX Neutrino only, this command displays the list of all mapinfos.
- @end table
- @node DJGPP Native
- @subsection Features for Debugging @sc{djgpp} Programs
- @cindex @sc{djgpp} debugging
- @cindex native @sc{djgpp} debugging
- @cindex MS-DOS-specific commands
- @cindex DPMI
- @sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and
- MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
- that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
- top of real-mode DOS systems and their emulations.
- @value{GDBN} supports native debugging of @sc{djgpp} programs, and
- defines a few commands specific to the @sc{djgpp} port. This
- subsection describes those commands.
- @table @code
- @kindex info dos
- @item info dos
- This is a prefix of @sc{djgpp}-specific commands which print
- information about the target system and important OS structures.
- @kindex sysinfo
- @cindex MS-DOS system info
- @cindex free memory information (MS-DOS)
- @item info dos sysinfo
- This command displays assorted information about the underlying
- platform: the CPU type and features, the OS version and flavor, the
- DPMI version, and the available conventional and DPMI memory.
- @cindex GDT
- @cindex LDT
- @cindex IDT
- @cindex segment descriptor tables
- @cindex descriptor tables display
- @item info dos gdt
- @itemx info dos ldt
- @itemx info dos idt
- These 3 commands display entries from, respectively, Global, Local,
- and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor
- tables are data structures which store a descriptor for each segment
- that is currently in use. The segment's selector is an index into a
- descriptor table; the table entry for that index holds the
- descriptor's base address and limit, and its attributes and access
- rights.
- A typical @sc{djgpp} program uses 3 segments: a code segment, a data
- segment (used for both data and the stack), and a DOS segment (which
- allows access to DOS/BIOS data structures and absolute addresses in
- conventional memory). However, the DPMI host will usually define
- additional segments in order to support the DPMI environment.
- @cindex garbled pointers
- These commands allow to display entries from the descriptor tables.
- Without an argument, all entries from the specified table are
- displayed. An argument, which should be an integer expression, means
- display a single entry whose index is given by the argument. For
- example, here's a convenient way to display information about the
- debugged program's data segment:
- @smallexample
- @exdent @code{(@value{GDBP}) info dos ldt $ds}
- @exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)}
- @end smallexample
- @noindent
- This comes in handy when you want to see whether a pointer is outside
- the data segment's limit (i.e.@: @dfn{garbled}).
- @cindex page tables display (MS-DOS)
- @item info dos pde
- @itemx info dos pte
- These two commands display entries from, respectively, the Page
- Directory and the Page Tables. Page Directories and Page Tables are
- data structures which control how virtual memory addresses are mapped
- into physical addresses. A Page Table includes an entry for every
- page of memory that is mapped into the program's address space; there
- may be several Page Tables, each one holding up to 4096 entries. A
- Page Directory has up to 4096 entries, one each for every Page Table
- that is currently in use.
- Without an argument, @kbd{info dos pde} displays the entire Page
- Directory, and @kbd{info dos pte} displays all the entries in all of
- the Page Tables. An argument, an integer expression, given to the
- @kbd{info dos pde} command means display only that entry from the Page
- Directory table. An argument given to the @kbd{info dos pte} command
- means display entries from a single Page Table, the one pointed to by
- the specified entry in the Page Directory.
- @cindex direct memory access (DMA) on MS-DOS
- These commands are useful when your program uses @dfn{DMA} (Direct
- Memory Access), which needs physical addresses to program the DMA
- controller.
- These commands are supported only with some DPMI servers.
- @cindex physical address from linear address
- @item info dos address-pte @var{addr}
- This command displays the Page Table entry for a specified linear
- address. The argument @var{addr} is a linear address which should
- already have the appropriate segment's base address added to it,
- because this command accepts addresses which may belong to @emph{any}
- segment. For example, here's how to display the Page Table entry for
- the page where a variable @code{i} is stored:
- @smallexample
- @exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
- @exdent @code{Page Table entry for address 0x11a00d30:}
- @exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
- @end smallexample
- @noindent
- This says that @code{i} is stored at offset @code{0xd30} from the page
- whose physical base address is @code{0x02698000}, and shows all the
- attributes of that page.
- Note that you must cast the addresses of variables to a @code{char *},
- since otherwise the value of @code{__djgpp_base_address}, the base
- address of all variables and functions in a @sc{djgpp} program, will
- be added using the rules of C pointer arithmetics: if @code{i} is
- declared an @code{int}, @value{GDBN} will add 4 times the value of
- @code{__djgpp_base_address} to the address of @code{i}.
- Here's another example, it displays the Page Table entry for the
- transfer buffer:
- @smallexample
- @exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)}
- @exdent @code{Page Table entry for address 0x29110:}
- @exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110}
- @end smallexample
- @noindent
- (The @code{+ 3} offset is because the transfer buffer's address is the
- 3rd member of the @code{_go32_info_block} structure.) The output
- clearly shows that this DPMI server maps the addresses in conventional
- memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and
- linear (@code{0x29110}) addresses are identical.
- This command is supported only with some DPMI servers.
- @end table
- @cindex DOS serial data link, remote debugging
- In addition to native debugging, the DJGPP port supports remote
- debugging via a serial data link. The following commands are specific
- to remote serial debugging in the DJGPP port of @value{GDBN}.
- @table @code
- @kindex set com1base
- @kindex set com1irq
- @kindex set com2base
- @kindex set com2irq
- @kindex set com3base
- @kindex set com3irq
- @kindex set com4base
- @kindex set com4irq
- @item set com1base @var{addr}
- This command sets the base I/O port address of the @file{COM1} serial
- port.
- @item set com1irq @var{irq}
- This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use
- for the @file{COM1} serial port.
- There are similar commands @samp{set com2base}, @samp{set com3irq},
- etc.@: for setting the port address and the @code{IRQ} lines for the
- other 3 COM ports.
- @kindex show com1base
- @kindex show com1irq
- @kindex show com2base
- @kindex show com2irq
- @kindex show com3base
- @kindex show com3irq
- @kindex show com4base
- @kindex show com4irq
- The related commands @samp{show com1base}, @samp{show com1irq} etc.@:
- display the current settings of the base address and the @code{IRQ}
- lines used by the COM ports.
- @item info serial
- @kindex info serial
- @cindex DOS serial port status
- This command prints the status of the 4 DOS serial ports. For each
- port, it prints whether it's active or not, its I/O base address and
- IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the
- counts of various errors encountered so far.
- @end table
- @node Cygwin Native
- @subsection Features for Debugging MS Windows PE Executables
- @cindex MS Windows debugging
- @cindex native Cygwin debugging
- @cindex Cygwin-specific commands
- @value{GDBN} supports native debugging of MS Windows programs, including
- DLLs with and without symbolic debugging information.
- @cindex Ctrl-BREAK, MS-Windows
- @cindex interrupt debuggee on MS-Windows
- MS-Windows programs that call @code{SetConsoleMode} to switch off the
- special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted
- by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows
- supports @kbd{C-@key{BREAK}} as an alternative interrupt key
- sequence, which can be used to interrupt the debuggee even if it
- ignores @kbd{C-c}.
- There are various additional Cygwin-specific commands, described in
- this section. Working with DLLs that have no debugging symbols is
- described in @ref{Non-debug DLL Symbols}.
- @table @code
- @kindex info w32
- @item info w32
- This is a prefix of MS Windows-specific commands which print
- information about the target system and important OS structures.
- @item info w32 selector
- This command displays information returned by
- the Win32 API @code{GetThreadSelectorEntry} function.
- It takes an optional argument that is evaluated to
- a long value to give the information about this given selector.
- Without argument, this command displays information
- about the six segment registers.
- @item info w32 thread-information-block
- This command displays thread specific information stored in the
- Thread Information Block (readable on the X86 CPU family using @code{$fs}
- selector for 32-bit programs and @code{$gs} for 64-bit programs).
- @kindex signal-event
- @item signal-event @var{id}
- This command signals an event with user-provided @var{id}. Used to resume
- crashing process when attached to it using MS-Windows JIT debugging (AeDebug).
- To use it, create or edit the following keys in
- @code{HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug} and/or
- @code{HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug}
- (for x86_64 versions):
- @itemize @minus
- @item
- @code{Debugger} (REG_SZ) --- a command to launch the debugger.
- Suggested command is: @code{@var{fully-qualified-path-to-gdb.exe} -ex
- "attach %ld" -ex "signal-event %ld" -ex "continue"}.
- The first @code{%ld} will be replaced by the process ID of the
- crashing process, the second @code{%ld} will be replaced by the ID of
- the event that blocks the crashing process, waiting for @value{GDBN}
- to attach.
- @item
- @code{Auto} (REG_SZ) --- either @code{1} or @code{0}. @code{1} will
- make the system run debugger specified by the Debugger key
- automatically, @code{0} will cause a dialog box with ``OK'' and
- ``Cancel'' buttons to appear, which allows the user to either
- terminate the crashing process (OK) or debug it (Cancel).
- @end itemize
- @kindex set cygwin-exceptions
- @cindex debugging the Cygwin DLL
- @cindex Cygwin DLL, debugging
- @item set cygwin-exceptions @var{mode}
- If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that
- happen inside the Cygwin DLL. If @var{mode} is @code{off},
- @value{GDBN} will delay recognition of exceptions, and may ignore some
- exceptions which seem to be caused by internal Cygwin DLL
- ``bookkeeping''. This option is meant primarily for debugging the
- Cygwin DLL itself; the default value is @code{off} to avoid annoying
- @value{GDBN} users with false @code{SIGSEGV} signals.
- @kindex show cygwin-exceptions
- @item show cygwin-exceptions
- Displays whether @value{GDBN} will break on exceptions that happen
- inside the Cygwin DLL itself.
- @kindex set new-console
- @item set new-console @var{mode}
- If @var{mode} is @code{on} the debuggee will
- be started in a new console on next start.
- If @var{mode} is @code{off}, the debuggee will
- be started in the same console as the debugger.
- @kindex show new-console
- @item show new-console
- Displays whether a new console is used
- when the debuggee is started.
- @kindex set new-group
- @item set new-group @var{mode}
- This boolean value controls whether the debuggee should
- start a new group or stay in the same group as the debugger.
- This affects the way the Windows OS handles
- @samp{Ctrl-C}.
- @kindex show new-group
- @item show new-group
- Displays current value of new-group boolean.
- @kindex set debugevents
- @item set debugevents
- This boolean value adds debug output concerning kernel events related
- to the debuggee seen by the debugger. This includes events that
- signal thread and process creation and exit, DLL loading and
- unloading, console interrupts, and debugging messages produced by the
- Windows @code{OutputDebugString} API call.
- @kindex set debugexec
- @item set debugexec
- This boolean value adds debug output concerning execute events
- (such as resume thread) seen by the debugger.
- @kindex set debugexceptions
- @item set debugexceptions
- This boolean value adds debug output concerning exceptions in the
- debuggee seen by the debugger.
- @kindex set debugmemory
- @item set debugmemory
- This boolean value adds debug output concerning debuggee memory reads
- and writes by the debugger.
- @kindex set shell
- @item set shell
- This boolean values specifies whether the debuggee is called
- via a shell or directly (default value is on).
- @kindex show shell
- @item show shell
- Displays if the debuggee will be started with a shell.
- @end table
- @menu
- * Non-debug DLL Symbols:: Support for DLLs without debugging symbols
- @end menu
- @node Non-debug DLL Symbols
- @subsubsection Support for DLLs without Debugging Symbols
- @cindex DLLs with no debugging symbols
- @cindex Minimal symbols and DLLs
- Very often on windows, some of the DLLs that your program relies on do
- not include symbolic debugging information (for example,
- @file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
- symbols in a DLL, it relies on the minimal amount of symbolic
- information contained in the DLL's export table. This section
- describes working with such symbols, known internally to @value{GDBN} as
- ``minimal symbols''.
- Note that before the debugged program has started execution, no DLLs
- will have been loaded. The easiest way around this problem is simply to
- start the program --- either by setting a breakpoint or letting the
- program run once to completion.
- @subsubsection DLL Name Prefixes
- In keeping with the naming conventions used by the Microsoft debugging
- tools, DLL export symbols are made available with a prefix based on the
- DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is
- also entered into the symbol table, so @code{CreateFileA} is often
- sufficient. In some cases there will be name clashes within a program
- (particularly if the executable itself includes full debugging symbols)
- necessitating the use of the fully qualified name when referring to the
- contents of the DLL. Use single-quotes around the name to avoid the
- exclamation mark (``!'') being interpreted as a language operator.
- Note that the internal name of the DLL may be all upper-case, even
- though the file name of the DLL is lower-case, or vice-versa. Since
- symbols within @value{GDBN} are @emph{case-sensitive} this may cause
- some confusion. If in doubt, try the @code{info functions} and
- @code{info variables} commands or even @code{maint print msymbols}
- (@pxref{Symbols}). Here's an example:
- @smallexample
- (@value{GDBP}) info function CreateFileA
- All functions matching regular expression "CreateFileA":
- Non-debugging symbols:
- 0x77e885f4 CreateFileA
- 0x77e885f4 KERNEL32!CreateFileA
- @end smallexample
- @smallexample
- (@value{GDBP}) info function !
- All functions matching regular expression "!":
- Non-debugging symbols:
- 0x6100114c cygwin1!__assert
- 0x61004034 cygwin1!_dll_crt0@@0
- 0x61004240 cygwin1!dll_crt0(per_process *)
- [etc...]
- @end smallexample
- @subsubsection Working with Minimal Symbols
- Symbols extracted from a DLL's export table do not contain very much
- type information. All that @value{GDBN} can do is guess whether a symbol
- refers to a function or variable depending on the linker section that
- contains the symbol. Also note that the actual contents of the memory
- contained in a DLL are not available unless the program is running. This
- means that you cannot examine the contents of a variable or disassemble
- a function within a DLL without a running program.
- Variables are generally treated as pointers and dereferenced
- automatically. For this reason, it is often necessary to prefix a
- variable name with the address-of operator (``&'') and provide explicit
- type information in the command. Here's an example of the type of
- problem:
- @smallexample
- (@value{GDBP}) print 'cygwin1!__argv'
- 'cygwin1!__argv' has unknown type; cast it to its declared type
- @end smallexample
- @smallexample
- (@value{GDBP}) x 'cygwin1!__argv'
- 'cygwin1!__argv' has unknown type; cast it to its declared type
- @end smallexample
- And two possible solutions:
- @smallexample
- (@value{GDBP}) print ((char **)'cygwin1!__argv')[0]
- $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
- @end smallexample
- @smallexample
- (@value{GDBP}) x/2x &'cygwin1!__argv'
- 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
- (@value{GDBP}) x/x 0x10021608
- 0x10021608: 0x0022fd98
- (@value{GDBP}) x/s 0x0022fd98
- 0x22fd98: "/cygdrive/c/mydirectory/myprogram"
- @end smallexample
- Setting a break point within a DLL is possible even before the program
- starts execution. However, under these circumstances, @value{GDBN} can't
- examine the initial instructions of the function in order to skip the
- function's frame set-up code. You can work around this by using ``*&''
- to set the breakpoint at a raw memory address:
- @smallexample
- (@value{GDBP}) break *&'python22!PyOS_Readline'
- Breakpoint 1 at 0x1e04eff0
- @end smallexample
- The author of these extensions is not entirely convinced that setting a
- break point within a shared DLL like @file{kernel32.dll} is completely
- safe.
- @node Hurd Native
- @subsection Commands Specific to @sc{gnu} Hurd Systems
- @cindex @sc{gnu} Hurd debugging
- This subsection describes @value{GDBN} commands specific to the
- @sc{gnu} Hurd native debugging.
- @table @code
- @item set signals
- @itemx set sigs
- @kindex set signals@r{, Hurd command}
- @kindex set sigs@r{, Hurd command}
- This command toggles the state of inferior signal interception by
- @value{GDBN}. Mach exceptions, such as breakpoint traps, are not
- affected by this command. @code{sigs} is a shorthand alias for
- @code{signals}.
- @item show signals
- @itemx show sigs
- @kindex show signals@r{, Hurd command}
- @kindex show sigs@r{, Hurd command}
- Show the current state of intercepting inferior's signals.
- @item set signal-thread
- @itemx set sigthread
- @kindex set signal-thread
- @kindex set sigthread
- This command tells @value{GDBN} which thread is the @code{libc} signal
- thread. That thread is run when a signal is delivered to a running
- process. @code{set sigthread} is the shorthand alias of @code{set
- signal-thread}.
- @item show signal-thread
- @itemx show sigthread
- @kindex show signal-thread
- @kindex show sigthread
- These two commands show which thread will run when the inferior is
- delivered a signal.
- @item set stopped
- @kindex set stopped@r{, Hurd command}
- This commands tells @value{GDBN} that the inferior process is stopped,
- as with the @code{SIGSTOP} signal. The stopped process can be
- continued by delivering a signal to it.
- @item show stopped
- @kindex show stopped@r{, Hurd command}
- This command shows whether @value{GDBN} thinks the debuggee is
- stopped.
- @item set exceptions
- @kindex set exceptions@r{, Hurd command}
- Use this command to turn off trapping of exceptions in the inferior.
- When exception trapping is off, neither breakpoints nor
- single-stepping will work. To restore the default, set exception
- trapping on.
- @item show exceptions
- @kindex show exceptions@r{, Hurd command}
- Show the current state of trapping exceptions in the inferior.
- @item set task pause
- @kindex set task@r{, Hurd commands}
- @cindex task attributes (@sc{gnu} Hurd)
- @cindex pause current task (@sc{gnu} Hurd)
- This command toggles task suspension when @value{GDBN} has control.
- Setting it to on takes effect immediately, and the task is suspended
- whenever @value{GDBN} gets control. Setting it to off will take
- effect the next time the inferior is continued. If this option is set
- to off, you can use @code{set thread default pause on} or @code{set
- thread pause on} (see below) to pause individual threads.
- @item show task pause
- @kindex show task@r{, Hurd commands}
- Show the current state of task suspension.
- @item set task detach-suspend-count
- @cindex task suspend count
- @cindex detach from task, @sc{gnu} Hurd
- This command sets the suspend count the task will be left with when
- @value{GDBN} detaches from it.
- @item show task detach-suspend-count
- Show the suspend count the task will be left with when detaching.
- @item set task exception-port
- @itemx set task excp
- @cindex task exception port, @sc{gnu} Hurd
- This command sets the task exception port to which @value{GDBN} will
- forward exceptions. The argument should be the value of the @dfn{send
- rights} of the task. @code{set task excp} is a shorthand alias.
- @item set noninvasive
- @cindex noninvasive task options
- This command switches @value{GDBN} to a mode that is the least
- invasive as far as interfering with the inferior is concerned. This
- is the same as using @code{set task pause}, @code{set exceptions}, and
- @code{set signals} to values opposite to the defaults.
- @item info send-rights
- @itemx info receive-rights
- @itemx info port-rights
- @itemx info port-sets
- @itemx info dead-names
- @itemx info ports
- @itemx info psets
- @cindex send rights, @sc{gnu} Hurd
- @cindex receive rights, @sc{gnu} Hurd
- @cindex port rights, @sc{gnu} Hurd
- @cindex port sets, @sc{gnu} Hurd
- @cindex dead names, @sc{gnu} Hurd
- These commands display information about, respectively, send rights,
- receive rights, port rights, port sets, and dead names of a task.
- There are also shorthand aliases: @code{info ports} for @code{info
- port-rights} and @code{info psets} for @code{info port-sets}.
- @item set thread pause
- @kindex set thread@r{, Hurd command}
- @cindex thread properties, @sc{gnu} Hurd
- @cindex pause current thread (@sc{gnu} Hurd)
- This command toggles current thread suspension when @value{GDBN} has
- control. Setting it to on takes effect immediately, and the current
- thread is suspended whenever @value{GDBN} gets control. Setting it to
- off will take effect the next time the inferior is continued.
- Normally, this command has no effect, since when @value{GDBN} has
- control, the whole task is suspended. However, if you used @code{set
- task pause off} (see above), this command comes in handy to suspend
- only the current thread.
- @item show thread pause
- @kindex show thread@r{, Hurd command}
- This command shows the state of current thread suspension.
- @item set thread run
- This command sets whether the current thread is allowed to run.
- @item show thread run
- Show whether the current thread is allowed to run.
- @item set thread detach-suspend-count
- @cindex thread suspend count, @sc{gnu} Hurd
- @cindex detach from thread, @sc{gnu} Hurd
- This command sets the suspend count @value{GDBN} will leave on a
- thread when detaching. This number is relative to the suspend count
- found by @value{GDBN} when it notices the thread; use @code{set thread
- takeover-suspend-count} to force it to an absolute value.
- @item show thread detach-suspend-count
- Show the suspend count @value{GDBN} will leave on the thread when
- detaching.
- @item set thread exception-port
- @itemx set thread excp
- Set the thread exception port to which to forward exceptions. This
- overrides the port set by @code{set task exception-port} (see above).
- @code{set thread excp} is the shorthand alias.
- @item set thread takeover-suspend-count
- Normally, @value{GDBN}'s thread suspend counts are relative to the
- value @value{GDBN} finds when it notices each thread. This command
- changes the suspend counts to be absolute instead.
- @item set thread default
- @itemx show thread default
- @cindex thread default settings, @sc{gnu} Hurd
- Each of the above @code{set thread} commands has a @code{set thread
- default} counterpart (e.g., @code{set thread default pause}, @code{set
- thread default exception-port}, etc.). The @code{thread default}
- variety of commands sets the default thread properties for all
- threads; you can then change the properties of individual threads with
- the non-default commands.
- @end table
- @node Darwin
- @subsection Darwin
- @cindex Darwin
- @value{GDBN} provides the following commands specific to the Darwin target:
- @table @code
- @item set debug darwin @var{num}
- @kindex set debug darwin
- When set to a non zero value, enables debugging messages specific to
- the Darwin support. Higher values produce more verbose output.
- @item show debug darwin
- @kindex show debug darwin
- Show the current state of Darwin messages.
- @item set debug mach-o @var{num}
- @kindex set debug mach-o
- When set to a non zero value, enables debugging messages while
- @value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the
- file format used on Darwin for object and executable files.) Higher
- values produce more verbose output. This is a command to diagnose
- problems internal to @value{GDBN} and should not be needed in normal
- usage.
- @item show debug mach-o
- @kindex show debug mach-o
- Show the current state of Mach-O file messages.
- @item set mach-exceptions on
- @itemx set mach-exceptions off
- @kindex set mach-exceptions
- On Darwin, faults are first reported as a Mach exception and are then
- mapped to a Posix signal. Use this command to turn on trapping of
- Mach exceptions in the inferior. This might be sometimes useful to
- better understand the cause of a fault. The default is off.
- @item show mach-exceptions
- @kindex show mach-exceptions
- Show the current state of exceptions trapping.
- @end table
- @node FreeBSD
- @subsection FreeBSD
- @cindex FreeBSD
- When the ABI of a system call is changed in the FreeBSD kernel, this
- is implemented by leaving a compatibility system call using the old
- ABI at the existing number and allocating a new system call number for
- the version using the new ABI. As a convenience, when a system call
- is caught by name (@pxref{catch syscall}), compatibility system calls
- are also caught.
- For example, FreeBSD 12 introduced a new variant of the @code{kevent}
- system call and catching the @code{kevent} system call by name catches
- both variants:
- @smallexample
- (@value{GDBP}) catch syscall kevent
- Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560])
- (@value{GDBP})
- @end smallexample
- @node Embedded OS
- @section Embedded Operating Systems
- This section describes configurations involving the debugging of
- embedded operating systems that are available for several different
- architectures.
- @value{GDBN} includes the ability to debug programs running on
- various real-time operating systems.
- @node Embedded Processors
- @section Embedded Processors
- This section goes into details specific to particular embedded
- configurations.
- @cindex send command to simulator
- Whenever a specific embedded processor has a simulator, @value{GDBN}
- allows to send an arbitrary command to the simulator.
- @table @code
- @item sim @var{command}
- @kindex sim@r{, a command}
- Send an arbitrary @var{command} string to the simulator. Consult the
- documentation for the specific simulator in use for information about
- acceptable commands.
- @end table
- @menu
- * ARC:: Synopsys ARC
- * ARM:: ARM
- * BPF:: eBPF
- * M68K:: Motorola M68K
- * MicroBlaze:: Xilinx MicroBlaze
- * MIPS Embedded:: MIPS Embedded
- * OpenRISC 1000:: OpenRISC 1000 (or1k)
- * PowerPC Embedded:: PowerPC Embedded
- * AVR:: Atmel AVR
- * CRIS:: CRIS
- * Super-H:: Renesas Super-H
- @end menu
- @node ARC
- @subsection Synopsys ARC
- @cindex Synopsys ARC
- @cindex ARC specific commands
- @cindex ARC600
- @cindex ARC700
- @cindex ARC EM
- @cindex ARC HS
- @value{GDBN} provides the following ARC-specific commands:
- @table @code
- @item set debug arc
- @kindex set debug arc
- Control the level of ARC specific debug messages. Use 0 for no messages (the
- default), 1 for debug messages, and 2 for even more debug messages.
- @item show debug arc
- @kindex show debug arc
- Show the level of ARC specific debugging in operation.
- @item maint print arc arc-instruction @var{address}
- @kindex maint print arc arc-instruction
- Print internal disassembler information about instruction at a given address.
- @end table
- @node ARM
- @subsection ARM
- @value{GDBN} provides the following ARM-specific commands:
- @table @code
- @item set arm disassembler
- @kindex set arm
- This commands selects from a list of disassembly styles. The
- @code{"std"} style is the standard style.
- @item show arm disassembler
- @kindex show arm
- Show the current disassembly style.
- @item set arm apcs32
- @cindex ARM 32-bit mode
- This command toggles ARM operation mode between 32-bit and 26-bit.
- @item show arm apcs32
- Display the current usage of the ARM 32-bit mode.
- @item set arm fpu @var{fputype}
- This command sets the ARM floating-point unit (FPU) type. The
- argument @var{fputype} can be one of these:
- @table @code
- @item auto
- Determine the FPU type by querying the OS ABI.
- @item softfpa
- Software FPU, with mixed-endian doubles on little-endian ARM
- processors.
- @item fpa
- GCC-compiled FPA co-processor.
- @item softvfp
- Software FPU with pure-endian doubles.
- @item vfp
- VFP co-processor.
- @end table
- @item show arm fpu
- Show the current type of the FPU.
- @item set arm abi
- This command forces @value{GDBN} to use the specified ABI.
- @item show arm abi
- Show the currently used ABI.
- @item set arm fallback-mode (arm|thumb|auto)
- @value{GDBN} uses the symbol table, when available, to determine
- whether instructions are ARM or Thumb. This command controls
- @value{GDBN}'s default behavior when the symbol table is not
- available. The default is @samp{auto}, which causes @value{GDBN} to
- use the current execution mode (from the @code{T} bit in the @code{CPSR}
- register).
- @item show arm fallback-mode
- Show the current fallback instruction mode.
- @item set arm force-mode (arm|thumb|auto)
- This command overrides use of the symbol table to determine whether
- instructions are ARM or Thumb. The default is @samp{auto}, which
- causes @value{GDBN} to use the symbol table and then the setting
- of @samp{set arm fallback-mode}.
- @item show arm force-mode
- Show the current forced instruction mode.
- @item set debug arm
- Toggle whether to display ARM-specific debugging messages from the ARM
- target support subsystem.
- @item show debug arm
- Show whether ARM-specific debugging messages are enabled.
- @end table
- @table @code
- @item target sim @r{[}@var{simargs}@r{]} @dots{}
- The @value{GDBN} ARM simulator accepts the following optional arguments.
- @table @code
- @item --swi-support=@var{type}
- Tell the simulator which SWI interfaces to support. The argument
- @var{type} may be a comma separated list of the following values.
- The default value is @code{all}.
- @table @code
- @item none
- @item demon
- @item angel
- @item redboot
- @item all
- @end table
- @end table
- @end table
- @node BPF
- @subsection BPF
- @table @code
- @item target sim @r{[}@var{simargs}@r{]} @dots{}
- The @value{GDBN} BPF simulator accepts the following optional arguments.
- @table @code
- @item --skb-data-offset=@var{offset}
- Tell the simulator the offset, measured in bytes, of the
- @code{skb_data} field in the kernel @code{struct sk_buff} structure.
- This offset is used by some BPF specific-purpose load/store
- instructions. Defaults to 0.
- @end table
- @end table
- @node M68K
- @subsection M68k
- The Motorola m68k configuration includes ColdFire support.
- @node MicroBlaze
- @subsection MicroBlaze
- @cindex Xilinx MicroBlaze
- @cindex XMD, Xilinx Microprocessor Debugger
- The MicroBlaze is a soft-core processor supported on various Xilinx
- FPGAs, such as Spartan or Virtex series. Boards with these processors
- usually have JTAG ports which connect to a host system running the Xilinx
- Embedded Development Kit (EDK) or Software Development Kit (SDK).
- This host system is used to download the configuration bitstream to
- the target FPGA. The Xilinx Microprocessor Debugger (XMD) program
- communicates with the target board using the JTAG interface and
- presents a @code{gdbserver} interface to the board. By default
- @code{xmd} uses port @code{1234}. (While it is possible to change
- this default port, it requires the use of undocumented @code{xmd}
- commands. Contact Xilinx support if you need to do this.)
- Use these GDB commands to connect to the MicroBlaze target processor.
- @table @code
- @item target remote :1234
- Use this command to connect to the target if you are running @value{GDBN}
- on the same system as @code{xmd}.
- @item target remote @var{xmd-host}:1234
- Use this command to connect to the target if it is connected to @code{xmd}
- running on a different system named @var{xmd-host}.
- @item load
- Use this command to download a program to the MicroBlaze target.
- @item set debug microblaze @var{n}
- Enable MicroBlaze-specific debugging messages if non-zero.
- @item show debug microblaze @var{n}
- Show MicroBlaze-specific debugging level.
- @end table
- @node MIPS Embedded
- @subsection @acronym{MIPS} Embedded
- @noindent
- @value{GDBN} supports these special commands for @acronym{MIPS} targets:
- @table @code
- @item set mipsfpu double
- @itemx set mipsfpu single
- @itemx set mipsfpu none
- @itemx set mipsfpu auto
- @itemx show mipsfpu
- @kindex set mipsfpu
- @kindex show mipsfpu
- @cindex @acronym{MIPS} remote floating point
- @cindex floating point, @acronym{MIPS} remote
- If your target board does not support the @acronym{MIPS} floating point
- coprocessor, you should use the command @samp{set mipsfpu none} (if you
- need this, you may wish to put the command in your @value{GDBN} init
- file). This tells @value{GDBN} how to find the return value of
- functions which return floating point values. It also allows
- @value{GDBN} to avoid saving the floating point registers when calling
- functions on the board. If you are using a floating point coprocessor
- with only single precision floating point support, as on the @sc{r4650}
- processor, use the command @samp{set mipsfpu single}. The default
- double precision floating point coprocessor may be selected using
- @samp{set mipsfpu double}.
- In previous versions the only choices were double precision or no
- floating point, so @samp{set mipsfpu on} will select double precision
- and @samp{set mipsfpu off} will select no floating point.
- As usual, you can inquire about the @code{mipsfpu} variable with
- @samp{show mipsfpu}.
- @end table
- @node OpenRISC 1000
- @subsection OpenRISC 1000
- @cindex OpenRISC 1000
- @noindent
- The OpenRISC 1000 provides a free RISC instruction set architecture. It is
- mainly provided as a soft-core which can run on Xilinx, Altera and other
- FPGA's.
- @value{GDBN} for OpenRISC supports the below commands when connecting to
- a target:
- @table @code
- @kindex target sim
- @item target sim
- Runs the builtin CPU simulator which can run very basic
- programs but does not support most hardware functions like MMU.
- For more complex use cases the user is advised to run an external
- target, and connect using @samp{target remote}.
- Example: @code{target sim}
- @item set debug or1k
- Toggle whether to display OpenRISC-specific debugging messages from the
- OpenRISC target support subsystem.
- @item show debug or1k
- Show whether OpenRISC-specific debugging messages are enabled.
- @end table
- @node PowerPC Embedded
- @subsection PowerPC Embedded
- @cindex DVC register
- @value{GDBN} supports using the DVC (Data Value Compare) register to
- implement in hardware simple hardware watchpoint conditions of the form:
- @smallexample
- (@value{GDBP}) watch @var{address|variable} \
- if @var{address|variable} == @var{constant expression}
- @end smallexample
- The DVC register will be automatically used when @value{GDBN} detects
- such pattern in a condition expression, and the created watchpoint uses one
- debug register (either the @code{exact-watchpoints} option is on and the
- variable is scalar, or the variable has a length of one byte). This feature
- is available in native @value{GDBN} running on a Linux kernel version 2.6.34
- or newer.
- When running on PowerPC embedded processors, @value{GDBN} automatically uses
- ranged hardware watchpoints, unless the @code{exact-watchpoints} option is on,
- in which case watchpoints using only one debug register are created when
- watching variables of scalar types.
- You can create an artificial array to watch an arbitrary memory
- region using one of the following commands (@pxref{Expressions}):
- @smallexample
- (@value{GDBP}) watch *((char *) @var{address})@@@var{length}
- (@value{GDBP}) watch @{char[@var{length}]@} @var{address}
- @end smallexample
- PowerPC embedded processors support masked watchpoints. See the discussion
- about the @code{mask} argument in @ref{Set Watchpoints}.
- @cindex ranged breakpoint
- PowerPC embedded processors support hardware accelerated
- @dfn{ranged breakpoints}. A ranged breakpoint stops execution of
- the inferior whenever it executes an instruction at any address within
- the range it specifies. To set a ranged breakpoint in @value{GDBN},
- use the @code{break-range} command.
- @value{GDBN} provides the following PowerPC-specific commands:
- @table @code
- @kindex break-range
- @item break-range @var{start-location}, @var{end-location}
- Set a breakpoint for an address range given by
- @var{start-location} and @var{end-location}, which can specify a function name,
- a line number, an offset of lines from the current line or from the start
- location, or an address of an instruction (see @ref{Specify Location},
- for a list of all the possible ways to specify a @var{location}.)
- The breakpoint will stop execution of the inferior whenever it
- executes an instruction at any address within the specified range,
- (including @var{start-location} and @var{end-location}.)
- @kindex set powerpc
- @item set powerpc soft-float
- @itemx show powerpc soft-float
- Force @value{GDBN} to use (or not use) a software floating point calling
- convention. By default, @value{GDBN} selects the calling convention based
- on the selected architecture and the provided executable file.
- @item set powerpc vector-abi
- @itemx show powerpc vector-abi
- Force @value{GDBN} to use the specified calling convention for vector
- arguments and return values. The valid options are @samp{auto};
- @samp{generic}, to avoid vector registers even if they are present;
- @samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE
- registers. By default, @value{GDBN} selects the calling convention
- based on the selected architecture and the provided executable file.
- @item set powerpc exact-watchpoints
- @itemx show powerpc exact-watchpoints
- Allow @value{GDBN} to use only one debug register when watching a variable
- of scalar type, thus assuming that the variable is accessed through the
- address of its first byte.
- @end table
- @node AVR
- @subsection Atmel AVR
- @cindex AVR
- When configured for debugging the Atmel AVR, @value{GDBN} supports the
- following AVR-specific commands:
- @table @code
- @item info io_registers
- @kindex info io_registers@r{, AVR}
- @cindex I/O registers (Atmel AVR)
- This command displays information about the AVR I/O registers. For
- each register, @value{GDBN} prints its number and value.
- @end table
- @node CRIS
- @subsection CRIS
- @cindex CRIS
- When configured for debugging CRIS, @value{GDBN} provides the
- following CRIS-specific commands:
- @table @code
- @item set cris-version @var{ver}
- @cindex CRIS version
- Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}.
- The CRIS version affects register names and sizes. This command is useful in
- case autodetection of the CRIS version fails.
- @item show cris-version
- Show the current CRIS version.
- @item set cris-dwarf2-cfi
- @cindex DWARF-2 CFI and CRIS
- Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}.
- Change to @samp{off} when using @code{gcc-cris} whose version is below
- @code{R59}.
- @item show cris-dwarf2-cfi
- Show the current state of using DWARF-2 CFI.
- @item set cris-mode @var{mode}
- @cindex CRIS mode
- Set the current CRIS mode to @var{mode}. It should only be changed when
- debugging in guru mode, in which case it should be set to
- @samp{guru} (the default is @samp{normal}).
- @item show cris-mode
- Show the current CRIS mode.
- @end table
- @node Super-H
- @subsection Renesas Super-H
- @cindex Super-H
- For the Renesas Super-H processor, @value{GDBN} provides these
- commands:
- @table @code
- @item set sh calling-convention @var{convention}
- @kindex set sh calling-convention
- Set the calling-convention used when calling functions from @value{GDBN}.
- Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}.
- With the @samp{gcc} setting, functions are called using the @value{NGCC} calling
- convention. If the DWARF-2 information of the called function specifies
- that the function follows the Renesas calling convention, the function
- is called using the Renesas calling convention. If the calling convention
- is set to @samp{renesas}, the Renesas calling convention is always used,
- regardless of the DWARF-2 information. This can be used to override the
- default of @samp{gcc} if debug information is missing, or the compiler
- does not emit the DWARF-2 calling convention entry for a function.
- @item show sh calling-convention
- @kindex show sh calling-convention
- Show the current calling convention setting.
- @end table
- @node Architectures
- @section Architectures
- This section describes characteristics of architectures that affect
- all uses of @value{GDBN} with the architecture, both native and cross.
- @menu
- * AArch64::
- * i386::
- * Alpha::
- * MIPS::
- * HPPA:: HP PA architecture
- * PowerPC::
- * Nios II::
- * Sparc64::
- * S12Z::
- @end menu
- @node AArch64
- @subsection AArch64
- @cindex AArch64 support
- When @value{GDBN} is debugging the AArch64 architecture, it provides the
- following special commands:
- @table @code
- @item set debug aarch64
- @kindex set debug aarch64
- This command determines whether AArch64 architecture-specific debugging
- messages are to be displayed.
- @item show debug aarch64
- Show whether AArch64 debugging messages are displayed.
- @end table
- @subsubsection AArch64 SVE.
- @cindex AArch64 SVE.
- When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Vector
- Extension (SVE) is present, then @value{GDBN} will provide the vector registers
- @code{$z0} through @code{$z31}, vector predicate registers @code{$p0} through
- @code{$p15}, and the @code{$ffr} register. In addition, the pseudo register
- @code{$vg} will be provided. This is the vector granule for the current thread
- and represents the number of 64-bit chunks in an SVE @code{z} register.
- If the vector length changes, then the @code{$vg} register will be updated,
- but the lengths of the @code{z} and @code{p} registers will not change. This
- is a known limitation of @value{GDBN} and does not affect the execution of the
- target process.
- @subsubsection AArch64 Pointer Authentication.
- @cindex AArch64 Pointer Authentication.
- @anchor{AArch64 PAC}
- When @value{GDBN} is debugging the AArch64 architecture, and the program is
- using the v8.3-A feature Pointer Authentication (PAC), then whenever the link
- register @code{$lr} is pointing to an PAC function its value will be masked.
- When GDB prints a backtrace, any addresses that required unmasking will be
- postfixed with the marker [PAC]. When using the MI, this is printed as part
- of the @code{addr_flags} field.
- @subsubsection AArch64 Memory Tagging Extension.
- @cindex AArch64 Memory Tagging Extension.
- When @value{GDBN} is debugging the AArch64 architecture, the program is
- using the v8.5-A feature Memory Tagging Extension (MTE) and there is support
- in the kernel for MTE, @value{GDBN} will make memory tagging functionality
- available for inspection and editing of logical and allocation tags.
- @xref{Memory Tagging}.
- To aid debugging, @value{GDBN} will output additional information when SIGSEGV
- signals are generated as a result of memory tag failures.
- If the tag violation is synchronous, the following will be shown:
- @smallexample
- Program received signal SIGSEGV, Segmentation fault
- Memory tag violation while accessing address 0x0500fffff7ff8000
- Allocation tag 0x1
- Logical tag 0x5.
- @end smallexample
- If the tag violation is asynchronous, the fault address is not available.
- In this case @value{GDBN} will show the following:
- @smallexample
- Program received signal SIGSEGV, Segmentation fault
- Memory tag violation
- Fault address unavailable.
- @end smallexample
- A special register, @code{tag_ctl}, is made available through the
- @code{org.gnu.gdb.aarch64.mte} feature. This register exposes some
- options that can be controlled at runtime and emulates the @code{prctl}
- option @code{PR_SET_TAGGED_ADDR_CTRL}. For further information, see the
- documentation in the Linux kernel.
- @node i386
- @subsection x86 Architecture-specific Issues
- @table @code
- @item set struct-convention @var{mode}
- @kindex set struct-convention
- @cindex struct return convention
- @cindex struct/union returned in registers
- Set the convention used by the inferior to return @code{struct}s and
- @code{union}s from functions to @var{mode}. Possible values of
- @var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the
- default). @code{"default"} or @code{"pcc"} means that @code{struct}s
- are returned on the stack, while @code{"reg"} means that a
- @code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will
- be returned in a register.
- @item show struct-convention
- @kindex show struct-convention
- Show the current setting of the convention to return @code{struct}s
- from functions.
- @end table
- @subsubsection Intel @dfn{Memory Protection Extensions} (MPX).
- @cindex Intel Memory Protection Extensions (MPX).
- Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
- @footnote{The register named with capital letters represent the architecture
- registers.} through @samp{BND3}. Bound registers store a pair of 64-bit values
- which are the lower bound and upper bound. Bounds are effective addresses or
- memory locations. The upper bounds are architecturally represented in 1's
- complement form. A bound having lower bound = 0, and upper bound = 0
- (1's complement of all bits set) will allow access to the entire address space.
- @samp{BND0} through @samp{BND3} are represented in @value{GDBN} as @samp{bnd0raw}
- through @samp{bnd3raw}. Pseudo registers @samp{bnd0} through @samp{bnd3}
- display the upper bound performing the complement of one operation on the
- upper bound value, i.e.@ when upper bound in @samp{bnd0raw} is 0 in the
- @value{GDBN} @samp{bnd0} it will be @code{0xfff@dots{}}. In this sense it
- can also be noted that the upper bounds are inclusive.
- As an example, assume that the register BND0 holds bounds for a pointer having
- access allowed for the range between 0x32 and 0x71. The values present on
- bnd0raw and bnd registers are presented as follows:
- @smallexample
- bnd0raw = @{0x32, 0xffffffff8e@}
- bnd0 = @{lbound = 0x32, ubound = 0x71@} : size 64
- @end smallexample
- This way the raw value can be accessed via bnd0raw@dots{}bnd3raw. Any
- change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its
- counterpart. When the bnd0@dots{}bnd3 registers are displayed via
- Python, the display includes the memory size, in bits, accessible to
- the pointer.
- Bounds can also be stored in bounds tables, which are stored in
- application memory. These tables store bounds for pointers by specifying
- the bounds pointer's value along with its bounds. Evaluating and changing
- bounds located in bound tables is therefore interesting while investigating
- bugs on MPX context. @value{GDBN} provides commands for this purpose:
- @table @code
- @item show mpx bound @var{pointer}
- @kindex show mpx bound
- Display bounds of the given @var{pointer}.
- @item set mpx bound @var{pointer}, @var{lbound}, @var{ubound}
- @kindex set mpx bound
- Set the bounds of a pointer in the bound table.
- This command takes three parameters: @var{pointer} is the pointers
- whose bounds are to be changed, @var{lbound} and @var{ubound} are new values
- for lower and upper bounds respectively.
- @end table
- When you call an inferior function on an Intel MPX enabled program,
- GDB sets the inferior's bound registers to the init (disabled) state
- before calling the function. As a consequence, bounds checks for the
- pointer arguments passed to the function will always pass.
- This is necessary because when you call an inferior function, the
- program is usually in the middle of the execution of other function.
- Since at that point bound registers are in an arbitrary state, not
- clearing them would lead to random bound violations in the called
- function.
- You can still examine the influence of the bound registers on the
- execution of the called function by stopping the execution of the
- called function at its prologue, setting bound registers, and
- continuing the execution. For example:
- @smallexample
- $ break *upper
- Breakpoint 2 at 0x4009de: file i386-mpx-call.c, line 47.
- $ print upper (a, b, c, d, 1)
- Breakpoint 2, upper (a=0x0, b=0x6e0000005b, c=0x0, d=0x0, len=48)....
- $ print $bnd0
- @{lbound = 0x0, ubound = ffffffff@} : size -1
- @end smallexample
- At this last step the value of bnd0 can be changed for investigation of bound
- violations caused along the execution of the call. In order to know how to
- set the bound registers or bound table for the call consult the ABI.
- @node Alpha
- @subsection Alpha
- See the following section.
- @node MIPS
- @subsection @acronym{MIPS}
- @cindex stack on Alpha
- @cindex stack on @acronym{MIPS}
- @cindex Alpha stack
- @cindex @acronym{MIPS} stack
- Alpha- and @acronym{MIPS}-based computers use an unusual stack frame, which
- sometimes requires @value{GDBN} to search backward in the object code to
- find the beginning of a function.
- @cindex response time, @acronym{MIPS} debugging
- To improve response time (especially for embedded applications, where
- @value{GDBN} may be restricted to a slow serial line for this search)
- you may want to limit the size of this search, using one of these
- commands:
- @table @code
- @cindex @code{heuristic-fence-post} (Alpha, @acronym{MIPS})
- @item set heuristic-fence-post @var{limit}
- Restrict @value{GDBN} to examining at most @var{limit} bytes in its
- search for the beginning of a function. A value of @var{0} (the
- default) means there is no limit. However, except for @var{0}, the
- larger the limit the more bytes @code{heuristic-fence-post} must search
- and therefore the longer it takes to run. You should only need to use
- this command when debugging a stripped executable.
- @item show heuristic-fence-post
- Display the current limit.
- @end table
- @noindent
- These commands are available @emph{only} when @value{GDBN} is configured
- for debugging programs on Alpha or @acronym{MIPS} processors.
- Several @acronym{MIPS}-specific commands are available when debugging @acronym{MIPS}
- programs:
- @table @code
- @item set mips abi @var{arg}
- @kindex set mips abi
- @cindex set ABI for @acronym{MIPS}
- Tell @value{GDBN} which @acronym{MIPS} ABI is used by the inferior. Possible
- values of @var{arg} are:
- @table @samp
- @item auto
- The default ABI associated with the current binary (this is the
- default).
- @item o32
- @item o64
- @item n32
- @item n64
- @item eabi32
- @item eabi64
- @end table
- @item show mips abi
- @kindex show mips abi
- Show the @acronym{MIPS} ABI used by @value{GDBN} to debug the inferior.
- @item set mips compression @var{arg}
- @kindex set mips compression
- @cindex code compression, @acronym{MIPS}
- Tell @value{GDBN} which @acronym{MIPS} compressed
- @acronym{ISA, Instruction Set Architecture} encoding is used by the
- inferior. @value{GDBN} uses this for code disassembly and other
- internal interpretation purposes. This setting is only referred to
- when no executable has been associated with the debugging session or
- the executable does not provide information about the encoding it uses.
- Otherwise this setting is automatically updated from information
- provided by the executable.
- Possible values of @var{arg} are @samp{mips16} and @samp{micromips}.
- The default compressed @acronym{ISA} encoding is @samp{mips16}, as
- executables containing @acronym{MIPS16} code frequently are not
- identified as such.
- This setting is ``sticky''; that is, it retains its value across
- debugging sessions until reset either explicitly with this command or
- implicitly from an executable.
- The compiler and/or assembler typically add symbol table annotations to
- identify functions compiled for the @acronym{MIPS16} or
- @acronym{microMIPS} @acronym{ISA}s. If these function-scope annotations
- are present, @value{GDBN} uses them in preference to the global
- compressed @acronym{ISA} encoding setting.
- @item show mips compression
- @kindex show mips compression
- Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by
- @value{GDBN} to debug the inferior.
- @item set mipsfpu
- @itemx show mipsfpu
- @xref{MIPS Embedded, set mipsfpu}.
- @item set mips mask-address @var{arg}
- @kindex set mips mask-address
- @cindex @acronym{MIPS} addresses, masking
- This command determines whether the most-significant 32 bits of 64-bit
- @acronym{MIPS} addresses are masked off. The argument @var{arg} can be
- @samp{on}, @samp{off}, or @samp{auto}. The latter is the default
- setting, which lets @value{GDBN} determine the correct value.
- @item show mips mask-address
- @kindex show mips mask-address
- Show whether the upper 32 bits of @acronym{MIPS} addresses are masked off or
- not.
- @item set remote-mips64-transfers-32bit-regs
- @kindex set remote-mips64-transfers-32bit-regs
- This command controls compatibility with 64-bit @acronym{MIPS} targets that
- transfer data in 32-bit quantities. If you have an old @acronym{MIPS} 64 target
- that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
- and 64 bits for other registers, set this option to @samp{on}.
- @item show remote-mips64-transfers-32bit-regs
- @kindex show remote-mips64-transfers-32bit-regs
- Show the current setting of compatibility with older @acronym{MIPS} 64 targets.
- @item set debug mips
- @kindex set debug mips
- This command turns on and off debugging messages for the @acronym{MIPS}-specific
- target code in @value{GDBN}.
- @item show debug mips
- @kindex show debug mips
- Show the current setting of @acronym{MIPS} debugging messages.
- @end table
- @node HPPA
- @subsection HPPA
- @cindex HPPA support
- When @value{GDBN} is debugging the HP PA architecture, it provides the
- following special commands:
- @table @code
- @item set debug hppa
- @kindex set debug hppa
- This command determines whether HPPA architecture-specific debugging
- messages are to be displayed.
- @item show debug hppa
- Show whether HPPA debugging messages are displayed.
- @item maint print unwind @var{address}
- @kindex maint print unwind@r{, HPPA}
- This command displays the contents of the unwind table entry at the
- given @var{address}.
- @end table
- @node PowerPC
- @subsection PowerPC
- @cindex PowerPC architecture
- When @value{GDBN} is debugging the PowerPC architecture, it provides a set of
- pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point
- numbers stored in the floating point registers. These values must be stored
- in two consecutive registers, always starting at an even register like
- @code{f0} or @code{f2}.
- The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed
- by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0},
- @code{f2} and @code{f3} for @code{$dl1} and so on.
- For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit
- wide Extended Floating Point Registers (@samp{f32} through @samp{f63}).
- @node Nios II
- @subsection Nios II
- @cindex Nios II architecture
- When @value{GDBN} is debugging the Nios II architecture,
- it provides the following special commands:
- @table @code
- @item set debug nios2
- @kindex set debug nios2
- This command turns on and off debugging messages for the Nios II
- target code in @value{GDBN}.
- @item show debug nios2
- @kindex show debug nios2
- Show the current setting of Nios II debugging messages.
- @end table
- @node Sparc64
- @subsection Sparc64
- @cindex Sparc64 support
- @cindex Application Data Integrity
- @subsubsection ADI Support
- The M7 processor supports an Application Data Integrity (ADI) feature that
- detects invalid data accesses. When software allocates memory and enables
- ADI on the allocated memory, it chooses a 4-bit version number, sets the
- version in the upper 4 bits of the 64-bit pointer to that data, and stores
- the 4-bit version in every cacheline of that data. Hardware saves the latter
- in spare bits in the cache and memory hierarchy. On each load and store,
- the processor compares the upper 4 VA (virtual address) bits to the
- cacheline's version. If there is a mismatch, the processor generates a
- version mismatch trap which can be either precise or disrupting. The trap
- is an error condition which the kernel delivers to the process as a SIGSEGV
- signal.
- Note that only 64-bit applications can use ADI and need to be built with
- ADI-enabled.
- Values of the ADI version tags, which are in granularity of a
- cacheline (64 bytes), can be viewed or modified.
- @table @code
- @kindex adi examine
- @item adi (examine | x) [ / @var{n} ] @var{addr}
- The @code{adi examine} command displays the value of one ADI version tag per
- cacheline.
- @var{n} is a decimal integer specifying the number in bytes; the default
- is 1. It specifies how much ADI version information, at the ratio of 1:ADI
- block size, to display.
- @var{addr} is the address in user address space where you want @value{GDBN}
- to begin displaying the ADI version tags.
- Below is an example of displaying ADI versions of variable "shmaddr".
- @smallexample
- (@value{GDBP}) adi x/100 shmaddr
- 0xfff800010002c000: 0 0
- @end smallexample
- @kindex adi assign
- @item adi (assign | a) [ / @var{n} ] @var{addr} = @var{tag}
- The @code{adi assign} command is used to assign new ADI version tag
- to an address.
- @var{n} is a decimal integer specifying the number in bytes;
- the default is 1. It specifies how much ADI version information, at the
- ratio of 1:ADI block size, to modify.
- @var{addr} is the address in user address space where you want @value{GDBN}
- to begin modifying the ADI version tags.
- @var{tag} is the new ADI version tag.
- For example, do the following to modify then verify ADI versions of
- variable "shmaddr":
- @smallexample
- (@value{GDBP}) adi a/100 shmaddr = 7
- (@value{GDBP}) adi x/100 shmaddr
- 0xfff800010002c000: 7 7
- @end smallexample
- @end table
- @node S12Z
- @subsection S12Z
- @cindex S12Z support
- When @value{GDBN} is debugging the S12Z architecture,
- it provides the following special command:
- @table @code
- @item maint info bdccsr
- @kindex maint info bdccsr@r{, S12Z}
- This command displays the current value of the microprocessor's
- BDCCSR register.
- @end table
- @node Controlling GDB
- @chapter Controlling @value{GDBN}
- You can alter the way @value{GDBN} interacts with you by using the
- @code{set} command. For commands controlling how @value{GDBN} displays
- data, see @ref{Print Settings, ,Print Settings}. Other settings are
- described here.
- @menu
- * Prompt:: Prompt
- * Editing:: Command editing
- * Command History:: Command history
- * Screen Size:: Screen size
- * Output Styling:: Output styling
- * Numbers:: Numbers
- * ABI:: Configuring the current ABI
- * Auto-loading:: Automatically loading associated files
- * Messages/Warnings:: Optional warnings and messages
- * Debugging Output:: Optional messages about internal happenings
- * Other Misc Settings:: Other Miscellaneous Settings
- @end menu
- @node Prompt
- @section Prompt
- @cindex prompt
- @value{GDBN} indicates its readiness to read a command by printing a string
- called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
- can change the prompt string with the @code{set prompt} command. For
- instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
- the prompt in one of the @value{GDBN} sessions so that you can always tell
- which one you are talking to.
- @emph{Note:} @code{set prompt} does not add a space for you after the
- prompt you set. This allows you to set a prompt which ends in a space
- or a prompt that does not.
- @table @code
- @kindex set prompt
- @item set prompt @var{newprompt}
- Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
- @kindex show prompt
- @item show prompt
- Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
- @end table
- Versions of @value{GDBN} that ship with Python scripting enabled have
- prompt extensions. The commands for interacting with these extensions
- are:
- @table @code
- @kindex set extended-prompt
- @item set extended-prompt @var{prompt}
- Set an extended prompt that allows for substitutions.
- @xref{gdb.prompt}, for a list of escape sequences that can be used for
- substitution. Any escape sequences specified as part of the prompt
- string are replaced with the corresponding strings each time the prompt
- is displayed.
- For example:
- @smallexample
- set extended-prompt Current working directory: \w (gdb)
- @end smallexample
- Note that when an extended-prompt is set, it takes control of the
- @var{prompt_hook} hook. @xref{prompt_hook}, for further information.
- @kindex show extended-prompt
- @item show extended-prompt
- Prints the extended prompt. Any escape sequences specified as part of
- the prompt string with @code{set extended-prompt}, are replaced with the
- corresponding strings each time the prompt is displayed.
- @end table
- @node Editing
- @section Command Editing
- @cindex readline
- @cindex command line editing
- @value{GDBN} reads its input commands via the @dfn{Readline} interface. This
- @sc{gnu} library provides consistent behavior for programs which provide a
- command line interface to the user. Advantages are @sc{gnu} Emacs-style
- or @dfn{vi}-style inline editing of commands, @code{csh}-like history
- substitution, and a storage and recall of command history across
- debugging sessions.
- You may control the behavior of command line editing in @value{GDBN} with the
- command @code{set}.
- @table @code
- @kindex set editing
- @cindex editing
- @item set editing
- @itemx set editing on
- Enable command line editing (enabled by default).
- @item set editing off
- Disable command line editing.
- @kindex show editing
- @item show editing
- Show whether command line editing is enabled.
- @end table
- @ifset SYSTEM_READLINE
- @xref{Command Line Editing, , , rluserman, GNU Readline Library},
- @end ifset
- @ifclear SYSTEM_READLINE
- @xref{Command Line Editing},
- @end ifclear
- for more details about the Readline
- interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
- encouraged to read that chapter.
- @cindex Readline application name
- @value{GDBN} sets the Readline application name to @samp{gdb}. This
- is useful for conditions in @file{.inputrc}.
- @cindex operate-and-get-next
- @value{GDBN} defines a bindable Readline command,
- @code{operate-and-get-next}. This is bound to @kbd{C-o} by default.
- This command accepts the current line for execution and fetches the
- next line relative to the current line from the history for editing.
- Any argument is ignored.
- @node Command History
- @section Command History
- @cindex command history
- @value{GDBN} can keep track of the commands you type during your
- debugging sessions, so that you can be certain of precisely what
- happened. Use these commands to manage the @value{GDBN} command
- history facility.
- @value{GDBN} uses the @sc{gnu} History library, a part of the Readline
- package, to provide the history facility.
- @ifset SYSTEM_READLINE
- @xref{Using History Interactively, , , history, GNU History Library},
- @end ifset
- @ifclear SYSTEM_READLINE
- @xref{Using History Interactively},
- @end ifclear
- for the detailed description of the History library.
- To issue a command to @value{GDBN} without affecting certain aspects of
- the state which is seen by users, prefix it with @samp{server }
- (@pxref{Server Prefix}). This
- means that this command will not affect the command history, nor will it
- affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
- pressed on a line by itself.
- @cindex @code{server}, command prefix
- The server prefix does not affect the recording of values into the value
- history; to print a value without recording it into the value history,
- use the @code{output} command instead of the @code{print} command.
- Here is the description of @value{GDBN} commands related to command
- history.
- @table @code
- @cindex history substitution
- @cindex history file
- @kindex set history filename
- @cindex @env{GDBHISTFILE}, environment variable
- @item set history filename @r{[}@var{fname}@r{]}
- Set the name of the @value{GDBN} command history file to @var{fname}.
- This is the file where @value{GDBN} reads an initial command history
- list, and where it writes the command history from this session when it
- exits. You can access this list through history expansion or through
- the history command editing characters listed below. This file defaults
- to the value of the environment variable @env{GDBHISTFILE}, or to
- @file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
- is not set.
- The @env{GDBHISTFILE} environment variable is read after processing
- any @value{GDBN} initialization files (@pxref{Startup}) and after
- processing any commands passed using command line options (for
- example, @code{-ex}).
- If the @var{fname} argument is not given, or if the @env{GDBHISTFILE}
- is the empty string then @value{GDBN} will neither try to load an
- existing history file, nor will it try to save the history on exit.
- @cindex save command history
- @kindex set history save
- @item set history save
- @itemx set history save on
- Record command history in a file, whose name may be specified with the
- @code{set history filename} command. By default, this option is
- disabled. The command history will be recorded when @value{GDBN}
- exits. If @code{set history filename} is set to the empty string then
- history saving is disabled, even when @code{set history save} is
- @code{on}.
- @item set history save off
- Don't record the command history into the file specified by @code{set
- history filename} when @value{GDBN} exits.
- @cindex history size
- @kindex set history size
- @cindex @env{GDBHISTSIZE}, environment variable
- @item set history size @var{size}
- @itemx set history size unlimited
- Set the number of commands which @value{GDBN} keeps in its history list.
- This defaults to the value of the environment variable @env{GDBHISTSIZE}, or
- to 256 if this variable is not set. Non-numeric values of @env{GDBHISTSIZE}
- are ignored. If @var{size} is @code{unlimited} or if @env{GDBHISTSIZE} is
- either a negative number or the empty string, then the number of commands
- @value{GDBN} keeps in the history list is unlimited.
- The @env{GDBHISTSIZE} environment variable is read after processing
- any @value{GDBN} initialization files (@pxref{Startup}) and after
- processing any commands passed using command line options (for
- example, @code{-ex}).
- @cindex remove duplicate history
- @kindex set history remove-duplicates
- @item set history remove-duplicates @var{count}
- @itemx set history remove-duplicates unlimited
- Control the removal of duplicate history entries in the command history list.
- If @var{count} is non-zero, @value{GDBN} will look back at the last @var{count}
- history entries and remove the first entry that is a duplicate of the current
- entry being added to the command history list. If @var{count} is
- @code{unlimited} then this lookbehind is unbounded. If @var{count} is 0, then
- removal of duplicate history entries is disabled.
- Only history entries added during the current session are considered for
- removal. This option is set to 0 by default.
- @end table
- History expansion assigns special meaning to the character @kbd{!}.
- @ifset SYSTEM_READLINE
- @xref{Event Designators, , , history, GNU History Library},
- @end ifset
- @ifclear SYSTEM_READLINE
- @xref{Event Designators},
- @end ifclear
- for more details.
- @cindex history expansion, turn on/off
- Since @kbd{!} is also the logical not operator in C, history expansion
- is off by default. If you decide to enable history expansion with the
- @code{set history expansion on} command, you may sometimes need to
- follow @kbd{!} (when it is used as logical not, in an expression) with
- a space or a tab to prevent it from being expanded. The readline
- history facilities do not attempt substitution on the strings
- @kbd{!=} and @kbd{!(}, even when history expansion is enabled.
- The commands to control history expansion are:
- @table @code
- @item set history expansion on
- @itemx set history expansion
- @kindex set history expansion
- Enable history expansion. History expansion is off by default.
- @item set history expansion off
- Disable history expansion.
- @c @group
- @kindex show history
- @item show history
- @itemx show history filename
- @itemx show history save
- @itemx show history size
- @itemx show history expansion
- These commands display the state of the @value{GDBN} history parameters.
- @code{show history} by itself displays all four states.
- @c @end group
- @end table
- @table @code
- @kindex show commands
- @cindex show last commands
- @cindex display command history
- @item show commands
- Display the last ten commands in the command history.
- @item show commands @var{n}
- Print ten commands centered on command number @var{n}.
- @item show commands +
- Print ten commands just after the commands last printed.
- @end table
- @node Screen Size
- @section Screen Size
- @cindex size of screen
- @cindex screen size
- @cindex pagination
- @cindex page size
- @cindex pauses in output
- Certain commands to @value{GDBN} may produce large amounts of
- information output to the screen. To help you read all of it,
- @value{GDBN} pauses and asks you for input at the end of each page of
- output. Type @key{RET} when you want to see one more page of output,
- @kbd{q} to discard the remaining output, or @kbd{c} to continue
- without paging for the rest of the current command. Also, the screen
- width setting determines when to wrap lines of output. Depending on
- what is being printed, @value{GDBN} tries to break the line at a
- readable place, rather than simply letting it overflow onto the
- following line.
- Normally @value{GDBN} knows the size of the screen from the terminal
- driver software. For example, on Unix @value{GDBN} uses the termcap data base
- together with the value of the @env{TERM} environment variable and the
- @code{stty rows} and @code{stty cols} settings. If this is not correct,
- you can override it with the @code{set height} and @code{set
- width} commands:
- @table @code
- @kindex set height
- @kindex set width
- @kindex show width
- @kindex show height
- @item set height @var{lpp}
- @itemx set height unlimited
- @itemx show height
- @itemx set width @var{cpl}
- @itemx set width unlimited
- @itemx show width
- These @code{set} commands specify a screen height of @var{lpp} lines and
- a screen width of @var{cpl} characters. The associated @code{show}
- commands display the current settings.
- If you specify a height of either @code{unlimited} or zero lines,
- @value{GDBN} does not pause during output no matter how long the
- output is. This is useful if output is to a file or to an editor
- buffer.
- Likewise, you can specify @samp{set width unlimited} or @samp{set
- width 0} to prevent @value{GDBN} from wrapping its output.
- @item set pagination on
- @itemx set pagination off
- @kindex set pagination
- Turn the output pagination on or off; the default is on. Turning
- pagination off is the alternative to @code{set height unlimited}. Note that
- running @value{GDBN} with the @option{--batch} option (@pxref{Mode
- Options, -batch}) also automatically disables pagination.
- @item show pagination
- @kindex show pagination
- Show the current pagination mode.
- @end table
- @node Output Styling
- @section Output Styling
- @cindex styling
- @cindex colors
- @kindex set style
- @kindex show style
- @value{GDBN} can style its output on a capable terminal. This is
- enabled by default on most systems, but disabled by default when in
- batch mode (@pxref{Mode Options}). Various style settings are available;
- and styles can also be disabled entirely.
- @table @code
- @item set style enabled @samp{on|off}
- Enable or disable all styling. The default is host-dependent, with
- most hosts defaulting to @samp{on}.
- @item show style enabled
- Show the current state of styling.
- @item set style sources @samp{on|off}
- Enable or disable source code styling. This affects whether source
- code, such as the output of the @code{list} command, is styled. The
- default is @samp{on}. Note that source styling only works if styling
- in general is enabled, and if a source highlighting library is
- available to @value{GDBN}.
- There are two ways that highlighting can be done. First, if
- @value{GDBN} was linked with the GNU Source Highlight library, then it
- is used. Otherwise, if @value{GDBN} was configured with Python
- scripting support, and if the Python Pygments package is available,
- then it will be used.
- @item show style sources
- Show the current state of source code styling.
- @item set style disassembler enabled @samp{on|off}
- Enable or disable disassembler styling. This affects whether
- disassembler output, such as the output of the @code{disassemble}
- command, is styled. Disassembler styling only works if styling in
- general is enabled (with @code{set style enabled on}), and if a source
- highlighting library is available to @value{GDBN}.
- To highlight disassembler output, @value{GDBN} must be compiled with
- Python support, and the Python Pygments package must be available. If
- these requirements are not met then @value{GDBN} will not highlight
- disassembler output, even when this option is @samp{on}.
- @item show style disassembler enabled
- Show the current state of disassembler styling.
- @end table
- Subcommands of @code{set style} control specific forms of styling.
- These subcommands all follow the same pattern: each style-able object
- can be styled with a foreground color, a background color, and an
- intensity.
- For example, the style of file names can be controlled using the
- @code{set style filename} group of commands:
- @table @code
- @item set style filename background @var{color}
- Set the background to @var{color}. Valid colors are @samp{none}
- (meaning the terminal's default color), @samp{black}, @samp{red},
- @samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan},
- and@samp{white}.
- @item set style filename foreground @var{color}
- Set the foreground to @var{color}. Valid colors are @samp{none}
- (meaning the terminal's default color), @samp{black}, @samp{red},
- @samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan},
- and@samp{white}.
- @item set style filename intensity @var{value}
- Set the intensity to @var{value}. Valid intensities are @samp{normal}
- (the default), @samp{bold}, and @samp{dim}.
- @end table
- The @code{show style} command and its subcommands are styling
- a style name in their output using its own style.
- So, use @command{show style} to see the complete list of styles,
- their characteristics and the visual aspect of each style.
- The style-able objects are:
- @table @code
- @item filename
- Control the styling of file names and URLs. By default, this style's
- foreground color is green.
- @item function
- Control the styling of function names. These are managed with the
- @code{set style function} family of commands. By default, this
- style's foreground color is yellow.
- @item variable
- Control the styling of variable names. These are managed with the
- @code{set style variable} family of commands. By default, this style's
- foreground color is cyan.
- @item address
- Control the styling of addresses. These are managed with the
- @code{set style address} family of commands. By default, this style's
- foreground color is blue.
- @item version
- Control the styling of @value{GDBN}'s version number text. By
- default, this style's foreground color is magenta and it has bold
- intensity. The version number is displayed in two places, the output
- of @command{show version}, and when @value{GDBN} starts up.
- In order to control how @value{GDBN} styles the version number at
- startup, add the @code{set style version} family of commands to the
- early initialization command file (@pxref{Initialization
- Files}).
- @item title
- Control the styling of titles. These are managed with the
- @code{set style title} family of commands. By default, this style's
- intensity is bold. Commands are using the title style to improve
- the readability of large output. For example, the commands
- @command{apropos} and @command{help} are using the title style
- for the command names.
- @item highlight
- Control the styling of highlightings. These are managed with the
- @code{set style highlight} family of commands. By default, this style's
- foreground color is red. Commands are using the highlight style to draw
- the user attention to some specific parts of their output. For example,
- the command @command{apropos -v REGEXP} uses the highlight style to
- mark the documentation parts matching @var{regexp}.
- @item tui-border
- Control the styling of the TUI border. Note that, unlike other
- styling options, only the color of the border can be controlled via
- @code{set style}. This was done for compatibility reasons, as TUI
- controls to set the border's intensity predated the addition of
- general styling to @value{GDBN}. @xref{TUI Configuration}.
- @item tui-active-border
- Control the styling of the active TUI border; that is, the TUI window
- that has the focus.
- @end table
- @node Numbers
- @section Numbers
- @cindex number representation
- @cindex entering numbers
- You can always enter numbers in octal, decimal, or hexadecimal in
- @value{GDBN} by the usual conventions: octal numbers begin with
- @samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
- begin with @samp{0x}. Numbers that neither begin with @samp{0} or
- @samp{0x}, nor end with a @samp{.} are, by default, entered in base
- 10; likewise, the default display for numbers---when no particular
- format is specified---is base 10. You can change the default base for
- both input and output with the commands described below.
- @table @code
- @kindex set input-radix
- @item set input-radix @var{base}
- Set the default base for numeric input. Supported choices
- for @var{base} are decimal 8, 10, or 16. The base must itself be
- specified either unambiguously or using the current input radix; for
- example, any of
- @smallexample
- set input-radix 012
- set input-radix 10.
- set input-radix 0xa
- @end smallexample
- @noindent
- sets the input base to decimal. On the other hand, @samp{set input-radix 10}
- leaves the input radix unchanged, no matter what it was, since
- @samp{10}, being without any leading or trailing signs of its base, is
- interpreted in the current radix. Thus, if the current radix is 16,
- @samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't
- change the radix.
- @kindex set output-radix
- @item set output-radix @var{base}
- Set the default base for numeric display. Supported choices
- for @var{base} are decimal 8, 10, or 16. The base must itself be
- specified either unambiguously or using the current input radix.
- @kindex show input-radix
- @item show input-radix
- Display the current default base for numeric input.
- @kindex show output-radix
- @item show output-radix
- Display the current default base for numeric display.
- @item set radix @r{[}@var{base}@r{]}
- @itemx show radix
- @kindex set radix
- @kindex show radix
- These commands set and show the default base for both input and output
- of numbers. @code{set radix} sets the radix of input and output to
- the same base; without an argument, it resets the radix back to its
- default value of 10.
- @end table
- @node ABI
- @section Configuring the Current ABI
- @value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your
- application automatically. However, sometimes you need to override its
- conclusions. Use these commands to manage @value{GDBN}'s view of the
- current ABI.
- @cindex OS ABI
- @kindex set osabi
- @kindex show osabi
- @cindex Newlib OS ABI and its influence on the longjmp handling
- One @value{GDBN} configuration can debug binaries for multiple operating
- system targets, either via remote debugging or native emulation.
- @value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use,
- but you can override its conclusion using the @code{set osabi} command.
- One example where this is useful is in debugging of binaries which use
- an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does
- not have the same identifying marks that the standard C library for your
- platform provides.
- When @value{GDBN} is debugging the AArch64 architecture, it provides a
- ``Newlib'' OS ABI. This is useful for handling @code{setjmp} and
- @code{longjmp} when debugging binaries that use the @sc{newlib} C library.
- The ``Newlib'' OS ABI can be selected by @code{set osabi Newlib}.
- @table @code
- @item show osabi
- Show the OS ABI currently in use.
- @item set osabi
- With no argument, show the list of registered available OS ABI's.
- @item set osabi @var{abi}
- Set the current OS ABI to @var{abi}.
- @end table
- @cindex float promotion
- Generally, the way that an argument of type @code{float} is passed to a
- function depends on whether the function is prototyped. For a prototyped
- (i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged,
- according to the architecture's convention for @code{float}. For unprototyped
- (i.e.@: K&R style) functions, @code{float} arguments are first promoted to type
- @code{double} and then passed.
- Unfortunately, some forms of debug information do not reliably indicate whether
- a function is prototyped. If @value{GDBN} calls a function that is not marked
- as prototyped, it consults @kbd{set coerce-float-to-double}.
- @table @code
- @kindex set coerce-float-to-double
- @item set coerce-float-to-double
- @itemx set coerce-float-to-double on
- Arguments of type @code{float} will be promoted to @code{double} when passed
- to an unprototyped function. This is the default setting.
- @item set coerce-float-to-double off
- Arguments of type @code{float} will be passed directly to unprototyped
- functions.
- @kindex show coerce-float-to-double
- @item show coerce-float-to-double
- Show the current setting of promoting @code{float} to @code{double}.
- @end table
- @kindex set cp-abi
- @kindex show cp-abi
- @value{GDBN} needs to know the ABI used for your program's C@t{++}
- objects. The correct C@t{++} ABI depends on which C@t{++} compiler was
- used to build your application. @value{GDBN} only fully supports
- programs with a single C@t{++} ABI; if your program contains code using
- multiple C@t{++} ABI's or if @value{GDBN} can not identify your
- program's ABI correctly, you can tell @value{GDBN} which ABI to use.
- Currently supported ABI's include ``gnu-v2'', for @code{g++} versions
- before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and
- ``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may
- use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is
- ``auto''.
- @table @code
- @item show cp-abi
- Show the C@t{++} ABI currently in use.
- @item set cp-abi
- With no argument, show the list of supported C@t{++} ABI's.
- @item set cp-abi @var{abi}
- @itemx set cp-abi auto
- Set the current C@t{++} ABI to @var{abi}, or return to automatic detection.
- @end table
- @node Auto-loading
- @section Automatically loading associated files
- @cindex auto-loading
- @value{GDBN} sometimes reads files with commands and settings automatically,
- without being explicitly told so by the user. We call this feature
- @dfn{auto-loading}. While auto-loading is useful for automatically adapting
- @value{GDBN} to the needs of your project, it can sometimes produce unexpected
- results or introduce security risks (e.g., if the file comes from untrusted
- sources).
- There are various kinds of files @value{GDBN} can automatically load.
- In addition to these files, @value{GDBN} supports auto-loading code written
- in various extension languages. @xref{Auto-loading extensions}.
- Note that loading of these associated files (including the local @file{.gdbinit}
- file) requires accordingly configured @code{auto-load safe-path}
- (@pxref{Auto-loading safe path}).
- For these reasons, @value{GDBN} includes commands and options to let you
- control when to auto-load files and which files should be auto-loaded.
- @table @code
- @anchor{set auto-load off}
- @kindex set auto-load off
- @item set auto-load off
- Globally disable loading of all auto-loaded files.
- You may want to use this command with the @samp{-iex} option
- (@pxref{Option -init-eval-command}) such as:
- @smallexample
- $ @kbd{gdb -iex "set auto-load off" untrusted-executable corefile}
- @end smallexample
- Be aware that system init file (@pxref{System-wide configuration})
- and init files from your home directory (@pxref{Home Directory Init File})
- still get read (as they come from generally trusted directories).
- To prevent @value{GDBN} from auto-loading even those init files, use the
- @option{-nx} option (@pxref{Mode Options}), in addition to
- @code{set auto-load no}.
- @anchor{show auto-load}
- @kindex show auto-load
- @item show auto-load
- Show whether auto-loading of each specific @samp{auto-load} file(s) is enabled
- or disabled.
- @smallexample
- (gdb) show auto-load
- gdb-scripts: Auto-loading of canned sequences of commands scripts is on.
- libthread-db: Auto-loading of inferior specific libthread_db is on.
- local-gdbinit: Auto-loading of .gdbinit script from current directory
- is on.
- python-scripts: Auto-loading of Python scripts is on.
- safe-path: List of directories from which it is safe to auto-load files
- is $debugdir:$datadir/auto-load.
- scripts-directory: List of directories from which to load auto-loaded scripts
- is $debugdir:$datadir/auto-load.
- @end smallexample
- @anchor{info auto-load}
- @kindex info auto-load
- @item info auto-load
- Print whether each specific @samp{auto-load} file(s) have been auto-loaded or
- not.
- @smallexample
- (gdb) info auto-load
- gdb-scripts:
- Loaded Script
- Yes /home/user/gdb/gdb-gdb.gdb
- libthread-db: No auto-loaded libthread-db.
- local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been
- loaded.
- python-scripts:
- Loaded Script
- Yes /home/user/gdb/gdb-gdb.py
- @end smallexample
- @end table
- These are @value{GDBN} control commands for the auto-loading:
- @multitable @columnfractions .5 .5
- @item @xref{set auto-load off}.
- @tab Disable auto-loading globally.
- @item @xref{show auto-load}.
- @tab Show setting of all kinds of files.
- @item @xref{info auto-load}.
- @tab Show state of all kinds of files.
- @item @xref{set auto-load gdb-scripts}.
- @tab Control for @value{GDBN} command scripts.
- @item @xref{show auto-load gdb-scripts}.
- @tab Show setting of @value{GDBN} command scripts.
- @item @xref{info auto-load gdb-scripts}.
- @tab Show state of @value{GDBN} command scripts.
- @item @xref{set auto-load python-scripts}.
- @tab Control for @value{GDBN} Python scripts.
- @item @xref{show auto-load python-scripts}.
- @tab Show setting of @value{GDBN} Python scripts.
- @item @xref{info auto-load python-scripts}.
- @tab Show state of @value{GDBN} Python scripts.
- @item @xref{set auto-load guile-scripts}.
- @tab Control for @value{GDBN} Guile scripts.
- @item @xref{show auto-load guile-scripts}.
- @tab Show setting of @value{GDBN} Guile scripts.
- @item @xref{info auto-load guile-scripts}.
- @tab Show state of @value{GDBN} Guile scripts.
- @item @xref{set auto-load scripts-directory}.
- @tab Control for @value{GDBN} auto-loaded scripts location.
- @item @xref{show auto-load scripts-directory}.
- @tab Show @value{GDBN} auto-loaded scripts location.
- @item @xref{add-auto-load-scripts-directory}.
- @tab Add directory for auto-loaded scripts location list.
- @item @xref{set auto-load local-gdbinit}.
- @tab Control for init file in the current directory.
- @item @xref{show auto-load local-gdbinit}.
- @tab Show setting of init file in the current directory.
- @item @xref{info auto-load local-gdbinit}.
- @tab Show state of init file in the current directory.
- @item @xref{set auto-load libthread-db}.
- @tab Control for thread debugging library.
- @item @xref{show auto-load libthread-db}.
- @tab Show setting of thread debugging library.
- @item @xref{info auto-load libthread-db}.
- @tab Show state of thread debugging library.
- @item @xref{set auto-load safe-path}.
- @tab Control directories trusted for automatic loading.
- @item @xref{show auto-load safe-path}.
- @tab Show directories trusted for automatic loading.
- @item @xref{add-auto-load-safe-path}.
- @tab Add directory trusted for automatic loading.
- @end multitable
- @menu
- * Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
- * libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
- * Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
- * Auto-loading verbose mode:: @samp{set/show debug auto-load}
- @end menu
- @node Init File in the Current Directory
- @subsection Automatically loading init file in the current directory
- @cindex auto-loading init file in the current directory
- By default, @value{GDBN} reads and executes the canned sequences of commands
- from init file (if any) in the current working directory,
- see @ref{Init File in the Current Directory during Startup}.
- Note that loading of this local @file{.gdbinit} file also requires accordingly
- configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}).
- @table @code
- @anchor{set auto-load local-gdbinit}
- @kindex set auto-load local-gdbinit
- @item set auto-load local-gdbinit [on|off]
- Enable or disable the auto-loading of canned sequences of commands
- (@pxref{Sequences}) found in init file in the current directory.
- @anchor{show auto-load local-gdbinit}
- @kindex show auto-load local-gdbinit
- @item show auto-load local-gdbinit
- Show whether auto-loading of canned sequences of commands from init file in the
- current directory is enabled or disabled.
- @anchor{info auto-load local-gdbinit}
- @kindex info auto-load local-gdbinit
- @item info auto-load local-gdbinit
- Print whether canned sequences of commands from init file in the
- current directory have been auto-loaded.
- @end table
- @node libthread_db.so.1 file
- @subsection Automatically loading thread debugging library
- @cindex auto-loading libthread_db.so.1
- This feature is currently present only on @sc{gnu}/Linux native hosts.
- @value{GDBN} reads in some cases thread debugging library from places specific
- to the inferior (@pxref{set libthread-db-search-path}).
- The special @samp{libthread-db-search-path} entry @samp{$sdir} is processed
- without checking this @samp{set auto-load libthread-db} switch as system
- libraries have to be trusted in general. In all other cases of
- @samp{libthread-db-search-path} entries @value{GDBN} checks first if @samp{set
- auto-load libthread-db} is enabled before trying to open such thread debugging
- library.
- Note that loading of this debugging library also requires accordingly configured
- @code{auto-load safe-path} (@pxref{Auto-loading safe path}).
- @table @code
- @anchor{set auto-load libthread-db}
- @kindex set auto-load libthread-db
- @item set auto-load libthread-db [on|off]
- Enable or disable the auto-loading of inferior specific thread debugging library.
- @anchor{show auto-load libthread-db}
- @kindex show auto-load libthread-db
- @item show auto-load libthread-db
- Show whether auto-loading of inferior specific thread debugging library is
- enabled or disabled.
- @anchor{info auto-load libthread-db}
- @kindex info auto-load libthread-db
- @item info auto-load libthread-db
- Print the list of all loaded inferior specific thread debugging libraries and
- for each such library print list of inferior @var{pid}s using it.
- @end table
- @node Auto-loading safe path
- @subsection Security restriction for auto-loading
- @cindex auto-loading safe-path
- As the files of inferior can come from untrusted source (such as submitted by
- an application user) @value{GDBN} does not always load any files automatically.
- @value{GDBN} provides the @samp{set auto-load safe-path} setting to list
- directories trusted for loading files not explicitly requested by user.
- Each directory can also be a shell wildcard pattern.
- If the path is not set properly you will see a warning and the file will not
- get loaded:
- @smallexample
- $ ./gdb -q ./gdb
- Reading symbols from /home/user/gdb/gdb...
- warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been
- declined by your `auto-load safe-path' set
- to "$debugdir:$datadir/auto-load".
- warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been
- declined by your `auto-load safe-path' set
- to "$debugdir:$datadir/auto-load".
- @end smallexample
- @noindent
- To instruct @value{GDBN} to go ahead and use the init files anyway,
- invoke @value{GDBN} like this:
- @smallexample
- $ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb
- @end smallexample
- The list of trusted directories is controlled by the following commands:
- @table @code
- @anchor{set auto-load safe-path}
- @kindex set auto-load safe-path
- @item set auto-load safe-path @r{[}@var{directories}@r{]}
- Set the list of directories (and their subdirectories) trusted for automatic
- loading and execution of scripts. You can also enter a specific trusted file.
- Each directory can also be a shell wildcard pattern; wildcards do not match
- directory separator - see @code{FNM_PATHNAME} for system function @code{fnmatch}
- (@pxref{Wildcard Matching, fnmatch, , libc, GNU C Library Reference Manual}).
- If you omit @var{directories}, @samp{auto-load safe-path} will be reset to
- its default value as specified during @value{GDBN} compilation.
- The list of directories uses path separator (@samp{:} on GNU and Unix
- systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
- to the @env{PATH} environment variable.
- @anchor{show auto-load safe-path}
- @kindex show auto-load safe-path
- @item show auto-load safe-path
- Show the list of directories trusted for automatic loading and execution of
- scripts.
- @anchor{add-auto-load-safe-path}
- @kindex add-auto-load-safe-path
- @item add-auto-load-safe-path
- Add an entry (or list of entries) to the list of directories trusted for
- automatic loading and execution of scripts. Multiple entries may be delimited
- by the host platform path separator in use.
- @end table
- This variable defaults to what @code{--with-auto-load-dir} has been configured
- to (@pxref{with-auto-load-dir}). @file{$debugdir} and @file{$datadir}
- substitution applies the same as for @ref{set auto-load scripts-directory}.
- The default @code{set auto-load safe-path} value can be also overriden by
- @value{GDBN} configuration option @option{--with-auto-load-safe-path}.
- Setting this variable to @file{/} disables this security protection,
- corresponding @value{GDBN} configuration option is
- @option{--without-auto-load-safe-path}.
- This variable is supposed to be set to the system directories writable by the
- system superuser only. Users can add their source directories in init files in
- their home directories (@pxref{Home Directory Init File}). See also deprecated
- init file in the current directory
- (@pxref{Init File in the Current Directory during Startup}).
- To force @value{GDBN} to load the files it declined to load in the previous
- example, you could use one of the following ways:
- @table @asis
- @item @file{~/.gdbinit}: @samp{add-auto-load-safe-path ~/src/gdb}
- Specify this trusted directory (or a file) as additional component of the list.
- You have to specify also any existing directories displayed by
- by @samp{show auto-load safe-path} (such as @samp{/usr:/bin} in this example).
- @item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" @dots{}}
- Specify this directory as in the previous case but just for a single
- @value{GDBN} session.
- @item @kbd{gdb -iex "set auto-load safe-path /" @dots{}}
- Disable auto-loading safety for a single @value{GDBN} session.
- This assumes all the files you debug during this @value{GDBN} session will come
- from trusted sources.
- @item @kbd{./configure --without-auto-load-safe-path}
- During compilation of @value{GDBN} you may disable any auto-loading safety.
- This assumes all the files you will ever debug with this @value{GDBN} come from
- trusted sources.
- @end table
- On the other hand you can also explicitly forbid automatic files loading which
- also suppresses any such warning messages:
- @table @asis
- @item @kbd{gdb -iex "set auto-load no" @dots{}}
- You can use @value{GDBN} command-line option for a single @value{GDBN} session.
- @item @file{~/.gdbinit}: @samp{set auto-load no}
- Disable auto-loading globally for the user
- (@pxref{Home Directory Init File}). While it is improbable, you could also
- use system init file instead (@pxref{System-wide configuration}).
- @end table
- This setting applies to the file names as entered by user. If no entry matches
- @value{GDBN} tries as a last resort to also resolve all the file names into
- their canonical form (typically resolving symbolic links) and compare the
- entries again. @value{GDBN} already canonicalizes most of the filenames on its
- own before starting the comparison so a canonical form of directories is
- recommended to be entered.
- @node Auto-loading verbose mode
- @subsection Displaying files tried for auto-load
- @cindex auto-loading verbose mode
- For better visibility of all the file locations where you can place scripts to
- be auto-loaded with inferior --- or to protect yourself against accidental
- execution of untrusted scripts --- @value{GDBN} provides a feature for printing
- all the files attempted to be loaded. Both existing and non-existing files may
- be printed.
- For example the list of directories from which it is safe to auto-load files
- (@pxref{Auto-loading safe path}) applies also to canonicalized filenames which
- may not be too obvious while setting it up.
- @smallexample
- (gdb) set debug auto-load on
- (gdb) file ~/src/t/true
- auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb"
- for objfile "/tmp/true".
- auto-load: Updating directories of "/usr:/opt".
- auto-load: Using directory "/usr".
- auto-load: Using directory "/opt".
- warning: File "/tmp/true-gdb.gdb" auto-loading has been declined
- by your `auto-load safe-path' set to "/usr:/opt".
- @end smallexample
- @table @code
- @anchor{set debug auto-load}
- @kindex set debug auto-load
- @item set debug auto-load [on|off]
- Set whether to print the filenames attempted to be auto-loaded.
- @anchor{show debug auto-load}
- @kindex show debug auto-load
- @item show debug auto-load
- Show whether printing of the filenames attempted to be auto-loaded is turned
- on or off.
- @end table
- @node Messages/Warnings
- @section Optional Warnings and Messages
- @cindex verbose operation
- @cindex optional warnings
- By default, @value{GDBN} is silent about its inner workings. If you are
- running on a slow machine, you may want to use the @code{set verbose}
- command. This makes @value{GDBN} tell you when it does a lengthy
- internal operation, so you will not think it has crashed.
- Currently, the messages controlled by @code{set verbose} are those
- which announce that the symbol table for a source file is being read;
- see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}.
- @table @code
- @kindex set verbose
- @item set verbose on
- Enables @value{GDBN} output of certain informational messages.
- @item set verbose off
- Disables @value{GDBN} output of certain informational messages.
- @kindex show verbose
- @item show verbose
- Displays whether @code{set verbose} is on or off.
- @end table
- By default, if @value{GDBN} encounters bugs in the symbol table of an
- object file, it is silent; but if you are debugging a compiler, you may
- find this information useful (@pxref{Symbol Errors, ,Errors Reading
- Symbol Files}).
- @table @code
- @kindex set complaints
- @item set complaints @var{limit}
- Permits @value{GDBN} to output @var{limit} complaints about each type of
- unusual symbols before becoming silent about the problem. Set
- @var{limit} to zero to suppress all complaints; set it to a large number
- to prevent complaints from being suppressed.
- @kindex show complaints
- @item show complaints
- Displays how many symbol complaints @value{GDBN} is permitted to produce.
- @end table
- @anchor{confirmation requests}
- By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
- lot of stupid questions to confirm certain commands. For example, if
- you try to run a program which is already running:
- @smallexample
- (@value{GDBP}) run
- The program being debugged has been started already.
- Start it from the beginning? (y or n)
- @end smallexample
- If you are willing to unflinchingly face the consequences of your own
- commands, you can disable this ``feature'':
- @table @code
- @kindex set confirm
- @cindex flinching
- @cindex confirmation
- @cindex stupid questions
- @item set confirm off
- Disables confirmation requests. Note that running @value{GDBN} with
- the @option{--batch} option (@pxref{Mode Options, -batch}) also
- automatically disables confirmation requests.
- @item set confirm on
- Enables confirmation requests (the default).
- @kindex show confirm
- @item show confirm
- Displays state of confirmation requests.
- @end table
- @cindex command tracing
- If you need to debug user-defined commands or sourced files you may find it
- useful to enable @dfn{command tracing}. In this mode each command will be
- printed as it is executed, prefixed with one or more @samp{+} symbols, the
- quantity denoting the call depth of each command.
- @table @code
- @kindex set trace-commands
- @cindex command scripts, debugging
- @item set trace-commands on
- Enable command tracing.
- @item set trace-commands off
- Disable command tracing.
- @item show trace-commands
- Display the current state of command tracing.
- @end table
- @node Debugging Output
- @section Optional Messages about Internal Happenings
- @cindex optional debugging messages
- @value{GDBN} has commands that enable optional debugging messages from
- various @value{GDBN} subsystems; normally these commands are of
- interest to @value{GDBN} maintainers, or when reporting a bug. This
- section documents those commands.
- @table @code
- @kindex set exec-done-display
- @item set exec-done-display
- Turns on or off the notification of asynchronous commands'
- completion. When on, @value{GDBN} will print a message when an
- asynchronous command finishes its execution. The default is off.
- @kindex show exec-done-display
- @item show exec-done-display
- Displays the current setting of asynchronous command completion
- notification.
- @kindex set debug
- @cindex ARM AArch64
- @item set debug aarch64
- Turns on or off display of debugging messages related to ARM AArch64.
- The default is off.
- @kindex show debug
- @item show debug aarch64
- Displays the current state of displaying debugging messages related to
- ARM AArch64.
- @cindex gdbarch debugging info
- @cindex architecture debugging info
- @item set debug arch
- Turns on or off display of gdbarch debugging info. The default is off
- @item show debug arch
- Displays the current state of displaying gdbarch debugging info.
- @item set debug aix-solib
- @cindex AIX shared library debugging
- Control display of debugging messages from the AIX shared library
- support module. The default is off.
- @item show debug aix-solib
- Show the current state of displaying AIX shared library debugging messages.
- @item set debug aix-thread
- @cindex AIX threads
- Display debugging messages about inner workings of the AIX thread
- module.
- @item show debug aix-thread
- Show the current state of AIX thread debugging info display.
- @item set debug check-physname
- @cindex physname
- Check the results of the ``physname'' computation. When reading DWARF
- debugging information for C@t{++}, @value{GDBN} attempts to compute
- each entity's name. @value{GDBN} can do this computation in two
- different ways, depending on exactly what information is present.
- When enabled, this setting causes @value{GDBN} to compute the names
- both ways and display any discrepancies.
- @item show debug check-physname
- Show the current state of ``physname'' checking.
- @item set debug coff-pe-read
- @cindex COFF/PE exported symbols
- Control display of debugging messages related to reading of COFF/PE
- exported symbols. The default is off.
- @item show debug coff-pe-read
- Displays the current state of displaying debugging messages related to
- reading of COFF/PE exported symbols.
- @item set debug dwarf-die
- @cindex DWARF DIEs
- Dump DWARF DIEs after they are read in.
- The value is the number of nesting levels to print.
- A value of zero turns off the display.
- @item show debug dwarf-die
- Show the current state of DWARF DIE debugging.
- @item set debug dwarf-line
- @cindex DWARF Line Tables
- Turns on or off display of debugging messages related to reading
- DWARF line tables. The default is 0 (off).
- A value of 1 provides basic information.
- A value greater than 1 provides more verbose information.
- @item show debug dwarf-line
- Show the current state of DWARF line table debugging.
- @item set debug dwarf-read
- @cindex DWARF Reading
- Turns on or off display of debugging messages related to reading
- DWARF debug info. The default is 0 (off).
- A value of 1 provides basic information.
- A value greater than 1 provides more verbose information.
- @item show debug dwarf-read
- Show the current state of DWARF reader debugging.
- @item set debug displaced
- @cindex displaced stepping debugging info
- Turns on or off display of @value{GDBN} debugging info for the
- displaced stepping support. The default is off.
- @item show debug displaced
- Displays the current state of displaying @value{GDBN} debugging info
- related to displaced stepping.
- @item set debug event
- @cindex event debugging info
- Turns on or off display of @value{GDBN} event debugging info. The
- default is off.
- @item show debug event
- Displays the current state of displaying @value{GDBN} event debugging
- info.
- @item set debug event-loop
- @cindex event-loop debugging
- Controls output of debugging info about the event loop. The possible
- values are @samp{off}, @samp{all} (shows all debugging info) and
- @samp{all-except-ui} (shows all debugging info except those about
- UI-related events).
- @item show debug event-loop
- Shows the current state of displaying debugging info about the event
- loop.
- @item set debug expression
- @cindex expression debugging info
- Turns on or off display of debugging info about @value{GDBN}
- expression parsing. The default is off.
- @item show debug expression
- Displays the current state of displaying debugging info about
- @value{GDBN} expression parsing.
- @item set debug fbsd-lwp
- @cindex FreeBSD LWP debug messages
- Turns on or off debugging messages from the FreeBSD LWP debug support.
- @item show debug fbsd-lwp
- Show the current state of FreeBSD LWP debugging messages.
- @item set debug fbsd-nat
- @cindex FreeBSD native target debug messages
- Turns on or off debugging messages from the FreeBSD native target.
- @item show debug fbsd-nat
- Show the current state of FreeBSD native target debugging messages.
- @item set debug fortran-array-slicing
- @cindex fortran array slicing debugging info
- Turns on or off display of @value{GDBN} Fortran array slicing
- debugging info. The default is off.
- @item show debug fortran-array-slicing
- Displays the current state of displaying @value{GDBN} Fortran array
- slicing debugging info.
- @item set debug frame
- @cindex frame debugging info
- Turns on or off display of @value{GDBN} frame debugging info. The
- default is off.
- @item show debug frame
- Displays the current state of displaying @value{GDBN} frame debugging
- info.
- @item set debug gnu-nat
- @cindex @sc{gnu}/Hurd debug messages
- Turn on or off debugging messages from the @sc{gnu}/Hurd debug support.
- @item show debug gnu-nat
- Show the current state of @sc{gnu}/Hurd debugging messages.
- @item set debug infrun
- @cindex inferior debugging info
- Turns on or off display of @value{GDBN} debugging info for running the inferior.
- The default is off. @file{infrun.c} contains GDB's runtime state machine used
- for implementing operations such as single-stepping the inferior.
- @item show debug infrun
- Displays the current state of @value{GDBN} inferior debugging.
- @item set debug jit
- @cindex just-in-time compilation, debugging messages
- Turn on or off debugging messages from JIT debug support.
- @item show debug jit
- Displays the current state of @value{GDBN} JIT debugging.
- @item set debug linux-nat @r{[}on@r{|}off@r{]}
- @cindex @sc{gnu}/Linux native target debug messages
- @cindex Linux native targets
- Turn on or off debugging messages from the Linux native target debug support.
- @item show debug linux-nat
- Show the current state of Linux native target debugging messages.
- @item set debug linux-namespaces
- @cindex @sc{gnu}/Linux namespaces debug messages
- Turn on or off debugging messages from the Linux namespaces debug support.
- @item show debug linux-namespaces
- Show the current state of Linux namespaces debugging messages.
- @item set debug mach-o
- @cindex Mach-O symbols processing
- Control display of debugging messages related to Mach-O symbols
- processing. The default is off.
- @item show debug mach-o
- Displays the current state of displaying debugging messages related to
- reading of COFF/PE exported symbols.
- @item set debug notification
- @cindex remote async notification debugging info
- Turn on or off debugging messages about remote async notification.
- The default is off.
- @item show debug notification
- Displays the current state of remote async notification debugging messages.
- @item set debug observer
- @cindex observer debugging info
- Turns on or off display of @value{GDBN} observer debugging. This
- includes info such as the notification of observable events.
- @item show debug observer
- Displays the current state of observer debugging.
- @item set debug overload
- @cindex C@t{++} overload debugging info
- Turns on or off display of @value{GDBN} C@t{++} overload debugging
- info. This includes info such as ranking of functions, etc. The default
- is off.
- @item show debug overload
- Displays the current state of displaying @value{GDBN} C@t{++} overload
- debugging info.
- @cindex expression parser, debugging info
- @cindex debug expression parser
- @item set debug parser
- Turns on or off the display of expression parser debugging output.
- Internally, this sets the @code{yydebug} variable in the expression
- parser. @xref{Tracing, , Tracing Your Parser, bison, Bison}, for
- details. The default is off.
- @item show debug parser
- Show the current state of expression parser debugging.
- @cindex packets, reporting on stdout
- @cindex serial connections, debugging
- @cindex debug remote protocol
- @cindex remote protocol debugging
- @cindex display remote packets
- @item set debug remote
- Turns on or off display of reports on all packets sent back and forth across
- the serial line to the remote machine. The info is printed on the
- @value{GDBN} standard output stream. The default is off.
- @item show debug remote
- Displays the state of display of remote packets.
- @item set debug remote-packet-max-chars
- Sets the maximum number of characters to display for each remote packet when
- @code{set debug remote} is on. This is useful to prevent @value{GDBN} from
- displaying lengthy remote packets and polluting the console.
- The default value is @code{512}, which means @value{GDBN} will truncate each
- remote packet after 512 bytes.
- Setting this option to @code{unlimited} will disable truncation and will output
- the full length of the remote packets.
- @item show debug remote-packet-max-chars
- Displays the number of bytes to output for remote packet debugging.
- @item set debug separate-debug-file
- Turns on or off display of debug output about separate debug file search.
- @item show debug separate-debug-file
- Displays the state of separate debug file search debug output.
- @item set debug serial
- Turns on or off display of @value{GDBN} serial debugging info. The
- default is off.
- @item show debug serial
- Displays the current state of displaying @value{GDBN} serial debugging
- info.
- @item set debug solib-frv
- @cindex FR-V shared-library debugging
- Turn on or off debugging messages for FR-V shared-library code.
- @item show debug solib-frv
- Display the current state of FR-V shared-library code debugging
- messages.
- @item set debug symbol-lookup
- @cindex symbol lookup
- Turns on or off display of debugging messages related to symbol lookup.
- The default is 0 (off).
- A value of 1 provides basic information.
- A value greater than 1 provides more verbose information.
- @item show debug symbol-lookup
- Show the current state of symbol lookup debugging messages.
- @item set debug symfile
- @cindex symbol file functions
- Turns on or off display of debugging messages related to symbol file functions.
- The default is off. @xref{Files}.
- @item show debug symfile
- Show the current state of symbol file debugging messages.
- @item set debug symtab-create
- @cindex symbol table creation
- Turns on or off display of debugging messages related to symbol table creation.
- The default is 0 (off).
- A value of 1 provides basic information.
- A value greater than 1 provides more verbose information.
- @item show debug symtab-create
- Show the current state of symbol table creation debugging.
- @item set debug target
- @cindex target debugging info
- Turns on or off display of @value{GDBN} target debugging info. This info
- includes what is going on at the target level of GDB, as it happens. The
- default is 0. Set it to 1 to track events, and to 2 to also track the
- value of large memory transfers.
- @item show debug target
- Displays the current state of displaying @value{GDBN} target debugging
- info.
- @item set debug timestamp
- @cindex timestamping debugging info
- Turns on or off display of timestamps with @value{GDBN} debugging info.
- When enabled, seconds and microseconds are displayed before each debugging
- message.
- @item show debug timestamp
- Displays the current state of displaying timestamps with @value{GDBN}
- debugging info.
- @item set debug varobj
- @cindex variable object debugging info
- Turns on or off display of @value{GDBN} variable object debugging
- info. The default is off.
- @item show debug varobj
- Displays the current state of displaying @value{GDBN} variable object
- debugging info.
- @item set debug xml
- @cindex XML parser debugging
- Turn on or off debugging messages for built-in XML parsers.
- @item show debug xml
- Displays the current state of XML debugging messages.
- @end table
- @node Other Misc Settings
- @section Other Miscellaneous Settings
- @cindex miscellaneous settings
- @table @code
- @kindex set interactive-mode
- @item set interactive-mode
- If @code{on}, forces @value{GDBN} to assume that GDB was started
- in a terminal. In practice, this means that @value{GDBN} should wait
- for the user to answer queries generated by commands entered at
- the command prompt. If @code{off}, forces @value{GDBN} to operate
- in the opposite mode, and it uses the default answers to all queries.
- If @code{auto} (the default), @value{GDBN} tries to determine whether
- its standard input is a terminal, and works in interactive-mode if it
- is, non-interactively otherwise.
- In the vast majority of cases, the debugger should be able to guess
- correctly which mode should be used. But this setting can be useful
- in certain specific cases, such as running a MinGW @value{GDBN}
- inside a cygwin window.
- @kindex show interactive-mode
- @item show interactive-mode
- Displays whether the debugger is operating in interactive mode or not.
- @end table
- @table @code
- @kindex set suppress-cli-notifications
- @item set suppress-cli-notifications
- If @code{on}, command-line-interface (CLI) notifications that are
- printed by @value{GDBN} are suppressed. If @code{off}, the
- notifications are printed as usual. The default value is @code{off}.
- CLI notifications occur when you change the selected context or when
- the program being debugged stops, as detailed below.
- @table @emph
- @item User-selected context changes:
- When you change the selected context (i.e.@: the current inferior,
- thread and/or the frame), @value{GDBN} prints information about the
- new context. For example, the default behavior is below:
- @smallexample
- (gdb) inferior 1
- [Switching to inferior 1 [process 634] (/tmp/test)]
- [Switching to thread 1 (process 634)]
- #0 main () at test.c:3
- 3 return 0;
- (gdb)
- @end smallexample
- When the notifications are suppressed, the new context is not printed:
- @smallexample
- (gdb) set suppress-cli-notifications on
- (gdb) inferior 1
- (gdb)
- @end smallexample
- @item The program being debugged stops:
- When the program you are debugging stops (e.g.@: because of hitting a
- breakpoint, completing source-stepping, an interrupt, etc.),
- @value{GDBN} prints information about the stop event. For example,
- below is a breakpoint hit:
- @smallexample
- (gdb) break test.c:3
- Breakpoint 2 at 0x555555555155: file test.c, line 3.
- (gdb) continue
- Continuing.
- Breakpoint 2, main () at test.c:3
- 3 return 0;
- (gdb)
- @end smallexample
- When the notifications are suppressed, the output becomes:
- @smallexample
- (gdb) break test.c:3
- Breakpoint 2 at 0x555555555155: file test.c, line 3.
- (gdb) set suppress-cli-notifications on
- (gdb) continue
- Continuing.
- (gdb)
- @end smallexample
- Suppressing CLI notifications may be useful in scripts to obtain a
- reduced output from a list of commands.
- @end table
- @kindex show suppress-cli-notifications
- @item show suppress-cli-notifications
- Displays whether printing CLI notifications is suppressed or not.
- @end table
- @node Extending GDB
- @chapter Extending @value{GDBN}
- @cindex extending GDB
- @value{GDBN} provides several mechanisms for extension.
- @value{GDBN} also provides the ability to automatically load
- extensions when it reads a file for debugging. This allows the
- user to automatically customize @value{GDBN} for the program
- being debugged.
- To facilitate the use of extension languages, @value{GDBN} is capable
- of evaluating the contents of a file. When doing so, @value{GDBN}
- can recognize which extension language is being used by looking at
- the filename extension. Files with an unrecognized filename extension
- are always treated as a @value{GDBN} Command Files.
- @xref{Command Files,, Command files}.
- You can control how @value{GDBN} evaluates these files with the following
- setting:
- @table @code
- @kindex set script-extension
- @kindex show script-extension
- @item set script-extension off
- All scripts are always evaluated as @value{GDBN} Command Files.
- @item set script-extension soft
- The debugger determines the scripting language based on filename
- extension. If this scripting language is supported, @value{GDBN}
- evaluates the script using that language. Otherwise, it evaluates
- the file as a @value{GDBN} Command File.
- @item set script-extension strict
- The debugger determines the scripting language based on filename
- extension, and evaluates the script using that language. If the
- language is not supported, then the evaluation fails.
- @item show script-extension
- Display the current value of the @code{script-extension} option.
- @end table
- @ifset SYSTEM_GDBINIT_DIR
- This setting is not used for files in the system-wide gdbinit directory.
- Files in that directory must have an extension matching their language,
- or have a @file{.gdb} extension to be interpreted as regular @value{GDBN}
- commands. @xref{Startup}.
- @end ifset
- @menu
- * Sequences:: Canned Sequences of @value{GDBN} Commands
- * Aliases:: Command Aliases
- * Python:: Extending @value{GDBN} using Python
- * Guile:: Extending @value{GDBN} using Guile
- * Auto-loading extensions:: Automatically loading extensions
- * Multiple Extension Languages:: Working with multiple extension languages
- @end menu
- @node Sequences
- @section Canned Sequences of Commands
- Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
- Command Lists}), @value{GDBN} provides two ways to store sequences of
- commands for execution as a unit: user-defined commands and command
- files.
- @menu
- * Define:: How to define your own commands
- * Hooks:: Hooks for user-defined commands
- * Command Files:: How to write scripts of commands to be stored in a file
- * Output:: Commands for controlled output
- * Auto-loading sequences:: Controlling auto-loaded command files
- @end menu
- @node Define
- @subsection User-defined Commands
- @cindex user-defined command
- @cindex arguments, to user-defined commands
- A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
- which you assign a new name as a command. This is done with the
- @code{define} command. User commands may accept an unlimited number of arguments
- separated by whitespace. Arguments are accessed within the user command
- via @code{$arg0@dots{}$argN}. A trivial example:
- @smallexample
- define adder
- print $arg0 + $arg1 + $arg2
- end
- @end smallexample
- @noindent
- To execute the command use:
- @smallexample
- adder 1 2 3
- @end smallexample
- @noindent
- This defines the command @code{adder}, which prints the sum of
- its three arguments. Note the arguments are text substitutions, so they may
- reference variables, use complex expressions, or even perform inferior
- functions calls.
- @cindex argument count in user-defined commands
- @cindex how many arguments (user-defined commands)
- In addition, @code{$argc} may be used to find out how many arguments have
- been passed.
- @smallexample
- define adder
- if $argc == 2
- print $arg0 + $arg1
- end
- if $argc == 3
- print $arg0 + $arg1 + $arg2
- end
- end
- @end smallexample
- Combining with the @code{eval} command (@pxref{eval}) makes it easier
- to process a variable number of arguments:
- @smallexample
- define adder
- set $i = 0
- set $sum = 0
- while $i < $argc
- eval "set $sum = $sum + $arg%d", $i
- set $i = $i + 1
- end
- print $sum
- end
- @end smallexample
- @table @code
- @kindex define
- @item define @var{commandname}
- Define a command named @var{commandname}. If there is already a command
- by that name, you are asked to confirm that you want to redefine it.
- The argument @var{commandname} may be a bare command name consisting of letters,
- numbers, dashes, dots, and underscores. It may also start with any
- predefined or user-defined prefix command.
- For example, @samp{define target my-target} creates
- a user-defined @samp{target my-target} command.
- The definition of the command is made up of other @value{GDBN} command lines,
- which are given following the @code{define} command. The end of these
- commands is marked by a line containing @code{end}.
- @kindex document
- @kindex end@r{ (user-defined commands)}
- @item document @var{commandname}
- Document the user-defined command @var{commandname}, so that it can be
- accessed by @code{help}. The command @var{commandname} must already be
- defined. This command reads lines of documentation just as @code{define}
- reads the lines of the command definition, ending with @code{end}.
- After the @code{document} command is finished, @code{help} on command
- @var{commandname} displays the documentation you have written.
- You may use the @code{document} command again to change the
- documentation of a command. Redefining the command with @code{define}
- does not change the documentation.
- @kindex define-prefix
- @item define-prefix @var{commandname}
- Define or mark the command @var{commandname} as a user-defined prefix
- command. Once marked, @var{commandname} can be used as prefix command
- by the @code{define} command.
- Note that @code{define-prefix} can be used with a not yet defined
- @var{commandname}. In such a case, @var{commandname} is defined as
- an empty user-defined command.
- In case you redefine a command that was marked as a user-defined
- prefix command, the subcommands of the redefined command are kept
- (and @value{GDBN} indicates so to the user).
- Example:
- @example
- (gdb) define-prefix abc
- (gdb) define-prefix abc def
- (gdb) define abc def
- Type commands for definition of "abc def".
- End with a line saying just "end".
- >echo command initial def\n
- >end
- (gdb) define abc def ghi
- Type commands for definition of "abc def ghi".
- End with a line saying just "end".
- >echo command ghi\n
- >end
- (gdb) define abc def
- Keeping subcommands of prefix command "def".
- Redefine command "def"? (y or n) y
- Type commands for definition of "abc def".
- End with a line saying just "end".
- >echo command def\n
- >end
- (gdb) abc def ghi
- command ghi
- (gdb) abc def
- command def
- (gdb)
- @end example
- @kindex dont-repeat
- @cindex don't repeat command
- @item dont-repeat
- Used inside a user-defined command, this tells @value{GDBN} that this
- command should not be repeated when the user hits @key{RET}
- (@pxref{Command Syntax, repeat last command}).
- @kindex help user-defined
- @item help user-defined
- List all user-defined commands and all python commands defined in class
- COMMAND_USER. The first line of the documentation or docstring is
- included (if any).
- @kindex show user
- @item show user
- @itemx show user @var{commandname}
- Display the @value{GDBN} commands used to define @var{commandname} (but
- not its documentation). If no @var{commandname} is given, display the
- definitions for all user-defined commands.
- This does not work for user-defined python commands.
- @cindex infinite recursion in user-defined commands
- @kindex show max-user-call-depth
- @kindex set max-user-call-depth
- @item show max-user-call-depth
- @itemx set max-user-call-depth
- The value of @code{max-user-call-depth} controls how many recursion
- levels are allowed in user-defined commands before @value{GDBN} suspects an
- infinite recursion and aborts the command.
- This does not apply to user-defined python commands.
- @end table
- In addition to the above commands, user-defined commands frequently
- use control flow commands, described in @ref{Command Files}.
- When user-defined commands are executed, the
- commands of the definition are not printed. An error in any command
- stops execution of the user-defined command.
- If used interactively, commands that would ask for confirmation proceed
- without asking when used inside a user-defined command. Many @value{GDBN}
- commands that normally print messages to say what they are doing omit the
- messages when used in a user-defined command.
- @node Hooks
- @subsection User-defined Command Hooks
- @cindex command hooks
- @cindex hooks, for commands
- @cindex hooks, pre-command
- @kindex hook
- You may define @dfn{hooks}, which are a special kind of user-defined
- command. Whenever you run the command @samp{foo}, if the user-defined
- command @samp{hook-foo} exists, it is executed (with no arguments)
- before that command.
- @cindex hooks, post-command
- @kindex hookpost
- A hook may also be defined which is run after the command you executed.
- Whenever you run the command @samp{foo}, if the user-defined command
- @samp{hookpost-foo} exists, it is executed (with no arguments) after
- that command. Post-execution hooks may exist simultaneously with
- pre-execution hooks, for the same command.
- It is valid for a hook to call the command which it hooks. If this
- occurs, the hook is not re-executed, thereby avoiding infinite recursion.
- @c It would be nice if hookpost could be passed a parameter indicating
- @c if the command it hooks executed properly or not. FIXME!
- @kindex stop@r{, a pseudo-command}
- In addition, a pseudo-command, @samp{stop} exists. Defining
- (@samp{hook-stop}) makes the associated commands execute every time
- execution stops in your program: before breakpoint commands are run,
- displays are printed, or the stack frame is printed.
- For example, to ignore @code{SIGALRM} signals while
- single-stepping, but treat them normally during normal execution,
- you could define:
- @smallexample
- define hook-stop
- handle SIGALRM nopass
- end
- define hook-run
- handle SIGALRM pass
- end
- define hook-continue
- handle SIGALRM pass
- end
- @end smallexample
- As a further example, to hook at the beginning and end of the @code{echo}
- command, and to add extra text to the beginning and end of the message,
- you could define:
- @smallexample
- define hook-echo
- echo <<<---
- end
- define hookpost-echo
- echo --->>>\n
- end
- (@value{GDBP}) echo Hello World
- <<<---Hello World--->>>
- (@value{GDBP})
- @end smallexample
- You can define a hook for any single-word command in @value{GDBN}, but
- not for command aliases; you should define a hook for the basic command
- name, e.g.@: @code{backtrace} rather than @code{bt}.
- @c FIXME! So how does Joe User discover whether a command is an alias
- @c or not?
- You can hook a multi-word command by adding @code{hook-} or
- @code{hookpost-} to the last word of the command, e.g.@:
- @samp{define target hook-remote} to add a hook to @samp{target remote}.
- If an error occurs during the execution of your hook, execution of
- @value{GDBN} commands stops and @value{GDBN} issues a prompt
- (before the command that you actually typed had a chance to run).
- If you try to define a hook which does not match any known command, you
- get a warning from the @code{define} command.
- @node Command Files
- @subsection Command Files
- @cindex command files
- @cindex scripting commands
- A command file for @value{GDBN} is a text file made of lines that are
- @value{GDBN} commands. Comments (lines starting with @kbd{#}) may
- also be included. An empty line in a command file does nothing; it
- does not mean to repeat the last command, as it would from the
- terminal.
- You can request the execution of a command file with the @code{source}
- command. Note that the @code{source} command is also used to evaluate
- scripts that are not Command Files. The exact behavior can be configured
- using the @code{script-extension} setting.
- @xref{Extending GDB,, Extending GDB}.
- @table @code
- @kindex source
- @cindex execute commands from a file
- @item source [-s] [-v] @var{filename}
- Execute the command file @var{filename}.
- @end table
- The lines in a command file are generally executed sequentially,
- unless the order of execution is changed by one of the
- @emph{flow-control commands} described below. The commands are not
- printed as they are executed. An error in any command terminates
- execution of the command file and control is returned to the console.
- @value{GDBN} first searches for @var{filename} in the current directory.
- If the file is not found there, and @var{filename} does not specify a
- directory, then @value{GDBN} also looks for the file on the source search path
- (specified with the @samp{directory} command);
- except that @file{$cdir} is not searched because the compilation directory
- is not relevant to scripts.
- If @code{-s} is specified, then @value{GDBN} searches for @var{filename}
- on the search path even if @var{filename} specifies a directory.
- The search is done by appending @var{filename} to each element of the
- search path. So, for example, if @var{filename} is @file{mylib/myscript}
- and the search path contains @file{/home/user} then @value{GDBN} will
- look for the script @file{/home/user/mylib/myscript}.
- The search is also done if @var{filename} is an absolute path.
- For example, if @var{filename} is @file{/tmp/myscript} and
- the search path contains @file{/home/user} then @value{GDBN} will
- look for the script @file{/home/user/tmp/myscript}.
- For DOS-like systems, if @var{filename} contains a drive specification,
- it is stripped before concatenation. For example, if @var{filename} is
- @file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN}
- will look for the script @file{c:/tmp/myscript}.
- If @code{-v}, for verbose mode, is given then @value{GDBN} displays
- each command as it is executed. The option must be given before
- @var{filename}, and is interpreted as part of the filename anywhere else.
- Commands that would ask for confirmation if used interactively proceed
- without asking when used in a command file. Many @value{GDBN} commands that
- normally print messages to say what they are doing omit the messages
- when called from command files.
- @value{GDBN} also accepts command input from standard input. In this
- mode, normal output goes to standard output and error output goes to
- standard error. Errors in a command file supplied on standard input do
- not terminate execution of the command file---execution continues with
- the next command.
- @smallexample
- gdb < cmds > log 2>&1
- @end smallexample
- (The syntax above will vary depending on the shell used.) This example
- will execute commands from the file @file{cmds}. All output and errors
- would be directed to @file{log}.
- Since commands stored on command files tend to be more general than
- commands typed interactively, they frequently need to deal with
- complicated situations, such as different or unexpected values of
- variables and symbols, changes in how the program being debugged is
- built, etc. @value{GDBN} provides a set of flow-control commands to
- deal with these complexities. Using these commands, you can write
- complex scripts that loop over data structures, execute commands
- conditionally, etc.
- @table @code
- @kindex if
- @kindex else
- @item if
- @itemx else
- This command allows to include in your script conditionally executed
- commands. The @code{if} command takes a single argument, which is an
- expression to evaluate. It is followed by a series of commands that
- are executed only if the expression is true (its value is nonzero).
- There can then optionally be an @code{else} line, followed by a series
- of commands that are only executed if the expression was false. The
- end of the list is marked by a line containing @code{end}.
- @kindex while
- @item while
- This command allows to write loops. Its syntax is similar to
- @code{if}: the command takes a single argument, which is an expression
- to evaluate, and must be followed by the commands to execute, one per
- line, terminated by an @code{end}. These commands are called the
- @dfn{body} of the loop. The commands in the body of @code{while} are
- executed repeatedly as long as the expression evaluates to true.
- @kindex loop_break
- @item loop_break
- This command exits the @code{while} loop in whose body it is included.
- Execution of the script continues after that @code{while}s @code{end}
- line.
- @kindex loop_continue
- @item loop_continue
- This command skips the execution of the rest of the body of commands
- in the @code{while} loop in whose body it is included. Execution
- branches to the beginning of the @code{while} loop, where it evaluates
- the controlling expression.
- @kindex end@r{ (if/else/while commands)}
- @item end
- Terminate the block of commands that are the body of @code{if},
- @code{else}, or @code{while} flow-control commands.
- @end table
- @node Output
- @subsection Commands for Controlled Output
- During the execution of a command file or a user-defined command, normal
- @value{GDBN} output is suppressed; the only output that appears is what is
- explicitly printed by the commands in the definition. This section
- describes three commands useful for generating exactly the output you
- want.
- @table @code
- @kindex echo
- @item echo @var{text}
- @c I do not consider backslash-space a standard C escape sequence
- @c because it is not in ANSI.
- Print @var{text}. Nonprinting characters can be included in
- @var{text} using C escape sequences, such as @samp{\n} to print a
- newline. @strong{No newline is printed unless you specify one.}
- In addition to the standard C escape sequences, a backslash followed
- by a space stands for a space. This is useful for displaying a
- string with spaces at the beginning or the end, since leading and
- trailing spaces are otherwise trimmed from all arguments.
- To print @samp{@w{ }and foo =@w{ }}, use the command
- @samp{echo \@w{ }and foo = \@w{ }}.
- A backslash at the end of @var{text} can be used, as in C, to continue
- the command onto subsequent lines. For example,
- @smallexample
- echo This is some text\n\
- which is continued\n\
- onto several lines.\n
- @end smallexample
- produces the same output as
- @smallexample
- echo This is some text\n
- echo which is continued\n
- echo onto several lines.\n
- @end smallexample
- @kindex output
- @item output @var{expression}
- Print the value of @var{expression} and nothing but that value: no
- newlines, no @samp{$@var{nn} = }. The value is not entered in the
- value history either. @xref{Expressions, ,Expressions}, for more information
- on expressions.
- @item output/@var{fmt} @var{expression}
- Print the value of @var{expression} in format @var{fmt}. You can use
- the same formats as for @code{print}. @xref{Output Formats,,Output
- Formats}, for more information.
- @kindex printf
- @item printf @var{template}, @var{expressions}@dots{}
- Print the values of one or more @var{expressions} under the control of
- the string @var{template}. To print several values, make
- @var{expressions} be a comma-separated list of individual expressions,
- which may be either numbers or pointers. Their values are printed as
- specified by @var{template}, exactly as a C program would do by
- executing the code below:
- @smallexample
- printf (@var{template}, @var{expressions}@dots{});
- @end smallexample
- As in @code{C} @code{printf}, ordinary characters in @var{template}
- are printed verbatim, while @dfn{conversion specification} introduced
- by the @samp{%} character cause subsequent @var{expressions} to be
- evaluated, their values converted and formatted according to type and
- style information encoded in the conversion specifications, and then
- printed.
- For example, you can print two values in hex like this:
- @smallexample
- printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
- @end smallexample
- @code{printf} supports all the standard @code{C} conversion
- specifications, including the flags and modifiers between the @samp{%}
- character and the conversion letter, with the following exceptions:
- @itemize @bullet
- @item
- The argument-ordering modifiers, such as @samp{2$}, are not supported.
- @item
- The modifier @samp{*} is not supported for specifying precision or
- width.
- @item
- The @samp{'} flag (for separation of digits into groups according to
- @code{LC_NUMERIC'}) is not supported.
- @item
- The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not
- supported.
- @item
- The conversion letter @samp{n} (as in @samp{%n}) is not supported.
- @item
- The conversion letters @samp{a} and @samp{A} are not supported.
- @end itemize
- @noindent
- Note that the @samp{ll} type modifier is supported only if the
- underlying @code{C} implementation used to build @value{GDBN} supports
- the @code{long long int} type, and the @samp{L} type modifier is
- supported only if @code{long double} type is available.
- As in @code{C}, @code{printf} supports simple backslash-escape
- sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"},
- @samp{\a}, and @samp{\f}, that consist of backslash followed by a
- single character. Octal and hexadecimal escape sequences are not
- supported.
- Additionally, @code{printf} supports conversion specifications for DFP
- (@dfn{Decimal Floating Point}) types using the following length modifiers
- together with a floating point specifier.
- letters:
- @itemize @bullet
- @item
- @samp{H} for printing @code{Decimal32} types.
- @item
- @samp{D} for printing @code{Decimal64} types.
- @item
- @samp{DD} for printing @code{Decimal128} types.
- @end itemize
- If the underlying @code{C} implementation used to build @value{GDBN} has
- support for the three length modifiers for DFP types, other modifiers
- such as width and precision will also be available for @value{GDBN} to use.
- In case there is no such @code{C} support, no additional modifiers will be
- available and the value will be printed in the standard way.
- Here's an example of printing DFP types using the above conversion letters:
- @smallexample
- printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
- @end smallexample
- @anchor{eval}
- @kindex eval
- @item eval @var{template}, @var{expressions}@dots{}
- Convert the values of one or more @var{expressions} under the control of
- the string @var{template} to a command line, and call it.
- @end table
- @node Auto-loading sequences
- @subsection Controlling auto-loading native @value{GDBN} scripts
- @cindex native script auto-loading
- When a new object file is read (for example, due to the @code{file}
- command, or because the inferior has loaded a shared library),
- @value{GDBN} will look for the command file @file{@var{objfile}-gdb.gdb}.
- @xref{Auto-loading extensions}.
- Auto-loading can be enabled or disabled,
- and the list of auto-loaded scripts can be printed.
- @table @code
- @anchor{set auto-load gdb-scripts}
- @kindex set auto-load gdb-scripts
- @item set auto-load gdb-scripts [on|off]
- Enable or disable the auto-loading of canned sequences of commands scripts.
- @anchor{show auto-load gdb-scripts}
- @kindex show auto-load gdb-scripts
- @item show auto-load gdb-scripts
- Show whether auto-loading of canned sequences of commands scripts is enabled or
- disabled.
- @anchor{info auto-load gdb-scripts}
- @kindex info auto-load gdb-scripts
- @cindex print list of auto-loaded canned sequences of commands scripts
- @item info auto-load gdb-scripts [@var{regexp}]
- Print the list of all canned sequences of commands scripts that @value{GDBN}
- auto-loaded.
- @end table
- If @var{regexp} is supplied only canned sequences of commands scripts with
- matching names are printed.
- @node Aliases
- @section Command Aliases
- @cindex aliases for commands
- Aliases allow you to define alternate spellings for existing commands.
- For example, if a new @value{GDBN} command defined in Python
- (@pxref{Python}) has a long name, it is handy to have an abbreviated
- version of it that involves less typing.
- @value{GDBN} itself uses aliases. For example @samp{s} is an alias
- of the @samp{step} command even though it is otherwise an ambiguous
- abbreviation of other commands like @samp{set} and @samp{show}.
- Aliases are also used to provide shortened or more common versions
- of multi-word commands. For example, @value{GDBN} provides the
- @samp{tty} alias of the @samp{set inferior-tty} command.
- You can define a new alias with the @samp{alias} command.
- @table @code
- @kindex alias
- @item alias [-a] [--] @var{alias} = @var{command} [@var{default-args}]
- @end table
- @var{alias} specifies the name of the new alias. Each word of
- @var{alias} must consist of letters, numbers, dashes and underscores.
- @var{command} specifies the name of an existing command
- that is being aliased.
- @var{command} can also be the name of an existing alias. In this
- case, @var{command} cannot be an alias that has default arguments.
- The @samp{-a} option specifies that the new alias is an abbreviation
- of the command. Abbreviations are not used in command completion.
- The @samp{--} option specifies the end of options,
- and is useful when @var{alias} begins with a dash.
- You can specify @var{default-args} for your alias. These
- @var{default-args} will be automatically added before the alias
- arguments typed explicitly on the command line.
- For example, the below defines an alias @code{btfullall} that shows all local
- variables and all frame arguments:
- @smallexample
- (@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all
- @end smallexample
- For more information about @var{default-args}, see @ref{Command
- aliases default args, ,Default Arguments}.
- Here is a simple example showing how to make an abbreviation of a
- command so that there is less to type. Suppose you were tired of
- typing @samp{disas}, the current shortest unambiguous abbreviation of
- the @samp{disassemble} command and you wanted an even shorter version
- named @samp{di}. The following will accomplish this.
- @smallexample
- (gdb) alias -a di = disas
- @end smallexample
- Note that aliases are different from user-defined commands. With a
- user-defined command, you also need to write documentation for it with
- the @samp{document} command. An alias automatically picks up the
- documentation of the existing command.
- Here is an example where we make @samp{elms} an abbreviation of
- @samp{elements} in the @samp{set print elements} command.
- This is to show that you can make an abbreviation of any part
- of a command.
- @smallexample
- (gdb) alias -a set print elms = set print elements
- (gdb) alias -a show print elms = show print elements
- (gdb) set p elms 200
- (gdb) show p elms
- Limit on string chars or array elements to print is 200.
- @end smallexample
- Note that if you are defining an alias of a @samp{set} command,
- and you want to have an alias for the corresponding @samp{show}
- command, then you need to define the latter separately.
- Unambiguously abbreviated commands are allowed in @var{command} and
- @var{alias}, just as they are normally.
- @smallexample
- (gdb) alias -a set pr elms = set p ele
- @end smallexample
- Finally, here is an example showing the creation of a one word
- alias for a more complex command.
- This creates alias @samp{spe} of the command @samp{set print elements}.
- @smallexample
- (gdb) alias spe = set print elements
- (gdb) spe 20
- @end smallexample
- @menu
- * Command aliases default args:: Default arguments for aliases
- @end menu
- @node Command aliases default args
- @subsection Default Arguments
- @cindex aliases for commands, default arguments
- You can tell @value{GDBN} to always prepend some default arguments to
- the list of arguments provided explicitly by the user when using a
- user-defined alias.
- If you repeatedly use the same arguments or options for a command, you
- can define an alias for this command and tell @value{GDBN} to
- automatically prepend these arguments or options to the list of
- arguments you type explicitly when using the alias@footnote{@value{GDBN}
- could easily accept default arguments for pre-defined commands and aliases,
- but it was deemed this would be confusing, and so is not allowed.}.
- For example, if you often use the command @code{thread apply all}
- specifying to work on the threads in ascending order and to continue in case it
- encounters an error, you can tell @value{GDBN} to automatically preprend
- the @code{-ascending} and @code{-c} options by using:
- @smallexample
- (@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c
- @end smallexample
- Once you have defined this alias with its default args, any time you type
- the @code{thread apply asc-all} followed by @code{some arguments},
- @value{GDBN} will execute @code{thread apply all -ascending -c some arguments}.
- To have even less to type, you can also define a one word alias:
- @smallexample
- (@value{GDBP}) alias t_a_c = thread apply all -ascending -c
- @end smallexample
- As usual, unambiguous abbreviations can be used for @var{alias}
- and @var{default-args}.
- The different aliases of a command do not share their default args.
- For example, you define a new alias @code{bt_ALL} showing all possible
- information and another alias @code{bt_SMALL} showing very limited information
- using:
- @smallexample
- (@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
- -past-main -past-entry -full
- (@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \
- -past-main off -past-entry off
- @end smallexample
- (For more on using the @code{alias} command, see @ref{Aliases}.)
- Default args are not limited to the arguments and options of @var{command},
- but can specify nested commands if @var{command} accepts such a nested command
- as argument.
- For example, the below defines @code{faalocalsoftype} that lists the
- frames having locals of a certain type, together with the matching
- local vars:
- @smallexample
- (@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t
- (@value{GDBP}) faalocalsoftype int
- #1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
- i = 0
- ret = 21845
- @end smallexample
- This is also very useful to define an alias for a set of nested @code{with}
- commands to have a particular combination of temporary settings. For example,
- the below defines the alias @code{pp10} that pretty prints an expression
- argument, with a maximum of 10 elements if the expression is a string or
- an array:
- @smallexample
- (@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print
- @end smallexample
- This defines the alias @code{pp10} as being a sequence of 3 commands.
- The first part @code{with print pretty --} temporarily activates the setting
- @code{set print pretty}, then launches the command that follows the separator
- @code{--}.
- The command following the first part is also a @code{with} command that
- temporarily changes the setting @code{set print elements} to 10, then
- launches the command that follows the second separator @code{--}.
- The third part @code{print} is the command the @code{pp10} alias will launch,
- using the temporary values of the settings and the arguments explicitly given
- by the user.
- For more information about the @code{with} command usage,
- see @ref{Command Settings}.
- @c Python docs live in a separate file.
- @include python.texi
- @c Guile docs live in a separate file.
- @include guile.texi
- @node Auto-loading extensions
- @section Auto-loading extensions
- @cindex auto-loading extensions
- @value{GDBN} provides two mechanisms for automatically loading
- extensions when a new object file is read (for example, due to the
- @code{file} command, or because the inferior has loaded a shared
- library): @file{@var{objfile}-gdb.@var{ext}} (@pxref{objfile-gdbdotext
- file,,The @file{@var{objfile}-gdb.@var{ext}} file}) and the
- @code{.debug_gdb_scripts} section of modern file formats like ELF
- (@pxref{dotdebug_gdb_scripts section,,The @code{.debug_gdb_scripts}
- section}). For a discussion of the differences between these two
- approaches see @ref{Which flavor to choose?}.
- The auto-loading feature is useful for supplying application-specific
- debugging commands and features.
- Auto-loading can be enabled or disabled,
- and the list of auto-loaded scripts can be printed.
- See the @samp{auto-loading} section of each extension language
- for more information.
- For @value{GDBN} command files see @ref{Auto-loading sequences}.
- For Python files see @ref{Python Auto-loading}.
- Note that loading of this script file also requires accordingly configured
- @code{auto-load safe-path} (@pxref{Auto-loading safe path}).
- @menu
- * objfile-gdbdotext file:: The @file{@var{objfile}-gdb.@var{ext}} file
- * dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
- * Which flavor to choose?:: Choosing between these approaches
- @end menu
- @node objfile-gdbdotext file
- @subsection The @file{@var{objfile}-gdb.@var{ext}} file
- @cindex @file{@var{objfile}-gdb.gdb}
- @cindex @file{@var{objfile}-gdb.py}
- @cindex @file{@var{objfile}-gdb.scm}
- When a new object file is read, @value{GDBN} looks for a file named
- @file{@var{objfile}-gdb.@var{ext}} (we call it @var{script-name} below),
- where @var{objfile} is the object file's name and
- where @var{ext} is the file extension for the extension language:
- @table @code
- @item @file{@var{objfile}-gdb.gdb}
- GDB's own command language
- @item @file{@var{objfile}-gdb.py}
- Python
- @item @file{@var{objfile}-gdb.scm}
- Guile
- @end table
- @var{script-name} is formed by ensuring that the file name of @var{objfile}
- is absolute, following all symlinks, and resolving @code{.} and @code{..}
- components, and appending the @file{-gdb.@var{ext}} suffix.
- If this file exists and is readable, @value{GDBN} will evaluate it as a
- script in the specified extension language.
- If this file does not exist, then @value{GDBN} will look for
- @var{script-name} file in all of the directories as specified below.
- (On MS-Windows/MS-DOS, the drive letter of the executable's leading
- directories is converted to a one-letter subdirectory, i.e.@:
- @file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows
- filesystems disallow colons in file names.)
- Note that loading of these files requires an accordingly configured
- @code{auto-load safe-path} (@pxref{Auto-loading safe path}).
- For object files using @file{.exe} suffix @value{GDBN} tries to load first the
- scripts normally according to its @file{.exe} filename. But if no scripts are
- found @value{GDBN} also tries script filenames matching the object file without
- its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
- is attempted on any platform. This makes the script filenames compatible
- between Unix and MS-Windows hosts.
- @table @code
- @anchor{set auto-load scripts-directory}
- @kindex set auto-load scripts-directory
- @item set auto-load scripts-directory @r{[}@var{directories}@r{]}
- Control @value{GDBN} auto-loaded scripts location. Multiple directory entries
- may be delimited by the host platform path separator in use
- (@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS).
- Each entry here needs to be covered also by the security setting
- @code{set auto-load safe-path} (@pxref{set auto-load safe-path}).
- @anchor{with-auto-load-dir}
- This variable defaults to @file{$debugdir:$datadir/auto-load}. The default
- @code{set auto-load safe-path} value can be also overriden by @value{GDBN}
- configuration option @option{--with-auto-load-dir}.
- Any reference to @file{$debugdir} will get replaced by
- @var{debug-file-directory} value (@pxref{Separate Debug Files}) and any
- reference to @file{$datadir} will get replaced by @var{data-directory} which is
- determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and
- @file{$datadir} must be placed as a directory component --- either alone or
- delimited by @file{/} or @file{\} directory separators, depending on the host
- platform.
- The list of directories uses path separator (@samp{:} on GNU and Unix
- systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
- to the @env{PATH} environment variable.
- @anchor{show auto-load scripts-directory}
- @kindex show auto-load scripts-directory
- @item show auto-load scripts-directory
- Show @value{GDBN} auto-loaded scripts location.
- @anchor{add-auto-load-scripts-directory}
- @kindex add-auto-load-scripts-directory
- @item add-auto-load-scripts-directory @r{[}@var{directories}@dots{}@r{]}
- Add an entry (or list of entries) to the list of auto-loaded scripts locations.
- Multiple entries may be delimited by the host platform path separator in use.
- @end table
- @value{GDBN} does not track which files it has already auto-loaded this way.
- @value{GDBN} will load the associated script every time the corresponding
- @var{objfile} is opened.
- So your @file{-gdb.@var{ext}} file should be careful to avoid errors if it
- is evaluated more than once.
- @node dotdebug_gdb_scripts section
- @subsection The @code{.debug_gdb_scripts} section
- @cindex @code{.debug_gdb_scripts} section
- For systems using file formats like ELF and COFF,
- when @value{GDBN} loads a new object file
- it will look for a special section named @code{.debug_gdb_scripts}.
- If this section exists, its contents is a list of null-terminated entries
- specifying scripts to load. Each entry begins with a non-null prefix byte that
- specifies the kind of entry, typically the extension language and whether the
- script is in a file or inlined in @code{.debug_gdb_scripts}.
- The following entries are supported:
- @table @code
- @item SECTION_SCRIPT_ID_PYTHON_FILE = 1
- @item SECTION_SCRIPT_ID_SCHEME_FILE = 3
- @item SECTION_SCRIPT_ID_PYTHON_TEXT = 4
- @item SECTION_SCRIPT_ID_SCHEME_TEXT = 6
- @end table
- @subsubsection Script File Entries
- If the entry specifies a file, @value{GDBN} will look for the file first
- in the current directory and then along the source search path
- (@pxref{Source Path, ,Specifying Source Directories}),
- except that @file{$cdir} is not searched, since the compilation
- directory is not relevant to scripts.
- File entries can be placed in section @code{.debug_gdb_scripts} with,
- for example, this GCC macro for Python scripts.
- @example
- /* Note: The "MS" section flags are to remove duplicates. */
- #define DEFINE_GDB_PY_SCRIPT(script_name) \
- asm("\
- .pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
- .byte 1 /* Python */\n\
- .asciz \"" script_name "\"\n\
- .popsection \n\
- ");
- @end example
- @noindent
- For Guile scripts, replace @code{.byte 1} with @code{.byte 3}.
- Then one can reference the macro in a header or source file like this:
- @example
- DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py")
- @end example
- The script name may include directories if desired.
- Note that loading of this script file also requires accordingly configured
- @code{auto-load safe-path} (@pxref{Auto-loading safe path}).
- If the macro invocation is put in a header, any application or library
- using this header will get a reference to the specified script,
- and with the use of @code{"MS"} attributes on the section, the linker
- will remove duplicates.
- @subsubsection Script Text Entries
- Script text entries allow to put the executable script in the entry
- itself instead of loading it from a file.
- The first line of the entry, everything after the prefix byte and up to
- the first newline (@code{0xa}) character, is the script name, and must not
- contain any kind of space character, e.g., spaces or tabs.
- The rest of the entry, up to the trailing null byte, is the script to
- execute in the specified language. The name needs to be unique among
- all script names, as @value{GDBN} executes each script only once based
- on its name.
- Here is an example from file @file{py-section-script.c} in the @value{GDBN}
- testsuite.
- @example
- #include "symcat.h"
- #include "gdb/section-scripts.h"
- asm(
- ".pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n"
- ".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n"
- ".ascii \"gdb.inlined-script\\n\"\n"
- ".ascii \"class test_cmd (gdb.Command):\\n\"\n"
- ".ascii \" def __init__ (self):\\n\"\n"
- ".ascii \" super (test_cmd, self).__init__ ("
- "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n"
- ".ascii \" def invoke (self, arg, from_tty):\\n\"\n"
- ".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n"
- ".ascii \"test_cmd ()\\n\"\n"
- ".byte 0\n"
- ".popsection\n"
- );
- @end example
- Loading of inlined scripts requires a properly configured
- @code{auto-load safe-path} (@pxref{Auto-loading safe path}).
- The path to specify in @code{auto-load safe-path} is the path of the file
- containing the @code{.debug_gdb_scripts} section.
- @node Which flavor to choose?
- @subsection Which flavor to choose?
- Given the multiple ways of auto-loading extensions, it might not always
- be clear which one to choose. This section provides some guidance.
- @noindent
- Benefits of the @file{-gdb.@var{ext}} way:
- @itemize @bullet
- @item
- Can be used with file formats that don't support multiple sections.
- @item
- Ease of finding scripts for public libraries.
- Scripts specified in the @code{.debug_gdb_scripts} section are searched for
- in the source search path.
- For publicly installed libraries, e.g., @file{libstdc++}, there typically
- isn't a source directory in which to find the script.
- @item
- Doesn't require source code additions.
- @end itemize
- @noindent
- Benefits of the @code{.debug_gdb_scripts} way:
- @itemize @bullet
- @item
- Works with static linking.
- Scripts for libraries done the @file{-gdb.@var{ext}} way require an objfile to
- trigger their loading. When an application is statically linked the only
- objfile available is the executable, and it is cumbersome to attach all the
- scripts from all the input libraries to the executable's
- @file{-gdb.@var{ext}} script.
- @item
- Works with classes that are entirely inlined.
- Some classes can be entirely inlined, and thus there may not be an associated
- shared library to attach a @file{-gdb.@var{ext}} script to.
- @item
- Scripts needn't be copied out of the source tree.
- In some circumstances, apps can be built out of large collections of internal
- libraries, and the build infrastructure necessary to install the
- @file{-gdb.@var{ext}} scripts in a place where @value{GDBN} can find them is
- cumbersome. It may be easier to specify the scripts in the
- @code{.debug_gdb_scripts} section as relative paths, and add a path to the
- top of the source tree to the source search path.
- @end itemize
- @node Multiple Extension Languages
- @section Multiple Extension Languages
- The Guile and Python extension languages do not share any state,
- and generally do not interfere with each other.
- There are some things to be aware of, however.
- @subsection Python comes first
- Python was @value{GDBN}'s first extension language, and to avoid breaking
- existing behaviour Python comes first. This is generally solved by the
- ``first one wins'' principle. @value{GDBN} maintains a list of enabled
- extension languages, and when it makes a call to an extension language,
- (say to pretty-print a value), it tries each in turn until an extension
- language indicates it has performed the request (e.g., has returned the
- pretty-printed form of a value).
- This extends to errors while performing such requests: If an error happens
- while, for example, trying to pretty-print an object then the error is
- reported and any following extension languages are not tried.
- @node Interpreters
- @chapter Command Interpreters
- @cindex command interpreters
- @value{GDBN} supports multiple command interpreters, and some command
- infrastructure to allow users or user interface writers to switch
- between interpreters or run commands in other interpreters.
- @value{GDBN} currently supports two command interpreters, the console
- interpreter (sometimes called the command-line interpreter or @sc{cli})
- and the machine interface interpreter (or @sc{gdb/mi}). This manual
- describes both of these interfaces in great detail.
- By default, @value{GDBN} will start with the console interpreter.
- However, the user may choose to start @value{GDBN} with another
- interpreter by specifying the @option{-i} or @option{--interpreter}
- startup options. Defined interpreters include:
- @table @code
- @item console
- @cindex console interpreter
- The traditional console or command-line interpreter. This is the most often
- used interpreter with @value{GDBN}. With no interpreter specified at runtime,
- @value{GDBN} will use this interpreter.
- @item mi
- @cindex mi interpreter
- The newest @sc{gdb/mi} interface (currently @code{mi3}). Used primarily
- by programs wishing to use @value{GDBN} as a backend for a debugger GUI
- or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
- Interface}.
- @item mi3
- @cindex mi3 interpreter
- The @sc{gdb/mi} interface introduced in @value{GDBN} 9.1.
- @item mi2
- @cindex mi2 interpreter
- The @sc{gdb/mi} interface introduced in @value{GDBN} 6.0.
- @item mi1
- @cindex mi1 interpreter
- The @sc{gdb/mi} interface introduced in @value{GDBN} 5.1.
- @end table
- @cindex invoke another interpreter
- @kindex interpreter-exec
- You may execute commands in any interpreter from the current
- interpreter using the appropriate command. If you are running the
- console interpreter, simply use the @code{interpreter-exec} command:
- @smallexample
- interpreter-exec mi "-data-list-register-names"
- @end smallexample
- @sc{gdb/mi} has a similar command, although it is only available in versions of
- @value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
- Note that @code{interpreter-exec} only changes the interpreter for the
- duration of the specified command. It does not change the interpreter
- permanently.
- @cindex start a new independent interpreter
- Although you may only choose a single interpreter at startup, it is
- possible to run an independent interpreter on a specified input/output
- device (usually a tty).
- For example, consider a debugger GUI or IDE that wants to provide a
- @value{GDBN} console view. It may do so by embedding a terminal
- emulator widget in its GUI, starting @value{GDBN} in the traditional
- command-line mode with stdin/stdout/stderr redirected to that
- terminal, and then creating an MI interpreter running on a specified
- input/output device. The console interpreter created by @value{GDBN}
- at startup handles commands the user types in the terminal widget,
- while the GUI controls and synchronizes state with @value{GDBN} using
- the separate MI interpreter.
- To start a new secondary @dfn{user interface} running MI, use the
- @code{new-ui} command:
- @kindex new-ui
- @cindex new user interface
- @smallexample
- new-ui @var{interpreter} @var{tty}
- @end smallexample
- The @var{interpreter} parameter specifies the interpreter to run.
- This accepts the same values as the @code{interpreter-exec} command.
- For example, @samp{console}, @samp{mi}, @samp{mi2}, etc. The
- @var{tty} parameter specifies the name of the bidirectional file the
- interpreter uses for input/output, usually the name of a
- pseudoterminal slave on Unix systems. For example:
- @smallexample
- (@value{GDBP}) new-ui mi /dev/pts/9
- @end smallexample
- @noindent
- runs an MI interpreter on @file{/dev/pts/9}.
- @node TUI
- @chapter @value{GDBN} Text User Interface
- @cindex TUI
- @cindex Text User Interface
- The @value{GDBN} Text User Interface (TUI) is a terminal
- interface which uses the @code{curses} library to show the source
- file, the assembly output, the program registers and @value{GDBN}
- commands in separate text windows. The TUI mode is supported only
- on platforms where a suitable version of the @code{curses} library
- is available.
- The TUI mode is enabled by default when you invoke @value{GDBN} as
- @samp{@value{GDBP} -tui}.
- You can also switch in and out of TUI mode while @value{GDBN} runs by
- using various TUI commands and key bindings, such as @command{tui
- enable} or @kbd{C-x C-a}. @xref{TUI Commands, ,TUI Commands}, and
- @ref{TUI Keys, ,TUI Key Bindings}.
- @menu
- * TUI Overview:: TUI overview
- * TUI Keys:: TUI key bindings
- * TUI Single Key Mode:: TUI single key mode
- * TUI Mouse Support:: TUI mouse support
- * TUI Commands:: TUI-specific commands
- * TUI Configuration:: TUI configuration variables
- @end menu
- @node TUI Overview
- @section TUI Overview
- In TUI mode, @value{GDBN} can display several text windows:
- @table @emph
- @item command
- This window is the @value{GDBN} command window with the @value{GDBN}
- prompt and the @value{GDBN} output. The @value{GDBN} input is still
- managed using readline.
- @item source
- The source window shows the source file of the program. The current
- line and active breakpoints are displayed in this window.
- @item assembly
- The assembly window shows the disassembly output of the program.
- @item register
- This window shows the processor registers. Registers are highlighted
- when their values change.
- @end table
- The source and assembly windows show the current program position
- by highlighting the current line and marking it with a @samp{>} marker.
- Breakpoints are indicated with two markers. The first marker
- indicates the breakpoint type:
- @table @code
- @item B
- Breakpoint which was hit at least once.
- @item b
- Breakpoint which was never hit.
- @item H
- Hardware breakpoint which was hit at least once.
- @item h
- Hardware breakpoint which was never hit.
- @end table
- The second marker indicates whether the breakpoint is enabled or not:
- @table @code
- @item +
- Breakpoint is enabled.
- @item -
- Breakpoint is disabled.
- @end table
- The source, assembly and register windows are updated when the current
- thread changes, when the frame changes, or when the program counter
- changes.
- These windows are not all visible at the same time. The command
- window is always visible. The others can be arranged in several
- layouts:
- @itemize @bullet
- @item
- source only,
- @item
- assembly only,
- @item
- source and assembly,
- @item
- source and registers, or
- @item
- assembly and registers.
- @end itemize
- These are the standard layouts, but other layouts can be defined.
- A status line above the command window shows the following information:
- @table @emph
- @item target
- Indicates the current @value{GDBN} target.
- (@pxref{Targets, ,Specifying a Debugging Target}).
- @item process
- Gives the current process or thread number.
- When no process is being debugged, this field is set to @code{No process}.
- @item function
- Gives the current function name for the selected frame.
- The name is demangled if demangling is turned on (@pxref{Print Settings}).
- When there is no symbol corresponding to the current program counter,
- the string @code{??} is displayed.
- @item line
- Indicates the current line number for the selected frame.
- When the current line number is not known, the string @code{??} is displayed.
- @item pc
- Indicates the current program counter address.
- @end table
- @node TUI Keys
- @section TUI Key Bindings
- @cindex TUI key bindings
- The TUI installs several key bindings in the readline keymaps
- @ifset SYSTEM_READLINE
- (@pxref{Command Line Editing, , , rluserman, GNU Readline Library}).
- @end ifset
- @ifclear SYSTEM_READLINE
- (@pxref{Command Line Editing}).
- @end ifclear
- The following key bindings are installed for both TUI mode and the
- @value{GDBN} standard mode.
- @table @kbd
- @kindex C-x C-a
- @item C-x C-a
- @kindex C-x a
- @itemx C-x a
- @kindex C-x A
- @itemx C-x A
- Enter or leave the TUI mode. When leaving the TUI mode,
- the curses window management stops and @value{GDBN} operates using
- its standard mode, writing on the terminal directly. When reentering
- the TUI mode, control is given back to the curses windows.
- The screen is then refreshed.
- This key binding uses the bindable Readline function
- @code{tui-switch-mode}.
- @kindex C-x 1
- @item C-x 1
- Use a TUI layout with only one window. The layout will
- either be @samp{source} or @samp{assembly}. When the TUI mode
- is not active, it will switch to the TUI mode.
- Think of this key binding as the Emacs @kbd{C-x 1} binding.
- This key binding uses the bindable Readline function
- @code{tui-delete-other-windows}.
- @kindex C-x 2
- @item C-x 2
- Use a TUI layout with at least two windows. When the current
- layout already has two windows, the next layout with two windows is used.
- When a new layout is chosen, one window will always be common to the
- previous layout and the new one.
- Think of it as the Emacs @kbd{C-x 2} binding.
- This key binding uses the bindable Readline function
- @code{tui-change-windows}.
- @kindex C-x o
- @item C-x o
- Change the active window. The TUI associates several key bindings
- (like scrolling and arrow keys) with the active window. This command
- gives the focus to the next TUI window.
- Think of it as the Emacs @kbd{C-x o} binding.
- This key binding uses the bindable Readline function
- @code{tui-other-window}.
- @kindex C-x s
- @item C-x s
- Switch in and out of the TUI SingleKey mode that binds single
- keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}).
- This key binding uses the bindable Readline function
- @code{next-keymap}.
- @end table
- The following key bindings only work in the TUI mode:
- @table @asis
- @kindex PgUp
- @item @key{PgUp}
- Scroll the active window one page up.
- @kindex PgDn
- @item @key{PgDn}
- Scroll the active window one page down.
- @kindex Up
- @item @key{Up}
- Scroll the active window one line up.
- @kindex Down
- @item @key{Down}
- Scroll the active window one line down.
- @kindex Left
- @item @key{Left}
- Scroll the active window one column left.
- @kindex Right
- @item @key{Right}
- Scroll the active window one column right.
- @kindex C-L
- @item @kbd{C-L}
- Refresh the screen.
- @end table
- Because the arrow keys scroll the active window in the TUI mode, they
- are not available for their normal use by readline unless the command
- window has the focus. When another window is active, you must use
- other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b}
- and @kbd{C-f} to control the command window.
- @node TUI Single Key Mode
- @section TUI Single Key Mode
- @cindex TUI single key mode
- The TUI also provides a @dfn{SingleKey} mode, which binds several
- frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to
- switch into this mode, where the following key bindings are used:
- @table @kbd
- @kindex c @r{(SingleKey TUI key)}
- @item c
- continue
- @kindex d @r{(SingleKey TUI key)}
- @item d
- down
- @kindex f @r{(SingleKey TUI key)}
- @item f
- finish
- @kindex n @r{(SingleKey TUI key)}
- @item n
- next
- @kindex o @r{(SingleKey TUI key)}
- @item o
- nexti. The shortcut letter @samp{o} stands for ``step Over''.
- @kindex q @r{(SingleKey TUI key)}
- @item q
- exit the SingleKey mode.
- @kindex r @r{(SingleKey TUI key)}
- @item r
- run
- @kindex s @r{(SingleKey TUI key)}
- @item s
- step
- @kindex i @r{(SingleKey TUI key)}
- @item i
- stepi. The shortcut letter @samp{i} stands for ``step Into''.
- @kindex u @r{(SingleKey TUI key)}
- @item u
- up
- @kindex v @r{(SingleKey TUI key)}
- @item v
- info locals
- @kindex w @r{(SingleKey TUI key)}
- @item w
- where
- @end table
- Other keys temporarily switch to the @value{GDBN} command prompt.
- The key that was pressed is inserted in the editing buffer so that
- it is possible to type most @value{GDBN} commands without interaction
- with the TUI SingleKey mode. Once the command is entered the TUI
- SingleKey mode is restored. The only way to permanently leave
- this mode is by typing @kbd{q} or @kbd{C-x s}.
- @cindex SingleKey keymap name
- If @value{GDBN} was built with Readline 8.0 or later, the TUI
- SingleKey keymap will be named @samp{SingleKey}. This can be used in
- @file{.inputrc} to add additional bindings to this keymap.
- @node TUI Mouse Support
- @section TUI Mouse Support
- @cindex TUI mouse support
- If the curses library supports the mouse, the TUI supports mouse
- actions.
- The mouse wheel scrolls the appropriate window under the mouse cursor.
- The TUI itself does not directly support copying/pasting with the
- mouse. However, on Unix terminals, you can typically press and hold
- the @key{SHIFT} key on your keyboard to temporarily bypass
- @value{GDBN}'s TUI and access the terminal's native mouse copy/paste
- functionality (commonly, click-drag-release or double-click to select
- text, middle-click to paste). This copy/paste works with the
- terminal's selection buffer, as opposed to the TUI's buffer.
- @node TUI Commands
- @section TUI-specific Commands
- @cindex TUI commands
- The TUI has specific commands to control the text windows.
- These commands are always available, even when @value{GDBN} is not in
- the TUI mode. When @value{GDBN} is in the standard mode, most
- of these commands will automatically switch to the TUI mode.
- Note that if @value{GDBN}'s @code{stdout} is not connected to a
- terminal, or @value{GDBN} has been started with the machine interface
- interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of
- these commands will fail with an error, because it would not be
- possible or desirable to enable curses window management.
- @table @code
- @item tui enable
- @kindex tui enable
- Activate TUI mode. The last active TUI window layout will be used if
- TUI mode has previously been used in the current debugging session,
- otherwise a default layout is used.
- @item tui disable
- @kindex tui disable
- Disable TUI mode, returning to the console interpreter.
- @anchor{info_win_command}
- @item info win
- @kindex info win
- List the names and sizes of all currently displayed windows.
- @item tui new-layout @var{name} @var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]}
- @kindex tui new-layout
- Create a new TUI layout. The new layout will be named @var{name}, and
- can be accessed using the @code{layout} command (see below).
- Each @var{window} parameter is either the name of a window to display,
- or a window description. The windows will be displayed from top to
- bottom in the order listed.
- The names of the windows are the same as the ones given to the
- @code{focus} command (see below); additional, the @code{status}
- window can be specified. Note that, because it is of fixed height,
- the weight assigned to the status window is of no importance. It is
- conventional to use @samp{0} here.
- A window description looks a bit like an invocation of @code{tui
- new-layout}, and is of the form
- @{@r{[}@code{-horizontal}@r{]}@var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]}@}.
- This specifies a sub-layout. If @code{-horizontal} is given, the
- windows in this description will be arranged side-by-side, rather than
- top-to-bottom.
- Each @var{weight} is an integer. It is the weight of this window
- relative to all the other windows in the layout. These numbers are
- used to calculate how much of the screen is given to each window.
- For example:
- @example
- (gdb) tui new-layout example src 1 regs 1 status 0 cmd 1
- @end example
- Here, the new layout is called @samp{example}. It shows the source
- and register windows, followed by the status window, and then finally
- the command window. The non-status windows all have the same weight,
- so the terminal will be split into three roughly equal sections.
- Here is a more complex example, showing a horizontal layout:
- @example
- (gdb) tui new-layout example @{-horizontal src 1 asm 1@} 2 status 0 cmd 1
- @end example
- This will result in side-by-side source and assembly windows; with the
- status and command window being beneath these, filling the entire
- width of the terminal. Because they have weight 2, the source and
- assembly windows will be twice the height of the command window.
- @kindex tui layout
- @kindex layout
- @item tui layout @var{name}
- @itemx layout @var{name}
- Changes which TUI windows are displayed. The @var{name} parameter
- controls which layout is shown. It can be either one of the built-in
- layout names, or the name of a layout defined by the user using
- @code{tui new-layout}.
- The built-in layouts are as follows:
- @table @code
- @item next
- Display the next layout.
- @item prev
- Display the previous layout.
- @item src
- Display the source and command windows.
- @item asm
- Display the assembly and command windows.
- @item split
- Display the source, assembly, and command windows.
- @item regs
- When in @code{src} layout display the register, source, and command
- windows. When in @code{asm} or @code{split} layout display the
- register, assembler, and command windows.
- @end table
- @kindex focus
- @item tui focus @var{name}
- @itemx focus @var{name}
- Changes which TUI window is currently active for scrolling. The
- @var{name} parameter can be any of the following:
- @table @code
- @item next
- Make the next window active for scrolling.
- @item prev
- Make the previous window active for scrolling.
- @item src
- Make the source window active for scrolling.
- @item asm
- Make the assembly window active for scrolling.
- @item regs
- Make the register window active for scrolling.
- @item cmd
- Make the command window active for scrolling.
- @end table
- @kindex tui refresh
- @kindex refresh
- @item tui refresh
- @itemx refresh
- Refresh the screen. This is similar to typing @kbd{C-L}.
- @item tui reg @var{group}
- @kindex tui reg
- Changes the register group displayed in the tui register window to
- @var{group}. If the register window is not currently displayed this
- command will cause the register window to be displayed. The list of
- register groups, as well as their order is target specific. The
- following groups are available on most targets:
- @table @code
- @item next
- Repeatedly selecting this group will cause the display to cycle
- through all of the available register groups.
- @item prev
- Repeatedly selecting this group will cause the display to cycle
- through all of the available register groups in the reverse order to
- @var{next}.
- @item general
- Display the general registers.
- @item float
- Display the floating point registers.
- @item system
- Display the system registers.
- @item vector
- Display the vector registers.
- @item all
- Display all registers.
- @end table
- @item update
- @kindex update
- Update the source window and the current execution point.
- @kindex tui window height
- @kindex winheight
- @item tui window height @var{name} +@var{count}
- @itemx tui window height @var{name} -@var{count}
- @itemx winheight @var{name} +@var{count}
- @itemx winheight @var{name} -@var{count}
- Change the height of the window @var{name} by @var{count} lines.
- Positive counts increase the height, while negative counts decrease
- it. The @var{name} parameter can be the name of any currently visible
- window. The names of the currently visible windows can be discovered
- using @kbd{info win} (@pxref{info_win_command,,info win}).
- The set of currently visible windows must always fill the terminal,
- and so, it is only possible to resize on window if there are other
- visible windows that can either give or receive the extra terminal
- space.
- @kindex tui window width
- @kindex winwidth
- @item tui window width @var{name} +@var{count}
- @itemx tui window width @var{name} -@var{count}
- @itemx winwidth @var{name} +@var{count}
- @itemx winwidth @var{name} -@var{count}
- Change the width of the window @var{name} by @var{count} columns.
- Positive counts increase the width, while negative counts decrease it.
- The @var{name} parameter can be the name of any currently visible
- window. The names of the currently visible windows can be discovered
- using @code{info win} (@pxref{info_win_command,,info win}).
- The set of currently visible windows must always fill the terminal,
- and so, it is only possible to resize on window if there are other
- visible windows that can either give or receive the extra terminal
- space.
- @end table
- @node TUI Configuration
- @section TUI Configuration Variables
- @cindex TUI configuration variables
- Several configuration variables control the appearance of TUI windows.
- @table @code
- @item set tui border-kind @var{kind}
- @kindex set tui border-kind
- Select the border appearance for the source, assembly and register windows.
- The possible values are the following:
- @table @code
- @item space
- Use a space character to draw the border.
- @item ascii
- Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border.
- @item acs
- Use the Alternate Character Set to draw the border. The border is
- drawn using character line graphics if the terminal supports them.
- @end table
- @item set tui border-mode @var{mode}
- @kindex set tui border-mode
- @itemx set tui active-border-mode @var{mode}
- @kindex set tui active-border-mode
- Select the display attributes for the borders of the inactive windows
- or the active window. The @var{mode} can be one of the following:
- @table @code
- @item normal
- Use normal attributes to display the border.
- @item standout
- Use standout mode.
- @item reverse
- Use reverse video mode.
- @item half
- Use half bright mode.
- @item half-standout
- Use half bright and standout mode.
- @item bold
- Use extra bright or bold mode.
- @item bold-standout
- Use extra bright or bold and standout mode.
- @end table
- @item set tui tab-width @var{nchars}
- @kindex set tui tab-width
- @kindex tabset
- Set the width of tab stops to be @var{nchars} characters. This
- setting affects the display of TAB characters in the source and
- assembly windows.
- @item set tui compact-source @r{[}on@r{|}off@r{]}
- @kindex set tui compact-source
- Set whether the TUI source window is displayed in ``compact'' form.
- The default display uses more space for line numbers and starts the
- source text at the next tab stop; the compact display uses only as
- much space as is needed for the line numbers in the current file, and
- only a single space to separate the line numbers from the source.
- @kindex set debug tui
- @item set debug tui @r{[}on|off@r{]}
- Turn on or off display of @value{GDBN} internal debug messages relating
- to the TUI.
- @kindex show debug tui
- @item show debug tui
- Show the current status of displaying @value{GDBN} internal debug
- messages relating to the TUI.
- @end table
- Note that the colors of the TUI borders can be controlled using the
- appropriate @code{set style} commands. @xref{Output Styling}.
- @node Emacs
- @chapter Using @value{GDBN} under @sc{gnu} Emacs
- @cindex Emacs
- @cindex @sc{gnu} Emacs
- A special interface allows you to use @sc{gnu} Emacs to view (and
- edit) the source files for the program you are debugging with
- @value{GDBN}.
- To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
- executable file you want to debug as an argument. This command starts
- @value{GDBN} as a subprocess of Emacs, with input and output through a newly
- created Emacs buffer.
- @c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
- Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two
- things:
- @itemize @bullet
- @item
- All ``terminal'' input and output goes through an Emacs buffer, called
- the GUD buffer.
- This applies both to @value{GDBN} commands and their output, and to the input
- and output done by the program you are debugging.
- This is useful because it means that you can copy the text of previous
- commands and input them again; you can even use parts of the output
- in this way.
- All the facilities of Emacs' Shell mode are available for interacting
- with your program. In particular, you can send signals the usual
- way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
- stop.
- @item
- @value{GDBN} displays source code through Emacs.
- Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
- source file for that frame and puts an arrow (@samp{=>}) at the
- left margin of the current line. Emacs uses a separate buffer for
- source display, and splits the screen to show both your @value{GDBN} session
- and the source.
- Explicit @value{GDBN} @code{list} or search commands still produce output as
- usual, but you probably have no reason to use them from Emacs.
- @end itemize
- We call this @dfn{text command mode}. Emacs 22.1, and later, also uses
- a graphical mode, enabled by default, which provides further buffers
- that can control the execution and describe the state of your program.
- @xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}.
- If you specify an absolute file name when prompted for the @kbd{M-x
- gdb} argument, then Emacs sets your current working directory to where
- your program resides. If you only specify the file name, then Emacs
- sets your current working directory to the directory associated
- with the previous buffer. In this case, @value{GDBN} may find your
- program by searching your environment's @env{PATH} variable, but on
- some operating systems it might not find the source. So, although the
- @value{GDBN} input and output session proceeds normally, the auxiliary
- buffer does not display the current source and line of execution.
- The initial working directory of @value{GDBN} is printed on the top
- line of the GUD buffer and this serves as a default for the commands
- that specify files for @value{GDBN} to operate on. @xref{Files,
- ,Commands to Specify Files}.
- By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you
- need to call @value{GDBN} by a different name (for example, if you
- keep several configurations around, with different names) you can
- customize the Emacs variable @code{gud-gdb-command-name} to run the
- one you want.
- In the GUD buffer, you can use these special Emacs commands in
- addition to the standard Shell mode commands:
- @table @kbd
- @item C-h m
- Describe the features of Emacs' GUD Mode.
- @item C-c C-s
- Execute to another source line, like the @value{GDBN} @code{step} command; also
- update the display window to show the current file and location.
- @item C-c C-n
- Execute to next source line in this function, skipping all function
- calls, like the @value{GDBN} @code{next} command. Then update the display window
- to show the current file and location.
- @item C-c C-i
- Execute one instruction, like the @value{GDBN} @code{stepi} command; update
- display window accordingly.
- @item C-c C-f
- Execute until exit from the selected stack frame, like the @value{GDBN}
- @code{finish} command.
- @item C-c C-r
- Continue execution of your program, like the @value{GDBN} @code{continue}
- command.
- @item C-c <
- Go up the number of frames indicated by the numeric argument
- (@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
- like the @value{GDBN} @code{up} command.
- @item C-c >
- Go down the number of frames indicated by the numeric argument, like the
- @value{GDBN} @code{down} command.
- @end table
- In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
- tells @value{GDBN} to set a breakpoint on the source line point is on.
- In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a
- separate frame which shows a backtrace when the GUD buffer is current.
- Move point to any frame in the stack and type @key{RET} to make it
- become the current frame and display the associated source in the
- source buffer. Alternatively, click @kbd{Mouse-2} to make the
- selected frame become the current one. In graphical mode, the
- speedbar displays watch expressions.
- If you accidentally delete the source-display buffer, an easy way to get
- it back is to type the command @code{f} in the @value{GDBN} buffer, to
- request a frame display; when you run under Emacs, this recreates
- the source buffer if necessary to show you the context of the current
- frame.
- The source files displayed in Emacs are in ordinary Emacs buffers
- which are visiting the source files in the usual way. You can edit
- the files with these buffers if you wish; but keep in mind that @value{GDBN}
- communicates with Emacs in terms of line numbers. If you add or
- delete lines from the text, the line numbers that @value{GDBN} knows cease
- to correspond properly with the code.
- A more detailed description of Emacs' interaction with @value{GDBN} is
- given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu}
- Emacs Manual}).
- @node GDB/MI
- @chapter The @sc{gdb/mi} Interface
- @unnumberedsec Function and Purpose
- @cindex @sc{gdb/mi}, its purpose
- @sc{gdb/mi} is a line based machine oriented text interface to
- @value{GDBN} and is activated by specifying using the
- @option{--interpreter} command line option (@pxref{Mode Options}). It
- is specifically intended to support the development of systems which
- use the debugger as just one small component of a larger system.
- This chapter is a specification of the @sc{gdb/mi} interface. It is written
- in the form of a reference manual.
- Note that @sc{gdb/mi} is still under construction, so some of the
- features described below are incomplete and subject to change
- (@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}).
- @unnumberedsec Notation and Terminology
- @cindex notational conventions, for @sc{gdb/mi}
- This chapter uses the following notation:
- @itemize @bullet
- @item
- @code{|} separates two alternatives.
- @item
- @code{[ @var{something} ]} indicates that @var{something} is optional:
- it may or may not be given.
- @item
- @code{( @var{group} )*} means that @var{group} inside the parentheses
- may repeat zero or more times.
- @item
- @code{( @var{group} )+} means that @var{group} inside the parentheses
- may repeat one or more times.
- @item
- @code{"@var{string}"} means a literal @var{string}.
- @end itemize
- @ignore
- @heading Dependencies
- @end ignore
- @menu
- * GDB/MI General Design::
- * GDB/MI Command Syntax::
- * GDB/MI Compatibility with CLI::
- * GDB/MI Development and Front Ends::
- * GDB/MI Output Records::
- * GDB/MI Simple Examples::
- * GDB/MI Command Description Format::
- * GDB/MI Breakpoint Commands::
- * GDB/MI Catchpoint Commands::
- * GDB/MI Program Context::
- * GDB/MI Thread Commands::
- * GDB/MI Ada Tasking Commands::
- * GDB/MI Program Execution::
- * GDB/MI Stack Manipulation::
- * GDB/MI Variable Objects::
- * GDB/MI Data Manipulation::
- * GDB/MI Tracepoint Commands::
- * GDB/MI Symbol Query::
- * GDB/MI File Commands::
- @ignore
- * GDB/MI Kod Commands::
- * GDB/MI Memory Overlay Commands::
- * GDB/MI Signal Handling Commands::
- @end ignore
- * GDB/MI Target Manipulation::
- * GDB/MI File Transfer Commands::
- * GDB/MI Ada Exceptions Commands::
- * GDB/MI Support Commands::
- * GDB/MI Miscellaneous Commands::
- @end menu
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI General Design
- @section @sc{gdb/mi} General Design
- @cindex GDB/MI General Design
- Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
- parts---commands sent to @value{GDBN}, responses to those commands
- and notifications. Each command results in exactly one response,
- indicating either successful completion of the command, or an error.
- For the commands that do not resume the target, the response contains the
- requested information. For the commands that resume the target, the
- response only indicates whether the target was successfully resumed.
- Notifications is the mechanism for reporting changes in the state of the
- target, or in @value{GDBN} state, that cannot conveniently be associated with
- a command and reported as part of that command response.
- The important examples of notifications are:
- @itemize @bullet
- @item
- Exec notifications. These are used to report changes in
- target state---when a target is resumed, or stopped. It would not
- be feasible to include this information in response of resuming
- commands, because one resume commands can result in multiple events in
- different threads. Also, quite some time may pass before any event
- happens in the target, while a frontend needs to know whether the resuming
- command itself was successfully executed.
- @item
- Console output, and status notifications. Console output
- notifications are used to report output of CLI commands, as well as
- diagnostics for other commands. Status notifications are used to
- report the progress of a long-running operation. Naturally, including
- this information in command response would mean no output is produced
- until the command is finished, which is undesirable.
- @item
- General notifications. Commands may have various side effects on
- the @value{GDBN} or target state beyond their official purpose. For example,
- a command may change the selected thread. Although such changes can
- be included in command response, using notification allows for more
- orthogonal frontend design.
- @end itemize
- There's no guarantee that whenever an MI command reports an error,
- @value{GDBN} or the target are in any specific state, and especially,
- the state is not reverted to the state before the MI command was
- processed. Therefore, whenever an MI command results in an error,
- we recommend that the frontend refreshes all the information shown in
- the user interface.
- @menu
- * Context management::
- * Asynchronous and non-stop modes::
- * Thread groups::
- @end menu
- @node Context management
- @subsection Context management
- @subsubsection Threads and Frames
- In most cases when @value{GDBN} accesses the target, this access is
- done in context of a specific thread and frame (@pxref{Frames}).
- Often, even when accessing global data, the target requires that a thread
- be specified. The CLI interface maintains the selected thread and frame,
- and supplies them to target on each command. This is convenient,
- because a command line user would not want to specify that information
- explicitly on each command, and because user interacts with
- @value{GDBN} via a single terminal, so no confusion is possible as
- to what thread and frame are the current ones.
- In the case of MI, the concept of selected thread and frame is less
- useful. First, a frontend can easily remember this information
- itself. Second, a graphical frontend can have more than one window,
- each one used for debugging a different thread, and the frontend might
- want to access additional threads for internal purposes. This
- increases the risk that by relying on implicitly selected thread, the
- frontend may be operating on a wrong one. Therefore, each MI command
- should explicitly specify which thread and frame to operate on. To
- make it possible, each MI command accepts the @samp{--thread} and
- @samp{--frame} options, the value to each is @value{GDBN} global
- identifier for thread and frame to operate on.
- Usually, each top-level window in a frontend allows the user to select
- a thread and a frame, and remembers the user selection for further
- operations. However, in some cases @value{GDBN} may suggest that the
- current thread or frame be changed. For example, when stopping on a
- breakpoint it is reasonable to switch to the thread where breakpoint is
- hit. For another example, if the user issues the CLI @samp{thread} or
- @samp{frame} commands via the frontend, it is desirable to change the
- frontend's selection to the one specified by user. @value{GDBN}
- communicates the suggestion to change current thread and frame using the
- @samp{=thread-selected} notification.
- Note that historically, MI shares the selected thread with CLI, so
- frontends used the @code{-thread-select} to execute commands in the
- right context. However, getting this to work right is cumbersome. The
- simplest way is for frontend to emit @code{-thread-select} command
- before every command. This doubles the number of commands that need
- to be sent. The alternative approach is to suppress @code{-thread-select}
- if the selected thread in @value{GDBN} is supposed to be identical to the
- thread the frontend wants to operate on. However, getting this
- optimization right can be tricky. In particular, if the frontend
- sends several commands to @value{GDBN}, and one of the commands changes the
- selected thread, then the behaviour of subsequent commands will
- change. So, a frontend should either wait for response from such
- problematic commands, or explicitly add @code{-thread-select} for
- all subsequent commands. No frontend is known to do this exactly
- right, so it is suggested to just always pass the @samp{--thread} and
- @samp{--frame} options.
- @subsubsection Language
- The execution of several commands depends on which language is selected.
- By default, the current language (@pxref{show language}) is used.
- But for commands known to be language-sensitive, it is recommended
- to use the @samp{--language} option. This option takes one argument,
- which is the name of the language to use while executing the command.
- For instance:
- @smallexample
- -data-evaluate-expression --language c "sizeof (void*)"
- ^done,value="4"
- (gdb)
- @end smallexample
- The valid language names are the same names accepted by the
- @samp{set language} command (@pxref{Manually}), excluding @samp{auto},
- @samp{local} or @samp{unknown}.
- @node Asynchronous and non-stop modes
- @subsection Asynchronous command execution and non-stop mode
- On some targets, @value{GDBN} is capable of processing MI commands
- even while the target is running. This is called @dfn{asynchronous
- command execution} (@pxref{Background Execution}). The frontend may
- specify a preference for asynchronous execution using the
- @code{-gdb-set mi-async 1} command, which should be emitted before
- either running the executable or attaching to the target. After the
- frontend has started the executable or attached to the target, it can
- find if asynchronous execution is enabled using the
- @code{-list-target-features} command.
- @table @code
- @cindex foreground execution
- @cindex background execution
- @cindex asynchronous execution
- @cindex execution, foreground, background and asynchronous
- @kindex set mi-async
- @item -gdb-set mi-async @r{[}on@r{|}off@r{]}
- Set whether MI is in asynchronous mode.
- When @code{off}, which is the default, MI execution commands (e.g.,
- @code{-exec-continue}) are foreground commands, and @value{GDBN} waits
- for the program to stop before processing further commands.
- When @code{on}, MI execution commands are background execution
- commands (e.g., @code{-exec-continue} becomes the equivalent of the
- @code{c&} CLI command), and so @value{GDBN} is capable of processing
- MI commands even while the target is running.
- @kindex show mi-async
- @item -gdb-show mi-async
- Show whether MI asynchronous mode is enabled.
- @end table
- Note: In @value{GDBN} version 7.7 and earlier, this option was called
- @code{target-async} instead of @code{mi-async}, and it had the effect
- of both putting MI in asynchronous mode and making CLI background
- commands possible. CLI background commands are now always possible
- ``out of the box'' if the target supports them. The old spelling is
- kept as a deprecated alias for backwards compatibility.
- Even if @value{GDBN} can accept a command while target is running,
- many commands that access the target do not work when the target is
- running. Therefore, asynchronous command execution is most useful
- when combined with non-stop mode (@pxref{Non-Stop Mode}). Then,
- it is possible to examine the state of one thread, while other threads
- are running.
- When a given thread is running, MI commands that try to access the
- target in the context of that thread may not work, or may work only on
- some targets. In particular, commands that try to operate on thread's
- stack will not work, on any target. Commands that read memory, or
- modify breakpoints, may work or not work, depending on the target. Note
- that even commands that operate on global state, such as @code{print},
- @code{set}, and breakpoint commands, still access the target in the
- context of a specific thread, so frontend should try to find a
- stopped thread and perform the operation on that thread (using the
- @samp{--thread} option).
- Which commands will work in the context of a running thread is
- highly target dependent. However, the two commands
- @code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
- to find the state of a thread, will always work.
- @node Thread groups
- @subsection Thread groups
- @value{GDBN} may be used to debug several processes at the same time.
- On some platforms, @value{GDBN} may support debugging of several
- hardware systems, each one having several cores with several different
- processes running on each core. This section describes the MI
- mechanism to support such debugging scenarios.
- The key observation is that regardless of the structure of the
- target, MI can have a global list of threads, because most commands that
- accept the @samp{--thread} option do not need to know what process that
- thread belongs to. Therefore, it is not necessary to introduce
- neither additional @samp{--process} option, nor an notion of the
- current process in the MI interface. The only strictly new feature
- that is required is the ability to find how the threads are grouped
- into processes.
- To allow the user to discover such grouping, and to support arbitrary
- hierarchy of machines/cores/processes, MI introduces the concept of a
- @dfn{thread group}. Thread group is a collection of threads and other
- thread groups. A thread group always has a string identifier, a type,
- and may have additional attributes specific to the type. A new
- command, @code{-list-thread-groups}, returns the list of top-level
- thread groups, which correspond to processes that @value{GDBN} is
- debugging at the moment. By passing an identifier of a thread group
- to the @code{-list-thread-groups} command, it is possible to obtain
- the members of specific thread group.
- To allow the user to easily discover processes, and other objects, he
- wishes to debug, a concept of @dfn{available thread group} is
- introduced. Available thread group is an thread group that
- @value{GDBN} is not debugging, but that can be attached to, using the
- @code{-target-attach} command. The list of available top-level thread
- groups can be obtained using @samp{-list-thread-groups --available}.
- In general, the content of a thread group may be only retrieved only
- after attaching to that thread group.
- Thread groups are related to inferiors (@pxref{Inferiors Connections and
- Programs}). Each inferior corresponds to a thread group of a special
- type @samp{process}, and some additional operations are permitted on
- such thread groups.
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Command Syntax
- @section @sc{gdb/mi} Command Syntax
- @menu
- * GDB/MI Input Syntax::
- * GDB/MI Output Syntax::
- @end menu
- @node GDB/MI Input Syntax
- @subsection @sc{gdb/mi} Input Syntax
- @cindex input syntax for @sc{gdb/mi}
- @cindex @sc{gdb/mi}, input syntax
- @table @code
- @item @var{command} @expansion{}
- @code{@var{cli-command} | @var{mi-command}}
- @item @var{cli-command} @expansion{}
- @code{[ @var{token} ] @var{cli-command} @var{nl}}, where
- @var{cli-command} is any existing @value{GDBN} CLI command.
- @item @var{mi-command} @expansion{}
- @code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
- @code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
- @item @var{token} @expansion{}
- "any sequence of digits"
- @item @var{option} @expansion{}
- @code{"-" @var{parameter} [ " " @var{parameter} ]}
- @item @var{parameter} @expansion{}
- @code{@var{non-blank-sequence} | @var{c-string}}
- @item @var{operation} @expansion{}
- @emph{any of the operations described in this chapter}
- @item @var{non-blank-sequence} @expansion{}
- @emph{anything, provided it doesn't contain special characters such as
- "-", @var{nl}, """ and of course " "}
- @item @var{c-string} @expansion{}
- @code{""" @var{seven-bit-iso-c-string-content} """}
- @item @var{nl} @expansion{}
- @code{CR | CR-LF}
- @end table
- @noindent
- Notes:
- @itemize @bullet
- @item
- The CLI commands are still handled by the @sc{mi} interpreter; their
- output is described below.
- @item
- The @code{@var{token}}, when present, is passed back when the command
- finishes.
- @item
- Some @sc{mi} commands accept optional arguments as part of the parameter
- list. Each option is identified by a leading @samp{-} (dash) and may be
- followed by an optional argument parameter. Options occur first in the
- parameter list and can be delimited from normal parameters using
- @samp{--} (this is useful when some parameters begin with a dash).
- @end itemize
- Pragmatics:
- @itemize @bullet
- @item
- We want easy access to the existing CLI syntax (for debugging).
- @item
- We want it to be easy to spot a @sc{mi} operation.
- @end itemize
- @node GDB/MI Output Syntax
- @subsection @sc{gdb/mi} Output Syntax
- @cindex output syntax of @sc{gdb/mi}
- @cindex @sc{gdb/mi}, output syntax
- The output from @sc{gdb/mi} consists of zero or more out-of-band records
- followed, optionally, by a single result record. This result record
- is for the most recent command. The sequence of output records is
- terminated by @samp{(gdb)}.
- If an input command was prefixed with a @code{@var{token}} then the
- corresponding output for that command will also be prefixed by that same
- @var{token}.
- @table @code
- @item @var{output} @expansion{}
- @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
- @item @var{result-record} @expansion{}
- @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
- @item @var{out-of-band-record} @expansion{}
- @code{@var{async-record} | @var{stream-record}}
- @item @var{async-record} @expansion{}
- @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
- @item @var{exec-async-output} @expansion{}
- @code{[ @var{token} ] "*" @var{async-output nl}}
- @item @var{status-async-output} @expansion{}
- @code{[ @var{token} ] "+" @var{async-output nl}}
- @item @var{notify-async-output} @expansion{}
- @code{[ @var{token} ] "=" @var{async-output nl}}
- @item @var{async-output} @expansion{}
- @code{@var{async-class} ( "," @var{result} )*}
- @item @var{result-class} @expansion{}
- @code{"done" | "running" | "connected" | "error" | "exit"}
- @item @var{async-class} @expansion{}
- @code{"stopped" | @var{others}} (where @var{others} will be added
- depending on the needs---this is still in development).
- @item @var{result} @expansion{}
- @code{ @var{variable} "=" @var{value}}
- @item @var{variable} @expansion{}
- @code{ @var{string} }
- @item @var{value} @expansion{}
- @code{ @var{const} | @var{tuple} | @var{list} }
- @item @var{const} @expansion{}
- @code{@var{c-string}}
- @item @var{tuple} @expansion{}
- @code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
- @item @var{list} @expansion{}
- @code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
- @var{result} ( "," @var{result} )* "]" }
- @item @var{stream-record} @expansion{}
- @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
- @item @var{console-stream-output} @expansion{}
- @code{"~" @var{c-string nl}}
- @item @var{target-stream-output} @expansion{}
- @code{"@@" @var{c-string nl}}
- @item @var{log-stream-output} @expansion{}
- @code{"&" @var{c-string nl}}
- @item @var{nl} @expansion{}
- @code{CR | CR-LF}
- @item @var{token} @expansion{}
- @emph{any sequence of digits}.
- @end table
- @noindent
- Notes:
- @itemize @bullet
- @item
- All output sequences end in a single line containing a period.
- @item
- The @code{@var{token}} is from the corresponding request. Note that
- for all async output, while the token is allowed by the grammar and
- may be output by future versions of @value{GDBN} for select async
- output messages, it is generally omitted. Frontends should treat
- all async output as reporting general changes in the state of the
- target and there should be no need to associate async output to any
- prior command.
- @item
- @cindex status output in @sc{gdb/mi}
- @var{status-async-output} contains on-going status information about the
- progress of a slow operation. It can be discarded. All status output is
- prefixed by @samp{+}.
- @item
- @cindex async output in @sc{gdb/mi}
- @var{exec-async-output} contains asynchronous state change on the target
- (stopped, started, disappeared). All async output is prefixed by
- @samp{*}.
- @item
- @cindex notify output in @sc{gdb/mi}
- @var{notify-async-output} contains supplementary information that the
- client should handle (e.g., a new breakpoint information). All notify
- output is prefixed by @samp{=}.
- @item
- @cindex console output in @sc{gdb/mi}
- @var{console-stream-output} is output that should be displayed as is in the
- console. It is the textual response to a CLI command. All the console
- output is prefixed by @samp{~}.
- @item
- @cindex target output in @sc{gdb/mi}
- @var{target-stream-output} is the output produced by the target program.
- All the target output is prefixed by @samp{@@}.
- @item
- @cindex log output in @sc{gdb/mi}
- @var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
- instance messages that should be displayed as part of an error log. All
- the log output is prefixed by @samp{&}.
- @item
- @cindex list output in @sc{gdb/mi}
- New @sc{gdb/mi} commands should only output @var{lists} containing
- @var{values}.
- @end itemize
- @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
- details about the various output records.
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Compatibility with CLI
- @section @sc{gdb/mi} Compatibility with CLI
- @cindex compatibility, @sc{gdb/mi} and CLI
- @cindex @sc{gdb/mi}, compatibility with CLI
- For the developers convenience CLI commands can be entered directly,
- but there may be some unexpected behaviour. For example, commands
- that query the user will behave as if the user replied yes, breakpoint
- command lists are not executed and some CLI commands, such as
- @code{if}, @code{when} and @code{define}, prompt for further input with
- @samp{>}, which is not valid MI output.
- This feature may be removed at some stage in the future and it is
- recommended that front ends use the @code{-interpreter-exec} command
- (@pxref{-interpreter-exec}).
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Development and Front Ends
- @section @sc{gdb/mi} Development and Front Ends
- @cindex @sc{gdb/mi} development
- The application which takes the MI output and presents the state of the
- program being debugged to the user is called a @dfn{front end}.
- Since @sc{gdb/mi} is used by a variety of front ends to @value{GDBN}, changes
- to the MI interface may break existing usage. This section describes how the
- protocol changes and how to request previous version of the protocol when it
- does.
- Some changes in MI need not break a carefully designed front end, and
- for these the MI version will remain unchanged. The following is a
- list of changes that may occur within one level, so front ends should
- parse MI output in a way that can handle them:
- @itemize @bullet
- @item
- New MI commands may be added.
- @item
- New fields may be added to the output of any MI command.
- @item
- The range of values for fields with specified values, e.g.,
- @code{in_scope} (@pxref{-var-update}) may be extended.
- @c The format of field's content e.g type prefix, may change so parse it
- @c at your own risk. Yes, in general?
- @c The order of fields may change? Shouldn't really matter but it might
- @c resolve inconsistencies.
- @end itemize
- If the changes are likely to break front ends, the MI version level
- will be increased by one. The new versions of the MI protocol are not compatible
- with the old versions. Old versions of MI remain available, allowing front ends
- to keep using them until they are modified to use the latest MI version.
- Since @code{--interpreter=mi} always points to the latest MI version, it is
- recommended that front ends request a specific version of MI when launching
- @value{GDBN} (e.g.@: @code{--interpreter=mi2}) to make sure they get an
- interpreter with the MI version they expect.
- The following table gives a summary of the released versions of the MI
- interface: the version number, the version of GDB in which it first appeared
- and the breaking changes compared to the previous version.
- @multitable @columnfractions .05 .05 .9
- @headitem MI version @tab GDB version @tab Breaking changes
- @item
- @center 1
- @tab
- @center 5.1
- @tab
- None
- @item
- @center 2
- @tab
- @center 6.0
- @tab
- @itemize
- @item
- The @code{-environment-pwd}, @code{-environment-directory} and
- @code{-environment-path} commands now returns values using the MI output
- syntax, rather than CLI output syntax.
- @item
- @code{-var-list-children}'s @code{children} result field is now a list, rather
- than a tuple.
- @item
- @code{-var-update}'s @code{changelist} result field is now a list, rather than
- a tuple.
- @end itemize
- @item
- @center 3
- @tab
- @center 9.1
- @tab
- @itemize
- @item
- The output of information about multi-location breakpoints has changed in the
- responses to the @code{-break-insert} and @code{-break-info} commands, as well
- as in the @code{=breakpoint-created} and @code{=breakpoint-modified} events.
- The multiple locations are now placed in a @code{locations} field, whose value
- is a list.
- @end itemize
- @end multitable
- If your front end cannot yet migrate to a more recent version of the
- MI protocol, you can nevertheless selectively enable specific features
- available in those recent MI versions, using the following commands:
- @table @code
- @item -fix-multi-location-breakpoint-output
- Use the output for multi-location breakpoints which was introduced by
- MI 3, even when using MI versions 2 or 1. This command has no
- effect when using MI version 3 or later.
- @end table
- The best way to avoid unexpected changes in MI that might break your front
- end is to make your project known to @value{GDBN} developers and
- follow development on @email{gdb@@sourceware.org} and
- @email{gdb-patches@@sourceware.org}.
- @cindex mailing lists
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Output Records
- @section @sc{gdb/mi} Output Records
- @menu
- * GDB/MI Result Records::
- * GDB/MI Stream Records::
- * GDB/MI Async Records::
- * GDB/MI Breakpoint Information::
- * GDB/MI Frame Information::
- * GDB/MI Thread Information::
- * GDB/MI Ada Exception Information::
- @end menu
- @node GDB/MI Result Records
- @subsection @sc{gdb/mi} Result Records
- @cindex result records in @sc{gdb/mi}
- @cindex @sc{gdb/mi}, result records
- In addition to a number of out-of-band notifications, the response to a
- @sc{gdb/mi} command includes one of the following result indications:
- @table @code
- @findex ^done
- @item "^done" [ "," @var{results} ]
- The synchronous operation was successful, @code{@var{results}} are the return
- values.
- @item "^running"
- @findex ^running
- This result record is equivalent to @samp{^done}. Historically, it
- was output instead of @samp{^done} if the command has resumed the
- target. This behaviour is maintained for backward compatibility, but
- all frontends should treat @samp{^done} and @samp{^running}
- identically and rely on the @samp{*running} output record to determine
- which threads are resumed.
- @item "^connected"
- @findex ^connected
- @value{GDBN} has connected to a remote target.
- @item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
- @findex ^error
- The operation failed. The @code{msg=@var{c-string}} variable contains
- the corresponding error message.
- If present, the @code{code=@var{c-string}} variable provides an error
- code on which consumers can rely on to detect the corresponding
- error condition. At present, only one error code is defined:
- @table @samp
- @item "undefined-command"
- Indicates that the command causing the error does not exist.
- @end table
- @item "^exit"
- @findex ^exit
- @value{GDBN} has terminated.
- @end table
- @node GDB/MI Stream Records
- @subsection @sc{gdb/mi} Stream Records
- @cindex @sc{gdb/mi}, stream records
- @cindex stream records in @sc{gdb/mi}
- @value{GDBN} internally maintains a number of output streams: the console, the
- target, and the log. The output intended for each of these streams is
- funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
- Each stream record begins with a unique @dfn{prefix character} which
- identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
- Syntax}). In addition to the prefix, each stream record contains a
- @code{@var{string-output}}. This is either raw text (with an implicit new
- line) or a quoted C string (which does not contain an implicit newline).
- @table @code
- @item "~" @var{string-output}
- The console output stream contains text that should be displayed in the
- CLI console window. It contains the textual responses to CLI commands.
- @item "@@" @var{string-output}
- The target output stream contains any textual output from the running
- target. This is only present when GDB's event loop is truly
- asynchronous, which is currently only the case for remote targets.
- @item "&" @var{string-output}
- The log stream contains debugging messages being produced by @value{GDBN}'s
- internals.
- @end table
- @node GDB/MI Async Records
- @subsection @sc{gdb/mi} Async Records
- @cindex async records in @sc{gdb/mi}
- @cindex @sc{gdb/mi}, async records
- @dfn{Async} records are used to notify the @sc{gdb/mi} client of
- additional changes that have occurred. Those changes can either be a
- consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of
- target activity (e.g., target stopped).
- The following is the list of possible async records:
- @table @code
- @item *running,thread-id="@var{thread}"
- The target is now running. The @var{thread} field can be the global
- thread ID of the thread that is now running, and it can be
- @samp{all} if all threads are running. The frontend should assume
- that no interaction with a running thread is possible after this
- notification is produced. The frontend should not assume that this
- notification is output only once for any command. @value{GDBN} may
- emit this notification several times, either for different threads,
- because it cannot resume all threads together, or even for a single
- thread, if the thread must be stepped though some code before letting
- it run freely.
- @item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}"
- The target has stopped. The @var{reason} field can have one of the
- following values:
- @table @code
- @item breakpoint-hit
- A breakpoint was reached.
- @item watchpoint-trigger
- A watchpoint was triggered.
- @item read-watchpoint-trigger
- A read watchpoint was triggered.
- @item access-watchpoint-trigger
- An access watchpoint was triggered.
- @item function-finished
- An -exec-finish or similar CLI command was accomplished.
- @item location-reached
- An -exec-until or similar CLI command was accomplished.
- @item watchpoint-scope
- A watchpoint has gone out of scope.
- @item end-stepping-range
- An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or
- similar CLI command was accomplished.
- @item exited-signalled
- The inferior exited because of a signal.
- @item exited
- The inferior exited.
- @item exited-normally
- The inferior exited normally.
- @item signal-received
- A signal was received by the inferior.
- @item solib-event
- The inferior has stopped due to a library being loaded or unloaded.
- This can happen when @code{stop-on-solib-events} (@pxref{Files}) is
- set or when a @code{catch load} or @code{catch unload} catchpoint is
- in use (@pxref{Set Catchpoints}).
- @item fork
- The inferior has forked. This is reported when @code{catch fork}
- (@pxref{Set Catchpoints}) has been used.
- @item vfork
- The inferior has vforked. This is reported in when @code{catch vfork}
- (@pxref{Set Catchpoints}) has been used.
- @item syscall-entry
- The inferior entered a system call. This is reported when @code{catch
- syscall} (@pxref{Set Catchpoints}) has been used.
- @item syscall-return
- The inferior returned from a system call. This is reported when
- @code{catch syscall} (@pxref{Set Catchpoints}) has been used.
- @item exec
- The inferior called @code{exec}. This is reported when @code{catch exec}
- (@pxref{Set Catchpoints}) has been used.
- @end table
- The @var{id} field identifies the global thread ID of the thread
- that directly caused the stop -- for example by hitting a breakpoint.
- Depending on whether all-stop
- mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
- stop all threads, or only the thread that directly triggered the stop.
- If all threads are stopped, the @var{stopped} field will have the
- value of @code{"all"}. Otherwise, the value of the @var{stopped}
- field will be a list of thread identifiers. Presently, this list will
- always include a single thread, but frontend should be prepared to see
- several threads in the list. The @var{core} field reports the
- processor core on which the stop event has happened. This field may be absent
- if such information is not available.
- @item =thread-group-added,id="@var{id}"
- @itemx =thread-group-removed,id="@var{id}"
- A thread group was either added or removed. The @var{id} field
- contains the @value{GDBN} identifier of the thread group. When a thread
- group is added, it generally might not be associated with a running
- process. When a thread group is removed, its id becomes invalid and
- cannot be used in any way.
- @item =thread-group-started,id="@var{id}",pid="@var{pid}"
- A thread group became associated with a running program,
- either because the program was just started or the thread group
- was attached to a program. The @var{id} field contains the
- @value{GDBN} identifier of the thread group. The @var{pid} field
- contains process identifier, specific to the operating system.
- @item =thread-group-exited,id="@var{id}"[,exit-code="@var{code}"]
- A thread group is no longer associated with a running program,
- either because the program has exited, or because it was detached
- from. The @var{id} field contains the @value{GDBN} identifier of the
- thread group. The @var{code} field is the exit code of the inferior; it exists
- only when the inferior exited with some code.
- @item =thread-created,id="@var{id}",group-id="@var{gid}"
- @itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
- A thread either was created, or has exited. The @var{id} field
- contains the global @value{GDBN} identifier of the thread. The @var{gid}
- field identifies the thread group this thread belongs to.
- @item =thread-selected,id="@var{id}"[,frame="@var{frame}"]
- Informs that the selected thread or frame were changed. This notification
- is not emitted as result of the @code{-thread-select} or
- @code{-stack-select-frame} commands, but is emitted whenever an MI command
- that is not documented to change the selected thread and frame actually
- changes them. In particular, invoking, directly or indirectly
- (via user-defined command), the CLI @code{thread} or @code{frame} commands,
- will generate this notification. Changing the thread or frame from another
- user interface (see @ref{Interpreters}) will also generate this notification.
- The @var{frame} field is only present if the newly selected thread is
- stopped. See @ref{GDB/MI Frame Information} for the format of its value.
- We suggest that in response to this notification, front ends
- highlight the selected thread and cause subsequent commands to apply to
- that thread.
- @item =library-loaded,...
- Reports that a new library file was loaded by the program. This
- notification has 5 fields---@var{id}, @var{target-name},
- @var{host-name}, @var{symbols-loaded} and @var{ranges}. The @var{id} field is an
- opaque identifier of the library. For remote debugging case,
- @var{target-name} and @var{host-name} fields give the name of the
- library file on the target, and on the host respectively. For native
- debugging, both those fields have the same value. The
- @var{symbols-loaded} field is emitted only for backward compatibility
- and should not be relied on to convey any useful information. The
- @var{thread-group} field, if present, specifies the id of the thread
- group in whose context the library was loaded. If the field is
- absent, it means the library was loaded in the context of all present
- thread groups. The @var{ranges} field specifies the ranges of addresses belonging
- to this library.
- @item =library-unloaded,...
- Reports that a library was unloaded by the program. This notification
- has 3 fields---@var{id}, @var{target-name} and @var{host-name} with
- the same meaning as for the @code{=library-loaded} notification.
- The @var{thread-group} field, if present, specifies the id of the
- thread group in whose context the library was unloaded. If the field is
- absent, it means the library was unloaded in the context of all present
- thread groups.
- @item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum}
- @itemx =traceframe-changed,end
- Reports that the trace frame was changed and its new number is
- @var{tfnum}. The number of the tracepoint associated with this trace
- frame is @var{tpnum}.
- @item =tsv-created,name=@var{name},initial=@var{initial}
- Reports that the new trace state variable @var{name} is created with
- initial value @var{initial}.
- @item =tsv-deleted,name=@var{name}
- @itemx =tsv-deleted
- Reports that the trace state variable @var{name} is deleted or all
- trace state variables are deleted.
- @item =tsv-modified,name=@var{name},initial=@var{initial}[,current=@var{current}]
- Reports that the trace state variable @var{name} is modified with
- the initial value @var{initial}. The current value @var{current} of
- trace state variable is optional and is reported if the current
- value of trace state variable is known.
- @item =breakpoint-created,bkpt=@{...@}
- @itemx =breakpoint-modified,bkpt=@{...@}
- @itemx =breakpoint-deleted,id=@var{number}
- Reports that a breakpoint was created, modified, or deleted,
- respectively. Only user-visible breakpoints are reported to the MI
- user.
- The @var{bkpt} argument is of the same form as returned by the various
- breakpoint commands; @xref{GDB/MI Breakpoint Commands}. The
- @var{number} is the ordinal number of the breakpoint.
- Note that if a breakpoint is emitted in the result record of a
- command, then it will not also be emitted in an async record.
- @item =record-started,thread-group="@var{id}",method="@var{method}"[,format="@var{format}"]
- @itemx =record-stopped,thread-group="@var{id}"
- Execution log recording was either started or stopped on an
- inferior. The @var{id} is the @value{GDBN} identifier of the thread
- group corresponding to the affected inferior.
- The @var{method} field indicates the method used to record execution. If the
- method in use supports multiple recording formats, @var{format} will be present
- and contain the currently used format. @xref{Process Record and Replay},
- for existing method and format values.
- @item =cmd-param-changed,param=@var{param},value=@var{value}
- Reports that a parameter of the command @code{set @var{param}} is
- changed to @var{value}. In the multi-word @code{set} command,
- the @var{param} is the whole parameter list to @code{set} command.
- For example, In command @code{set check type on}, @var{param}
- is @code{check type} and @var{value} is @code{on}.
- @item =memory-changed,thread-group=@var{id},addr=@var{addr},len=@var{len}[,type="code"]
- Reports that bytes from @var{addr} to @var{data} + @var{len} were
- written in an inferior. The @var{id} is the identifier of the
- thread group corresponding to the affected inferior. The optional
- @code{type="code"} part is reported if the memory written to holds
- executable code.
- @end table
- @node GDB/MI Breakpoint Information
- @subsection @sc{gdb/mi} Breakpoint Information
- When @value{GDBN} reports information about a breakpoint, a
- tracepoint, a watchpoint, or a catchpoint, it uses a tuple with the
- following fields:
- @table @code
- @item number
- The breakpoint number.
- @item type
- The type of the breakpoint. For ordinary breakpoints this will be
- @samp{breakpoint}, but many values are possible.
- @item catch-type
- If the type of the breakpoint is @samp{catchpoint}, then this
- indicates the exact type of catchpoint.
- @item disp
- This is the breakpoint disposition---either @samp{del}, meaning that
- the breakpoint will be deleted at the next stop, or @samp{keep},
- meaning that the breakpoint will not be deleted.
- @item enabled
- This indicates whether the breakpoint is enabled, in which case the
- value is @samp{y}, or disabled, in which case the value is @samp{n}.
- Note that this is not the same as the field @code{enable}.
- @item addr
- The address of the breakpoint. This may be a hexidecimal number,
- giving the address; or the string @samp{<PENDING>}, for a pending
- breakpoint; or the string @samp{<MULTIPLE>}, for a breakpoint with
- multiple locations. This field will not be present if no address can
- be determined. For example, a watchpoint does not have an address.
- @item addr_flags
- Optional field containing any flags related to the address. These flags are
- architecture-dependent; see @ref{Architectures} for their meaning for a
- particular CPU.
- @item func
- If known, the function in which the breakpoint appears.
- If not known, this field is not present.
- @item filename
- The name of the source file which contains this function, if known.
- If not known, this field is not present.
- @item fullname
- The full file name of the source file which contains this function, if
- known. If not known, this field is not present.
- @item line
- The line number at which this breakpoint appears, if known.
- If not known, this field is not present.
- @item at
- If the source file is not known, this field may be provided. If
- provided, this holds the address of the breakpoint, possibly followed
- by a symbol name.
- @item pending
- If this breakpoint is pending, this field is present and holds the
- text used to set the breakpoint, as entered by the user.
- @item evaluated-by
- Where this breakpoint's condition is evaluated, either @samp{host} or
- @samp{target}.
- @item thread
- If this is a thread-specific breakpoint, then this identifies the
- thread in which the breakpoint can trigger.
- @item task
- If this breakpoint is restricted to a particular Ada task, then this
- field will hold the task identifier.
- @item cond
- If the breakpoint is conditional, this is the condition expression.
- @item ignore
- The ignore count of the breakpoint.
- @item enable
- The enable count of the breakpoint.
- @item traceframe-usage
- FIXME.
- @item static-tracepoint-marker-string-id
- For a static tracepoint, the name of the static tracepoint marker.
- @item mask
- For a masked watchpoint, this is the mask.
- @item pass
- A tracepoint's pass count.
- @item original-location
- The location of the breakpoint as originally specified by the user.
- This field is optional.
- @item times
- The number of times the breakpoint has been hit.
- @item installed
- This field is only given for tracepoints. This is either @samp{y},
- meaning that the tracepoint is installed, or @samp{n}, meaning that it
- is not.
- @item what
- Some extra data, the exact contents of which are type-dependent.
- @item locations
- This field is present if the breakpoint has multiple locations. It is also
- exceptionally present if the breakpoint is enabled and has a single, disabled
- location.
- The value is a list of locations. The format of a location is described below.
- @end table
- A location in a multi-location breakpoint is represented as a tuple with the
- following fields:
- @table @code
- @item number
- The location number as a dotted pair, like @samp{1.2}. The first digit is the
- number of the parent breakpoint. The second digit is the number of the
- location within that breakpoint.
- @item enabled
- There are three possible values, with the following meanings:
- @table @code
- @item y
- The location is enabled.
- @item n
- The location is disabled by the user.
- @item N
- The location is disabled because the breakpoint condition is invalid
- at this location.
- @end table
- @item addr
- The address of this location as an hexidecimal number.
- @item addr_flags
- Optional field containing any flags related to the address. These flags are
- architecture-dependent; see @ref{Architectures} for their meaning for a
- particular CPU.
- @item func
- If known, the function in which the location appears.
- If not known, this field is not present.
- @item file
- The name of the source file which contains this location, if known.
- If not known, this field is not present.
- @item fullname
- The full file name of the source file which contains this location, if
- known. If not known, this field is not present.
- @item line
- The line number at which this location appears, if known.
- If not known, this field is not present.
- @item thread-groups
- The thread groups this location is in.
- @end table
- For example, here is what the output of @code{-break-insert}
- (@pxref{GDB/MI Breakpoint Commands}) might be:
- @smallexample
- -> -break-insert main
- <- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
- enabled="y",addr="0x08048564",func="main",file="myprog.c",
- fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
- times="0"@}
- <- (gdb)
- @end smallexample
- @node GDB/MI Frame Information
- @subsection @sc{gdb/mi} Frame Information
- Response from many MI commands includes an information about stack
- frame. This information is a tuple that may have the following
- fields:
- @table @code
- @item level
- The level of the stack frame. The innermost frame has the level of
- zero. This field is always present.
- @item func
- The name of the function corresponding to the frame. This field may
- be absent if @value{GDBN} is unable to determine the function name.
- @item addr
- The code address for the frame. This field is always present.
- @item addr_flags
- Optional field containing any flags related to the address. These flags are
- architecture-dependent; see @ref{Architectures} for their meaning for a
- particular CPU.
- @item file
- The name of the source files that correspond to the frame's code
- address. This field may be absent.
- @item line
- The source line corresponding to the frames' code address. This field
- may be absent.
- @item from
- The name of the binary file (either executable or shared library) the
- corresponds to the frame's code address. This field may be absent.
- @end table
- @node GDB/MI Thread Information
- @subsection @sc{gdb/mi} Thread Information
- Whenever @value{GDBN} has to report an information about a thread, it
- uses a tuple with the following fields. The fields are always present unless
- stated otherwise.
- @table @code
- @item id
- The global numeric id assigned to the thread by @value{GDBN}.
- @item target-id
- The target-specific string identifying the thread.
- @item details
- Additional information about the thread provided by the target.
- It is supposed to be human-readable and not interpreted by the
- frontend. This field is optional.
- @item name
- The name of the thread. If the user specified a name using the
- @code{thread name} command, then this name is given. Otherwise, if
- @value{GDBN} can extract the thread name from the target, then that
- name is given. If @value{GDBN} cannot find the thread name, then this
- field is omitted.
- @item state
- The execution state of the thread, either @samp{stopped} or @samp{running},
- depending on whether the thread is presently running.
- @item frame
- The stack frame currently executing in the thread. This field is only present
- if the thread is stopped. Its format is documented in
- @ref{GDB/MI Frame Information}.
- @item core
- The value of this field is an integer number of the processor core the
- thread was last seen on. This field is optional.
- @end table
- @node GDB/MI Ada Exception Information
- @subsection @sc{gdb/mi} Ada Exception Information
- Whenever a @code{*stopped} record is emitted because the program
- stopped after hitting an exception catchpoint (@pxref{Set Catchpoints}),
- @value{GDBN} provides the name of the exception that was raised via
- the @code{exception-name} field. Also, for exceptions that were raised
- with an exception message, @value{GDBN} provides that message via
- the @code{exception-message} field.
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Simple Examples
- @section Simple Examples of @sc{gdb/mi} Interaction
- @cindex @sc{gdb/mi}, simple examples
- This subsection presents several simple examples of interaction using
- the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
- following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
- the output received from @sc{gdb/mi}.
- Note the line breaks shown in the examples are here only for
- readability, they don't appear in the real output.
- @subheading Setting a Breakpoint
- Setting a breakpoint generates synchronous output which contains detailed
- information of the breakpoint.
- @smallexample
- -> -break-insert main
- <- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
- enabled="y",addr="0x08048564",func="main",file="myprog.c",
- fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
- times="0"@}
- <- (gdb)
- @end smallexample
- @subheading Program Execution
- Program execution generates asynchronous records and MI gives the
- reason that execution stopped.
- @smallexample
- -> -exec-run
- <- ^running
- <- (gdb)
- <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
- frame=@{addr="0x08048564",func="main",
- args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
- file="myprog.c",fullname="/home/nickrob/myprog.c",line="68",
- arch="i386:x86_64"@}
- <- (gdb)
- -> -exec-continue
- <- ^running
- <- (gdb)
- <- *stopped,reason="exited-normally"
- <- (gdb)
- @end smallexample
- @subheading Quitting @value{GDBN}
- Quitting @value{GDBN} just prints the result class @samp{^exit}.
- @smallexample
- -> (gdb)
- <- -gdb-exit
- <- ^exit
- @end smallexample
- Please note that @samp{^exit} is printed immediately, but it might
- take some time for @value{GDBN} to actually exit. During that time, @value{GDBN}
- performs necessary cleanups, including killing programs being debugged
- or disconnecting from debug hardware, so the frontend should wait till
- @value{GDBN} exits and should only forcibly kill @value{GDBN} if it
- fails to exit in reasonable time.
- @subheading A Bad Command
- Here's what happens if you pass a non-existent command:
- @smallexample
- -> -rubbish
- <- ^error,msg="Undefined MI command: rubbish"
- <- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Command Description Format
- @section @sc{gdb/mi} Command Description Format
- The remaining sections describe blocks of commands. Each block of
- commands is laid out in a fashion similar to this section.
- @subheading Motivation
- The motivation for this collection of commands.
- @subheading Introduction
- A brief introduction to this collection of commands as a whole.
- @subheading Commands
- For each command in the block, the following is described:
- @subsubheading Synopsis
- @smallexample
- -command @var{args}@dots{}
- @end smallexample
- @subsubheading Result
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} CLI command(s), if any.
- @subsubheading Example
- Example(s) formatted for readability. Some of the described commands have
- not been implemented yet and these are labeled N.A.@: (not available).
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Breakpoint Commands
- @section @sc{gdb/mi} Breakpoint Commands
- @cindex breakpoint commands for @sc{gdb/mi}
- @cindex @sc{gdb/mi}, breakpoint commands
- This section documents @sc{gdb/mi} commands for manipulating
- breakpoints.
- @subheading The @code{-break-after} Command
- @findex -break-after
- @subsubheading Synopsis
- @smallexample
- -break-after @var{number} @var{count}
- @end smallexample
- The breakpoint number @var{number} is not in effect until it has been
- hit @var{count} times. To see how this is reflected in the output of
- the @samp{-break-list} command, see the description of the
- @samp{-break-list} command below.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{ignore}.
- @subsubheading Example
- @smallexample
- (gdb)
- -break-insert main
- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
- enabled="y",addr="0x000100d0",func="main",file="hello.c",
- fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
- times="0"@}
- (gdb)
- -break-after 1 3
- ~
- ^done
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
- line="5",thread-groups=["i1"],times="0",ignore="3"@}]@}
- (gdb)
- @end smallexample
- @ignore
- @subheading The @code{-break-catch} Command
- @findex -break-catch
- @end ignore
- @subheading The @code{-break-commands} Command
- @findex -break-commands
- @subsubheading Synopsis
- @smallexample
- -break-commands @var{number} [ @var{command1} ... @var{commandN} ]
- @end smallexample
- Specifies the CLI commands that should be executed when breakpoint
- @var{number} is hit. The parameters @var{command1} to @var{commandN}
- are the commands. If no command is specified, any previously-set
- commands are cleared. @xref{Break Commands}. Typical use of this
- functionality is tracing a program, that is, printing of values of
- some variables whenever breakpoint is hit and then continuing.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{commands}.
- @subsubheading Example
- @smallexample
- (gdb)
- -break-insert main
- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
- enabled="y",addr="0x000100d0",func="main",file="hello.c",
- fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
- times="0"@}
- (gdb)
- -break-commands 1 "print v" "continue"
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-break-condition} Command
- @findex -break-condition
- @subsubheading Synopsis
- @smallexample
- -break-condition [ --force ] @var{number} [ @var{expr} ]
- @end smallexample
- Breakpoint @var{number} will stop the program only if the condition in
- @var{expr} is true. The condition becomes part of the
- @samp{-break-list} output (see the description of the @samp{-break-list}
- command below). If the @samp{--force} flag is passed, the condition
- is forcibly defined even when it is invalid for all locations of
- breakpoint @var{number}. If the @var{expr} argument is omitted,
- breakpoint @var{number} becomes unconditional.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{condition}.
- @subsubheading Example
- @smallexample
- (gdb)
- -break-condition 1 1
- ^done
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
- line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"@}]@}
- (gdb)
- @end smallexample
- @subheading The @code{-break-delete} Command
- @findex -break-delete
- @subsubheading Synopsis
- @smallexample
- -break-delete ( @var{breakpoint} )+
- @end smallexample
- Delete the breakpoint(s) whose number(s) are specified in the argument
- list. This is obviously reflected in the breakpoint list.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{delete}.
- @subsubheading Example
- @smallexample
- (gdb)
- -break-delete 1
- ^done
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[]@}
- (gdb)
- @end smallexample
- @subheading The @code{-break-disable} Command
- @findex -break-disable
- @subsubheading Synopsis
- @smallexample
- -break-disable ( @var{breakpoint} )+
- @end smallexample
- Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
- break list is now set to @samp{n} for the named @var{breakpoint}(s).
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{disable}.
- @subsubheading Example
- @smallexample
- (gdb)
- -break-disable 2
- ^done
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
- addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
- line="5",thread-groups=["i1"],times="0"@}]@}
- (gdb)
- @end smallexample
- @subheading The @code{-break-enable} Command
- @findex -break-enable
- @subsubheading Synopsis
- @smallexample
- -break-enable ( @var{breakpoint} )+
- @end smallexample
- Enable (previously disabled) @var{breakpoint}(s).
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{enable}.
- @subsubheading Example
- @smallexample
- (gdb)
- -break-enable 2
- ^done
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
- addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
- line="5",thread-groups=["i1"],times="0"@}]@}
- (gdb)
- @end smallexample
- @subheading The @code{-break-info} Command
- @findex -break-info
- @subsubheading Synopsis
- @smallexample
- -break-info @var{breakpoint}
- @end smallexample
- @c REDUNDANT???
- Get information about a single breakpoint.
- The result is a table of breakpoints. @xref{GDB/MI Breakpoint
- Information}, for details on the format of each breakpoint in the
- table.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
- @subsubheading Example
- N.A.
- @subheading The @code{-break-insert} Command
- @findex -break-insert
- @anchor{-break-insert}
- @subsubheading Synopsis
- @smallexample
- -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ]
- [ -c @var{condition} ] [ --force-condition ] [ -i @var{ignore-count} ]
- [ -p @var{thread-id} ] [ @var{location} ]
- @end smallexample
- @noindent
- If specified, @var{location}, can be one of:
- @table @var
- @item linespec location
- A linespec location. @xref{Linespec Locations}.
- @item explicit location
- An explicit location. @sc{gdb/mi} explicit locations are
- analogous to the CLI's explicit locations using the option names
- listed below. @xref{Explicit Locations}.
- @table @samp
- @item --source @var{filename}
- The source file name of the location. This option requires the use
- of either @samp{--function} or @samp{--line}.
- @item --function @var{function}
- The name of a function or method.
- @item --label @var{label}
- The name of a label.
- @item --line @var{lineoffset}
- An absolute or relative line offset from the start of the location.
- @end table
- @item address location
- An address location, *@var{address}. @xref{Address Locations}.
- @end table
- @noindent
- The possible optional parameters of this command are:
- @table @samp
- @item -t
- Insert a temporary breakpoint.
- @item -h
- Insert a hardware breakpoint.
- @item -f
- If @var{location} cannot be parsed (for example if it
- refers to unknown files or functions), create a pending
- breakpoint. Without this flag, @value{GDBN} will report
- an error, and won't create a breakpoint, if @var{location}
- cannot be parsed.
- @item -d
- Create a disabled breakpoint.
- @item -a
- Create a tracepoint. @xref{Tracepoints}. When this parameter
- is used together with @samp{-h}, a fast tracepoint is created.
- @item -c @var{condition}
- Make the breakpoint conditional on @var{condition}.
- @item --force-condition
- Forcibly define the breakpoint even if the condition is invalid at
- all of the breakpoint locations.
- @item -i @var{ignore-count}
- Initialize the @var{ignore-count}.
- @item -p @var{thread-id}
- Restrict the breakpoint to the thread with the specified global
- @var{thread-id}.
- @item --qualified
- This option makes @value{GDBN} interpret a function name specified as
- a complete fully-qualified name.
- @end table
- @subsubheading Result
- @xref{GDB/MI Breakpoint Information}, for details on the format of the
- resulting breakpoint.
- Note: this format is open to change.
- @c An out-of-band breakpoint instead of part of the result?
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
- @samp{hbreak}, and @samp{thbreak}. @c and @samp{rbreak}.
- @subsubheading Example
- @smallexample
- (gdb)
- -break-insert main
- ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
- fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],
- times="0"@}
- (gdb)
- -break-insert -t foo
- ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
- fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],
- times="0"@}
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x0001072c", func="main",file="recursive2.c",
- fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],
- times="0"@},
- bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
- addr="0x00010774",func="foo",file="recursive2.c",
- fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
- times="0"@}]@}
- (gdb)
- @c -break-insert -r foo.*
- @c ~int foo(int, int);
- @c ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
- @c "fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
- @c times="0"@}
- @c (gdb)
- @end smallexample
- @subheading The @code{-dprintf-insert} Command
- @findex -dprintf-insert
- @subsubheading Synopsis
- @smallexample
- -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ]
- [ -c @var{condition} ] [--force-condition] [ -i @var{ignore-count} ]
- [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ]
- [ @var{argument} ]
- @end smallexample
- @noindent
- If supplied, @var{location} and @code{--qualified} may be specified
- the same way as for the @code{-break-insert} command.
- @xref{-break-insert}.
- The possible optional parameters of this command are:
- @table @samp
- @item -t
- Insert a temporary breakpoint.
- @item -f
- If @var{location} cannot be parsed (for example, if it
- refers to unknown files or functions), create a pending
- breakpoint. Without this flag, @value{GDBN} will report
- an error, and won't create a breakpoint, if @var{location}
- cannot be parsed.
- @item -d
- Create a disabled breakpoint.
- @item -c @var{condition}
- Make the breakpoint conditional on @var{condition}.
- @item --force-condition
- Forcibly define the breakpoint even if the condition is invalid at
- all of the breakpoint locations.
- @item -i @var{ignore-count}
- Set the ignore count of the breakpoint (@pxref{Conditions, ignore count})
- to @var{ignore-count}.
- @item -p @var{thread-id}
- Restrict the breakpoint to the thread with the specified global
- @var{thread-id}.
- @end table
- @subsubheading Result
- @xref{GDB/MI Breakpoint Information}, for details on the format of the
- resulting breakpoint.
- @c An out-of-band breakpoint instead of part of the result?
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{dprintf}.
- @subsubheading Example
- @smallexample
- (gdb)
- 4-dprintf-insert foo "At foo entry\n"
- 4^done,bkpt=@{number="1",type="dprintf",disp="keep",enabled="y",
- addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
- fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
- times="0",script=@{"printf \"At foo entry\\n\"","continue"@},
- original-location="foo"@}
- (gdb)
- 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
- 5^done,bkpt=@{number="2",type="dprintf",disp="keep",enabled="y",
- addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
- fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
- times="0",script=@{"printf \"arg=%d, g=%d\\n\", arg, g","continue"@},
- original-location="mi-dprintf.c:26"@}
- (gdb)
- @end smallexample
- @subheading The @code{-break-list} Command
- @findex -break-list
- @subsubheading Synopsis
- @smallexample
- -break-list
- @end smallexample
- Displays the list of inserted breakpoints, showing the following fields:
- @table @samp
- @item Number
- number of the breakpoint
- @item Type
- type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
- @item Disposition
- should the breakpoint be deleted or disabled when it is hit: @samp{keep}
- or @samp{nokeep}
- @item Enabled
- is the breakpoint enabled or no: @samp{y} or @samp{n}
- @item Address
- memory location at which the breakpoint is set
- @item What
- logical location of the breakpoint, expressed by function name, file
- name, line number
- @item Thread-groups
- list of thread groups to which this breakpoint applies
- @item Times
- number of times the breakpoint has been hit
- @end table
- If there are no breakpoints or watchpoints, the @code{BreakpointTable}
- @code{body} field is an empty list.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info break}.
- @subsubheading Example
- @smallexample
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],
- times="0"@},
- bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
- addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
- line="13",thread-groups=["i1"],times="0"@}]@}
- (gdb)
- @end smallexample
- Here's an example of the result when there are no breakpoints:
- @smallexample
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[]@}
- (gdb)
- @end smallexample
- @subheading The @code{-break-passcount} Command
- @findex -break-passcount
- @subsubheading Synopsis
- @smallexample
- -break-passcount @var{tracepoint-number} @var{passcount}
- @end smallexample
- Set the passcount for tracepoint @var{tracepoint-number} to
- @var{passcount}. If the breakpoint referred to by @var{tracepoint-number}
- is not a tracepoint, error is emitted. This corresponds to CLI
- command @samp{passcount}.
- @subheading The @code{-break-watch} Command
- @findex -break-watch
- @subsubheading Synopsis
- @smallexample
- -break-watch [ -a | -r ]
- @end smallexample
- Create a watchpoint. With the @samp{-a} option it will create an
- @dfn{access} watchpoint, i.e., a watchpoint that triggers either on a
- read from or on a write to the memory location. With the @samp{-r}
- option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will
- trigger only when the memory location is accessed for reading. Without
- either of the options, the watchpoint created is a regular watchpoint,
- i.e., it will trigger when the memory location is accessed for writing.
- @xref{Set Watchpoints, , Setting Watchpoints}.
- Note that @samp{-break-list} will report a single list of watchpoints and
- breakpoints inserted.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
- @samp{rwatch}.
- @subsubheading Example
- Setting a watchpoint on a variable in the @code{main} function:
- @smallexample
- (gdb)
- -break-watch x
- ^done,wpt=@{number="2",exp="x"@}
- (gdb)
- -exec-continue
- ^running
- (gdb)
- *stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
- value=@{old="-268439212",new="55"@},
- frame=@{func="main",args=[],file="recursive2.c",
- fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
- the program execution twice: first for the variable changing value, then
- for the watchpoint going out of scope.
- @smallexample
- (gdb)
- -break-watch C
- ^done,wpt=@{number="5",exp="C"@}
- (gdb)
- -exec-continue
- ^running
- (gdb)
- *stopped,reason="watchpoint-trigger",
- wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
- frame=@{func="callee4",args=[],
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",
- arch="i386:x86_64"@}
- (gdb)
- -exec-continue
- ^running
- (gdb)
- *stopped,reason="watchpoint-scope",wpnum="5",
- frame=@{func="callee3",args=[@{name="strarg",
- value="0x11940 \"A string argument.\""@}],
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
- arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- Listing breakpoints and watchpoints, at different points in the program
- execution. Note that once the watchpoint goes out of scope, it is
- deleted.
- @smallexample
- (gdb)
- -break-watch C
- ^done,wpt=@{number="2",exp="C"@}
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x00010734",func="callee4",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],
- times="1"@},
- bkpt=@{number="2",type="watchpoint",disp="keep",
- enabled="y",addr="",what="C",thread-groups=["i1"],times="0"@}]@}
- (gdb)
- -exec-continue
- ^running
- (gdb)
- *stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
- value=@{old="-276895068",new="3"@},
- frame=@{func="callee4",args=[],
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",
- arch="i386:x86_64"@}
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x00010734",func="callee4",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],
- times="1"@},
- bkpt=@{number="2",type="watchpoint",disp="keep",
- enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"@}]@}
- (gdb)
- -exec-continue
- ^running
- ^done,reason="watchpoint-scope",wpnum="2",
- frame=@{func="callee3",args=[@{name="strarg",
- value="0x11940 \"A string argument.\""@}],
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
- arch="i386:x86_64"@}
- (gdb)
- -break-list
- ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
- hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
- @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
- @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
- @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
- @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
- @{width="40",alignment="2",col_name="what",colhdr="What"@}],
- body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x00010734",func="callee4",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
- thread-groups=["i1"],times="1"@}]@}
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Catchpoint Commands
- @section @sc{gdb/mi} Catchpoint Commands
- This section documents @sc{gdb/mi} commands for manipulating
- catchpoints.
- @menu
- * Shared Library GDB/MI Catchpoint Commands::
- * Ada Exception GDB/MI Catchpoint Commands::
- * C++ Exception GDB/MI Catchpoint Commands::
- @end menu
- @node Shared Library GDB/MI Catchpoint Commands
- @subsection Shared Library @sc{gdb/mi} Catchpoints
- @subheading The @code{-catch-load} Command
- @findex -catch-load
- @subsubheading Synopsis
- @smallexample
- -catch-load [ -t ] [ -d ] @var{regexp}
- @end smallexample
- Add a catchpoint for library load events. If the @samp{-t} option is used,
- the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting
- Breakpoints}). If the @samp{-d} option is used, the catchpoint is created
- in a disabled state. The @samp{regexp} argument is a regular
- expression used to match the name of the loaded library.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{catch load}.
- @subsubheading Example
- @smallexample
- -catch-load -t foo.so
- ^done,bkpt=@{number="1",type="catchpoint",disp="del",enabled="y",
- what="load of library matching foo.so",catch-type="load",times="0"@}
- (gdb)
- @end smallexample
- @subheading The @code{-catch-unload} Command
- @findex -catch-unload
- @subsubheading Synopsis
- @smallexample
- -catch-unload [ -t ] [ -d ] @var{regexp}
- @end smallexample
- Add a catchpoint for library unload events. If the @samp{-t} option is
- used, the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting
- Breakpoints}). If the @samp{-d} option is used, the catchpoint is
- created in a disabled state. The @samp{regexp} argument is a regular
- expression used to match the name of the unloaded library.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{catch unload}.
- @subsubheading Example
- @smallexample
- -catch-unload -d bar.so
- ^done,bkpt=@{number="2",type="catchpoint",disp="keep",enabled="n",
- what="load of library matching bar.so",catch-type="unload",times="0"@}
- (gdb)
- @end smallexample
- @node Ada Exception GDB/MI Catchpoint Commands
- @subsection Ada Exception @sc{gdb/mi} Catchpoints
- The following @sc{gdb/mi} commands can be used to create catchpoints
- that stop the execution when Ada exceptions are being raised.
- @subheading The @code{-catch-assert} Command
- @findex -catch-assert
- @subsubheading Synopsis
- @smallexample
- -catch-assert [ -c @var{condition}] [ -d ] [ -t ]
- @end smallexample
- Add a catchpoint for failed Ada assertions.
- The possible optional parameters for this command are:
- @table @samp
- @item -c @var{condition}
- Make the catchpoint conditional on @var{condition}.
- @item -d
- Create a disabled catchpoint.
- @item -t
- Create a temporary catchpoint.
- @end table
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{catch assert}.
- @subsubheading Example
- @smallexample
- -catch-assert
- ^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep",
- enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
- thread-groups=["i1"],times="0",
- original-location="__gnat_debug_raise_assert_failure"@}
- (gdb)
- @end smallexample
- @subheading The @code{-catch-exception} Command
- @findex -catch-exception
- @subsubheading Synopsis
- @smallexample
- -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
- [ -t ] [ -u ]
- @end smallexample
- Add a catchpoint stopping when Ada exceptions are raised.
- By default, the command stops the program when any Ada exception
- gets raised. But it is also possible, by using some of the
- optional parameters described below, to create more selective
- catchpoints.
- The possible optional parameters for this command are:
- @table @samp
- @item -c @var{condition}
- Make the catchpoint conditional on @var{condition}.
- @item -d
- Create a disabled catchpoint.
- @item -e @var{exception-name}
- Only stop when @var{exception-name} is raised. This option cannot
- be used combined with @samp{-u}.
- @item -t
- Create a temporary catchpoint.
- @item -u
- Stop only when an unhandled exception gets raised. This option
- cannot be used combined with @samp{-e}.
- @end table
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{catch exception}
- and @samp{catch exception unhandled}.
- @subsubheading Example
- @smallexample
- -catch-exception -e Program_Error
- ^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
- enabled="y",addr="0x0000000000404874",
- what="`Program_Error' Ada exception", thread-groups=["i1"],
- times="0",original-location="__gnat_debug_raise_exception"@}
- (gdb)
- @end smallexample
- @subheading The @code{-catch-handlers} Command
- @findex -catch-handlers
- @subsubheading Synopsis
- @smallexample
- -catch-handlers [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
- [ -t ]
- @end smallexample
- Add a catchpoint stopping when Ada exceptions are handled.
- By default, the command stops the program when any Ada exception
- gets handled. But it is also possible, by using some of the
- optional parameters described below, to create more selective
- catchpoints.
- The possible optional parameters for this command are:
- @table @samp
- @item -c @var{condition}
- Make the catchpoint conditional on @var{condition}.
- @item -d
- Create a disabled catchpoint.
- @item -e @var{exception-name}
- Only stop when @var{exception-name} is handled.
- @item -t
- Create a temporary catchpoint.
- @end table
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{catch handlers}.
- @subsubheading Example
- @smallexample
- -catch-handlers -e Constraint_Error
- ^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
- enabled="y",addr="0x0000000000402f68",
- what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"],
- times="0",original-location="__gnat_begin_handler"@}
- (gdb)
- @end smallexample
- @node C++ Exception GDB/MI Catchpoint Commands
- @subsection C@t{++} Exception @sc{gdb/mi} Catchpoints
- The following @sc{gdb/mi} commands can be used to create catchpoints
- that stop the execution when C@t{++} exceptions are being throw, rethrown,
- or caught.
- @subheading The @code{-catch-throw} Command
- @findex -catch-throw
- @subsubheading Synopsis
- @smallexample
- -catch-throw [ -t ] [ -r @var{regexp}]
- @end smallexample
- Stop when the debuggee throws a C@t{++} exception. If @var{regexp} is
- given, then only exceptions whose type matches the regular expression
- will be caught.
- If @samp{-t} is given, then the catchpoint is enabled only for one
- stop, the catchpoint is automatically deleted after stopping once for
- the event.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{catch throw}
- and @samp{tcatch throw} (@pxref{Set Catchpoints}).
- @subsubheading Example
- @smallexample
- -catch-throw -r exception_type
- ^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
- what="exception throw",catch-type="throw",
- thread-groups=["i1"],
- regexp="exception_type",times="0"@}
- (gdb)
- -exec-run
- ^running
- (gdb)
- ~"\n"
- ~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed
- in __cxa_throw () from /lib64/libstdc++.so.6\n"
- *stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
- frame=@{addr="0x00007ffff7ae00ed",func="__cxa_throw",
- args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
- thread-id="1",stopped-threads="all",core="6"
- (gdb)
- @end smallexample
- @subheading The @code{-catch-rethrow} Command
- @findex -catch-rethrow
- @subsubheading Synopsis
- @smallexample
- -catch-rethrow [ -t ] [ -r @var{regexp}]
- @end smallexample
- Stop when a C@t{++} exception is re-thrown. If @var{regexp} is given,
- then only exceptions whose type matches the regular expression will be
- caught.
- If @samp{-t} is given, then the catchpoint is enabled only for one
- stop, the catchpoint is automatically deleted after the first event is
- caught.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{catch rethrow}
- and @samp{tcatch rethrow} (@pxref{Set Catchpoints}).
- @subsubheading Example
- @smallexample
- -catch-rethrow -r exception_type
- ^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
- what="exception rethrow",catch-type="rethrow",
- thread-groups=["i1"],
- regexp="exception_type",times="0"@}
- (gdb)
- -exec-run
- ^running
- (gdb)
- ~"\n"
- ~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed
- in __cxa_rethrow () from /lib64/libstdc++.so.6\n"
- *stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
- frame=@{addr="0x00007ffff7ae00ed",func="__cxa_rethrow",
- args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
- thread-id="1",stopped-threads="all",core="6"
- (gdb)
- @end smallexample
- @subheading The @code{-catch-catch} Command
- @findex -catch-catch
- @subsubheading Synopsis
- @smallexample
- -catch-catch [ -t ] [ -r @var{regexp}]
- @end smallexample
- Stop when the debuggee catches a C@t{++} exception. If @var{regexp}
- is given, then only exceptions whose type matches the regular
- expression will be caught.
- If @samp{-t} is given, then the catchpoint is enabled only for one
- stop, the catchpoint is automatically deleted after the first event is
- caught.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{catch catch}
- and @samp{tcatch catch} (@pxref{Set Catchpoints}).
- @subsubheading Example
- @smallexample
- -catch-catch -r exception_type
- ^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
- what="exception catch",catch-type="catch",
- thread-groups=["i1"],
- regexp="exception_type",times="0"@}
- (gdb)
- -exec-run
- ^running
- (gdb)
- ~"\n"
- ~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed
- in __cxa_begin_catch () from /lib64/libstdc++.so.6\n"
- *stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
- frame=@{addr="0x00007ffff7ae00ed",func="__cxa_begin_catch",
- args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
- thread-id="1",stopped-threads="all",core="6"
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Program Context
- @section @sc{gdb/mi} Program Context
- @subheading The @code{-exec-arguments} Command
- @findex -exec-arguments
- @subsubheading Synopsis
- @smallexample
- -exec-arguments @var{args}
- @end smallexample
- Set the inferior program arguments, to be used in the next
- @samp{-exec-run}.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{set args}.
- @subsubheading Example
- @smallexample
- (gdb)
- -exec-arguments -v word
- ^done
- (gdb)
- @end smallexample
- @ignore
- @subheading The @code{-exec-show-arguments} Command
- @findex -exec-show-arguments
- @subsubheading Synopsis
- @smallexample
- -exec-show-arguments
- @end smallexample
- Print the arguments of the program.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{show args}.
- @subsubheading Example
- N.A.
- @end ignore
- @subheading The @code{-environment-cd} Command
- @findex -environment-cd
- @subsubheading Synopsis
- @smallexample
- -environment-cd @var{pathdir}
- @end smallexample
- Set @value{GDBN}'s working directory.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{cd}.
- @subsubheading Example
- @smallexample
- (gdb)
- -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-environment-directory} Command
- @findex -environment-directory
- @subsubheading Synopsis
- @smallexample
- -environment-directory [ -r ] [ @var{pathdir} ]+
- @end smallexample
- Add directories @var{pathdir} to beginning of search path for source files.
- If the @samp{-r} option is used, the search path is reset to the default
- search path. If directories @var{pathdir} are supplied in addition to the
- @samp{-r} option, the search path is first reset and then addition
- occurs as normal.
- Multiple directories may be specified, separated by blanks. Specifying
- multiple directories in a single command
- results in the directories added to the beginning of the
- search path in the same order they were presented in the command.
- If blanks are needed as
- part of a directory name, double-quotes should be used around
- the name. In the command output, the path will show up separated
- by the system directory-separator character. The directory-separator
- character must not be used
- in any directory name.
- If no directories are specified, the current search path is displayed.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{dir}.
- @subsubheading Example
- @smallexample
- (gdb)
- -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
- ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
- (gdb)
- -environment-directory ""
- ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
- (gdb)
- -environment-directory -r /home/jjohnstn/src/gdb /usr/src
- ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
- (gdb)
- -environment-directory -r
- ^done,source-path="$cdir:$cwd"
- (gdb)
- @end smallexample
- @subheading The @code{-environment-path} Command
- @findex -environment-path
- @subsubheading Synopsis
- @smallexample
- -environment-path [ -r ] [ @var{pathdir} ]+
- @end smallexample
- Add directories @var{pathdir} to beginning of search path for object files.
- If the @samp{-r} option is used, the search path is reset to the original
- search path that existed at gdb start-up. If directories @var{pathdir} are
- supplied in addition to the
- @samp{-r} option, the search path is first reset and then addition
- occurs as normal.
- Multiple directories may be specified, separated by blanks. Specifying
- multiple directories in a single command
- results in the directories added to the beginning of the
- search path in the same order they were presented in the command.
- If blanks are needed as
- part of a directory name, double-quotes should be used around
- the name. In the command output, the path will show up separated
- by the system directory-separator character. The directory-separator
- character must not be used
- in any directory name.
- If no directories are specified, the current path is displayed.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{path}.
- @subsubheading Example
- @smallexample
- (gdb)
- -environment-path
- ^done,path="/usr/bin"
- (gdb)
- -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
- ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
- (gdb)
- -environment-path -r /usr/local/bin
- ^done,path="/usr/local/bin:/usr/bin"
- (gdb)
- @end smallexample
- @subheading The @code{-environment-pwd} Command
- @findex -environment-pwd
- @subsubheading Synopsis
- @smallexample
- -environment-pwd
- @end smallexample
- Show the current working directory.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{pwd}.
- @subsubheading Example
- @smallexample
- (gdb)
- -environment-pwd
- ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Thread Commands
- @section @sc{gdb/mi} Thread Commands
- @subheading The @code{-thread-info} Command
- @findex -thread-info
- @subsubheading Synopsis
- @smallexample
- -thread-info [ @var{thread-id} ]
- @end smallexample
- Reports information about either a specific thread, if the
- @var{thread-id} parameter is present, or about all threads.
- @var{thread-id} is the thread's global thread ID. When printing
- information about all threads, also reports the global ID of the
- current thread.
- @subsubheading @value{GDBN} Command
- The @samp{info thread} command prints the same information
- about all threads.
- @subsubheading Result
- The result contains the following attributes:
- @table @samp
- @item threads
- A list of threads. The format of the elements of the list is described in
- @ref{GDB/MI Thread Information}.
- @item current-thread-id
- The global id of the currently selected thread. This field is omitted if there
- is no selected thread (for example, when the selected inferior is not running,
- and therefore has no threads) or if a @var{thread-id} argument was passed to
- the command.
- @end table
- @subsubheading Example
- @smallexample
- -thread-info
- ^done,threads=[
- @{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
- frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",
- args=[]@},state="running"@},
- @{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
- frame=@{level="0",addr="0x0804891f",func="foo",
- args=[@{name="i",value="10"@}],
- file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},
- state="running"@}],
- current-thread-id="1"
- (gdb)
- @end smallexample
- @subheading The @code{-thread-list-ids} Command
- @findex -thread-list-ids
- @subsubheading Synopsis
- @smallexample
- -thread-list-ids
- @end smallexample
- Produces a list of the currently known global @value{GDBN} thread ids.
- At the end of the list it also prints the total number of such
- threads.
- This command is retained for historical reasons, the
- @code{-thread-info} command should be used instead.
- @subsubheading @value{GDBN} Command
- Part of @samp{info threads} supplies the same information.
- @subsubheading Example
- @smallexample
- (gdb)
- -thread-list-ids
- ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
- current-thread-id="1",number-of-threads="3"
- (gdb)
- @end smallexample
- @subheading The @code{-thread-select} Command
- @findex -thread-select
- @subsubheading Synopsis
- @smallexample
- -thread-select @var{thread-id}
- @end smallexample
- Make thread with global thread number @var{thread-id} the current
- thread. It prints the number of the new current thread, and the
- topmost frame for that thread.
- This command is deprecated in favor of explicitly using the
- @samp{--thread} option to each command.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{thread}.
- @subsubheading Example
- @smallexample
- (gdb)
- -exec-next
- ^running
- (gdb)
- *stopped,reason="end-stepping-range",thread-id="2",line="187",
- file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
- (gdb)
- -thread-list-ids
- ^done,
- thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
- number-of-threads="3"
- (gdb)
- -thread-select 3
- ^done,new-thread-id="3",
- frame=@{level="0",func="vprintf",
- args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
- @{name="arg",value="0x2"@}],file="vprintf.c",line="31",arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Ada Tasking Commands
- @section @sc{gdb/mi} Ada Tasking Commands
- @subheading The @code{-ada-task-info} Command
- @findex -ada-task-info
- @subsubheading Synopsis
- @smallexample
- -ada-task-info [ @var{task-id} ]
- @end smallexample
- Reports information about either a specific Ada task, if the
- @var{task-id} parameter is present, or about all Ada tasks.
- @subsubheading @value{GDBN} Command
- The @samp{info tasks} command prints the same information
- about all Ada tasks (@pxref{Ada Tasks}).
- @subsubheading Result
- The result is a table of Ada tasks. The following columns are
- defined for each Ada task:
- @table @samp
- @item current
- This field exists only for the current thread. It has the value @samp{*}.
- @item id
- The identifier that @value{GDBN} uses to refer to the Ada task.
- @item task-id
- The identifier that the target uses to refer to the Ada task.
- @item thread-id
- The global thread identifier of the thread corresponding to the Ada
- task.
- This field should always exist, as Ada tasks are always implemented
- on top of a thread. But if @value{GDBN} cannot find this corresponding
- thread for any reason, the field is omitted.
- @item parent-id
- This field exists only when the task was created by another task.
- In this case, it provides the ID of the parent task.
- @item priority
- The base priority of the task.
- @item state
- The current state of the task. For a detailed description of the
- possible states, see @ref{Ada Tasks}.
- @item name
- The name of the task.
- @end table
- @subsubheading Example
- @smallexample
- -ada-task-info
- ^done,tasks=@{nr_rows="3",nr_cols="8",
- hdr=[@{width="1",alignment="-1",col_name="current",colhdr=""@},
- @{width="3",alignment="1",col_name="id",colhdr="ID"@},
- @{width="9",alignment="1",col_name="task-id",colhdr="TID"@},
- @{width="4",alignment="1",col_name="thread-id",colhdr=""@},
- @{width="4",alignment="1",col_name="parent-id",colhdr="P-ID"@},
- @{width="3",alignment="1",col_name="priority",colhdr="Pri"@},
- @{width="22",alignment="-1",col_name="state",colhdr="State"@},
- @{width="1",alignment="2",col_name="name",colhdr="Name"@}],
- body=[@{current="*",id="1",task-id=" 644010",thread-id="1",priority="48",
- state="Child Termination Wait",name="main_task"@}]@}
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Program Execution
- @section @sc{gdb/mi} Program Execution
- These are the asynchronous commands which generate the out-of-band
- record @samp{*stopped}. Currently @value{GDBN} only really executes
- asynchronously with remote targets and this interaction is mimicked in
- other cases.
- @subheading The @code{-exec-continue} Command
- @findex -exec-continue
- @subsubheading Synopsis
- @smallexample
- -exec-continue [--reverse] [--all|--thread-group N]
- @end smallexample
- Resumes the execution of the inferior program, which will continue
- to execute until it reaches a debugger stop event. If the
- @samp{--reverse} option is specified, execution resumes in reverse until
- it reaches a stop event. Stop events may include
- @itemize @bullet
- @item
- breakpoints or watchpoints
- @item
- signals or exceptions
- @item
- the end of the process (or its beginning under @samp{--reverse})
- @item
- the end or beginning of a replay log if one is being used.
- @end itemize
- In all-stop mode (@pxref{All-Stop
- Mode}), may resume only one thread, or all threads, depending on the
- value of the @samp{scheduler-locking} variable. If @samp{--all} is
- specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is
- ignored in all-stop mode. If the @samp{--thread-group} options is
- specified, then all threads in that thread group are resumed.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} corresponding is @samp{continue}.
- @subsubheading Example
- @smallexample
- -exec-continue
- ^running
- (gdb)
- @@Hello world
- *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{
- func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
- line="13",arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- @subheading The @code{-exec-finish} Command
- @findex -exec-finish
- @subsubheading Synopsis
- @smallexample
- -exec-finish [--reverse]
- @end smallexample
- Resumes the execution of the inferior program until the current
- function is exited. Displays the results returned by the function.
- If the @samp{--reverse} option is specified, resumes the reverse
- execution of the inferior program until the point where current
- function was called.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{finish}.
- @subsubheading Example
- Function returning @code{void}.
- @smallexample
- -exec-finish
- ^running
- (gdb)
- @@hello from foo
- *stopped,reason="function-finished",frame=@{func="main",args=[],
- file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- Function returning other than @code{void}. The name of the internal
- @value{GDBN} variable storing the result is printed, together with the
- value itself.
- @smallexample
- -exec-finish
- ^running
- (gdb)
- *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
- args=[@{name="a",value="1"],@{name="b",value="9"@}@},
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- gdb-result-var="$1",return-value="0"
- (gdb)
- @end smallexample
- @subheading The @code{-exec-interrupt} Command
- @findex -exec-interrupt
- @subsubheading Synopsis
- @smallexample
- -exec-interrupt [--all|--thread-group N]
- @end smallexample
- Interrupts the background execution of the target. Note how the token
- associated with the stop message is the one for the execution command
- that has been interrupted. The token for the interrupt itself only
- appears in the @samp{^done} output. If the user is trying to
- interrupt a non-running program, an error message will be printed.
- Note that when asynchronous execution is enabled, this command is
- asynchronous just like other execution commands. That is, first the
- @samp{^done} response will be printed, and the target stop will be
- reported after that using the @samp{*stopped} notification.
- In non-stop mode, only the context thread is interrupted by default.
- All threads (in all inferiors) will be interrupted if the
- @samp{--all} option is specified. If the @samp{--thread-group}
- option is specified, all threads in that group will be interrupted.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{interrupt}.
- @subsubheading Example
- @smallexample
- (gdb)
- 111-exec-continue
- 111^running
- (gdb)
- 222-exec-interrupt
- 222^done
- (gdb)
- 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
- frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
- fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@}
- (gdb)
- (gdb)
- -exec-interrupt
- ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
- (gdb)
- @end smallexample
- @subheading The @code{-exec-jump} Command
- @findex -exec-jump
- @subsubheading Synopsis
- @smallexample
- -exec-jump @var{location}
- @end smallexample
- Resumes execution of the inferior program at the location specified by
- parameter. @xref{Specify Location}, for a description of the
- different forms of @var{location}.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{jump}.
- @subsubheading Example
- @smallexample
- -exec-jump foo.c:10
- *running,thread-id="all"
- ^running
- @end smallexample
- @subheading The @code{-exec-next} Command
- @findex -exec-next
- @subsubheading Synopsis
- @smallexample
- -exec-next [--reverse]
- @end smallexample
- Resumes execution of the inferior program, stopping when the beginning
- of the next source line is reached.
- If the @samp{--reverse} option is specified, resumes reverse execution
- of the inferior program, stopping at the beginning of the previous
- source line. If you issue this command on the first line of a
- function, it will take you back to the caller of that function, to the
- source line where the function was called.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{next}.
- @subsubheading Example
- @smallexample
- -exec-next
- ^running
- (gdb)
- *stopped,reason="end-stepping-range",line="8",file="hello.c"
- (gdb)
- @end smallexample
- @subheading The @code{-exec-next-instruction} Command
- @findex -exec-next-instruction
- @subsubheading Synopsis
- @smallexample
- -exec-next-instruction [--reverse]
- @end smallexample
- Executes one machine instruction. If the instruction is a function
- call, continues until the function returns. If the program stops at an
- instruction in the middle of a source line, the address will be
- printed as well.
- If the @samp{--reverse} option is specified, resumes reverse execution
- of the inferior program, stopping at the previous instruction. If the
- previously executed instruction was a return from another function,
- it will continue to execute in reverse until the call to that function
- (from the current stack frame) is reached.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{nexti}.
- @subsubheading Example
- @smallexample
- (gdb)
- -exec-next-instruction
- ^running
- (gdb)
- *stopped,reason="end-stepping-range",
- addr="0x000100d4",line="5",file="hello.c"
- (gdb)
- @end smallexample
- @subheading The @code{-exec-return} Command
- @findex -exec-return
- @subsubheading Synopsis
- @smallexample
- -exec-return
- @end smallexample
- Makes current function return immediately. Doesn't execute the inferior.
- Displays the new current frame.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{return}.
- @subsubheading Example
- @smallexample
- (gdb)
- 200-break-insert callee4
- 200^done,bkpt=@{number="1",addr="0x00010734",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
- (gdb)
- 000-exec-run
- 000^running
- (gdb)
- 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
- frame=@{func="callee4",args=[],
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
- arch="i386:x86_64"@}
- (gdb)
- 205-break-delete
- 205^done
- (gdb)
- 111-exec-return
- 111^done,frame=@{level="0",func="callee3",
- args=[@{name="strarg",
- value="0x11940 \"A string argument.\""@}],
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
- arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- @subheading The @code{-exec-run} Command
- @findex -exec-run
- @subsubheading Synopsis
- @smallexample
- -exec-run [ --all | --thread-group N ] [ --start ]
- @end smallexample
- Starts execution of the inferior from the beginning. The inferior
- executes until either a breakpoint is encountered or the program
- exits. In the latter case the output will include an exit code, if
- the program has exited exceptionally.
- When neither the @samp{--all} nor the @samp{--thread-group} option
- is specified, the current inferior is started. If the
- @samp{--thread-group} option is specified, it should refer to a thread
- group of type @samp{process}, and that thread group will be started.
- If the @samp{--all} option is specified, then all inferiors will be started.
- Using the @samp{--start} option instructs the debugger to stop
- the execution at the start of the inferior's main subprogram,
- following the same behavior as the @code{start} command
- (@pxref{Starting}).
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{run}.
- @subsubheading Examples
- @smallexample
- (gdb)
- -break-insert main
- ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
- (gdb)
- -exec-run
- ^running
- (gdb)
- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
- frame=@{func="main",args=[],file="recursive2.c",
- fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- @noindent
- Program exited normally:
- @smallexample
- (gdb)
- -exec-run
- ^running
- (gdb)
- x = 55
- *stopped,reason="exited-normally"
- (gdb)
- @end smallexample
- @noindent
- Program exited exceptionally:
- @smallexample
- (gdb)
- -exec-run
- ^running
- (gdb)
- x = 55
- *stopped,reason="exited",exit-code="01"
- (gdb)
- @end smallexample
- Another way the program can terminate is if it receives a signal such as
- @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
- @smallexample
- (gdb)
- *stopped,reason="exited-signalled",signal-name="SIGINT",
- signal-meaning="Interrupt"
- @end smallexample
- @c @subheading -exec-signal
- @subheading The @code{-exec-step} Command
- @findex -exec-step
- @subsubheading Synopsis
- @smallexample
- -exec-step [--reverse]
- @end smallexample
- Resumes execution of the inferior program, stopping when the beginning
- of the next source line is reached, if the next source line is not a
- function call. If it is, stop at the first instruction of the called
- function. If the @samp{--reverse} option is specified, resumes reverse
- execution of the inferior program, stopping at the beginning of the
- previously executed source line.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{step}.
- @subsubheading Example
- Stepping into a function:
- @smallexample
- -exec-step
- ^running
- (gdb)
- *stopped,reason="end-stepping-range",
- frame=@{func="foo",args=[@{name="a",value="10"@},
- @{name="b",value="0"@}],file="recursive2.c",
- fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- Regular stepping:
- @smallexample
- -exec-step
- ^running
- (gdb)
- *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
- (gdb)
- @end smallexample
- @subheading The @code{-exec-step-instruction} Command
- @findex -exec-step-instruction
- @subsubheading Synopsis
- @smallexample
- -exec-step-instruction [--reverse]
- @end smallexample
- Resumes the inferior which executes one machine instruction. If the
- @samp{--reverse} option is specified, resumes reverse execution of the
- inferior program, stopping at the previously executed instruction.
- The output, once @value{GDBN} has stopped, will vary depending on
- whether we have stopped in the middle of a source line or not. In the
- former case, the address at which the program stopped will be printed
- as well.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{stepi}.
- @subsubheading Example
- @smallexample
- (gdb)
- -exec-step-instruction
- ^running
- (gdb)
- *stopped,reason="end-stepping-range",
- frame=@{func="foo",args=[],file="try.c",
- fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@}
- (gdb)
- -exec-step-instruction
- ^running
- (gdb)
- *stopped,reason="end-stepping-range",
- frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
- fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- @subheading The @code{-exec-until} Command
- @findex -exec-until
- @subsubheading Synopsis
- @smallexample
- -exec-until [ @var{location} ]
- @end smallexample
- Executes the inferior until the @var{location} specified in the
- argument is reached. If there is no argument, the inferior executes
- until a source line greater than the current one is reached. The
- reason for stopping in this case will be @samp{location-reached}.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{until}.
- @subsubheading Example
- @smallexample
- (gdb)
- -exec-until recursive2.c:6
- ^running
- (gdb)
- x = 55
- *stopped,reason="location-reached",frame=@{func="main",args=[],
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6",
- arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- @ignore
- @subheading -file-clear
- Is this going away????
- @end ignore
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Stack Manipulation
- @section @sc{gdb/mi} Stack Manipulation Commands
- @subheading The @code{-enable-frame-filters} Command
- @findex -enable-frame-filters
- @smallexample
- -enable-frame-filters
- @end smallexample
- @value{GDBN} allows Python-based frame filters to affect the output of
- the MI commands relating to stack traces. As there is no way to
- implement this in a fully backward-compatible way, a front end must
- request that this functionality be enabled.
- Once enabled, this feature cannot be disabled.
- Note that if Python support has not been compiled into @value{GDBN},
- this command will still succeed (and do nothing).
- @subheading The @code{-stack-info-frame} Command
- @findex -stack-info-frame
- @subsubheading Synopsis
- @smallexample
- -stack-info-frame
- @end smallexample
- Get info on the selected frame.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
- (without arguments).
- @subsubheading Example
- @smallexample
- (gdb)
- -stack-info-frame
- ^done,frame=@{level="1",addr="0x0001076c",func="callee3",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17",
- arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- @subheading The @code{-stack-info-depth} Command
- @findex -stack-info-depth
- @subsubheading Synopsis
- @smallexample
- -stack-info-depth [ @var{max-depth} ]
- @end smallexample
- Return the depth of the stack. If the integer argument @var{max-depth}
- is specified, do not count beyond @var{max-depth} frames.
- @subsubheading @value{GDBN} Command
- There's no equivalent @value{GDBN} command.
- @subsubheading Example
- For a stack with frame levels 0 through 11:
- @smallexample
- (gdb)
- -stack-info-depth
- ^done,depth="12"
- (gdb)
- -stack-info-depth 4
- ^done,depth="4"
- (gdb)
- -stack-info-depth 12
- ^done,depth="12"
- (gdb)
- -stack-info-depth 11
- ^done,depth="11"
- (gdb)
- -stack-info-depth 13
- ^done,depth="12"
- (gdb)
- @end smallexample
- @anchor{-stack-list-arguments}
- @subheading The @code{-stack-list-arguments} Command
- @findex -stack-list-arguments
- @subsubheading Synopsis
- @smallexample
- -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
- [ @var{low-frame} @var{high-frame} ]
- @end smallexample
- Display a list of the arguments for the frames between @var{low-frame}
- and @var{high-frame} (inclusive). If @var{low-frame} and
- @var{high-frame} are not provided, list the arguments for the whole
- call stack. If the two arguments are equal, show the single frame
- at the corresponding level. It is an error if @var{low-frame} is
- larger than the actual number of frames. On the other hand,
- @var{high-frame} may be larger than the actual number of frames, in
- which case only existing frames will be returned.
- If @var{print-values} is 0 or @code{--no-values}, print only the names of
- the variables; if it is 1 or @code{--all-values}, print also their
- values; and if it is 2 or @code{--simple-values}, print the name,
- type and value for simple data types, and the name and type for arrays,
- structures and unions. If the option @code{--no-frame-filters} is
- supplied, then Python frame filters will not be executed.
- If the @code{--skip-unavailable} option is specified, arguments that
- are not available are not listed. Partially available arguments
- are still displayed, however.
- Use of this command to obtain arguments in a single frame is
- deprecated in favor of the @samp{-stack-list-variables} command.
- @subsubheading @value{GDBN} Command
- @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
- @samp{gdb_get_args} command which partially overlaps with the
- functionality of @samp{-stack-list-arguments}.
- @subsubheading Example
- @smallexample
- (gdb)
- -stack-list-frames
- ^done,
- stack=[
- frame=@{level="0",addr="0x00010734",func="callee4",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
- arch="i386:x86_64"@},
- frame=@{level="1",addr="0x0001076c",func="callee3",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17",
- arch="i386:x86_64"@},
- frame=@{level="2",addr="0x0001078c",func="callee2",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22",
- arch="i386:x86_64"@},
- frame=@{level="3",addr="0x000107b4",func="callee1",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27",
- arch="i386:x86_64"@},
- frame=@{level="4",addr="0x000107e0",func="main",
- file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
- fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32",
- arch="i386:x86_64"@}]
- (gdb)
- -stack-list-arguments 0
- ^done,
- stack-args=[
- frame=@{level="0",args=[]@},
- frame=@{level="1",args=[name="strarg"]@},
- frame=@{level="2",args=[name="intarg",name="strarg"]@},
- frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
- frame=@{level="4",args=[]@}]
- (gdb)
- -stack-list-arguments 1
- ^done,
- stack-args=[
- frame=@{level="0",args=[]@},
- frame=@{level="1",
- args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
- frame=@{level="2",args=[
- @{name="intarg",value="2"@},
- @{name="strarg",value="0x11940 \"A string argument.\""@}]@},
- @{frame=@{level="3",args=[
- @{name="intarg",value="2"@},
- @{name="strarg",value="0x11940 \"A string argument.\""@},
- @{name="fltarg",value="3.5"@}]@},
- frame=@{level="4",args=[]@}]
- (gdb)
- -stack-list-arguments 0 2 2
- ^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
- (gdb)
- -stack-list-arguments 1 2 2
- ^done,stack-args=[frame=@{level="2",
- args=[@{name="intarg",value="2"@},
- @{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
- (gdb)
- @end smallexample
- @c @subheading -stack-list-exception-handlers
- @anchor{-stack-list-frames}
- @subheading The @code{-stack-list-frames} Command
- @findex -stack-list-frames
- @subsubheading Synopsis
- @smallexample
- -stack-list-frames [ --no-frame-filters @var{low-frame} @var{high-frame} ]
- @end smallexample
- List the frames currently on the stack. For each frame it displays the
- following info:
- @table @samp
- @item @var{level}
- The frame number, 0 being the topmost frame, i.e., the innermost function.
- @item @var{addr}
- The @code{$pc} value for that frame.
- @item @var{func}
- Function name.
- @item @var{file}
- File name of the source file where the function lives.
- @item @var{fullname}
- The full file name of the source file where the function lives.
- @item @var{line}
- Line number corresponding to the @code{$pc}.
- @item @var{from}
- The shared library where this function is defined. This is only given
- if the frame's function is not known.
- @item @var{arch}
- Frame's architecture.
- @end table
- If invoked without arguments, this command prints a backtrace for the
- whole stack. If given two integer arguments, it shows the frames whose
- levels are between the two arguments (inclusive). If the two arguments
- are equal, it shows the single frame at the corresponding level. It is
- an error if @var{low-frame} is larger than the actual number of
- frames. On the other hand, @var{high-frame} may be larger than the
- actual number of frames, in which case only existing frames will be
- returned. If the option @code{--no-frame-filters} is supplied, then
- Python frame filters will not be executed.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
- @subsubheading Example
- Full stack backtrace:
- @smallexample
- (gdb)
- -stack-list-frames
- ^done,stack=
- [frame=@{level="0",addr="0x0001076c",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11",
- arch="i386:x86_64"@},
- frame=@{level="1",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="2",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="6",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="7",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="8",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="9",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="10",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="11",addr="0x00010738",func="main",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4",
- arch="i386:x86_64"@}]
- (gdb)
- @end smallexample
- Show frames between @var{low_frame} and @var{high_frame}:
- @smallexample
- (gdb)
- -stack-list-frames 3 5
- ^done,stack=
- [frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@},
- frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@}]
- (gdb)
- @end smallexample
- Show a single frame:
- @smallexample
- (gdb)
- -stack-list-frames 3 3
- ^done,stack=
- [frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
- arch="i386:x86_64"@}]
- (gdb)
- @end smallexample
- @subheading The @code{-stack-list-locals} Command
- @findex -stack-list-locals
- @anchor{-stack-list-locals}
- @subsubheading Synopsis
- @smallexample
- -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
- @end smallexample
- Display the local variable names for the selected frame. If
- @var{print-values} is 0 or @code{--no-values}, print only the names of
- the variables; if it is 1 or @code{--all-values}, print also their
- values; and if it is 2 or @code{--simple-values}, print the name,
- type and value for simple data types, and the name and type for arrays,
- structures and unions. In this last case, a frontend can immediately
- display the value of simple data types and create variable objects for
- other data types when the user wishes to explore their values in
- more detail. If the option @code{--no-frame-filters} is supplied, then
- Python frame filters will not be executed.
- If the @code{--skip-unavailable} option is specified, local variables
- that are not available are not listed. Partially available local
- variables are still displayed, however.
- This command is deprecated in favor of the
- @samp{-stack-list-variables} command.
- @subsubheading @value{GDBN} Command
- @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
- @subsubheading Example
- @smallexample
- (gdb)
- -stack-list-locals 0
- ^done,locals=[name="A",name="B",name="C"]
- (gdb)
- -stack-list-locals --all-values
- ^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
- @{name="C",value="@{1, 2, 3@}"@}]
- -stack-list-locals --simple-values
- ^done,locals=[@{name="A",type="int",value="1"@},
- @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
- (gdb)
- @end smallexample
- @anchor{-stack-list-variables}
- @subheading The @code{-stack-list-variables} Command
- @findex -stack-list-variables
- @subsubheading Synopsis
- @smallexample
- -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
- @end smallexample
- Display the names of local variables and function arguments for the selected frame. If
- @var{print-values} is 0 or @code{--no-values}, print only the names of
- the variables; if it is 1 or @code{--all-values}, print also their
- values; and if it is 2 or @code{--simple-values}, print the name,
- type and value for simple data types, and the name and type for arrays,
- structures and unions. If the option @code{--no-frame-filters} is
- supplied, then Python frame filters will not be executed.
- If the @code{--skip-unavailable} option is specified, local variables
- and arguments that are not available are not listed. Partially
- available arguments and local variables are still displayed, however.
- @subsubheading Example
- @smallexample
- (gdb)
- -stack-list-variables --thread 1 --frame 0 --all-values
- ^done,variables=[@{name="x",value="11"@},@{name="s",value="@{a = 1, b = 2@}"@}]
- (gdb)
- @end smallexample
- @subheading The @code{-stack-select-frame} Command
- @findex -stack-select-frame
- @subsubheading Synopsis
- @smallexample
- -stack-select-frame @var{framenum}
- @end smallexample
- Change the selected frame. Select a different frame @var{framenum} on
- the stack.
- This command in deprecated in favor of passing the @samp{--frame}
- option to every command.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
- @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
- @subsubheading Example
- @smallexample
- (gdb)
- -stack-select-frame 2
- ^done
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Variable Objects
- @section @sc{gdb/mi} Variable Objects
- @ignore
- @subheading Motivation for Variable Objects in @sc{gdb/mi}
- For the implementation of a variable debugger window (locals, watched
- expressions, etc.), we are proposing the adaptation of the existing code
- used by @code{Insight}.
- The two main reasons for that are:
- @enumerate 1
- @item
- It has been proven in practice (it is already on its second generation).
- @item
- It will shorten development time (needless to say how important it is
- now).
- @end enumerate
- The original interface was designed to be used by Tcl code, so it was
- slightly changed so it could be used through @sc{gdb/mi}. This section
- describes the @sc{gdb/mi} operations that will be available and gives some
- hints about their use.
- @emph{Note}: In addition to the set of operations described here, we
- expect the @sc{gui} implementation of a variable window to require, at
- least, the following operations:
- @itemize @bullet
- @item @code{-gdb-show} @code{output-radix}
- @item @code{-stack-list-arguments}
- @item @code{-stack-list-locals}
- @item @code{-stack-select-frame}
- @end itemize
- @end ignore
- @subheading Introduction to Variable Objects
- @cindex variable objects in @sc{gdb/mi}
- Variable objects are "object-oriented" MI interface for examining and
- changing values of expressions. Unlike some other MI interfaces that
- work with expressions, variable objects are specifically designed for
- simple and efficient presentation in the frontend. A variable object
- is identified by string name. When a variable object is created, the
- frontend specifies the expression for that variable object. The
- expression can be a simple variable, or it can be an arbitrary complex
- expression, and can even involve CPU registers. After creating a
- variable object, the frontend can invoke other variable object
- operations---for example to obtain or change the value of a variable
- object, or to change display format.
- Variable objects have hierarchical tree structure. Any variable object
- that corresponds to a composite type, such as structure in C, has
- a number of child variable objects, for example corresponding to each
- element of a structure. A child variable object can itself have
- children, recursively. Recursion ends when we reach
- leaf variable objects, which always have built-in types. Child variable
- objects are created only by explicit request, so if a frontend
- is not interested in the children of a particular variable object, no
- child will be created.
- For a leaf variable object it is possible to obtain its value as a
- string, or set the value from a string. String value can be also
- obtained for a non-leaf variable object, but it's generally a string
- that only indicates the type of the object, and does not list its
- contents. Assignment to a non-leaf variable object is not allowed.
-
- A frontend does not need to read the values of all variable objects each time
- the program stops. Instead, MI provides an update command that lists all
- variable objects whose values has changed since the last update
- operation. This considerably reduces the amount of data that must
- be transferred to the frontend. As noted above, children variable
- objects are created on demand, and only leaf variable objects have a
- real value. As result, gdb will read target memory only for leaf
- variables that frontend has created.
- The automatic update is not always desirable. For example, a frontend
- might want to keep a value of some expression for future reference,
- and never update it. For another example, fetching memory is
- relatively slow for embedded targets, so a frontend might want
- to disable automatic update for the variables that are either not
- visible on the screen, or ``closed''. This is possible using so
- called ``frozen variable objects''. Such variable objects are never
- implicitly updated.
- Variable objects can be either @dfn{fixed} or @dfn{floating}. For the
- fixed variable object, the expression is parsed when the variable
- object is created, including associating identifiers to specific
- variables. The meaning of expression never changes. For a floating
- variable object the values of variables whose names appear in the
- expressions are re-evaluated every time in the context of the current
- frame. Consider this example:
- @smallexample
- void do_work(...)
- @{
- struct work_state state;
- if (...)
- do_work(...);
- @}
- @end smallexample
- If a fixed variable object for the @code{state} variable is created in
- this function, and we enter the recursive call, the variable
- object will report the value of @code{state} in the top-level
- @code{do_work} invocation. On the other hand, a floating variable
- object will report the value of @code{state} in the current frame.
- If an expression specified when creating a fixed variable object
- refers to a local variable, the variable object becomes bound to the
- thread and frame in which the variable object is created. When such
- variable object is updated, @value{GDBN} makes sure that the
- thread/frame combination the variable object is bound to still exists,
- and re-evaluates the variable object in context of that thread/frame.
- The following is the complete set of @sc{gdb/mi} operations defined to
- access this functionality:
- @multitable @columnfractions .4 .6
- @item @strong{Operation}
- @tab @strong{Description}
- @item @code{-enable-pretty-printing}
- @tab enable Python-based pretty-printing
- @item @code{-var-create}
- @tab create a variable object
- @item @code{-var-delete}
- @tab delete the variable object and/or its children
- @item @code{-var-set-format}
- @tab set the display format of this variable
- @item @code{-var-show-format}
- @tab show the display format of this variable
- @item @code{-var-info-num-children}
- @tab tells how many children this object has
- @item @code{-var-list-children}
- @tab return a list of the object's children
- @item @code{-var-info-type}
- @tab show the type of this variable object
- @item @code{-var-info-expression}
- @tab print parent-relative expression that this variable object represents
- @item @code{-var-info-path-expression}
- @tab print full expression that this variable object represents
- @item @code{-var-show-attributes}
- @tab is this variable editable? does it exist here?
- @item @code{-var-evaluate-expression}
- @tab get the value of this variable
- @item @code{-var-assign}
- @tab set the value of this variable
- @item @code{-var-update}
- @tab update the variable and its children
- @item @code{-var-set-frozen}
- @tab set frozenness attribute
- @item @code{-var-set-update-range}
- @tab set range of children to display on update
- @end multitable
- In the next subsection we describe each operation in detail and suggest
- how it can be used.
- @subheading Description And Use of Operations on Variable Objects
- @subheading The @code{-enable-pretty-printing} Command
- @findex -enable-pretty-printing
- @smallexample
- -enable-pretty-printing
- @end smallexample
- @value{GDBN} allows Python-based visualizers to affect the output of the
- MI variable object commands. However, because there was no way to
- implement this in a fully backward-compatible way, a front end must
- request that this functionality be enabled.
- Once enabled, this feature cannot be disabled.
- Note that if Python support has not been compiled into @value{GDBN},
- this command will still succeed (and do nothing).
- This feature is currently (as of @value{GDBN} 7.0) experimental, and
- may work differently in future versions of @value{GDBN}.
- @subheading The @code{-var-create} Command
- @findex -var-create
- @subsubheading Synopsis
- @smallexample
- -var-create @{@var{name} | "-"@}
- @{@var{frame-addr} | "*" | "@@"@} @var{expression}
- @end smallexample
- This operation creates a variable object, which allows the monitoring of
- a variable, the result of an expression, a memory cell or a CPU
- register.
- The @var{name} parameter is the string by which the object can be
- referenced. It must be unique. If @samp{-} is specified, the varobj
- system will generate a string ``varNNNNNN'' automatically. It will be
- unique provided that one does not specify @var{name} of that format.
- The command fails if a duplicate name is found.
- The frame under which the expression should be evaluated can be
- specified by @var{frame-addr}. A @samp{*} indicates that the current
- frame should be used. A @samp{@@} indicates that a floating variable
- object must be created.
- @var{expression} is any expression valid on the current language set (must not
- begin with a @samp{*}), or one of the following:
- @itemize @bullet
- @item
- @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
- @item
- @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
- @item
- @samp{$@var{regname}} --- a CPU register name
- @end itemize
- @cindex dynamic varobj
- A varobj's contents may be provided by a Python-based pretty-printer. In this
- case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs
- have slightly different semantics in some cases. If the
- @code{-enable-pretty-printing} command is not sent, then @value{GDBN}
- will never create a dynamic varobj. This ensures backward
- compatibility for existing clients.
- @subsubheading Result
- This operation returns attributes of the newly-created varobj. These
- are:
- @table @samp
- @item name
- The name of the varobj.
- @item numchild
- The number of children of the varobj. This number is not necessarily
- reliable for a dynamic varobj. Instead, you must examine the
- @samp{has_more} attribute.
- @item value
- The varobj's scalar value. For a varobj whose type is some sort of
- aggregate (e.g., a @code{struct}), or for a dynamic varobj, this value
- will not be interesting.
- @item type
- The varobj's type. This is a string representation of the type, as
- would be printed by the @value{GDBN} CLI. If @samp{print object}
- (@pxref{Print Settings, set print object}) is set to @code{on}, the
- @emph{actual} (derived) type of the object is shown rather than the
- @emph{declared} one.
- @item thread-id
- If a variable object is bound to a specific thread, then this is the
- thread's global identifier.
- @item has_more
- For a dynamic varobj, this indicates whether there appear to be any
- children available. For a non-dynamic varobj, this will be 0.
- @item dynamic
- This attribute will be present and have the value @samp{1} if the
- varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
- then this attribute will not be present.
- @item displayhint
- A dynamic varobj can supply a display hint to the front end. The
- value comes directly from the Python pretty-printer object's
- @code{display_hint} method. @xref{Pretty Printing API}.
- @end table
- Typical output will look like this:
- @smallexample
- name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}",
- has_more="@var{has_more}"
- @end smallexample
- @subheading The @code{-var-delete} Command
- @findex -var-delete
- @subsubheading Synopsis
- @smallexample
- -var-delete [ -c ] @var{name}
- @end smallexample
- Deletes a previously created variable object and all of its children.
- With the @samp{-c} option, just deletes the children.
- Returns an error if the object @var{name} is not found.
- @subheading The @code{-var-set-format} Command
- @findex -var-set-format
- @subsubheading Synopsis
- @smallexample
- -var-set-format @var{name} @var{format-spec}
- @end smallexample
- Sets the output format for the value of the object @var{name} to be
- @var{format-spec}.
- @anchor{-var-set-format}
- The syntax for the @var{format-spec} is as follows:
- @smallexample
- @var{format-spec} @expansion{}
- @{binary | decimal | hexadecimal | octal | natural | zero-hexadecimal@}
- @end smallexample
- The natural format is the default format choosen automatically
- based on the variable type (like decimal for an @code{int}, hex
- for pointers, etc.).
- The zero-hexadecimal format has a representation similar to hexadecimal
- but with padding zeroes to the left of the value. For example, a 32-bit
- hexadecimal value of 0x1234 would be represented as 0x00001234 in the
- zero-hexadecimal format.
- For a variable with children, the format is set only on the
- variable itself, and the children are not affected.
- @subheading The @code{-var-show-format} Command
- @findex -var-show-format
- @subsubheading Synopsis
- @smallexample
- -var-show-format @var{name}
- @end smallexample
- Returns the format used to display the value of the object @var{name}.
- @smallexample
- @var{format} @expansion{}
- @var{format-spec}
- @end smallexample
- @subheading The @code{-var-info-num-children} Command
- @findex -var-info-num-children
- @subsubheading Synopsis
- @smallexample
- -var-info-num-children @var{name}
- @end smallexample
- Returns the number of children of a variable object @var{name}:
- @smallexample
- numchild=@var{n}
- @end smallexample
- Note that this number is not completely reliable for a dynamic varobj.
- It will return the current number of children, but more children may
- be available.
- @subheading The @code{-var-list-children} Command
- @findex -var-list-children
- @subsubheading Synopsis
- @smallexample
- -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
- @end smallexample
- @anchor{-var-list-children}
- Return a list of the children of the specified variable object and
- create variable objects for them, if they do not already exist. With
- a single argument or if @var{print-values} has a value of 0 or
- @code{--no-values}, print only the names of the variables; if
- @var{print-values} is 1 or @code{--all-values}, also print their
- values; and if it is 2 or @code{--simple-values} print the name and
- value for simple data types and just the name for arrays, structures
- and unions.
- @var{from} and @var{to}, if specified, indicate the range of children
- to report. If @var{from} or @var{to} is less than zero, the range is
- reset and all children will be reported. Otherwise, children starting
- at @var{from} (zero-based) and up to and excluding @var{to} will be
- reported.
- If a child range is requested, it will only affect the current call to
- @code{-var-list-children}, but not future calls to @code{-var-update}.
- For this, you must instead use @code{-var-set-update-range}. The
- intent of this approach is to enable a front end to implement any
- update approach it likes; for example, scrolling a view may cause the
- front end to request more children with @code{-var-list-children}, and
- then the front end could call @code{-var-set-update-range} with a
- different range to ensure that future updates are restricted to just
- the visible items.
- For each child the following results are returned:
- @table @var
- @item name
- Name of the variable object created for this child.
- @item exp
- The expression to be shown to the user by the front end to designate this child.
- For example this may be the name of a structure member.
- For a dynamic varobj, this value cannot be used to form an
- expression. There is no way to do this at all with a dynamic varobj.
- For C/C@t{++} structures there are several pseudo children returned to
- designate access qualifiers. For these pseudo children @var{exp} is
- @samp{public}, @samp{private}, or @samp{protected}. In this case the
- type and value are not present.
- A dynamic varobj will not report the access qualifying
- pseudo-children, regardless of the language. This information is not
- available at all with a dynamic varobj.
- @item numchild
- Number of children this child has. For a dynamic varobj, this will be
- 0.
- @item type
- The type of the child. If @samp{print object}
- (@pxref{Print Settings, set print object}) is set to @code{on}, the
- @emph{actual} (derived) type of the object is shown rather than the
- @emph{declared} one.
- @item value
- If values were requested, this is the value.
- @item thread-id
- If this variable object is associated with a thread, this is the
- thread's global thread id. Otherwise this result is not present.
- @item frozen
- If the variable object is frozen, this variable will be present with a value of 1.
- @item displayhint
- A dynamic varobj can supply a display hint to the front end. The
- value comes directly from the Python pretty-printer object's
- @code{display_hint} method. @xref{Pretty Printing API}.
- @item dynamic
- This attribute will be present and have the value @samp{1} if the
- varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
- then this attribute will not be present.
- @end table
- The result may have its own attributes:
- @table @samp
- @item displayhint
- A dynamic varobj can supply a display hint to the front end. The
- value comes directly from the Python pretty-printer object's
- @code{display_hint} method. @xref{Pretty Printing API}.
- @item has_more
- This is an integer attribute which is nonzero if there are children
- remaining after the end of the selected range.
- @end table
- @subsubheading Example
- @smallexample
- (gdb)
- -var-list-children n
- ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
- numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
- (gdb)
- -var-list-children --all-values n
- ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
- numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
- @end smallexample
- @subheading The @code{-var-info-type} Command
- @findex -var-info-type
- @subsubheading Synopsis
- @smallexample
- -var-info-type @var{name}
- @end smallexample
- Returns the type of the specified variable @var{name}. The type is
- returned as a string in the same format as it is output by the
- @value{GDBN} CLI:
- @smallexample
- type=@var{typename}
- @end smallexample
- @subheading The @code{-var-info-expression} Command
- @findex -var-info-expression
- @subsubheading Synopsis
- @smallexample
- -var-info-expression @var{name}
- @end smallexample
- Returns a string that is suitable for presenting this
- variable object in user interface. The string is generally
- not valid expression in the current language, and cannot be evaluated.
- For example, if @code{a} is an array, and variable object
- @code{A} was created for @code{a}, then we'll get this output:
- @smallexample
- (gdb) -var-info-expression A.1
- ^done,lang="C",exp="1"
- @end smallexample
- @noindent
- Here, the value of @code{lang} is the language name, which can be
- found in @ref{Supported Languages}.
- Note that the output of the @code{-var-list-children} command also
- includes those expressions, so the @code{-var-info-expression} command
- is of limited use.
- @subheading The @code{-var-info-path-expression} Command
- @findex -var-info-path-expression
- @subsubheading Synopsis
- @smallexample
- -var-info-path-expression @var{name}
- @end smallexample
- Returns an expression that can be evaluated in the current
- context and will yield the same value that a variable object has.
- Compare this with the @code{-var-info-expression} command, which
- result can be used only for UI presentation. Typical use of
- the @code{-var-info-path-expression} command is creating a
- watchpoint from a variable object.
- This command is currently not valid for children of a dynamic varobj,
- and will give an error when invoked on one.
- For example, suppose @code{C} is a C@t{++} class, derived from class
- @code{Base}, and that the @code{Base} class has a member called
- @code{m_size}. Assume a variable @code{c} is has the type of
- @code{C} and a variable object @code{C} was created for variable
- @code{c}. Then, we'll get this output:
- @smallexample
- (gdb) -var-info-path-expression C.Base.public.m_size
- ^done,path_expr=((Base)c).m_size)
- @end smallexample
- @subheading The @code{-var-show-attributes} Command
- @findex -var-show-attributes
- @subsubheading Synopsis
- @smallexample
- -var-show-attributes @var{name}
- @end smallexample
- List attributes of the specified variable object @var{name}:
- @smallexample
- status=@var{attr} [ ( ,@var{attr} )* ]
- @end smallexample
- @noindent
- where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
- @subheading The @code{-var-evaluate-expression} Command
- @findex -var-evaluate-expression
- @subsubheading Synopsis
- @smallexample
- -var-evaluate-expression [-f @var{format-spec}] @var{name}
- @end smallexample
- Evaluates the expression that is represented by the specified variable
- object and returns its value as a string. The format of the string
- can be specified with the @samp{-f} option. The possible values of
- this option are the same as for @code{-var-set-format}
- (@pxref{-var-set-format}). If the @samp{-f} option is not specified,
- the current display format will be used. The current display format
- can be changed using the @code{-var-set-format} command.
- @smallexample
- value=@var{value}
- @end smallexample
- Note that one must invoke @code{-var-list-children} for a variable
- before the value of a child variable can be evaluated.
- @subheading The @code{-var-assign} Command
- @findex -var-assign
- @subsubheading Synopsis
- @smallexample
- -var-assign @var{name} @var{expression}
- @end smallexample
- Assigns the value of @var{expression} to the variable object specified
- by @var{name}. The object must be @samp{editable}. If the variable's
- value is altered by the assign, the variable will show up in any
- subsequent @code{-var-update} list.
- @subsubheading Example
- @smallexample
- (gdb)
- -var-assign var1 3
- ^done,value="3"
- (gdb)
- -var-update *
- ^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
- (gdb)
- @end smallexample
- @subheading The @code{-var-update} Command
- @findex -var-update
- @subsubheading Synopsis
- @smallexample
- -var-update [@var{print-values}] @{@var{name} | "*"@}
- @end smallexample
- Reevaluate the expressions corresponding to the variable object
- @var{name} and all its direct and indirect children, and return the
- list of variable objects whose values have changed; @var{name} must
- be a root variable object. Here, ``changed'' means that the result of
- @code{-var-evaluate-expression} before and after the
- @code{-var-update} is different. If @samp{*} is used as the variable
- object names, all existing variable objects are updated, except
- for frozen ones (@pxref{-var-set-frozen}). The option
- @var{print-values} determines whether both names and values, or just
- names are printed. The possible values of this option are the same
- as for @code{-var-list-children} (@pxref{-var-list-children}). It is
- recommended to use the @samp{--all-values} option, to reduce the
- number of MI commands needed on each program stop.
- With the @samp{*} parameter, if a variable object is bound to a
- currently running thread, it will not be updated, without any
- diagnostic.
- If @code{-var-set-update-range} was previously used on a varobj, then
- only the selected range of children will be reported.
- @code{-var-update} reports all the changed varobjs in a tuple named
- @samp{changelist}.
- Each item in the change list is itself a tuple holding:
- @table @samp
- @item name
- The name of the varobj.
- @item value
- If values were requested for this update, then this field will be
- present and will hold the value of the varobj.
- @item in_scope
- @anchor{-var-update}
- This field is a string which may take one of three values:
- @table @code
- @item "true"
- The variable object's current value is valid.
- @item "false"
- The variable object does not currently hold a valid value but it may
- hold one in the future if its associated expression comes back into
- scope.
- @item "invalid"
- The variable object no longer holds a valid value.
- This can occur when the executable file being debugged has changed,
- either through recompilation or by using the @value{GDBN} @code{file}
- command. The front end should normally choose to delete these variable
- objects.
- @end table
- In the future new values may be added to this list so the front should
- be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}.
- @item type_changed
- This is only present if the varobj is still valid. If the type
- changed, then this will be the string @samp{true}; otherwise it will
- be @samp{false}.
- When a varobj's type changes, its children are also likely to have
- become incorrect. Therefore, the varobj's children are automatically
- deleted when this attribute is @samp{true}. Also, the varobj's update
- range, when set using the @code{-var-set-update-range} command, is
- unset.
- @item new_type
- If the varobj's type changed, then this field will be present and will
- hold the new type.
- @item new_num_children
- For a dynamic varobj, if the number of children changed, or if the
- type changed, this will be the new number of children.
- The @samp{numchild} field in other varobj responses is generally not
- valid for a dynamic varobj -- it will show the number of children that
- @value{GDBN} knows about, but because dynamic varobjs lazily
- instantiate their children, this will not reflect the number of
- children which may be available.
- The @samp{new_num_children} attribute only reports changes to the
- number of children known by @value{GDBN}. This is the only way to
- detect whether an update has removed children (which necessarily can
- only happen at the end of the update range).
- @item displayhint
- The display hint, if any.
- @item has_more
- This is an integer value, which will be 1 if there are more children
- available outside the varobj's update range.
- @item dynamic
- This attribute will be present and have the value @samp{1} if the
- varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
- then this attribute will not be present.
- @item new_children
- If new children were added to a dynamic varobj within the selected
- update range (as set by @code{-var-set-update-range}), then they will
- be listed in this attribute.
- @end table
- @subsubheading Example
- @smallexample
- (gdb)
- -var-assign var1 3
- ^done,value="3"
- (gdb)
- -var-update --all-values var1
- ^done,changelist=[@{name="var1",value="3",in_scope="true",
- type_changed="false"@}]
- (gdb)
- @end smallexample
- @subheading The @code{-var-set-frozen} Command
- @findex -var-set-frozen
- @anchor{-var-set-frozen}
- @subsubheading Synopsis
- @smallexample
- -var-set-frozen @var{name} @var{flag}
- @end smallexample
- Set the frozenness flag on the variable object @var{name}. The
- @var{flag} parameter should be either @samp{1} to make the variable
- frozen or @samp{0} to make it unfrozen. If a variable object is
- frozen, then neither itself, nor any of its children, are
- implicitly updated by @code{-var-update} of
- a parent variable or by @code{-var-update *}. Only
- @code{-var-update} of the variable itself will update its value and
- values of its children. After a variable object is unfrozen, it is
- implicitly updated by all subsequent @code{-var-update} operations.
- Unfreezing a variable does not update it, only subsequent
- @code{-var-update} does.
- @subsubheading Example
- @smallexample
- (gdb)
- -var-set-frozen V 1
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-var-set-update-range} command
- @findex -var-set-update-range
- @anchor{-var-set-update-range}
- @subsubheading Synopsis
- @smallexample
- -var-set-update-range @var{name} @var{from} @var{to}
- @end smallexample
- Set the range of children to be returned by future invocations of
- @code{-var-update}.
- @var{from} and @var{to} indicate the range of children to report. If
- @var{from} or @var{to} is less than zero, the range is reset and all
- children will be reported. Otherwise, children starting at @var{from}
- (zero-based) and up to and excluding @var{to} will be reported.
- @subsubheading Example
- @smallexample
- (gdb)
- -var-set-update-range V 1 2
- ^done
- @end smallexample
- @subheading The @code{-var-set-visualizer} command
- @findex -var-set-visualizer
- @anchor{-var-set-visualizer}
- @subsubheading Synopsis
- @smallexample
- -var-set-visualizer @var{name} @var{visualizer}
- @end smallexample
- Set a visualizer for the variable object @var{name}.
- @var{visualizer} is the visualizer to use. The special value
- @samp{None} means to disable any visualizer in use.
- If not @samp{None}, @var{visualizer} must be a Python expression.
- This expression must evaluate to a callable object which accepts a
- single argument. @value{GDBN} will call this object with the value of
- the varobj @var{name} as an argument (this is done so that the same
- Python pretty-printing code can be used for both the CLI and MI).
- When called, this object must return an object which conforms to the
- pretty-printing interface (@pxref{Pretty Printing API}).
- The pre-defined function @code{gdb.default_visualizer} may be used to
- select a visualizer by following the built-in process
- (@pxref{Selecting Pretty-Printers}). This is done automatically when
- a varobj is created, and so ordinarily is not needed.
- This feature is only available if Python support is enabled. The MI
- command @code{-list-features} (@pxref{GDB/MI Support Commands})
- can be used to check this.
- @subsubheading Example
- Resetting the visualizer:
- @smallexample
- (gdb)
- -var-set-visualizer V None
- ^done
- @end smallexample
- Reselecting the default (type-based) visualizer:
- @smallexample
- (gdb)
- -var-set-visualizer V gdb.default_visualizer
- ^done
- @end smallexample
- Suppose @code{SomeClass} is a visualizer class. A lambda expression
- can be used to instantiate this class for a varobj:
- @smallexample
- (gdb)
- -var-set-visualizer V "lambda val: SomeClass()"
- ^done
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Data Manipulation
- @section @sc{gdb/mi} Data Manipulation
- @cindex data manipulation, in @sc{gdb/mi}
- @cindex @sc{gdb/mi}, data manipulation
- This section describes the @sc{gdb/mi} commands that manipulate data:
- examine memory and registers, evaluate expressions, etc.
- For details about what an addressable memory unit is,
- @pxref{addressable memory unit}.
- @c REMOVED FROM THE INTERFACE.
- @c @subheading -data-assign
- @c Change the value of a program variable. Plenty of side effects.
- @c @subsubheading GDB Command
- @c set variable
- @c @subsubheading Example
- @c N.A.
- @subheading The @code{-data-disassemble} Command
- @findex -data-disassemble
- @subsubheading Synopsis
- @smallexample
- -data-disassemble
- [ -s @var{start-addr} -e @var{end-addr} ]
- | [ -a @var{addr} ]
- | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
- -- @var{mode}
- @end smallexample
- @noindent
- Where:
- @table @samp
- @item @var{start-addr}
- is the beginning address (or @code{$pc})
- @item @var{end-addr}
- is the end address
- @item @var{addr}
- is an address anywhere within (or the name of) the function to
- disassemble. If an address is specified, the whole function
- surrounding that address will be disassembled. If a name is
- specified, the whole function with that name will be disassembled.
- @item @var{filename}
- is the name of the file to disassemble
- @item @var{linenum}
- is the line number to disassemble around
- @item @var{lines}
- is the number of disassembly lines to be produced. If it is -1,
- the whole function will be disassembled, in case no @var{end-addr} is
- specified. If @var{end-addr} is specified as a non-zero value, and
- @var{lines} is lower than the number of disassembly lines between
- @var{start-addr} and @var{end-addr}, only @var{lines} lines are
- displayed; if @var{lines} is higher than the number of lines between
- @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
- are displayed.
- @item @var{mode}
- is one of:
- @itemize @bullet
- @item 0 disassembly only
- @item 1 mixed source and disassembly (deprecated)
- @item 2 disassembly with raw opcodes
- @item 3 mixed source and disassembly with raw opcodes (deprecated)
- @item 4 mixed source and disassembly
- @item 5 mixed source and disassembly with raw opcodes
- @end itemize
- Modes 1 and 3 are deprecated. The output is ``source centric''
- which hasn't proved useful in practice.
- @xref{Machine Code}, for a discussion of the difference between
- @code{/m} and @code{/s} output of the @code{disassemble} command.
- @end table
- @subsubheading Result
- The result of the @code{-data-disassemble} command will be a list named
- @samp{asm_insns}, the contents of this list depend on the @var{mode}
- used with the @code{-data-disassemble} command.
- For modes 0 and 2 the @samp{asm_insns} list contains tuples with the
- following fields:
- @table @code
- @item address
- The address at which this instruction was disassembled.
- @item func-name
- The name of the function this instruction is within.
- @item offset
- The decimal offset in bytes from the start of @samp{func-name}.
- @item inst
- The text disassembly for this @samp{address}.
- @item opcodes
- This field is only present for modes 2, 3 and 5. This contains the raw opcode
- bytes for the @samp{inst} field.
- @end table
- For modes 1, 3, 4 and 5 the @samp{asm_insns} list contains tuples named
- @samp{src_and_asm_line}, each of which has the following fields:
- @table @code
- @item line
- The line number within @samp{file}.
- @item file
- The file name from the compilation unit. This might be an absolute
- file name or a relative file name depending on the compile command
- used.
- @item fullname
- Absolute file name of @samp{file}. It is converted to a canonical form
- using the source file search path
- (@pxref{Source Path, ,Specifying Source Directories})
- and after resolving all the symbolic links.
- If the source file is not found this field will contain the path as
- present in the debug information.
- @item line_asm_insn
- This is a list of tuples containing the disassembly for @samp{line} in
- @samp{file}. The fields of each tuple are the same as for
- @code{-data-disassemble} in @var{mode} 0 and 2, so @samp{address},
- @samp{func-name}, @samp{offset}, @samp{inst}, and optionally
- @samp{opcodes}.
- @end table
- Note that whatever included in the @samp{inst} field, is not
- manipulated directly by @sc{gdb/mi}, i.e., it is not possible to
- adjust its format.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{disassemble}.
- @subsubheading Example
- Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
- @smallexample
- (gdb)
- -data-disassemble -s $pc -e "$pc + 20" -- 0
- ^done,
- asm_insns=[
- @{address="0x000107c0",func-name="main",offset="4",
- inst="mov 2, %o0"@},
- @{address="0x000107c4",func-name="main",offset="8",
- inst="sethi %hi(0x11800), %o2"@},
- @{address="0x000107c8",func-name="main",offset="12",
- inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
- @{address="0x000107cc",func-name="main",offset="16",
- inst="sethi %hi(0x11800), %o2"@},
- @{address="0x000107d0",func-name="main",offset="20",
- inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
- (gdb)
- @end smallexample
- Disassemble the whole @code{main} function. Line 32 is part of
- @code{main}.
- @smallexample
- -data-disassemble -f basics.c -l 32 -- 0
- ^done,asm_insns=[
- @{address="0x000107bc",func-name="main",offset="0",
- inst="save %sp, -112, %sp"@},
- @{address="0x000107c0",func-name="main",offset="4",
- inst="mov 2, %o0"@},
- @{address="0x000107c4",func-name="main",offset="8",
- inst="sethi %hi(0x11800), %o2"@},
- [@dots{}]
- @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
- @{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
- (gdb)
- @end smallexample
- Disassemble 3 instructions from the start of @code{main}:
- @smallexample
- (gdb)
- -data-disassemble -f basics.c -l 32 -n 3 -- 0
- ^done,asm_insns=[
- @{address="0x000107bc",func-name="main",offset="0",
- inst="save %sp, -112, %sp"@},
- @{address="0x000107c0",func-name="main",offset="4",
- inst="mov 2, %o0"@},
- @{address="0x000107c4",func-name="main",offset="8",
- inst="sethi %hi(0x11800), %o2"@}]
- (gdb)
- @end smallexample
- Disassemble 3 instructions from the start of @code{main} in mixed mode:
- @smallexample
- (gdb)
- -data-disassemble -f basics.c -l 32 -n 3 -- 1
- ^done,asm_insns=[
- src_and_asm_line=@{line="31",
- file="../../../src/gdb/testsuite/gdb.mi/basics.c",
- fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
- line_asm_insn=[@{address="0x000107bc",
- func-name="main",offset="0",inst="save %sp, -112, %sp"@}]@},
- src_and_asm_line=@{line="32",
- file="../../../src/gdb/testsuite/gdb.mi/basics.c",
- fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
- line_asm_insn=[@{address="0x000107c0",
- func-name="main",offset="4",inst="mov 2, %o0"@},
- @{address="0x000107c4",func-name="main",offset="8",
- inst="sethi %hi(0x11800), %o2"@}]@}]
- (gdb)
- @end smallexample
- @subheading The @code{-data-evaluate-expression} Command
- @findex -data-evaluate-expression
- @subsubheading Synopsis
- @smallexample
- -data-evaluate-expression @var{expr}
- @end smallexample
- Evaluate @var{expr} as an expression. The expression could contain an
- inferior function call. The function call will execute synchronously.
- If the expression contains spaces, it must be enclosed in double quotes.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
- @samp{call}. In @code{gdbtk} only, there's a corresponding
- @samp{gdb_eval} command.
- @subsubheading Example
- In the following example, the numbers that precede the commands are the
- @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
- Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
- output.
- @smallexample
- 211-data-evaluate-expression A
- 211^done,value="1"
- (gdb)
- 311-data-evaluate-expression &A
- 311^done,value="0xefffeb7c"
- (gdb)
- 411-data-evaluate-expression A+3
- 411^done,value="4"
- (gdb)
- 511-data-evaluate-expression "A + 3"
- 511^done,value="4"
- (gdb)
- @end smallexample
- @subheading The @code{-data-list-changed-registers} Command
- @findex -data-list-changed-registers
- @subsubheading Synopsis
- @smallexample
- -data-list-changed-registers
- @end smallexample
- Display a list of the registers that have changed.
- @subsubheading @value{GDBN} Command
- @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
- has the corresponding command @samp{gdb_changed_register_list}.
- @subsubheading Example
- On a PPC MBX board:
- @smallexample
- (gdb)
- -exec-continue
- ^running
- (gdb)
- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{
- func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
- line="5",arch="powerpc"@}
- (gdb)
- -data-list-changed-registers
- ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
- "10","11","13","14","15","16","17","18","19","20","21","22","23",
- "24","25","26","27","28","30","31","64","65","66","67","69"]
- (gdb)
- @end smallexample
- @subheading The @code{-data-list-register-names} Command
- @findex -data-list-register-names
- @subsubheading Synopsis
- @smallexample
- -data-list-register-names [ ( @var{regno} )+ ]
- @end smallexample
- Show a list of register names for the current target. If no arguments
- are given, it shows a list of the names of all the registers. If
- integer numbers are given as arguments, it will print a list of the
- names of the registers corresponding to the arguments. To ensure
- consistency between a register name and its number, the output list may
- include empty register names.
- @subsubheading @value{GDBN} Command
- @value{GDBN} does not have a command which corresponds to
- @samp{-data-list-register-names}. In @code{gdbtk} there is a
- corresponding command @samp{gdb_regnames}.
- @subsubheading Example
- For the PPC MBX board:
- @smallexample
- (gdb)
- -data-list-register-names
- ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
- "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
- "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
- "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
- "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
- "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
- "", "pc","ps","cr","lr","ctr","xer"]
- (gdb)
- -data-list-register-names 1 2 3
- ^done,register-names=["r1","r2","r3"]
- (gdb)
- @end smallexample
- @subheading The @code{-data-list-register-values} Command
- @findex -data-list-register-values
- @subsubheading Synopsis
- @smallexample
- -data-list-register-values
- [ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*]
- @end smallexample
- Display the registers' contents. The format according to which the
- registers' contents are to be returned is given by @var{fmt}, followed
- by an optional list of numbers specifying the registers to display. A
- missing list of numbers indicates that the contents of all the
- registers must be returned. The @code{--skip-unavailable} option
- indicates that only the available registers are to be returned.
- Allowed formats for @var{fmt} are:
- @table @code
- @item x
- Hexadecimal
- @item o
- Octal
- @item t
- Binary
- @item d
- Decimal
- @item r
- Raw
- @item N
- Natural
- @end table
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
- all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
- @subsubheading Example
- For a PPC MBX board (note: line breaks are for readability only, they
- don't appear in the actual output):
- @smallexample
- (gdb)
- -data-list-register-values r 64 65
- ^done,register-values=[@{number="64",value="0xfe00a300"@},
- @{number="65",value="0x00029002"@}]
- (gdb)
- -data-list-register-values x
- ^done,register-values=[@{number="0",value="0xfe0043c8"@},
- @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
- @{number="3",value="0x0"@},@{number="4",value="0xa"@},
- @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
- @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
- @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
- @{number="11",value="0x1"@},@{number="12",value="0x0"@},
- @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
- @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
- @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
- @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
- @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
- @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
- @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
- @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
- @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
- @{number="31",value="0x0"@},@{number="32",value="0x0"@},
- @{number="33",value="0x0"@},@{number="34",value="0x0"@},
- @{number="35",value="0x0"@},@{number="36",value="0x0"@},
- @{number="37",value="0x0"@},@{number="38",value="0x0"@},
- @{number="39",value="0x0"@},@{number="40",value="0x0"@},
- @{number="41",value="0x0"@},@{number="42",value="0x0"@},
- @{number="43",value="0x0"@},@{number="44",value="0x0"@},
- @{number="45",value="0x0"@},@{number="46",value="0x0"@},
- @{number="47",value="0x0"@},@{number="48",value="0x0"@},
- @{number="49",value="0x0"@},@{number="50",value="0x0"@},
- @{number="51",value="0x0"@},@{number="52",value="0x0"@},
- @{number="53",value="0x0"@},@{number="54",value="0x0"@},
- @{number="55",value="0x0"@},@{number="56",value="0x0"@},
- @{number="57",value="0x0"@},@{number="58",value="0x0"@},
- @{number="59",value="0x0"@},@{number="60",value="0x0"@},
- @{number="61",value="0x0"@},@{number="62",value="0x0"@},
- @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
- @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
- @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
- @{number="69",value="0x20002b03"@}]
- (gdb)
- @end smallexample
- @subheading The @code{-data-read-memory} Command
- @findex -data-read-memory
- This command is deprecated, use @code{-data-read-memory-bytes} instead.
- @subsubheading Synopsis
- @smallexample
- -data-read-memory [ -o @var{byte-offset} ]
- @var{address} @var{word-format} @var{word-size}
- @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
- @end smallexample
- @noindent
- where:
- @table @samp
- @item @var{address}
- An expression specifying the address of the first memory word to be
- read. Complex expressions containing embedded white space should be
- quoted using the C convention.
- @item @var{word-format}
- The format to be used to print the memory words. The notation is the
- same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
- ,Output Formats}).
- @item @var{word-size}
- The size of each memory word in bytes.
- @item @var{nr-rows}
- The number of rows in the output table.
- @item @var{nr-cols}
- The number of columns in the output table.
- @item @var{aschar}
- If present, indicates that each row should include an @sc{ascii} dump. The
- value of @var{aschar} is used as a padding character when a byte is not a
- member of the printable @sc{ascii} character set (printable @sc{ascii}
- characters are those whose code is between 32 and 126, inclusively).
- @item @var{byte-offset}
- An offset to add to the @var{address} before fetching memory.
- @end table
- This command displays memory contents as a table of @var{nr-rows} by
- @var{nr-cols} words, each word being @var{word-size} bytes. In total,
- @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
- (returned as @samp{total-bytes}). Should less than the requested number
- of bytes be returned by the target, the missing words are identified
- using @samp{N/A}. The number of bytes read from the target is returned
- in @samp{nr-bytes} and the starting address used to read memory in
- @samp{addr}.
- The address of the next/previous row or page is available in
- @samp{next-row} and @samp{prev-row}, @samp{next-page} and
- @samp{prev-page}.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
- @samp{gdb_get_mem} memory read command.
- @subsubheading Example
- Read six bytes of memory starting at @code{bytes+6} but then offset by
- @code{-6} bytes. Format as three rows of two columns. One byte per
- word. Display each word in hex.
- @smallexample
- (gdb)
- 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
- 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
- next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
- prev-page="0x0000138a",memory=[
- @{addr="0x00001390",data=["0x00","0x01"]@},
- @{addr="0x00001392",data=["0x02","0x03"]@},
- @{addr="0x00001394",data=["0x04","0x05"]@}]
- (gdb)
- @end smallexample
- Read two bytes of memory starting at address @code{shorts + 64} and
- display as a single word formatted in decimal.
- @smallexample
- (gdb)
- 5-data-read-memory shorts+64 d 2 1 1
- 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
- next-row="0x00001512",prev-row="0x0000150e",
- next-page="0x00001512",prev-page="0x0000150e",memory=[
- @{addr="0x00001510",data=["128"]@}]
- (gdb)
- @end smallexample
- Read thirty two bytes of memory starting at @code{bytes+16} and format
- as eight rows of four columns. Include a string encoding with @samp{x}
- used as the non-printable character.
- @smallexample
- (gdb)
- 4-data-read-memory bytes+16 x 1 8 4 x
- 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
- next-row="0x000013c0",prev-row="0x0000139c",
- next-page="0x000013c0",prev-page="0x00001380",memory=[
- @{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
- @{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
- @{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
- @{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
- @{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
- @{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
- @{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
- @{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
- (gdb)
- @end smallexample
- @subheading The @code{-data-read-memory-bytes} Command
- @findex -data-read-memory-bytes
- @subsubheading Synopsis
- @smallexample
- -data-read-memory-bytes [ -o @var{offset} ]
- @var{address} @var{count}
- @end smallexample
- @noindent
- where:
- @table @samp
- @item @var{address}
- An expression specifying the address of the first addressable memory unit
- to be read. Complex expressions containing embedded white space should be
- quoted using the C convention.
- @item @var{count}
- The number of addressable memory units to read. This should be an integer
- literal.
- @item @var{offset}
- The offset relative to @var{address} at which to start reading. This
- should be an integer literal. This option is provided so that a frontend
- is not required to first evaluate address and then perform address
- arithmetics itself.
- @end table
- This command attempts to read all accessible memory regions in the
- specified range. First, all regions marked as unreadable in the memory
- map (if one is defined) will be skipped. @xref{Memory Region
- Attributes}. Second, @value{GDBN} will attempt to read the remaining
- regions. For each one, if reading full region results in an errors,
- @value{GDBN} will try to read a subset of the region.
- In general, every single memory unit in the region may be readable or not,
- and the only way to read every readable unit is to try a read at
- every address, which is not practical. Therefore, @value{GDBN} will
- attempt to read all accessible memory units at either beginning or the end
- of the region, using a binary division scheme. This heuristic works
- well for reading across a memory map boundary. Note that if a region
- has a readable range that is neither at the beginning or the end,
- @value{GDBN} will not read it.
- The result record (@pxref{GDB/MI Result Records}) that is output of
- the command includes a field named @samp{memory} whose content is a
- list of tuples. Each tuple represent a successfully read memory block
- and has the following fields:
- @table @code
- @item begin
- The start address of the memory block, as hexadecimal literal.
- @item end
- The end address of the memory block, as hexadecimal literal.
- @item offset
- The offset of the memory block, as hexadecimal literal, relative to
- the start address passed to @code{-data-read-memory-bytes}.
- @item contents
- The contents of the memory block, in hex.
- @end table
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{x}.
- @subsubheading Example
- @smallexample
- (gdb)
- -data-read-memory-bytes &a 10
- ^done,memory=[@{begin="0xbffff154",offset="0x00000000",
- end="0xbffff15e",
- contents="01000000020000000300"@}]
- (gdb)
- @end smallexample
- @subheading The @code{-data-write-memory-bytes} Command
- @findex -data-write-memory-bytes
- @subsubheading Synopsis
- @smallexample
- -data-write-memory-bytes @var{address} @var{contents}
- -data-write-memory-bytes @var{address} @var{contents} @r{[}@var{count}@r{]}
- @end smallexample
- @noindent
- where:
- @table @samp
- @item @var{address}
- An expression specifying the address of the first addressable memory unit
- to be written. Complex expressions containing embedded white space should
- be quoted using the C convention.
- @item @var{contents}
- The hex-encoded data to write. It is an error if @var{contents} does
- not represent an integral number of addressable memory units.
- @item @var{count}
- Optional argument indicating the number of addressable memory units to be
- written. If @var{count} is greater than @var{contents}' length,
- @value{GDBN} will repeatedly write @var{contents} until it fills
- @var{count} memory units.
- @end table
- @subsubheading @value{GDBN} Command
- There's no corresponding @value{GDBN} command.
- @subsubheading Example
- @smallexample
- (gdb)
- -data-write-memory-bytes &a "aabbccdd"
- ^done
- (gdb)
- @end smallexample
- @smallexample
- (gdb)
- -data-write-memory-bytes &a "aabbccdd" 16e
- ^done
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Tracepoint Commands
- @section @sc{gdb/mi} Tracepoint Commands
- The commands defined in this section implement MI support for
- tracepoints. For detailed introduction, see @ref{Tracepoints}.
- @subheading The @code{-trace-find} Command
- @findex -trace-find
- @subsubheading Synopsis
- @smallexample
- -trace-find @var{mode} [@var{parameters}@dots{}]
- @end smallexample
- Find a trace frame using criteria defined by @var{mode} and
- @var{parameters}. The following table lists permissible
- modes and their parameters. For details of operation, see @ref{tfind}.
- @table @samp
- @item none
- No parameters are required. Stops examining trace frames.
- @item frame-number
- An integer is required as parameter. Selects tracepoint frame with
- that index.
- @item tracepoint-number
- An integer is required as parameter. Finds next
- trace frame that corresponds to tracepoint with the specified number.
- @item pc
- An address is required as parameter. Finds
- next trace frame that corresponds to any tracepoint at the specified
- address.
- @item pc-inside-range
- Two addresses are required as parameters. Finds next trace
- frame that corresponds to a tracepoint at an address inside the
- specified range. Both bounds are considered to be inside the range.
- @item pc-outside-range
- Two addresses are required as parameters. Finds
- next trace frame that corresponds to a tracepoint at an address outside
- the specified range. Both bounds are considered to be inside the range.
- @item line
- Line specification is required as parameter. @xref{Specify Location}.
- Finds next trace frame that corresponds to a tracepoint at
- the specified location.
- @end table
- If @samp{none} was passed as @var{mode}, the response does not
- have fields. Otherwise, the response may have the following fields:
- @table @samp
- @item found
- This field has either @samp{0} or @samp{1} as the value, depending
- on whether a matching tracepoint was found.
- @item traceframe
- The index of the found traceframe. This field is present iff
- the @samp{found} field has value of @samp{1}.
- @item tracepoint
- The index of the found tracepoint. This field is present iff
- the @samp{found} field has value of @samp{1}.
- @item frame
- The information about the frame corresponding to the found trace
- frame. This field is present only if a trace frame was found.
- @xref{GDB/MI Frame Information}, for description of this field.
- @end table
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{tfind}.
- @subheading -trace-define-variable
- @findex -trace-define-variable
- @subsubheading Synopsis
- @smallexample
- -trace-define-variable @var{name} [ @var{value} ]
- @end smallexample
- Create trace variable @var{name} if it does not exist. If
- @var{value} is specified, sets the initial value of the specified
- trace variable to that value. Note that the @var{name} should start
- with the @samp{$} character.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{tvariable}.
- @subheading The @code{-trace-frame-collected} Command
- @findex -trace-frame-collected
- @subsubheading Synopsis
- @smallexample
- -trace-frame-collected
- [--var-print-values @var{var_pval}]
- [--comp-print-values @var{comp_pval}]
- [--registers-format @var{regformat}]
- [--memory-contents]
- @end smallexample
- This command returns the set of collected objects, register names,
- trace state variable names, memory ranges and computed expressions
- that have been collected at a particular trace frame. The optional
- parameters to the command affect the output format in different ways.
- See the output description table below for more details.
- The reported names can be used in the normal manner to create
- varobjs and inspect the objects themselves. The items returned by
- this command are categorized so that it is clear which is a variable,
- which is a register, which is a trace state variable, which is a
- memory range and which is a computed expression.
- For instance, if the actions were
- @smallexample
- collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
- collect *(int*)0xaf02bef0@@40
- @end smallexample
- @noindent
- the object collected in its entirety would be @code{myVar}. The
- object @code{myArray} would be partially collected, because only the
- element at index @code{myIndex} would be collected. The remaining
- objects would be computed expressions.
- An example output would be:
- @smallexample
- (gdb)
- -trace-frame-collected
- ^done,
- explicit-variables=[@{name="myVar",value="1"@}],
- computed-expressions=[@{name="myArray[myIndex]",value="0"@},
- @{name="myObj.field",value="0"@},
- @{name="myPtr->field",value="1"@},
- @{name="myCount + 2",value="3"@},
- @{name="$tvar1 + 1",value="43970027"@}],
- registers=[@{number="0",value="0x7fe2c6e79ec8"@},
- @{number="1",value="0x0"@},
- @{number="2",value="0x4"@},
- ...
- @{number="125",value="0x0"@}],
- tvars=[@{name="$tvar1",current="43970026"@}],
- memory=[@{address="0x0000000000602264",length="4"@},
- @{address="0x0000000000615bc0",length="4"@}]
- (gdb)
- @end smallexample
- Where:
- @table @code
- @item explicit-variables
- The set of objects that have been collected in their entirety (as
- opposed to collecting just a few elements of an array or a few struct
- members). For each object, its name and value are printed.
- The @code{--var-print-values} option affects how or whether the value
- field is output. If @var{var_pval} is 0, then print only the names;
- if it is 1, print also their values; and if it is 2, print the name,
- type and value for simple data types, and the name and type for
- arrays, structures and unions.
- @item computed-expressions
- The set of computed expressions that have been collected at the
- current trace frame. The @code{--comp-print-values} option affects
- this set like the @code{--var-print-values} option affects the
- @code{explicit-variables} set. See above.
- @item registers
- The registers that have been collected at the current trace frame.
- For each register collected, the name and current value are returned.
- The value is formatted according to the @code{--registers-format}
- option. See the @command{-data-list-register-values} command for a
- list of the allowed formats. The default is @samp{x}.
- @item tvars
- The trace state variables that have been collected at the current
- trace frame. For each trace state variable collected, the name and
- current value are returned.
- @item memory
- The set of memory ranges that have been collected at the current trace
- frame. Its content is a list of tuples. Each tuple represents a
- collected memory range and has the following fields:
- @table @code
- @item address
- The start address of the memory range, as hexadecimal literal.
- @item length
- The length of the memory range, as decimal literal.
- @item contents
- The contents of the memory block, in hex. This field is only present
- if the @code{--memory-contents} option is specified.
- @end table
- @end table
- @subsubheading @value{GDBN} Command
- There is no corresponding @value{GDBN} command.
- @subsubheading Example
- @subheading -trace-list-variables
- @findex -trace-list-variables
- @subsubheading Synopsis
- @smallexample
- -trace-list-variables
- @end smallexample
- Return a table of all defined trace variables. Each element of the
- table has the following fields:
- @table @samp
- @item name
- The name of the trace variable. This field is always present.
- @item initial
- The initial value. This is a 64-bit signed integer. This
- field is always present.
- @item current
- The value the trace variable has at the moment. This is a 64-bit
- signed integer. This field is absent iff current value is
- not defined, for example if the trace was never run, or is
- presently running.
- @end table
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{tvariables}.
- @subsubheading Example
- @smallexample
- (gdb)
- -trace-list-variables
- ^done,trace-variables=@{nr_rows="1",nr_cols="3",
- hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
- @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
- @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
- body=[variable=@{name="$trace_timestamp",initial="0"@}
- variable=@{name="$foo",initial="10",current="15"@}]@}
- (gdb)
- @end smallexample
- @subheading -trace-save
- @findex -trace-save
- @subsubheading Synopsis
- @smallexample
- -trace-save [ -r ] [ -ctf ] @var{filename}
- @end smallexample
- Saves the collected trace data to @var{filename}. Without the
- @samp{-r} option, the data is downloaded from the target and saved
- in a local file. With the @samp{-r} option the target is asked
- to perform the save.
- By default, this command will save the trace in the tfile format. You can
- supply the optional @samp{-ctf} argument to save it the CTF format. See
- @ref{Trace Files} for more information about CTF.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{tsave}.
- @subheading -trace-start
- @findex -trace-start
- @subsubheading Synopsis
- @smallexample
- -trace-start
- @end smallexample
- Starts a tracing experiment. The result of this command does not
- have any fields.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{tstart}.
- @subheading -trace-status
- @findex -trace-status
- @subsubheading Synopsis
- @smallexample
- -trace-status
- @end smallexample
- Obtains the status of a tracing experiment. The result may include
- the following fields:
- @table @samp
- @item supported
- May have a value of either @samp{0}, when no tracing operations are
- supported, @samp{1}, when all tracing operations are supported, or
- @samp{file} when examining trace file. In the latter case, examining
- of trace frame is possible but new tracing experiement cannot be
- started. This field is always present.
- @item running
- May have a value of either @samp{0} or @samp{1} depending on whether
- tracing experiement is in progress on target. This field is present
- if @samp{supported} field is not @samp{0}.
- @item stop-reason
- Report the reason why the tracing was stopped last time. This field
- may be absent iff tracing was never stopped on target yet. The
- value of @samp{request} means the tracing was stopped as result of
- the @code{-trace-stop} command. The value of @samp{overflow} means
- the tracing buffer is full. The value of @samp{disconnection} means
- tracing was automatically stopped when @value{GDBN} has disconnected.
- The value of @samp{passcount} means tracing was stopped when a
- tracepoint was passed a maximal number of times for that tracepoint.
- This field is present if @samp{supported} field is not @samp{0}.
- @item stopping-tracepoint
- The number of tracepoint whose passcount as exceeded. This field is
- present iff the @samp{stop-reason} field has the value of
- @samp{passcount}.
- @item frames
- @itemx frames-created
- The @samp{frames} field is a count of the total number of trace frames
- in the trace buffer, while @samp{frames-created} is the total created
- during the run, including ones that were discarded, such as when a
- circular trace buffer filled up. Both fields are optional.
- @item buffer-size
- @itemx buffer-free
- These fields tell the current size of the tracing buffer and the
- remaining space. These fields are optional.
- @item circular
- The value of the circular trace buffer flag. @code{1} means that the
- trace buffer is circular and old trace frames will be discarded if
- necessary to make room, @code{0} means that the trace buffer is linear
- and may fill up.
- @item disconnected
- The value of the disconnected tracing flag. @code{1} means that
- tracing will continue after @value{GDBN} disconnects, @code{0} means
- that the trace run will stop.
- @item trace-file
- The filename of the trace file being examined. This field is
- optional, and only present when examining a trace file.
- @end table
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{tstatus}.
- @subheading -trace-stop
- @findex -trace-stop
- @subsubheading Synopsis
- @smallexample
- -trace-stop
- @end smallexample
- Stops a tracing experiment. The result of this command has the same
- fields as @code{-trace-status}, except that the @samp{supported} and
- @samp{running} fields are not output.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{tstop}.
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Symbol Query
- @section @sc{gdb/mi} Symbol Query Commands
- @ignore
- @subheading The @code{-symbol-info-address} Command
- @findex -symbol-info-address
- @subsubheading Synopsis
- @smallexample
- -symbol-info-address @var{symbol}
- @end smallexample
- Describe where @var{symbol} is stored.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info address}.
- @subsubheading Example
- N.A.
- @subheading The @code{-symbol-info-file} Command
- @findex -symbol-info-file
- @subsubheading Synopsis
- @smallexample
- -symbol-info-file
- @end smallexample
- Show the file for the symbol.
- @subsubheading @value{GDBN} Command
- There's no equivalent @value{GDBN} command. @code{gdbtk} has
- @samp{gdb_find_file}.
- @subsubheading Example
- N.A.
- @end ignore
- @subheading The @code{-symbol-info-functions} Command
- @findex -symbol-info-functions
- @anchor{-symbol-info-functions}
- @subsubheading Synopsis
- @smallexample
- -symbol-info-functions [--include-nondebug]
- [--type @var{type_regexp}]
- [--name @var{name_regexp}]
- [--max-results @var{limit}]
- @end smallexample
- @noindent
- Return a list containing the names and types for all global functions
- taken from the debug information. The functions are grouped by source
- file, and shown with the line number on which each function is
- defined.
- The @code{--include-nondebug} option causes the output to include
- code symbols from the symbol table.
- The options @code{--type} and @code{--name} allow the symbols returned
- to be filtered based on either the name of the function, or the type
- signature of the function.
- The option @code{--max-results} restricts the command to return no
- more than @var{limit} results. If exactly @var{limit} results are
- returned then there might be additional results available if a higher
- limit is used.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info functions}.
- @subsubheading Example
- @smallexample
- @group
- (gdb)
- -symbol-info-functions
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="36", name="f4", type="void (int *)",
- description="void f4(int *);"@},
- @{line="42", name="main", type="int ()",
- description="int main();"@},
- @{line="30", name="f1", type="my_int_t (int, int)",
- description="static my_int_t f1(int, int);"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="33", name="f2", type="float (another_float_t)",
- description="float f2(another_float_t);"@},
- @{line="39", name="f3", type="int (another_int_t)",
- description="int f3(another_int_t);"@},
- @{line="27", name="f1", type="another_float_t (int)",
- description="static another_float_t f1(int);"@}]@}]@}
- @end group
- @group
- (gdb)
- -symbol-info-functions --name f1
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="30", name="f1", type="my_int_t (int, int)",
- description="static my_int_t f1(int, int);"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="27", name="f1", type="another_float_t (int)",
- description="static another_float_t f1(int);"@}]@}]@}
- @end group
- @group
- (gdb)
- -symbol-info-functions --type void
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="36", name="f4", type="void (int *)",
- description="void f4(int *);"@}]@}]@}
- @end group
- @group
- (gdb)
- -symbol-info-functions --include-nondebug
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="36", name="f4", type="void (int *)",
- description="void f4(int *);"@},
- @{line="42", name="main", type="int ()",
- description="int main();"@},
- @{line="30", name="f1", type="my_int_t (int, int)",
- description="static my_int_t f1(int, int);"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="33", name="f2", type="float (another_float_t)",
- description="float f2(another_float_t);"@},
- @{line="39", name="f3", type="int (another_int_t)",
- description="int f3(another_int_t);"@},
- @{line="27", name="f1", type="another_float_t (int)",
- description="static another_float_t f1(int);"@}]@}],
- nondebug=
- [@{address="0x0000000000400398",name="_init"@},
- @{address="0x00000000004003b0",name="_start"@},
- ...
- ]@}
- @end group
- @end smallexample
- @subheading The @code{-symbol-info-module-functions} Command
- @findex -symbol-info-module-functions
- @anchor{-symbol-info-module-functions}
- @subsubheading Synopsis
- @smallexample
- -symbol-info-module-functions [--module @var{module_regexp}]
- [--name @var{name_regexp}]
- [--type @var{type_regexp}]
- @end smallexample
- @noindent
- Return a list containing the names of all known functions within all
- know Fortran modules. The functions are grouped by source file and
- containing module, and shown with the line number on which each
- function is defined.
- The option @code{--module} only returns results for modules matching
- @var{module_regexp}. The option @code{--name} only returns functions
- whose name matches @var{name_regexp}, and @code{--type} only returns
- functions whose type matches @var{type_regexp}.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info module functions}.
- @subsubheading Example
- @smallexample
- @group
- (gdb)
- -symbol-info-module-functions
- ^done,symbols=
- [@{module="mod1",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- symbols=[@{line="21",name="mod1::check_all",type="void (void)",
- description="void mod1::check_all(void);"@}]@}]@},
- @{module="mod2",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- symbols=[@{line="30",name="mod2::check_var_i",type="void (void)",
- description="void mod2::check_var_i(void);"@}]@}]@},
- @{module="mod3",
- files=[@{filename="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- fullname="/projec/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- symbols=[@{line="21",name="mod3::check_all",type="void (void)",
- description="void mod3::check_all(void);"@},
- @{line="27",name="mod3::check_mod2",type="void (void)",
- description="void mod3::check_mod2(void);"@}]@}]@},
- @{module="modmany",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- symbols=[@{line="35",name="modmany::check_some",type="void (void)",
- description="void modmany::check_some(void);"@}]@}]@},
- @{module="moduse",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- symbols=[@{line="44",name="moduse::check_all",type="void (void)",
- description="void moduse::check_all(void);"@},
- @{line="49",name="moduse::check_var_x",type="void (void)",
- description="void moduse::check_var_x(void);"@}]@}]@}]
- @end group
- @end smallexample
- @subheading The @code{-symbol-info-module-variables} Command
- @findex -symbol-info-module-variables
- @anchor{-symbol-info-module-variables}
- @subsubheading Synopsis
- @smallexample
- -symbol-info-module-variables [--module @var{module_regexp}]
- [--name @var{name_regexp}]
- [--type @var{type_regexp}]
- @end smallexample
- @noindent
- Return a list containing the names of all known variables within all
- know Fortran modules. The variables are grouped by source file and
- containing module, and shown with the line number on which each
- variable is defined.
- The option @code{--module} only returns results for modules matching
- @var{module_regexp}. The option @code{--name} only returns variables
- whose name matches @var{name_regexp}, and @code{--type} only returns
- variables whose type matches @var{type_regexp}.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info module variables}.
- @subsubheading Example
- @smallexample
- @group
- (gdb)
- -symbol-info-module-variables
- ^done,symbols=
- [@{module="mod1",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- symbols=[@{line="18",name="mod1::var_const",type="integer(kind=4)",
- description="integer(kind=4) mod1::var_const;"@},
- @{line="17",name="mod1::var_i",type="integer(kind=4)",
- description="integer(kind=4) mod1::var_i;"@}]@}]@},
- @{module="mod2",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- symbols=[@{line="28",name="mod2::var_i",type="integer(kind=4)",
- description="integer(kind=4) mod2::var_i;"@}]@}]@},
- @{module="mod3",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- symbols=[@{line="18",name="mod3::mod1",type="integer(kind=4)",
- description="integer(kind=4) mod3::mod1;"@},
- @{line="17",name="mod3::mod2",type="integer(kind=4)",
- description="integer(kind=4) mod3::mod2;"@},
- @{line="19",name="mod3::var_i",type="integer(kind=4)",
- description="integer(kind=4) mod3::var_i;"@}]@}]@},
- @{module="modmany",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- symbols=[@{line="33",name="modmany::var_a",type="integer(kind=4)",
- description="integer(kind=4) modmany::var_a;"@},
- @{line="33",name="modmany::var_b",type="integer(kind=4)",
- description="integer(kind=4) modmany::var_b;"@},
- @{line="33",name="modmany::var_c",type="integer(kind=4)",
- description="integer(kind=4) modmany::var_c;"@},
- @{line="33",name="modmany::var_i",type="integer(kind=4)",
- description="integer(kind=4) modmany::var_i;"@}]@}]@},
- @{module="moduse",
- files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- symbols=[@{line="42",name="moduse::var_x",type="integer(kind=4)",
- description="integer(kind=4) moduse::var_x;"@},
- @{line="42",name="moduse::var_y",type="integer(kind=4)",
- description="integer(kind=4) moduse::var_y;"@}]@}]@}]
- @end group
- @end smallexample
- @subheading The @code{-symbol-info-modules} Command
- @findex -symbol-info-modules
- @anchor{-symbol-info-modules}
- @subsubheading Synopsis
- @smallexample
- -symbol-info-modules [--name @var{name_regexp}]
- [--max-results @var{limit}]
- @end smallexample
- @noindent
- Return a list containing the names of all known Fortran modules. The
- modules are grouped by source file, and shown with the line number on
- which each modules is defined.
- The option @code{--name} allows the modules returned to be filtered
- based the name of the module.
- The option @code{--max-results} restricts the command to return no
- more than @var{limit} results. If exactly @var{limit} results are
- returned then there might be additional results available if a higher
- limit is used.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info modules}.
- @subsubheading Example
- @smallexample
- @group
- (gdb)
- -symbol-info-modules
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- symbols=[@{line="16",name="mod1"@},
- @{line="22",name="mod2"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- symbols=[@{line="16",name="mod3"@},
- @{line="22",name="modmany"@},
- @{line="26",name="moduse"@}]@}]@}
- @end group
- @group
- (gdb)
- -symbol-info-modules --name mod[123]
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90",
- symbols=[@{line="16",name="mod1"@},
- @{line="22",name="mod2"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90",
- symbols=[@{line="16",name="mod3"@}]@}]@}
- @end group
- @end smallexample
- @subheading The @code{-symbol-info-types} Command
- @findex -symbol-info-types
- @anchor{-symbol-info-types}
- @subsubheading Synopsis
- @smallexample
- -symbol-info-types [--name @var{name_regexp}]
- [--max-results @var{limit}]
- @end smallexample
- @noindent
- Return a list of all defined types. The types are grouped by source
- file, and shown with the line number on which each user defined type
- is defined. Some base types are not defined in the source code but
- are added to the debug information by the compiler, for example
- @code{int}, @code{float}, etc.; these types do not have an associated
- line number.
- The option @code{--name} allows the list of types returned to be
- filtered by name.
- The option @code{--max-results} restricts the command to return no
- more than @var{limit} results. If exactly @var{limit} results are
- returned then there might be additional results available if a higher
- limit is used.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info types}.
- @subsubheading Example
- @smallexample
- @group
- (gdb)
- -symbol-info-types
- ^done,symbols=
- @{debug=
- [@{filename="gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{name="float"@},
- @{name="int"@},
- @{line="27",name="typedef int my_int_t;"@}]@},
- @{filename="gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="24",name="typedef float another_float_t;"@},
- @{line="23",name="typedef int another_int_t;"@},
- @{name="float"@},
- @{name="int"@}]@}]@}
- @end group
- @group
- (gdb)
- -symbol-info-types --name _int_
- ^done,symbols=
- @{debug=
- [@{filename="gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="27",name="typedef int my_int_t;"@}]@},
- @{filename="gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="23",name="typedef int another_int_t;"@}]@}]@}
- @end group
- @end smallexample
- @subheading The @code{-symbol-info-variables} Command
- @findex -symbol-info-variables
- @anchor{-symbol-info-variables}
- @subsubheading Synopsis
- @smallexample
- -symbol-info-variables [--include-nondebug]
- [--type @var{type_regexp}]
- [--name @var{name_regexp}]
- [--max-results @var{limit}]
- @end smallexample
- @noindent
- Return a list containing the names and types for all global variables
- taken from the debug information. The variables are grouped by source
- file, and shown with the line number on which each variable is
- defined.
- The @code{--include-nondebug} option causes the output to include
- data symbols from the symbol table.
- The options @code{--type} and @code{--name} allow the symbols returned
- to be filtered based on either the name of the variable, or the type
- of the variable.
- The option @code{--max-results} restricts the command to return no
- more than @var{limit} results. If exactly @var{limit} results are
- returned then there might be additional results available if a higher
- limit is used.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info variables}.
- @subsubheading Example
- @smallexample
- @group
- (gdb)
- -symbol-info-variables
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="25",name="global_f1",type="float",
- description="static float global_f1;"@},
- @{line="24",name="global_i1",type="int",
- description="static int global_i1;"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="21",name="global_f2",type="int",
- description="int global_f2;"@},
- @{line="20",name="global_i2",type="int",
- description="int global_i2;"@},
- @{line="19",name="global_f1",type="float",
- description="static float global_f1;"@},
- @{line="18",name="global_i1",type="int",
- description="static int global_i1;"@}]@}]@}
- @end group
- @group
- (gdb)
- -symbol-info-variables --name f1
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="25",name="global_f1",type="float",
- description="static float global_f1;"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="19",name="global_f1",type="float",
- description="static float global_f1;"@}]@}]@}
- @end group
- @group
- (gdb)
- -symbol-info-variables --type float
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="25",name="global_f1",type="float",
- description="static float global_f1;"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="19",name="global_f1",type="float",
- description="static float global_f1;"@}]@}]@}
- @end group
- @group
- (gdb)
- -symbol-info-variables --include-nondebug
- ^done,symbols=
- @{debug=
- [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
- symbols=[@{line="25",name="global_f1",type="float",
- description="static float global_f1;"@},
- @{line="24",name="global_i1",type="int",
- description="static int global_i1;"@}]@},
- @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c",
- symbols=[@{line="21",name="global_f2",type="int",
- description="int global_f2;"@},
- @{line="20",name="global_i2",type="int",
- description="int global_i2;"@},
- @{line="19",name="global_f1",type="float",
- description="static float global_f1;"@},
- @{line="18",name="global_i1",type="int",
- description="static int global_i1;"@}]@}],
- nondebug=
- [@{address="0x00000000004005d0",name="_IO_stdin_used"@},
- @{address="0x00000000004005d8",name="__dso_handle"@}
- ...
- ]@}
- @end group
- @end smallexample
- @ignore
- @subheading The @code{-symbol-info-line} Command
- @findex -symbol-info-line
- @subsubheading Synopsis
- @smallexample
- -symbol-info-line
- @end smallexample
- Show the core addresses of the code for a source line.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info line}.
- @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
- @subsubheading Example
- N.A.
- @subheading The @code{-symbol-info-symbol} Command
- @findex -symbol-info-symbol
- @subsubheading Synopsis
- @smallexample
- -symbol-info-symbol @var{addr}
- @end smallexample
- Describe what symbol is at location @var{addr}.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info symbol}.
- @subsubheading Example
- N.A.
- @subheading The @code{-symbol-list-functions} Command
- @findex -symbol-list-functions
- @subsubheading Synopsis
- @smallexample
- -symbol-list-functions
- @end smallexample
- List the functions in the executable.
- @subsubheading @value{GDBN} Command
- @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
- @samp{gdb_search} in @code{gdbtk}.
- @subsubheading Example
- N.A.
- @end ignore
- @subheading The @code{-symbol-list-lines} Command
- @findex -symbol-list-lines
- @subsubheading Synopsis
- @smallexample
- -symbol-list-lines @var{filename}
- @end smallexample
- Print the list of lines that contain code and their associated program
- addresses for the given source filename. The entries are sorted in
- ascending PC order.
- @subsubheading @value{GDBN} Command
- There is no corresponding @value{GDBN} command.
- @subsubheading Example
- @smallexample
- (gdb)
- -symbol-list-lines basics.c
- ^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
- (gdb)
- @end smallexample
- @ignore
- @subheading The @code{-symbol-list-types} Command
- @findex -symbol-list-types
- @subsubheading Synopsis
- @smallexample
- -symbol-list-types
- @end smallexample
- List all the type names.
- @subsubheading @value{GDBN} Command
- The corresponding commands are @samp{info types} in @value{GDBN},
- @samp{gdb_search} in @code{gdbtk}.
- @subsubheading Example
- N.A.
- @subheading The @code{-symbol-list-variables} Command
- @findex -symbol-list-variables
- @subsubheading Synopsis
- @smallexample
- -symbol-list-variables
- @end smallexample
- List all the global and static variable names.
- @subsubheading @value{GDBN} Command
- @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
- @subsubheading Example
- N.A.
- @subheading The @code{-symbol-locate} Command
- @findex -symbol-locate
- @subsubheading Synopsis
- @smallexample
- -symbol-locate
- @end smallexample
- @subsubheading @value{GDBN} Command
- @samp{gdb_loc} in @code{gdbtk}.
- @subsubheading Example
- N.A.
- @subheading The @code{-symbol-type} Command
- @findex -symbol-type
- @subsubheading Synopsis
- @smallexample
- -symbol-type @var{variable}
- @end smallexample
- Show type of @var{variable}.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
- @samp{gdb_obj_variable}.
- @subsubheading Example
- N.A.
- @end ignore
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI File Commands
- @section @sc{gdb/mi} File Commands
- This section describes the GDB/MI commands to specify executable file names
- and to read in and obtain symbol table information.
- @subheading The @code{-file-exec-and-symbols} Command
- @findex -file-exec-and-symbols
- @subsubheading Synopsis
- @smallexample
- -file-exec-and-symbols @var{file}
- @end smallexample
- Specify the executable file to be debugged. This file is the one from
- which the symbol table is also read. If no file is specified, the
- command clears the executable and symbol information. If breakpoints
- are set when using this command with no arguments, @value{GDBN} will produce
- error messages. Otherwise, no output is produced, except a completion
- notification.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{file}.
- @subsubheading Example
- @smallexample
- (gdb)
- -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-file-exec-file} Command
- @findex -file-exec-file
- @subsubheading Synopsis
- @smallexample
- -file-exec-file @var{file}
- @end smallexample
- Specify the executable file to be debugged. Unlike
- @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
- from this file. If used without argument, @value{GDBN} clears the information
- about the executable file. No output is produced, except a completion
- notification.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{exec-file}.
- @subsubheading Example
- @smallexample
- (gdb)
- -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
- ^done
- (gdb)
- @end smallexample
- @ignore
- @subheading The @code{-file-list-exec-sections} Command
- @findex -file-list-exec-sections
- @subsubheading Synopsis
- @smallexample
- -file-list-exec-sections
- @end smallexample
- List the sections of the current executable file.
- @subsubheading @value{GDBN} Command
- The @value{GDBN} command @samp{info file} shows, among the rest, the same
- information as this command. @code{gdbtk} has a corresponding command
- @samp{gdb_load_info}.
- @subsubheading Example
- N.A.
- @end ignore
- @subheading The @code{-file-list-exec-source-file} Command
- @findex -file-list-exec-source-file
- @subsubheading Synopsis
- @smallexample
- -file-list-exec-source-file
- @end smallexample
- List the line number, the current source file, and the absolute path
- to the current source file for the current executable. The macro
- information field has a value of @samp{1} or @samp{0} depending on
- whether or not the file includes preprocessor macro information.
- @subsubheading @value{GDBN} Command
- The @value{GDBN} equivalent is @samp{info source}
- @subsubheading Example
- @smallexample
- (gdb)
- 123-file-list-exec-source-file
- 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
- (gdb)
- @end smallexample
- @subheading The @code{-file-list-exec-source-files} Command
- @kindex info sources
- @findex -file-list-exec-source-files
- @subsubheading Synopsis
- @smallexample
- -file-list-exec-source-files @r{[} @var{--group-by-objfile} @r{]}
- @r{[} @var{--dirname} @r{|} @var{--basename} @r{]}
- @r{[} -- @r{]}
- @r{[} @var{regexp} @r{]}
- @end smallexample
- This command returns information about the source files @value{GDBN}
- knows about, it will output both the filename and fullname (absolute
- file name) of a source file, though the fullname can be elided if this
- information is not known to @value{GDBN}.
- With no arguments this command returns a list of source files. Each
- source file is represented by a tuple with the fields; @var{file},
- @var{fullname}, and @var{debug-fully-read}. The @var{file} is the
- display name for the file, while @var{fullname} is the absolute name
- of the file. The @var{fullname} field can be elided if the absolute
- name of the source file can't be computed. The field
- @var{debug-fully-read} will be a string, either @code{true} or
- @code{false}. When @code{true}, this indicates the full debug
- information for the compilation unit describing this file has been
- read in. When @code{false}, the full debug information has not yet
- been read in. While reading in the full debug information it is
- possible that @value{GDBN} could become aware of additional source
- files.
- The optional @var{regexp} can be used to filter the list of source
- files returned. The @var{regexp} will be matched against the full
- source file name. The matching is case-sensitive, except on operating
- systems that have case-insensitive filesystem (e.g.,
- MS-Windows). @samp{--} can be used before @var{regexp} to prevent
- @value{GDBN} interpreting @var{regexp} as a command option (e.g.@: if
- @var{regexp} starts with @samp{-}).
- If @code{--dirname} is provided, then @var{regexp} is matched only
- against the directory name of each source file. If @code{--basename}
- is provided, then @var{regexp} is matched against the basename of each
- source file. Only one of @code{--dirname} or @code{--basename} may be
- given, and if either is given then @var{regexp} is required.
- If @code{--group-by-objfile} is used then the format of the results is
- changed. The results will now be a list of tuples, with each tuple
- representing an object file (executable or shared library) loaded into
- @value{GDBN}. The fields of these tuples are; @var{filename},
- @var{debug-info}, and @var{sources}. The @var{filename} is the
- absolute name of the object file, @var{debug-info} is a string with
- one of the following values:
- @table @code
- @item none
- This object file has no debug information.
- @item partially-read
- This object file has debug information, but it is not fully read in
- yet. When it is read in later, GDB might become aware of additional
- source files.
- @item fully-read
- This object file has debug information, and this information is fully
- read into GDB. The list of source files is complete.
- @end table
- The @var{sources} is a list or tuples, with each tuple describing a
- single source file with the same fields as described previously. The
- @var{sources} list can be empty for object files that have no debug
- information.
- @subsubheading @value{GDBN} Command
- The @value{GDBN} equivalent is @samp{info sources}.
- @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
- @subsubheading Example
- @smallexample
- (@value{GDBP})
- -file-list-exec-source-files
- ^done,files=[@{file="foo.c",fullname="/home/foo.c",debug-fully-read="true"@},
- @{file="/home/bar.c",fullname="/home/bar.c",debug-fully-read="true"@},
- @{file="gdb_could_not_find_fullpath.c",debug-fully-read="true"@}]
- (@value{GDBP})
- -file-list-exec-source-files
- ^done,files=[@{file="test.c",
- fullname="/tmp/info-sources/test.c",
- debug-fully-read="true"@},
- @{file="/usr/include/stdc-predef.h",
- fullname="/usr/include/stdc-predef.h",
- debug-fully-read="true"@},
- @{file="header.h",
- fullname="/tmp/info-sources/header.h",
- debug-fully-read="true"@},
- @{file="helper.c",
- fullname="/tmp/info-sources/helper.c",
- debug-fully-read="true"@}]
- (@value{GDBP})
- -file-list-exec-source-files -- \\.c
- ^done,files=[@{file="test.c",
- fullname="/tmp/info-sources/test.c",
- debug-fully-read="true"@},
- @{file="helper.c",
- fullname="/tmp/info-sources/helper.c",
- debug-fully-read="true"@}]
- (@value{GDBP})
- -file-list-exec-source-files --group-by-objfile
- ^done,files=[@{filename="/tmp/info-sources/test.x",
- debug-info="fully-read",
- sources=[@{file="test.c",
- fullname="/tmp/info-sources/test.c",
- debug-fully-read="true"@},
- @{file="/usr/include/stdc-predef.h",
- fullname="/usr/include/stdc-predef.h",
- debug-fully-read="true"@},
- @{file="header.h",
- fullname="/tmp/info-sources/header.h",
- debug-fully-read="true"@}]@},
- @{filename="/lib64/ld-linux-x86-64.so.2",
- debug-info="none",
- sources=[]@},
- @{filename="system-supplied DSO at 0x7ffff7fcf000",
- debug-info="none",
- sources=[]@},
- @{filename="/tmp/info-sources/libhelper.so",
- debug-info="fully-read",
- sources=[@{file="helper.c",
- fullname="/tmp/info-sources/helper.c",
- debug-fully-read="true"@},
- @{file="/usr/include/stdc-predef.h",
- fullname="/usr/include/stdc-predef.h",
- debug-fully-read="true"@},
- @{file="header.h",
- fullname="/tmp/info-sources/header.h",
- debug-fully-read="true"@}]@},
- @{filename="/lib64/libc.so.6",
- debug-info="none",
- sources=[]@}]
- @end smallexample
- @subheading The @code{-file-list-shared-libraries} Command
- @findex -file-list-shared-libraries
- @subsubheading Synopsis
- @smallexample
- -file-list-shared-libraries [ @var{regexp} ]
- @end smallexample
- List the shared libraries in the program.
- With a regular expression @var{regexp}, only those libraries whose
- names match @var{regexp} are listed.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info shared}. The fields
- have a similar meaning to the @code{=library-loaded} notification.
- The @code{ranges} field specifies the multiple segments belonging to this
- library. Each range has the following fields:
- @table @samp
- @item from
- The address defining the inclusive lower bound of the segment.
- @item to
- The address defining the exclusive upper bound of the segment.
- @end table
- @subsubheading Example
- @smallexample
- (gdb)
- -file-list-exec-source-files
- ^done,shared-libraries=[
- @{id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x72815989",to="0x728162c0"@}]@},
- @{id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x76ee48c0",to="0x76ee9160"@}]@}]
- (gdb)
- @end smallexample
- @ignore
- @subheading The @code{-file-list-symbol-files} Command
- @findex -file-list-symbol-files
- @subsubheading Synopsis
- @smallexample
- -file-list-symbol-files
- @end smallexample
- List symbol files.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info file} (part of it).
- @subsubheading Example
- N.A.
- @end ignore
- @subheading The @code{-file-symbol-file} Command
- @findex -file-symbol-file
- @subsubheading Synopsis
- @smallexample
- -file-symbol-file @var{file}
- @end smallexample
- Read symbol table info from the specified @var{file} argument. When
- used without arguments, clears @value{GDBN}'s symbol table info. No output is
- produced, except for a completion notification.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{symbol-file}.
- @subsubheading Example
- @smallexample
- (gdb)
- -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
- ^done
- (gdb)
- @end smallexample
- @ignore
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Memory Overlay Commands
- @section @sc{gdb/mi} Memory Overlay Commands
- The memory overlay commands are not implemented.
- @c @subheading -overlay-auto
- @c @subheading -overlay-list-mapping-state
- @c @subheading -overlay-list-overlays
- @c @subheading -overlay-map
- @c @subheading -overlay-off
- @c @subheading -overlay-on
- @c @subheading -overlay-unmap
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Signal Handling Commands
- @section @sc{gdb/mi} Signal Handling Commands
- Signal handling commands are not implemented.
- @c @subheading -signal-handle
- @c @subheading -signal-list-handle-actions
- @c @subheading -signal-list-signal-types
- @end ignore
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Target Manipulation
- @section @sc{gdb/mi} Target Manipulation Commands
- @subheading The @code{-target-attach} Command
- @findex -target-attach
- @subsubheading Synopsis
- @smallexample
- -target-attach @var{pid} | @var{gid} | @var{file}
- @end smallexample
- Attach to a process @var{pid} or a file @var{file} outside of
- @value{GDBN}, or a thread group @var{gid}. If attaching to a thread
- group, the id previously returned by
- @samp{-list-thread-groups --available} must be used.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{attach}.
- @subsubheading Example
- @smallexample
- (gdb)
- -target-attach 34
- =thread-created,id="1"
- *stopped,thread-id="1",frame=@{addr="0xb7f7e410",func="bar",args=[]@}
- ^done
- (gdb)
- @end smallexample
- @ignore
- @subheading The @code{-target-compare-sections} Command
- @findex -target-compare-sections
- @subsubheading Synopsis
- @smallexample
- -target-compare-sections [ @var{section} ]
- @end smallexample
- Compare data of section @var{section} on target to the exec file.
- Without the argument, all sections are compared.
- @subsubheading @value{GDBN} Command
- The @value{GDBN} equivalent is @samp{compare-sections}.
- @subsubheading Example
- N.A.
- @end ignore
- @subheading The @code{-target-detach} Command
- @findex -target-detach
- @subsubheading Synopsis
- @smallexample
- -target-detach [ @var{pid} | @var{gid} ]
- @end smallexample
- Detach from the remote target which normally resumes its execution.
- If either @var{pid} or @var{gid} is specified, detaches from either
- the specified process, or specified thread group. There's no output.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{detach}.
- @subsubheading Example
- @smallexample
- (gdb)
- -target-detach
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-target-disconnect} Command
- @findex -target-disconnect
- @subsubheading Synopsis
- @smallexample
- -target-disconnect
- @end smallexample
- Disconnect from the remote target. There's no output and the target is
- generally not resumed.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{disconnect}.
- @subsubheading Example
- @smallexample
- (gdb)
- -target-disconnect
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-target-download} Command
- @findex -target-download
- @subsubheading Synopsis
- @smallexample
- -target-download
- @end smallexample
- Loads the executable onto the remote target.
- It prints out an update message every half second, which includes the fields:
- @table @samp
- @item section
- The name of the section.
- @item section-sent
- The size of what has been sent so far for that section.
- @item section-size
- The size of the section.
- @item total-sent
- The total size of what was sent so far (the current and the previous sections).
- @item total-size
- The size of the overall executable to download.
- @end table
- @noindent
- Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
- @sc{gdb/mi} Output Syntax}).
- In addition, it prints the name and size of the sections, as they are
- downloaded. These messages include the following fields:
- @table @samp
- @item section
- The name of the section.
- @item section-size
- The size of the section.
- @item total-size
- The size of the overall executable to download.
- @end table
- @noindent
- At the end, a summary is printed.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{load}.
- @subsubheading Example
- Note: each status message appears on a single line. Here the messages
- have been broken down so that they can fit onto a page.
- @smallexample
- (gdb)
- -target-download
- +download,@{section=".text",section-size="6668",total-size="9880"@}
- +download,@{section=".text",section-sent="512",section-size="6668",
- total-sent="512",total-size="9880"@}
- +download,@{section=".text",section-sent="1024",section-size="6668",
- total-sent="1024",total-size="9880"@}
- +download,@{section=".text",section-sent="1536",section-size="6668",
- total-sent="1536",total-size="9880"@}
- +download,@{section=".text",section-sent="2048",section-size="6668",
- total-sent="2048",total-size="9880"@}
- +download,@{section=".text",section-sent="2560",section-size="6668",
- total-sent="2560",total-size="9880"@}
- +download,@{section=".text",section-sent="3072",section-size="6668",
- total-sent="3072",total-size="9880"@}
- +download,@{section=".text",section-sent="3584",section-size="6668",
- total-sent="3584",total-size="9880"@}
- +download,@{section=".text",section-sent="4096",section-size="6668",
- total-sent="4096",total-size="9880"@}
- +download,@{section=".text",section-sent="4608",section-size="6668",
- total-sent="4608",total-size="9880"@}
- +download,@{section=".text",section-sent="5120",section-size="6668",
- total-sent="5120",total-size="9880"@}
- +download,@{section=".text",section-sent="5632",section-size="6668",
- total-sent="5632",total-size="9880"@}
- +download,@{section=".text",section-sent="6144",section-size="6668",
- total-sent="6144",total-size="9880"@}
- +download,@{section=".text",section-sent="6656",section-size="6668",
- total-sent="6656",total-size="9880"@}
- +download,@{section=".init",section-size="28",total-size="9880"@}
- +download,@{section=".fini",section-size="28",total-size="9880"@}
- +download,@{section=".data",section-size="3156",total-size="9880"@}
- +download,@{section=".data",section-sent="512",section-size="3156",
- total-sent="7236",total-size="9880"@}
- +download,@{section=".data",section-sent="1024",section-size="3156",
- total-sent="7748",total-size="9880"@}
- +download,@{section=".data",section-sent="1536",section-size="3156",
- total-sent="8260",total-size="9880"@}
- +download,@{section=".data",section-sent="2048",section-size="3156",
- total-sent="8772",total-size="9880"@}
- +download,@{section=".data",section-sent="2560",section-size="3156",
- total-sent="9284",total-size="9880"@}
- +download,@{section=".data",section-sent="3072",section-size="3156",
- total-sent="9796",total-size="9880"@}
- ^done,address="0x10004",load-size="9880",transfer-rate="6586",
- write-rate="429"
- (gdb)
- @end smallexample
- @ignore
- @subheading The @code{-target-exec-status} Command
- @findex -target-exec-status
- @subsubheading Synopsis
- @smallexample
- -target-exec-status
- @end smallexample
- Provide information on the state of the target (whether it is running or
- not, for instance).
- @subsubheading @value{GDBN} Command
- There's no equivalent @value{GDBN} command.
- @subsubheading Example
- N.A.
- @subheading The @code{-target-list-available-targets} Command
- @findex -target-list-available-targets
- @subsubheading Synopsis
- @smallexample
- -target-list-available-targets
- @end smallexample
- List the possible targets to connect to.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{help target}.
- @subsubheading Example
- N.A.
- @subheading The @code{-target-list-current-targets} Command
- @findex -target-list-current-targets
- @subsubheading Synopsis
- @smallexample
- -target-list-current-targets
- @end smallexample
- Describe the current target.
- @subsubheading @value{GDBN} Command
- The corresponding information is printed by @samp{info file} (among
- other things).
- @subsubheading Example
- N.A.
- @subheading The @code{-target-list-parameters} Command
- @findex -target-list-parameters
- @subsubheading Synopsis
- @smallexample
- -target-list-parameters
- @end smallexample
- @c ????
- @end ignore
- @subsubheading @value{GDBN} Command
- No equivalent.
- @subsubheading Example
- N.A.
- @subheading The @code{-target-flash-erase} Command
- @findex -target-flash-erase
- @subsubheading Synopsis
- @smallexample
- -target-flash-erase
- @end smallexample
- Erases all known flash memory regions on the target.
- The corresponding @value{GDBN} command is @samp{flash-erase}.
- The output is a list of flash regions that have been erased, with starting
- addresses and memory region sizes.
- @smallexample
- (gdb)
- -target-flash-erase
- ^done,erased-regions=@{address="0x0",size="0x40000"@}
- (gdb)
- @end smallexample
- @subheading The @code{-target-select} Command
- @findex -target-select
- @subsubheading Synopsis
- @smallexample
- -target-select @var{type} @var{parameters @dots{}}
- @end smallexample
- Connect @value{GDBN} to the remote target. This command takes two args:
- @table @samp
- @item @var{type}
- The type of target, for instance @samp{remote}, etc.
- @item @var{parameters}
- Device names, host names and the like. @xref{Target Commands, ,
- Commands for Managing Targets}, for more details.
- @end table
- The output is a connection notification, followed by the address at
- which the target program is, in the following form:
- @smallexample
- ^connected,addr="@var{address}",func="@var{function name}",
- args=[@var{arg list}]
- @end smallexample
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{target}.
- @subsubheading Example
- @smallexample
- (gdb)
- -target-select remote /dev/ttya
- ^connected,addr="0xfe00a300",func="??",args=[]
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI File Transfer Commands
- @section @sc{gdb/mi} File Transfer Commands
- @subheading The @code{-target-file-put} Command
- @findex -target-file-put
- @subsubheading Synopsis
- @smallexample
- -target-file-put @var{hostfile} @var{targetfile}
- @end smallexample
- Copy file @var{hostfile} from the host system (the machine running
- @value{GDBN}) to @var{targetfile} on the target system.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{remote put}.
- @subsubheading Example
- @smallexample
- (gdb)
- -target-file-put localfile remotefile
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-target-file-get} Command
- @findex -target-file-get
- @subsubheading Synopsis
- @smallexample
- -target-file-get @var{targetfile} @var{hostfile}
- @end smallexample
- Copy file @var{targetfile} from the target system to @var{hostfile}
- on the host system.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{remote get}.
- @subsubheading Example
- @smallexample
- (gdb)
- -target-file-get remotefile localfile
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-target-file-delete} Command
- @findex -target-file-delete
- @subsubheading Synopsis
- @smallexample
- -target-file-delete @var{targetfile}
- @end smallexample
- Delete @var{targetfile} from the target system.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{remote delete}.
- @subsubheading Example
- @smallexample
- (gdb)
- -target-file-delete remotefile
- ^done
- (gdb)
- @end smallexample
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Ada Exceptions Commands
- @section Ada Exceptions @sc{gdb/mi} Commands
- @subheading The @code{-info-ada-exceptions} Command
- @findex -info-ada-exceptions
- @subsubheading Synopsis
- @smallexample
- -info-ada-exceptions [ @var{regexp}]
- @end smallexample
- List all Ada exceptions defined within the program being debugged.
- With a regular expression @var{regexp}, only those exceptions whose
- names match @var{regexp} are listed.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info exceptions}.
- @subsubheading Result
- The result is a table of Ada exceptions. The following columns are
- defined for each exception:
- @table @samp
- @item name
- The name of the exception.
- @item address
- The address of the exception.
- @end table
- @subsubheading Example
- @smallexample
- -info-ada-exceptions aint
- ^done,ada-exceptions=@{nr_rows="2",nr_cols="2",
- hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@},
- @{width="1",alignment="-1",col_name="address",colhdr="Address"@}],
- body=[@{name="constraint_error",address="0x0000000000613da0"@},
- @{name="const.aint_global_e",address="0x0000000000613b00"@}]@}
- @end smallexample
- @subheading Catching Ada Exceptions
- The commands describing how to ask @value{GDBN} to stop when a program
- raises an exception are described at @ref{Ada Exception GDB/MI
- Catchpoint Commands}.
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Support Commands
- @section @sc{gdb/mi} Support Commands
- Since new commands and features get regularly added to @sc{gdb/mi},
- some commands are available to help front-ends query the debugger
- about support for these capabilities. Similarly, it is also possible
- to query @value{GDBN} about target support of certain features.
- @subheading The @code{-info-gdb-mi-command} Command
- @cindex @code{-info-gdb-mi-command}
- @findex -info-gdb-mi-command
- @subsubheading Synopsis
- @smallexample
- -info-gdb-mi-command @var{cmd_name}
- @end smallexample
- Query support for the @sc{gdb/mi} command named @var{cmd_name}.
- Note that the dash (@code{-}) starting all @sc{gdb/mi} commands
- is technically not part of the command name (@pxref{GDB/MI Input
- Syntax}), and thus should be omitted in @var{cmd_name}. However,
- for ease of use, this command also accepts the form with the leading
- dash.
- @subsubheading @value{GDBN} Command
- There is no corresponding @value{GDBN} command.
- @subsubheading Result
- The result is a tuple. There is currently only one field:
- @table @samp
- @item exists
- This field is equal to @code{"true"} if the @sc{gdb/mi} command exists,
- @code{"false"} otherwise.
- @end table
- @subsubheading Example
- Here is an example where the @sc{gdb/mi} command does not exist:
- @smallexample
- -info-gdb-mi-command unsupported-command
- ^done,command=@{exists="false"@}
- @end smallexample
- @noindent
- And here is an example where the @sc{gdb/mi} command is known
- to the debugger:
- @smallexample
- -info-gdb-mi-command symbol-list-lines
- ^done,command=@{exists="true"@}
- @end smallexample
- @subheading The @code{-list-features} Command
- @findex -list-features
- @cindex supported @sc{gdb/mi} features, list
- Returns a list of particular features of the MI protocol that
- this version of gdb implements. A feature can be a command,
- or a new field in an output of some command, or even an
- important bugfix. While a frontend can sometimes detect presence
- of a feature at runtime, it is easier to perform detection at debugger
- startup.
- The command returns a list of strings, with each string naming an
- available feature. Each returned string is just a name, it does not
- have any internal structure. The list of possible feature names
- is given below.
- Example output:
- @smallexample
- (gdb) -list-features
- ^done,result=["feature1","feature2"]
- @end smallexample
- The current list of features is:
- @ftable @samp
- @item frozen-varobjs
- Indicates support for the @code{-var-set-frozen} command, as well
- as possible presence of the @code{frozen} field in the output
- of @code{-varobj-create}.
- @item pending-breakpoints
- Indicates support for the @option{-f} option to the @code{-break-insert}
- command.
- @item python
- Indicates Python scripting support, Python-based
- pretty-printing commands, and possible presence of the
- @samp{display_hint} field in the output of @code{-var-list-children}
- @item thread-info
- Indicates support for the @code{-thread-info} command.
- @item data-read-memory-bytes
- Indicates support for the @code{-data-read-memory-bytes} and the
- @code{-data-write-memory-bytes} commands.
- @item breakpoint-notifications
- Indicates that changes to breakpoints and breakpoints created via the
- CLI will be announced via async records.
- @item ada-task-info
- Indicates support for the @code{-ada-task-info} command.
- @item language-option
- Indicates that all @sc{gdb/mi} commands accept the @option{--language}
- option (@pxref{Context management}).
- @item info-gdb-mi-command
- Indicates support for the @code{-info-gdb-mi-command} command.
- @item undefined-command-error-code
- Indicates support for the "undefined-command" error code in error result
- records, produced when trying to execute an undefined @sc{gdb/mi} command
- (@pxref{GDB/MI Result Records}).
- @item exec-run-start-option
- Indicates that the @code{-exec-run} command supports the @option{--start}
- option (@pxref{GDB/MI Program Execution}).
- @item data-disassemble-a-option
- Indicates that the @code{-data-disassemble} command supports the @option{-a}
- option (@pxref{GDB/MI Data Manipulation}).
- @end ftable
- @subheading The @code{-list-target-features} Command
- @findex -list-target-features
- Returns a list of particular features that are supported by the
- target. Those features affect the permitted MI commands, but
- unlike the features reported by the @code{-list-features} command, the
- features depend on which target GDB is using at the moment. Whenever
- a target can change, due to commands such as @code{-target-select},
- @code{-target-attach} or @code{-exec-run}, the list of target features
- may change, and the frontend should obtain it again.
- Example output:
- @smallexample
- (gdb) -list-target-features
- ^done,result=["async"]
- @end smallexample
- The current list of features is:
- @table @samp
- @item async
- Indicates that the target is capable of asynchronous command
- execution, which means that @value{GDBN} will accept further commands
- while the target is running.
- @item reverse
- Indicates that the target is capable of reverse execution.
- @xref{Reverse Execution}, for more information.
- @end table
- @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- @node GDB/MI Miscellaneous Commands
- @section Miscellaneous @sc{gdb/mi} Commands
- @c @subheading -gdb-complete
- @subheading The @code{-gdb-exit} Command
- @findex -gdb-exit
- @subsubheading Synopsis
- @smallexample
- -gdb-exit
- @end smallexample
- Exit @value{GDBN} immediately.
- @subsubheading @value{GDBN} Command
- Approximately corresponds to @samp{quit}.
- @subsubheading Example
- @smallexample
- (gdb)
- -gdb-exit
- ^exit
- @end smallexample
- @ignore
- @subheading The @code{-exec-abort} Command
- @findex -exec-abort
- @subsubheading Synopsis
- @smallexample
- -exec-abort
- @end smallexample
- Kill the inferior running program.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{kill}.
- @subsubheading Example
- N.A.
- @end ignore
- @subheading The @code{-gdb-set} Command
- @findex -gdb-set
- @subsubheading Synopsis
- @smallexample
- -gdb-set
- @end smallexample
- Set an internal @value{GDBN} variable.
- @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{set}.
- @subsubheading Example
- @smallexample
- (gdb)
- -gdb-set $foo=3
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-gdb-show} Command
- @findex -gdb-show
- @subsubheading Synopsis
- @smallexample
- -gdb-show
- @end smallexample
- Show the current value of a @value{GDBN} variable.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{show}.
- @subsubheading Example
- @smallexample
- (gdb)
- -gdb-show annotate
- ^done,value="0"
- (gdb)
- @end smallexample
- @c @subheading -gdb-source
- @subheading The @code{-gdb-version} Command
- @findex -gdb-version
- @subsubheading Synopsis
- @smallexample
- -gdb-version
- @end smallexample
- Show version information for @value{GDBN}. Used mostly in testing.
- @subsubheading @value{GDBN} Command
- The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by
- default shows this information when you start an interactive session.
- @subsubheading Example
- @c This example modifies the actual output from GDB to avoid overfull
- @c box in TeX.
- @smallexample
- (gdb)
- -gdb-version
- ~GNU gdb 5.2.1
- ~Copyright 2000 Free Software Foundation, Inc.
- ~GDB is free software, covered by the GNU General Public License, and
- ~you are welcome to change it and/or distribute copies of it under
- ~ certain conditions.
- ~Type "show copying" to see the conditions.
- ~There is absolutely no warranty for GDB. Type "show warranty" for
- ~ details.
- ~This GDB was configured as
- "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-list-thread-groups} Command
- @findex -list-thread-groups
- @subheading Synopsis
- @smallexample
- -list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ]
- @end smallexample
- Lists thread groups (@pxref{Thread groups}). When a single thread
- group is passed as the argument, lists the children of that group.
- When several thread group are passed, lists information about those
- thread groups. Without any parameters, lists information about all
- top-level thread groups.
- Normally, thread groups that are being debugged are reported.
- With the @samp{--available} option, @value{GDBN} reports thread groups
- available on the target.
- The output of this command may have either a @samp{threads} result or
- a @samp{groups} result. The @samp{thread} result has a list of tuples
- as value, with each tuple describing a thread (@pxref{GDB/MI Thread
- Information}). The @samp{groups} result has a list of tuples as value,
- each tuple describing a thread group. If top-level groups are
- requested (that is, no parameter is passed), or when several groups
- are passed, the output always has a @samp{groups} result. The format
- of the @samp{group} result is described below.
- To reduce the number of roundtrips it's possible to list thread groups
- together with their children, by passing the @samp{--recurse} option
- and the recursion depth. Presently, only recursion depth of 1 is
- permitted. If this option is present, then every reported thread group
- will also include its children, either as @samp{group} or
- @samp{threads} field.
- In general, any combination of option and parameters is permitted, with
- the following caveats:
- @itemize @bullet
- @item
- When a single thread group is passed, the output will typically
- be the @samp{threads} result. Because threads may not contain
- anything, the @samp{recurse} option will be ignored.
- @item
- When the @samp{--available} option is passed, limited information may
- be available. In particular, the list of threads of a process might
- be inaccessible. Further, specifying specific thread groups might
- not give any performance advantage over listing all thread groups.
- The frontend should assume that @samp{-list-thread-groups --available}
- is always an expensive operation and cache the results.
- @end itemize
- The @samp{groups} result is a list of tuples, where each tuple may
- have the following fields:
- @table @code
- @item id
- Identifier of the thread group. This field is always present.
- The identifier is an opaque string; frontends should not try to
- convert it to an integer, even though it might look like one.
- @item type
- The type of the thread group. At present, only @samp{process} is a
- valid type.
- @item pid
- The target-specific process identifier. This field is only present
- for thread groups of type @samp{process} and only if the process exists.
- @item exit-code
- The exit code of this group's last exited thread, formatted in octal.
- This field is only present for thread groups of type @samp{process} and
- only if the process is not running.
- @item num_children
- The number of children this thread group has. This field may be
- absent for an available thread group.
- @item threads
- This field has a list of tuples as value, each tuple describing a
- thread. It may be present if the @samp{--recurse} option is
- specified, and it's actually possible to obtain the threads.
- @item cores
- This field is a list of integers, each identifying a core that one
- thread of the group is running on. This field may be absent if
- such information is not available.
- @item executable
- The name of the executable file that corresponds to this thread group.
- The field is only present for thread groups of type @samp{process},
- and only if there is a corresponding executable file.
- @end table
- @subheading Example
- @smallexample
- (@value{GDBP})
- -list-thread-groups
- ^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
- -list-thread-groups 17
- ^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
- frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
- @{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
- frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
- file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},state="running"@}]]
- -list-thread-groups --available
- ^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}]
- -list-thread-groups --available --recurse 1
- ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
- threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
- @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..]
- -list-thread-groups --available --recurse 1 17 18
- ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
- threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
- @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
- @end smallexample
- @subheading The @code{-info-os} Command
- @findex -info-os
- @subsubheading Synopsis
- @smallexample
- -info-os [ @var{type} ]
- @end smallexample
- If no argument is supplied, the command returns a table of available
- operating-system-specific information types. If one of these types is
- supplied as an argument @var{type}, then the command returns a table
- of data of that type.
- The types of information available depend on the target operating
- system.
- @subsubheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{info os}.
- @subsubheading Example
- When run on a @sc{gnu}/Linux system, the output will look something
- like this:
- @smallexample
- (@value{GDBP})
- -info-os
- ^done,OSDataTable=@{nr_rows="10",nr_cols="3",
- hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@},
- @{width="10",alignment="-1",col_name="col1",colhdr="Description"@},
- @{width="10",alignment="-1",col_name="col2",colhdr="Title"@}],
- body=[item=@{col0="cpus",col1="Listing of all cpus/cores on the system",
- col2="CPUs"@},
- item=@{col0="files",col1="Listing of all file descriptors",
- col2="File descriptors"@},
- item=@{col0="modules",col1="Listing of all loaded kernel modules",
- col2="Kernel modules"@},
- item=@{col0="msg",col1="Listing of all message queues",
- col2="Message queues"@},
- item=@{col0="processes",col1="Listing of all processes",
- col2="Processes"@},
- item=@{col0="procgroups",col1="Listing of all process groups",
- col2="Process groups"@},
- item=@{col0="semaphores",col1="Listing of all semaphores",
- col2="Semaphores"@},
- item=@{col0="shm",col1="Listing of all shared-memory regions",
- col2="Shared-memory regions"@},
- item=@{col0="sockets",col1="Listing of all internet-domain sockets",
- col2="Sockets"@},
- item=@{col0="threads",col1="Listing of all threads",
- col2="Threads"@}]
- (@value{GDBP})
- -info-os processes
- ^done,OSDataTable=@{nr_rows="190",nr_cols="4",
- hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="pid"@},
- @{width="10",alignment="-1",col_name="col1",colhdr="user"@},
- @{width="10",alignment="-1",col_name="col2",colhdr="command"@},
- @{width="10",alignment="-1",col_name="col3",colhdr="cores"@}],
- body=[item=@{col0="1",col1="root",col2="/sbin/init",col3="0"@},
- item=@{col0="2",col1="root",col2="[kthreadd]",col3="1"@},
- item=@{col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"@},
- ...
- item=@{col0="26446",col1="stan",col2="bash",col3="0"@},
- item=@{col0="28152",col1="stan",col2="bash",col3="1"@}]@}
- (@value{GDBP})
- @end smallexample
- (Note that the MI output here includes a @code{"Title"} column that
- does not appear in command-line @code{info os}; this column is useful
- for MI clients that want to enumerate the types of data, such as in a
- popup menu, but is needless clutter on the command line, and
- @code{info os} omits it.)
- @subheading The @code{-add-inferior} Command
- @findex -add-inferior
- @subheading Synopsis
- @smallexample
- -add-inferior [ --no-connection ]
- @end smallexample
- Creates a new inferior (@pxref{Inferiors Connections and Programs}). The created
- inferior is not associated with any executable. Such association may
- be established with the @samp{-file-exec-and-symbols} command
- (@pxref{GDB/MI File Commands}).
- By default, the new inferior begins connected to the same target
- connection as the current inferior. For example, if the current
- inferior was connected to @code{gdbserver} with @code{target remote},
- then the new inferior will be connected to the same @code{gdbserver}
- instance. The @samp{--no-connection} option starts the new inferior
- with no connection yet. You can then for example use the
- @code{-target-select remote} command to connect to some other
- @code{gdbserver} instance, use @code{-exec-run} to spawn a local
- program, etc.
- The command response always has a field, @var{inferior}, whose value
- is the identifier of the thread group corresponding to the new
- inferior.
- An additional section field, @var{connection}, is optional. This
- field will only exist if the new inferior has a target connection. If
- this field exists, then its value will be a tuple containing the
- following fields:
- @table @samp
- @item number
- The number of the connection used for the new inferior.
- @item name
- The name of the connection type used for the new inferior.
- @end table
- @subheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{add-inferior}
- (@pxref{add_inferior_cli,,@samp{add-inferior}}).
- @subheading Example
- @smallexample
- (@value{GDBP})
- -add-inferior
- ^done,inferior="i3"
- @end smallexample
- @subheading The @code{-interpreter-exec} Command
- @findex -interpreter-exec
- @subheading Synopsis
- @smallexample
- -interpreter-exec @var{interpreter} @var{command}
- @end smallexample
- @anchor{-interpreter-exec}
- Execute the specified @var{command} in the given @var{interpreter}.
- @subheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{interpreter-exec}.
- @subheading Example
- @smallexample
- (gdb)
- -interpreter-exec console "break main"
- &"During symbol reading, couldn't parse type; debugger out of date?.\n"
- &"During symbol reading, bad structure-type format.\n"
- ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-inferior-tty-set} Command
- @findex -inferior-tty-set
- @subheading Synopsis
- @smallexample
- -inferior-tty-set /dev/pts/1
- @end smallexample
- Set terminal for future runs of the program being debugged.
- @subheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1.
- @subheading Example
- @smallexample
- (gdb)
- -inferior-tty-set /dev/pts/1
- ^done
- (gdb)
- @end smallexample
- @subheading The @code{-inferior-tty-show} Command
- @findex -inferior-tty-show
- @subheading Synopsis
- @smallexample
- -inferior-tty-show
- @end smallexample
- Show terminal for future runs of program being debugged.
- @subheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{show inferior-tty}.
- @subheading Example
- @smallexample
- (gdb)
- -inferior-tty-set /dev/pts/1
- ^done
- (gdb)
- -inferior-tty-show
- ^done,inferior_tty_terminal="/dev/pts/1"
- (gdb)
- @end smallexample
- @subheading The @code{-enable-timings} Command
- @findex -enable-timings
- @subheading Synopsis
- @smallexample
- -enable-timings [yes | no]
- @end smallexample
- Toggle the printing of the wallclock, user and system times for an MI
- command as a field in its output. This command is to help frontend
- developers optimize the performance of their code. No argument is
- equivalent to @samp{yes}.
- @subheading @value{GDBN} Command
- No equivalent.
- @subheading Example
- @smallexample
- (gdb)
- -enable-timings
- ^done
- (gdb)
- -break-insert main
- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
- addr="0x080484ed",func="main",file="myprog.c",
- fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"],
- times="0"@},
- time=@{wallclock="0.05185",user="0.00800",system="0.00000"@}
- (gdb)
- -enable-timings no
- ^done
- (gdb)
- -exec-run
- ^running
- (gdb)
- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
- frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@},
- @{name="argv",value="0xbfb60364"@}],file="myprog.c",
- fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"@}
- (gdb)
- @end smallexample
- @subheading The @code{-complete} Command
- @findex -complete
- @subheading Synopsis
- @smallexample
- -complete @var{command}
- @end smallexample
- Show a list of completions for partially typed CLI @var{command}.
- This command is intended for @sc{gdb/mi} frontends that cannot use two separate
- CLI and MI channels --- for example: because of lack of PTYs like on Windows or
- because @value{GDBN} is used remotely via a SSH connection.
- @subheading Result
- The result consists of two or three fields:
- @table @samp
- @item completion
- This field contains the completed @var{command}. If @var{command}
- has no known completions, this field is omitted.
- @item matches
- This field contains a (possibly empty) array of matches. It is always present.
- @item max_completions_reached
- This field contains @code{1} if number of known completions is above
- @code{max-completions} limit (@pxref{Completion}), otherwise it contains
- @code{0}. It is always present.
- @end table
- @subheading @value{GDBN} Command
- The corresponding @value{GDBN} command is @samp{complete}.
- @subheading Example
- @smallexample
- (gdb)
- -complete br
- ^done,completion="break",
- matches=["break","break-range"],
- max_completions_reached="0"
- (gdb)
- -complete "b ma"
- ^done,completion="b ma",
- matches=["b madvise","b main"],max_completions_reached="0"
- (gdb)
- -complete "b push_b"
- ^done,completion="b push_back(",
- matches=[
- "b A::push_back(void*)",
- "b std::string::push_back(char)",
- "b std::vector<int, std::allocator<int> >::push_back(int&&)"],
- max_completions_reached="0"
- (gdb)
- -complete "nonexist"
- ^done,matches=[],max_completions_reached="0"
- (gdb)
- @end smallexample
- @node Annotations
- @chapter @value{GDBN} Annotations
- This chapter describes annotations in @value{GDBN}. Annotations were
- designed to interface @value{GDBN} to graphical user interfaces or other
- similar programs which want to interact with @value{GDBN} at a
- relatively high level.
- The annotation mechanism has largely been superseded by @sc{gdb/mi}
- (@pxref{GDB/MI}).
- @ignore
- This is Edition @value{EDITION}, @value{DATE}.
- @end ignore
- @menu
- * Annotations Overview:: What annotations are; the general syntax.
- * Server Prefix:: Issuing a command without affecting user state.
- * Prompting:: Annotations marking @value{GDBN}'s need for input.
- * Errors:: Annotations for error messages.
- * Invalidation:: Some annotations describe things now invalid.
- * Annotations for Running::
- Whether the program is running, how it stopped, etc.
- * Source Annotations:: Annotations describing source code.
- @end menu
- @node Annotations Overview
- @section What is an Annotation?
- @cindex annotations
- Annotations start with a newline character, two @samp{control-z}
- characters, and the name of the annotation. If there is no additional
- information associated with this annotation, the name of the annotation
- is followed immediately by a newline. If there is additional
- information, the name of the annotation is followed by a space, the
- additional information, and a newline. The additional information
- cannot contain newline characters.
- Any output not beginning with a newline and two @samp{control-z}
- characters denotes literal output from @value{GDBN}. Currently there is
- no need for @value{GDBN} to output a newline followed by two
- @samp{control-z} characters, but if there was such a need, the
- annotations could be extended with an @samp{escape} annotation which
- means those three characters as output.
- The annotation @var{level}, which is specified using the
- @option{--annotate} command line option (@pxref{Mode Options}), controls
- how much information @value{GDBN} prints together with its prompt,
- values of expressions, source lines, and other types of output. Level 0
- is for no annotations, level 1 is for use when @value{GDBN} is run as a
- subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
- for programs that control @value{GDBN}, and level 2 annotations have
- been made obsolete (@pxref{Limitations, , Limitations of the Annotation
- Interface, annotate, GDB's Obsolete Annotations}).
- @table @code
- @kindex set annotate
- @item set annotate @var{level}
- The @value{GDBN} command @code{set annotate} sets the level of
- annotations to the specified @var{level}.
- @item show annotate
- @kindex show annotate
- Show the current annotation level.
- @end table
- This chapter describes level 3 annotations.
- A simple example of starting up @value{GDBN} with annotations is:
- @smallexample
- $ @kbd{gdb --annotate=3}
- GNU gdb 6.0
- Copyright 2003 Free Software Foundation, Inc.
- GDB is free software, covered by the GNU General Public License,
- and you are welcome to change it and/or distribute copies of it
- under certain conditions.
- Type "show copying" to see the conditions.
- There is absolutely no warranty for GDB. Type "show warranty"
- for details.
- This GDB was configured as "i386-pc-linux-gnu"
- ^Z^Zpre-prompt
- (@value{GDBP})
- ^Z^Zprompt
- @kbd{quit}
- ^Z^Zpost-prompt
- $
- @end smallexample
- Here @samp{quit} is input to @value{GDBN}; the rest is output from
- @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
- denotes a @samp{control-z} character) are annotations; the rest is
- output from @value{GDBN}.
- @node Server Prefix
- @section The Server Prefix
- @cindex server prefix
- If you prefix a command with @samp{server } then it will not affect
- the command history, nor will it affect @value{GDBN}'s notion of which
- command to repeat if @key{RET} is pressed on a line by itself. This
- means that commands can be run behind a user's back by a front-end in
- a transparent manner.
- The @code{server } prefix does not affect the recording of values into
- the value history; to print a value without recording it into the
- value history, use the @code{output} command instead of the
- @code{print} command.
- Using this prefix also disables confirmation requests
- (@pxref{confirmation requests}).
- @node Prompting
- @section Annotation for @value{GDBN} Input
- @cindex annotations for prompts
- When @value{GDBN} prompts for input, it annotates this fact so it is possible
- to know when to send output, when the output from a given command is
- over, etc.
- Different kinds of input each have a different @dfn{input type}. Each
- input type has three annotations: a @code{pre-} annotation, which
- denotes the beginning of any prompt which is being output, a plain
- annotation, which denotes the end of the prompt, and then a @code{post-}
- annotation which denotes the end of any echo which may (or may not) be
- associated with the input. For example, the @code{prompt} input type
- features the following annotations:
- @smallexample
- ^Z^Zpre-prompt
- ^Z^Zprompt
- ^Z^Zpost-prompt
- @end smallexample
- The input types are
- @table @code
- @findex pre-prompt annotation
- @findex prompt annotation
- @findex post-prompt annotation
- @item prompt
- When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
- @findex pre-commands annotation
- @findex commands annotation
- @findex post-commands annotation
- @item commands
- When @value{GDBN} prompts for a set of commands, like in the @code{commands}
- command. The annotations are repeated for each command which is input.
- @findex pre-overload-choice annotation
- @findex overload-choice annotation
- @findex post-overload-choice annotation
- @item overload-choice
- When @value{GDBN} wants the user to select between various overloaded functions.
- @findex pre-query annotation
- @findex query annotation
- @findex post-query annotation
- @item query
- When @value{GDBN} wants the user to confirm a potentially dangerous operation.
- @findex pre-prompt-for-continue annotation
- @findex prompt-for-continue annotation
- @findex post-prompt-for-continue annotation
- @item prompt-for-continue
- When @value{GDBN} is asking the user to press return to continue. Note: Don't
- expect this to work well; instead use @code{set height 0} to disable
- prompting. This is because the counting of lines is buggy in the
- presence of annotations.
- @end table
- @node Errors
- @section Errors
- @cindex annotations for errors, warnings and interrupts
- @findex quit annotation
- @smallexample
- ^Z^Zquit
- @end smallexample
- This annotation occurs right before @value{GDBN} responds to an interrupt.
- @findex error annotation
- @smallexample
- ^Z^Zerror
- @end smallexample
- This annotation occurs right before @value{GDBN} responds to an error.
- Quit and error annotations indicate that any annotations which @value{GDBN} was
- in the middle of may end abruptly. For example, if a
- @code{value-history-begin} annotation is followed by a @code{error}, one
- cannot expect to receive the matching @code{value-history-end}. One
- cannot expect not to receive it either, however; an error annotation
- does not necessarily mean that @value{GDBN} is immediately returning all the way
- to the top level.
- @findex error-begin annotation
- A quit or error annotation may be preceded by
- @smallexample
- ^Z^Zerror-begin
- @end smallexample
- Any output between that and the quit or error annotation is the error
- message.
- Warning messages are not yet annotated.
- @c If we want to change that, need to fix warning(), type_error(),
- @c range_error(), and possibly other places.
- @node Invalidation
- @section Invalidation Notices
- @cindex annotations for invalidation messages
- The following annotations say that certain pieces of state may have
- changed.
- @table @code
- @findex frames-invalid annotation
- @item ^Z^Zframes-invalid
- The frames (for example, output from the @code{backtrace} command) may
- have changed.
- @findex breakpoints-invalid annotation
- @item ^Z^Zbreakpoints-invalid
- The breakpoints may have changed. For example, the user just added or
- deleted a breakpoint.
- @end table
- @node Annotations for Running
- @section Running the Program
- @cindex annotations for running programs
- @findex starting annotation
- @findex stopping annotation
- When the program starts executing due to a @value{GDBN} command such as
- @code{step} or @code{continue},
- @smallexample
- ^Z^Zstarting
- @end smallexample
- is output. When the program stops,
- @smallexample
- ^Z^Zstopped
- @end smallexample
- is output. Before the @code{stopped} annotation, a variety of
- annotations describe how the program stopped.
- @table @code
- @findex exited annotation
- @item ^Z^Zexited @var{exit-status}
- The program exited, and @var{exit-status} is the exit status (zero for
- successful exit, otherwise nonzero).
- @findex signalled annotation
- @findex signal-name annotation
- @findex signal-name-end annotation
- @findex signal-string annotation
- @findex signal-string-end annotation
- @item ^Z^Zsignalled
- The program exited with a signal. After the @code{^Z^Zsignalled}, the
- annotation continues:
- @smallexample
- @var{intro-text}
- ^Z^Zsignal-name
- @var{name}
- ^Z^Zsignal-name-end
- @var{middle-text}
- ^Z^Zsignal-string
- @var{string}
- ^Z^Zsignal-string-end
- @var{end-text}
- @end smallexample
- @noindent
- where @var{name} is the name of the signal, such as @code{SIGILL} or
- @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
- as @code{Illegal Instruction} or @code{Segmentation fault}. The arguments
- @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
- user's benefit and have no particular format.
- @findex signal annotation
- @item ^Z^Zsignal
- The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
- just saying that the program received the signal, not that it was
- terminated with it.
- @findex breakpoint annotation
- @item ^Z^Zbreakpoint @var{number}
- The program hit breakpoint number @var{number}.
- @findex watchpoint annotation
- @item ^Z^Zwatchpoint @var{number}
- The program hit watchpoint number @var{number}.
- @end table
- @node Source Annotations
- @section Displaying Source
- @cindex annotations for source display
- @findex source annotation
- The following annotation is used instead of displaying source code:
- @smallexample
- ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
- @end smallexample
- where @var{filename} is an absolute file name indicating which source
- file, @var{line} is the line number within that file (where 1 is the
- first line in the file), @var{character} is the character position
- within the file (where 0 is the first character in the file) (for most
- debug formats this will necessarily point to the beginning of a line),
- @var{middle} is @samp{middle} if @var{addr} is in the middle of the
- line, or @samp{beg} if @var{addr} is at the beginning of the line, and
- @var{addr} is the address in the target program associated with the
- source which is being displayed. The @var{addr} is in the form @samp{0x}
- followed by one or more lowercase hex digits (note that this does not
- depend on the language).
- @node JIT Interface
- @chapter JIT Compilation Interface
- @cindex just-in-time compilation
- @cindex JIT compilation interface
- This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation
- interface. A JIT compiler is a program or library that generates native
- executable code at runtime and executes it, usually in order to achieve good
- performance while maintaining platform independence.
- Programs that use JIT compilation are normally difficult to debug because
- portions of their code are generated at runtime, instead of being loaded from
- object files, which is where @value{GDBN} normally finds the program's symbols
- and debug information. In order to debug programs that use JIT compilation,
- @value{GDBN} has an interface that allows the program to register in-memory
- symbol files with @value{GDBN} at runtime.
- If you are using @value{GDBN} to debug a program that uses this interface, then
- it should work transparently so long as you have not stripped the binary. If
- you are developing a JIT compiler, then the interface is documented in the rest
- of this chapter. At this time, the only known client of this interface is the
- LLVM JIT.
- Broadly speaking, the JIT interface mirrors the dynamic loader interface. The
- JIT compiler communicates with @value{GDBN} by writing data into a global
- variable and calling a function at a well-known symbol. When @value{GDBN}
- attaches, it reads a linked list of symbol files from the global variable to
- find existing code, and puts a breakpoint in the function so that it can find
- out about additional code.
- @menu
- * Declarations:: Relevant C struct declarations
- * Registering Code:: Steps to register code
- * Unregistering Code:: Steps to unregister code
- * Custom Debug Info:: Emit debug information in a custom format
- @end menu
- @node Declarations
- @section JIT Declarations
- These are the relevant struct declarations that a C program should include to
- implement the interface:
- @smallexample
- typedef enum
- @{
- JIT_NOACTION = 0,
- JIT_REGISTER_FN,
- JIT_UNREGISTER_FN
- @} jit_actions_t;
- struct jit_code_entry
- @{
- struct jit_code_entry *next_entry;
- struct jit_code_entry *prev_entry;
- const char *symfile_addr;
- uint64_t symfile_size;
- @};
- struct jit_descriptor
- @{
- uint32_t version;
- /* This type should be jit_actions_t, but we use uint32_t
- to be explicit about the bitwidth. */
- uint32_t action_flag;
- struct jit_code_entry *relevant_entry;
- struct jit_code_entry *first_entry;
- @};
- /* GDB puts a breakpoint in this function. */
- void __attribute__((noinline)) __jit_debug_register_code() @{ @};
- /* Make sure to specify the version statically, because the
- debugger may check the version before we can set it. */
- struct jit_descriptor __jit_debug_descriptor = @{ 1, 0, 0, 0 @};
- @end smallexample
- If the JIT is multi-threaded, then it is important that the JIT synchronize any
- modifications to this global data properly, which can easily be done by putting
- a global mutex around modifications to these structures.
- @node Registering Code
- @section Registering Code
- To register code with @value{GDBN}, the JIT should follow this protocol:
- @itemize @bullet
- @item
- Generate an object file in memory with symbols and other desired debug
- information. The file must include the virtual addresses of the sections.
- @item
- Create a code entry for the file, which gives the start and size of the symbol
- file.
- @item
- Add it to the linked list in the JIT descriptor.
- @item
- Point the relevant_entry field of the descriptor at the entry.
- @item
- Set @code{action_flag} to @code{JIT_REGISTER} and call
- @code{__jit_debug_register_code}.
- @end itemize
- When @value{GDBN} is attached and the breakpoint fires, @value{GDBN} uses the
- @code{relevant_entry} pointer so it doesn't have to walk the list looking for
- new code. However, the linked list must still be maintained in order to allow
- @value{GDBN} to attach to a running process and still find the symbol files.
- @node Unregistering Code
- @section Unregistering Code
- If code is freed, then the JIT should use the following protocol:
- @itemize @bullet
- @item
- Remove the code entry corresponding to the code from the linked list.
- @item
- Point the @code{relevant_entry} field of the descriptor at the code entry.
- @item
- Set @code{action_flag} to @code{JIT_UNREGISTER} and call
- @code{__jit_debug_register_code}.
- @end itemize
- If the JIT frees or recompiles code without unregistering it, then @value{GDBN}
- and the JIT will leak the memory used for the associated symbol files.
- @node Custom Debug Info
- @section Custom Debug Info
- @cindex custom JIT debug info
- @cindex JIT debug info reader
- Generating debug information in platform-native file formats (like ELF
- or COFF) may be an overkill for JIT compilers; especially if all the
- debug info is used for is displaying a meaningful backtrace. The
- issue can be resolved by having the JIT writers decide on a debug info
- format and also provide a reader that parses the debug info generated
- by the JIT compiler. This section gives a brief overview on writing
- such a parser. More specific details can be found in the source file
- @file{gdb/jit-reader.in}, which is also installed as a header at
- @file{@var{includedir}/gdb/jit-reader.h} for easy inclusion.
- The reader is implemented as a shared object (so this functionality is
- not available on platforms which don't allow loading shared objects at
- runtime). Two @value{GDBN} commands, @code{jit-reader-load} and
- @code{jit-reader-unload} are provided, to be used to load and unload
- the readers from a preconfigured directory. Once loaded, the shared
- object is used the parse the debug information emitted by the JIT
- compiler.
- @menu
- * Using JIT Debug Info Readers:: How to use supplied readers correctly
- * Writing JIT Debug Info Readers:: Creating a debug-info reader
- @end menu
- @node Using JIT Debug Info Readers
- @subsection Using JIT Debug Info Readers
- @kindex jit-reader-load
- @kindex jit-reader-unload
- Readers can be loaded and unloaded using the @code{jit-reader-load}
- and @code{jit-reader-unload} commands.
- @table @code
- @item jit-reader-load @var{reader}
- Load the JIT reader named @var{reader}, which is a shared
- object specified as either an absolute or a relative file name. In
- the latter case, @value{GDBN} will try to load the reader from a
- pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX
- system (here @var{libdir} is the system library directory, often
- @file{/usr/local/lib}).
- Only one reader can be active at a time; trying to load a second
- reader when one is already loaded will result in @value{GDBN}
- reporting an error. A new JIT reader can be loaded by first unloading
- the current one using @code{jit-reader-unload} and then invoking
- @code{jit-reader-load}.
- @item jit-reader-unload
- Unload the currently loaded JIT reader.
- @end table
- @node Writing JIT Debug Info Readers
- @subsection Writing JIT Debug Info Readers
- @cindex writing JIT debug info readers
- As mentioned, a reader is essentially a shared object conforming to a
- certain ABI. This ABI is described in @file{jit-reader.h}.
- @file{jit-reader.h} defines the structures, macros and functions
- required to write a reader. It is installed (along with
- @value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is
- the system include directory.
- Readers need to be released under a GPL compatible license. A reader
- can be declared as released under such a license by placing the macro
- @code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file.
- The entry point for readers is the symbol @code{gdb_init_reader},
- which is expected to be a function with the prototype
- @findex gdb_init_reader
- @smallexample
- extern struct gdb_reader_funcs *gdb_init_reader (void);
- @end smallexample
- @cindex @code{struct gdb_reader_funcs}
- @code{struct gdb_reader_funcs} contains a set of pointers to callback
- functions. These functions are executed to read the debug info
- generated by the JIT compiler (@code{read}), to unwind stack frames
- (@code{unwind}) and to create canonical frame IDs
- (@code{get_frame_id}). It also has a callback that is called when the
- reader is being unloaded (@code{destroy}). The struct looks like this
- @smallexample
- struct gdb_reader_funcs
- @{
- /* Must be set to GDB_READER_INTERFACE_VERSION. */
- int reader_version;
- /* For use by the reader. */
- void *priv_data;
- gdb_read_debug_info *read;
- gdb_unwind_frame *unwind;
- gdb_get_frame_id *get_frame_id;
- gdb_destroy_reader *destroy;
- @};
- @end smallexample
- @cindex @code{struct gdb_symbol_callbacks}
- @cindex @code{struct gdb_unwind_callbacks}
- The callbacks are provided with another set of callbacks by
- @value{GDBN} to do their job. For @code{read}, these callbacks are
- passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind}
- and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}.
- @code{struct gdb_symbol_callbacks} has callbacks to create new object
- files and new symbol tables inside those object files. @code{struct
- gdb_unwind_callbacks} has callbacks to read registers off the current
- frame and to write out the values of the registers in the previous
- frame. Both have a callback (@code{target_read}) to read bytes off the
- target's address space.
- @node In-Process Agent
- @chapter In-Process Agent
- @cindex debugging agent
- The traditional debugging model is conceptually low-speed, but works fine,
- because most bugs can be reproduced in debugging-mode execution. However,
- as multi-core or many-core processors are becoming mainstream, and
- multi-threaded programs become more and more popular, there should be more
- and more bugs that only manifest themselves at normal-mode execution, for
- example, thread races, because debugger's interference with the program's
- timing may conceal the bugs. On the other hand, in some applications,
- it is not feasible for the debugger to interrupt the program's execution
- long enough for the developer to learn anything helpful about its behavior.
- If the program's correctness depends on its real-time behavior, delays
- introduced by a debugger might cause the program to fail, even when the
- code itself is correct. It is useful to be able to observe the program's
- behavior without interrupting it.
- Therefore, traditional debugging model is too intrusive to reproduce
- some bugs. In order to reduce the interference with the program, we can
- reduce the number of operations performed by debugger. The
- @dfn{In-Process Agent}, a shared library, is running within the same
- process with inferior, and is able to perform some debugging operations
- itself. As a result, debugger is only involved when necessary, and
- performance of debugging can be improved accordingly. Note that
- interference with program can be reduced but can't be removed completely,
- because the in-process agent will still stop or slow down the program.
- The in-process agent can interpret and execute Agent Expressions
- (@pxref{Agent Expressions}) during performing debugging operations. The
- agent expressions can be used for different purposes, such as collecting
- data in tracepoints, and condition evaluation in breakpoints.
- @anchor{Control Agent}
- You can control whether the in-process agent is used as an aid for
- debugging with the following commands:
- @table @code
- @kindex set agent on
- @item set agent on
- Causes the in-process agent to perform some operations on behalf of the
- debugger. Just which operations requested by the user will be done
- by the in-process agent depends on the its capabilities. For example,
- if you request to evaluate breakpoint conditions in the in-process agent,
- and the in-process agent has such capability as well, then breakpoint
- conditions will be evaluated in the in-process agent.
- @kindex set agent off
- @item set agent off
- Disables execution of debugging operations by the in-process agent. All
- of the operations will be performed by @value{GDBN}.
- @kindex show agent
- @item show agent
- Display the current setting of execution of debugging operations by
- the in-process agent.
- @end table
- @menu
- * In-Process Agent Protocol::
- @end menu
- @node In-Process Agent Protocol
- @section In-Process Agent Protocol
- @cindex in-process agent protocol
- The in-process agent is able to communicate with both @value{GDBN} and
- GDBserver (@pxref{In-Process Agent}). This section documents the protocol
- used for communications between @value{GDBN} or GDBserver and the IPA.
- In general, @value{GDBN} or GDBserver sends commands
- (@pxref{IPA Protocol Commands}) and data to in-process agent, and then
- in-process agent replies back with the return result of the command, or
- some other information. The data sent to in-process agent is composed
- of primitive data types, such as 4-byte or 8-byte type, and composite
- types, which are called objects (@pxref{IPA Protocol Objects}).
- @menu
- * IPA Protocol Objects::
- * IPA Protocol Commands::
- @end menu
- @node IPA Protocol Objects
- @subsection IPA Protocol Objects
- @cindex ipa protocol objects
- The commands sent to and results received from agent may contain some
- complex data types called @dfn{objects}.
- The in-process agent is running on the same machine with @value{GDBN}
- or GDBserver, so it doesn't have to handle as much differences between
- two ends as remote protocol (@pxref{Remote Protocol}) tries to handle.
- However, there are still some differences of two ends in two processes:
- @enumerate
- @item
- word size. On some 64-bit machines, @value{GDBN} or GDBserver can be
- compiled as a 64-bit executable, while in-process agent is a 32-bit one.
- @item
- ABI. Some machines may have multiple types of ABI, @value{GDBN} or
- GDBserver is compiled with one, and in-process agent is compiled with
- the other one.
- @end enumerate
- Here are the IPA Protocol Objects:
- @enumerate
- @item
- agent expression object. It represents an agent expression
- (@pxref{Agent Expressions}).
- @anchor{agent expression object}
- @item
- tracepoint action object. It represents a tracepoint action
- (@pxref{Tracepoint Actions,,Tracepoint Action Lists}) to collect registers,
- memory, static trace data and to evaluate expression.
- @anchor{tracepoint action object}
- @item
- tracepoint object. It represents a tracepoint (@pxref{Tracepoints}).
- @anchor{tracepoint object}
- @end enumerate
- The following table describes important attributes of each IPA protocol
- object:
- @multitable @columnfractions .30 .20 .50
- @headitem Name @tab Size @tab Description
- @item @emph{agent expression object} @tab @tab
- @item length @tab 4 @tab length of bytes code
- @item byte code @tab @var{length} @tab contents of byte code
- @item @emph{tracepoint action for collecting memory} @tab @tab
- @item 'M' @tab 1 @tab type of tracepoint action
- @item addr @tab 8 @tab if @var{basereg} is @samp{-1}, @var{addr} is the
- address of the lowest byte to collect, otherwise @var{addr} is the offset
- of @var{basereg} for memory collecting.
- @item len @tab 8 @tab length of memory for collecting
- @item basereg @tab 4 @tab the register number containing the starting
- memory address for collecting.
- @item @emph{tracepoint action for collecting registers} @tab @tab
- @item 'R' @tab 1 @tab type of tracepoint action
- @item @emph{tracepoint action for collecting static trace data} @tab @tab
- @item 'L' @tab 1 @tab type of tracepoint action
- @item @emph{tracepoint action for expression evaluation} @tab @tab
- @item 'X' @tab 1 @tab type of tracepoint action
- @item agent expression @tab length of @tab @ref{agent expression object}
- @item @emph{tracepoint object} @tab @tab
- @item number @tab 4 @tab number of tracepoint
- @item address @tab 8 @tab address of tracepoint inserted on
- @item type @tab 4 @tab type of tracepoint
- @item enabled @tab 1 @tab enable or disable of tracepoint
- @item step_count @tab 8 @tab step
- @item pass_count @tab 8 @tab pass
- @item numactions @tab 4 @tab number of tracepoint actions
- @item hit count @tab 8 @tab hit count
- @item trace frame usage @tab 8 @tab trace frame usage
- @item compiled_cond @tab 8 @tab compiled condition
- @item orig_size @tab 8 @tab orig size
- @item condition @tab 4 if condition is NULL otherwise length of
- @ref{agent expression object}
- @tab zero if condition is NULL, otherwise is
- @ref{agent expression object}
- @item actions @tab variable
- @tab numactions number of @ref{tracepoint action object}
- @end multitable
- @node IPA Protocol Commands
- @subsection IPA Protocol Commands
- @cindex ipa protocol commands
- The spaces in each command are delimiters to ease reading this commands
- specification. They don't exist in real commands.
- @table @samp
- @item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head}
- Installs a new fast tracepoint described by @var{tracepoint_object}
- (@pxref{tracepoint object}). The @var{gdb_jump_pad_head}, 8-byte long, is the
- head of @dfn{jumppad}, which is used to jump to data collection routine
- in IPA finally.
- Replies:
- @table @samp
- @item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump}
- @var{target_address} is address of tracepoint in the inferior.
- The @var{gdb_jump_pad_head} is updated head of jumppad. Both of
- @var{target_address} and @var{gdb_jump_pad_head} are 8-byte long.
- The @var{fjump} contains a sequence of instructions jump to jumppad entry.
- The @var{fjump_size}, 4-byte long, is the size of @var{fjump}.
- @item E @var{NN}
- for an error
- @end table
- @item close
- Closes the in-process agent. This command is sent when @value{GDBN} or GDBserver
- is about to kill inferiors.
- @item qTfSTM
- @xref{qTfSTM}.
- @item qTsSTM
- @xref{qTsSTM}.
- @item qTSTMat
- @xref{qTSTMat}.
- @item probe_marker_at:@var{address}
- Asks in-process agent to probe the marker at @var{address}.
- Replies:
- @table @samp
- @item E @var{NN}
- for an error
- @end table
- @item unprobe_marker_at:@var{address}
- Asks in-process agent to unprobe the marker at @var{address}.
- @end table
- @node GDB Bugs
- @chapter Reporting Bugs in @value{GDBN}
- @cindex bugs in @value{GDBN}
- @cindex reporting bugs in @value{GDBN}
- Your bug reports play an essential role in making @value{GDBN} reliable.
- Reporting a bug may help you by bringing a solution to your problem, or it
- may not. But in any case the principal function of a bug report is to help
- the entire community by making the next version of @value{GDBN} work better. Bug
- reports are your contribution to the maintenance of @value{GDBN}.
- In order for a bug report to serve its purpose, you must include the
- information that enables us to fix the bug.
- @menu
- * Bug Criteria:: Have you found a bug?
- * Bug Reporting:: How to report bugs
- @end menu
- @node Bug Criteria
- @section Have You Found a Bug?
- @cindex bug criteria
- If you are not sure whether you have found a bug, here are some guidelines:
- @itemize @bullet
- @cindex fatal signal
- @cindex debugger crash
- @cindex crash of debugger
- @item
- If the debugger gets a fatal signal, for any input whatever, that is a
- @value{GDBN} bug. Reliable debuggers never crash.
- @cindex error on valid input
- @item
- If @value{GDBN} produces an error message for valid input, that is a
- bug. (Note that if you're cross debugging, the problem may also be
- somewhere in the connection to the target.)
- @cindex invalid input
- @item
- If @value{GDBN} does not produce an error message for invalid input,
- that is a bug. However, you should note that your idea of
- ``invalid input'' might be our idea of ``an extension'' or ``support
- for traditional practice''.
- @item
- If you are an experienced user of debugging tools, your suggestions
- for improvement of @value{GDBN} are welcome in any case.
- @end itemize
- @node Bug Reporting
- @section How to Report Bugs
- @cindex bug reports
- @cindex @value{GDBN} bugs, reporting
- A number of companies and individuals offer support for @sc{gnu} products.
- If you obtained @value{GDBN} from a support organization, we recommend you
- contact that organization first.
- You can find contact information for many support companies and
- individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
- distribution.
- @c should add a web page ref...
- @ifset BUGURL
- @ifset BUGURL_DEFAULT
- In any event, we also recommend that you submit bug reports for
- @value{GDBN}. The preferred method is to submit them directly using
- @uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
- page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can
- be used.
- @strong{Do not send bug reports to @samp{info-gdb}, or to
- @samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
- not want to receive bug reports. Those that do have arranged to receive
- @samp{bug-gdb}.
- The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
- serves as a repeater. The mailing list and the newsgroup carry exactly
- the same messages. Often people think of posting bug reports to the
- newsgroup instead of mailing them. This appears to work, but it has one
- problem which can be crucial: a newsgroup posting often lacks a mail
- path back to the sender. Thus, if we need to ask for more information,
- we may be unable to reach you. For this reason, it is better to send
- bug reports to the mailing list.
- @end ifset
- @ifclear BUGURL_DEFAULT
- In any event, we also recommend that you submit bug reports for
- @value{GDBN} to @value{BUGURL}.
- @end ifclear
- @end ifset
- The fundamental principle of reporting bugs usefully is this:
- @strong{report all the facts}. If you are not sure whether to state a
- fact or leave it out, state it!
- Often people omit facts because they think they know what causes the
- problem and assume that some details do not matter. Thus, you might
- assume that the name of the variable you use in an example does not matter.
- Well, probably it does not, but one cannot be sure. Perhaps the bug is a
- stray memory reference which happens to fetch from the location where that
- name is stored in memory; perhaps, if the name were different, the contents
- of that location would fool the debugger into doing the right thing despite
- the bug. Play it safe and give a specific, complete example. That is the
- easiest thing for you to do, and the most helpful.
- Keep in mind that the purpose of a bug report is to enable us to fix the
- bug. It may be that the bug has been reported previously, but neither
- you nor we can know that unless your bug report is complete and
- self-contained.
- Sometimes people give a few sketchy facts and ask, ``Does this ring a
- bell?'' Those bug reports are useless, and we urge everyone to
- @emph{refuse to respond to them} except to chide the sender to report
- bugs properly.
- To enable us to fix the bug, you should include all these things:
- @itemize @bullet
- @item
- The version of @value{GDBN}. @value{GDBN} announces it if you start
- with no arguments; you can also print it at any time using @code{show
- version}.
- Without this, we will not know whether there is any point in looking for
- the bug in the current version of @value{GDBN}.
- @item
- The type of machine you are using, and the operating system name and
- version number.
- @item
- The details of the @value{GDBN} build-time configuration.
- @value{GDBN} shows these details if you invoke it with the
- @option{--configuration} command-line option, or if you type
- @code{show configuration} at @value{GDBN}'s prompt.
- @item
- What compiler (and its version) was used to compile @value{GDBN}---e.g.@:
- ``@value{GCC}--2.8.1''.
- @item
- What compiler (and its version) was used to compile the program you are
- debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
- C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version}
- to get this information; for other compilers, see the documentation for
- those compilers.
- @item
- The command arguments you gave the compiler to compile your example and
- observe the bug. For example, did you use @samp{-O}? To guarantee
- you will not omit something important, list them all. A copy of the
- Makefile (or the output from make) is sufficient.
- If we were to try to guess the arguments, we would probably guess wrong
- and then we might not encounter the bug.
- @item
- A complete input script, and all necessary source files, that will
- reproduce the bug.
- @item
- A description of what behavior you observe that you believe is
- incorrect. For example, ``It gets a fatal signal.''
- Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
- will certainly notice it. But if the bug is incorrect output, we might
- not notice unless it is glaringly wrong. You might as well not give us
- a chance to make a mistake.
- Even if the problem you experience is a fatal signal, you should still
- say so explicitly. Suppose something strange is going on, such as, your
- copy of @value{GDBN} is out of synch, or you have encountered a bug in
- the C library on your system. (This has happened!) Your copy might
- crash and ours would not. If you told us to expect a crash, then when
- ours fails to crash, we would know that the bug was not happening for
- us. If you had not told us to expect a crash, then we would not be able
- to draw any conclusion from our observations.
- @pindex script
- @cindex recording a session script
- To collect all this information, you can use a session recording program
- such as @command{script}, which is available on many Unix systems.
- Just run your @value{GDBN} session inside @command{script} and then
- include the @file{typescript} file with your bug report.
- Another way to record a @value{GDBN} session is to run @value{GDBN}
- inside Emacs and then save the entire buffer to a file.
- @item
- If you wish to suggest changes to the @value{GDBN} source, send us context
- diffs. If you even discuss something in the @value{GDBN} source, refer to
- it by context, not by line number.
- The line numbers in our development sources will not match those in your
- sources. Your line numbers would convey no useful information to us.
- @end itemize
- Here are some things that are not necessary:
- @itemize @bullet
- @item
- A description of the envelope of the bug.
- Often people who encounter a bug spend a lot of time investigating
- which changes to the input file will make the bug go away and which
- changes will not affect it.
- This is often time consuming and not very useful, because the way we
- will find the bug is by running a single example under the debugger
- with breakpoints, not by pure deduction from a series of examples.
- We recommend that you save your time for something else.
- Of course, if you can find a simpler example to report @emph{instead}
- of the original one, that is a convenience for us. Errors in the
- output will be easier to spot, running under the debugger will take
- less time, and so on.
- However, simplification is not vital; if you do not want to do this,
- report the bug anyway and send us the entire test case you used.
- @item
- A patch for the bug.
- A patch for the bug does help us if it is a good one. But do not omit
- the necessary information, such as the test case, on the assumption that
- a patch is all we need. We might see problems with your patch and decide
- to fix the problem another way, or we might not understand it at all.
- Sometimes with a program as complicated as @value{GDBN} it is very hard to
- construct an example that will make the program follow a certain path
- through the code. If you do not send us the example, we will not be able
- to construct one, so we will not be able to verify that the bug is fixed.
- And if we cannot understand what bug you are trying to fix, or why your
- patch should be an improvement, we will not install it. A test case will
- help us to understand.
- @item
- A guess about what the bug is or what it depends on.
- Such guesses are usually wrong. Even we cannot guess right about such
- things without first using the debugger to find the facts.
- @end itemize
- @c The readline documentation is distributed with the readline code
- @c and consists of the two following files:
- @c rluser.texi
- @c hsuser.texi
- @c Use -I with makeinfo to point to the appropriate directory,
- @c environment var TEXINPUTS with TeX.
- @ifclear SYSTEM_READLINE
- @include rluser.texi
- @include hsuser.texi
- @end ifclear
- @node In Memoriam
- @appendix In Memoriam
- The @value{GDBN} project mourns the loss of the following long-time
- contributors:
- @table @code
- @item Fred Fish
- Fred was a long-standing contributor to @value{GDBN} (1991-2006), and
- to Free Software in general. Outside of @value{GDBN}, he was known in
- the Amiga world for his series of Fish Disks, and the GeekGadget project.
- @item Michael Snyder
- Michael was one of the Global Maintainers of the @value{GDBN} project,
- with contributions recorded as early as 1996, until 2011. In addition
- to his day to day participation, he was a large driving force behind
- adding Reverse Debugging to @value{GDBN}.
- @end table
- Beyond their technical contributions to the project, they were also
- enjoyable members of the Free Software Community. We will miss them.
- @node Formatting Documentation
- @appendix Formatting Documentation
- @cindex @value{GDBN} reference card
- @cindex reference card
- The @value{GDBN} 4 release includes an already-formatted reference card, ready
- for printing with PostScript or Ghostscript, in the @file{gdb}
- subdirectory of the main source directory@footnote{In
- @file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
- release.}. If you can use PostScript or Ghostscript with your printer,
- you can print the reference card immediately with @file{refcard.ps}.
- The release also includes the source for the reference card. You
- can format it, using @TeX{}, by typing:
- @smallexample
- make refcard.dvi
- @end smallexample
- The @value{GDBN} reference card is designed to print in @dfn{landscape}
- mode on US ``letter'' size paper;
- that is, on a sheet 11 inches wide by 8.5 inches
- high. You will need to specify this form of printing as an option to
- your @sc{dvi} output program.
- @cindex documentation
- All the documentation for @value{GDBN} comes as part of the machine-readable
- distribution. The documentation is written in Texinfo format, which is
- a documentation system that uses a single source file to produce both
- on-line information and a printed manual. You can use one of the Info
- formatting commands to create the on-line version of the documentation
- and @TeX{} (or @code{texi2roff}) to typeset the printed version.
- @value{GDBN} includes an already formatted copy of the on-line Info
- version of this manual in the @file{gdb} subdirectory. The main Info
- file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
- subordinate files matching @samp{gdb.info*} in the same directory. If
- necessary, you can print out these files, or read them with any editor;
- but they are easier to read using the @code{info} subsystem in @sc{gnu}
- Emacs or the standalone @code{info} program, available as part of the
- @sc{gnu} Texinfo distribution.
- If you want to format these Info files yourself, you need one of the
- Info formatting programs, such as @code{texinfo-format-buffer} or
- @code{makeinfo}.
- If you have @code{makeinfo} installed, and are in the top level
- @value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
- version @value{GDBVN}), you can make the Info file by typing:
- @smallexample
- cd gdb
- make gdb.info
- @end smallexample
- If you want to typeset and print copies of this manual, you need @TeX{},
- a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
- Texinfo definitions file.
- @TeX{} is a typesetting program; it does not print files directly, but
- produces output files called @sc{dvi} files. To print a typeset
- document, you need a program to print @sc{dvi} files. If your system
- has @TeX{} installed, chances are it has such a program. The precise
- command to use depends on your system; @kbd{lpr -d} is common; another
- (for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
- require a file name without any extension or a @samp{.dvi} extension.
- @TeX{} also requires a macro definitions file called
- @file{texinfo.tex}. This file tells @TeX{} how to typeset a document
- written in Texinfo format. On its own, @TeX{} cannot either read or
- typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
- and is located in the @file{gdb-@var{version-number}/texinfo}
- directory.
- If you have @TeX{} and a @sc{dvi} printer program installed, you can
- typeset and print this manual. First switch to the @file{gdb}
- subdirectory of the main source directory (for example, to
- @file{gdb-@value{GDBVN}/gdb}) and type:
- @smallexample
- make gdb.dvi
- @end smallexample
- Then give @file{gdb.dvi} to your @sc{dvi} printing program.
- @node Installing GDB
- @appendix Installing @value{GDBN}
- @cindex installation
- @menu
- * Requirements:: Requirements for building @value{GDBN}
- * Running Configure:: Invoking the @value{GDBN} @file{configure} script
- * Separate Objdir:: Compiling @value{GDBN} in another directory
- * Config Names:: Specifying names for hosts and targets
- * Configure Options:: Summary of options for configure
- * System-wide configuration:: Having a system-wide init file
- @end menu
- @node Requirements
- @section Requirements for Building @value{GDBN}
- @cindex building @value{GDBN}, requirements for
- Building @value{GDBN} requires various tools and packages to be available.
- Other packages will be used only if they are found.
- @heading Tools/Packages Necessary for Building @value{GDBN}
- @table @asis
- @item C@t{++}11 compiler
- @value{GDBN} is written in C@t{++}11. It should be buildable with any
- recent C@t{++}11 compiler, e.g.@: GCC.
- @item GNU make
- @value{GDBN}'s build system relies on features only found in the GNU
- make program. Other variants of @code{make} will not work.
- @item GMP (The GNU Multiple Precision Arithmetic Library)
- @value{GDBN} now uses GMP to perform some of its arithmetics.
- This library may be included with your operating system distribution;
- if it is not, you can get the latest version from
- @url{https://gmplib.org/}. If GMP is installed at an unusual path,
- you can use the @option{--with-libgmp-prefix} option to specify
- its location.
- @end table
- @heading Tools/Packages Optional for Building @value{GDBN}
- @table @asis
- @item Expat
- @anchor{Expat}
- @value{GDBN} can use the Expat XML parsing library. This library may be
- included with your operating system distribution; if it is not, you
- can get the latest version from @url{http://expat.sourceforge.net}.
- The @file{configure} script will search for this library in several
- standard locations; if it is installed in an unusual path, you can
- use the @option{--with-libexpat-prefix} option to specify its location.
- Expat is used for:
- @itemize @bullet
- @item
- Remote protocol memory maps (@pxref{Memory Map Format})
- @item
- Target descriptions (@pxref{Target Descriptions})
- @item
- Remote shared library lists (@xref{Library List Format},
- or alternatively @pxref{Library List Format for SVR4 Targets})
- @item
- MS-Windows shared libraries (@pxref{Shared Libraries})
- @item
- Traceframe info (@pxref{Traceframe Info Format})
- @item
- Branch trace (@pxref{Branch Trace Format},
- @pxref{Branch Trace Configuration Format})
- @end itemize
- @item Guile
- @value{GDBN} can be scripted using GNU Guile. @xref{Guile}. By
- default, @value{GDBN} will be compiled if the Guile libraries are
- installed and are found by @file{configure}. You can use the
- @code{--with-guile} option to request Guile, and pass either the Guile
- version number or the file name of the relevant @code{pkg-config}
- program to choose a particular version of Guile.
- @item iconv
- @value{GDBN}'s features related to character sets (@pxref{Character
- Sets}) require a functioning @code{iconv} implementation. If you are
- on a GNU system, then this is provided by the GNU C Library. Some
- other systems also provide a working @code{iconv}.
- If @value{GDBN} is using the @code{iconv} program which is installed
- in a non-standard place, you will need to tell @value{GDBN} where to
- find it. This is done with @option{--with-iconv-bin} which specifies
- the directory that contains the @code{iconv} program. This program is
- run in order to make a list of the available character sets.
- On systems without @code{iconv}, you can install GNU Libiconv. If
- Libiconv is installed in a standard place, @value{GDBN} will
- automatically use it if it is needed. If you have previously
- installed Libiconv in a non-standard place, you can use the
- @option{--with-libiconv-prefix} option to @file{configure}.
- @value{GDBN}'s top-level @file{configure} and @file{Makefile} will
- arrange to build Libiconv if a directory named @file{libiconv} appears
- in the top-most source directory. If Libiconv is built this way, and
- if the operating system does not provide a suitable @code{iconv}
- implementation, then the just-built library will automatically be used
- by @value{GDBN}. One easy way to set this up is to download GNU
- Libiconv, unpack it inside the top-level directory of the @value{GDBN}
- source tree, and then rename the directory holding the Libiconv source
- code to @samp{libiconv}.
- @item lzma
- @value{GDBN} can support debugging sections that are compressed with
- the LZMA library. @xref{MiniDebugInfo}. If this library is not
- included with your operating system, you can find it in the xz package
- at @url{http://tukaani.org/xz/}. If the LZMA library is available in
- the usual place, then the @file{configure} script will use it
- automatically. If it is installed in an unusual path, you can use the
- @option{--with-liblzma-prefix} option to specify its location.
- @item MPFR
- @anchor{MPFR}
- @value{GDBN} can use the GNU MPFR multiple-precision floating-point
- library. This library may be included with your operating system
- distribution; if it is not, you can get the latest version from
- @url{http://www.mpfr.org}. The @file{configure} script will search
- for this library in several standard locations; if it is installed
- in an unusual path, you can use the @option{--with-libmpfr-prefix}
- option to specify its location.
- GNU MPFR is used to emulate target floating-point arithmetic during
- expression evaluation when the target uses different floating-point
- formats than the host. If GNU MPFR it is not available, @value{GDBN}
- will fall back to using host floating-point arithmetic.
- @item Python
- @value{GDBN} can be scripted using Python language. @xref{Python}.
- By default, @value{GDBN} will be compiled if the Python libraries are
- installed and are found by @file{configure}. You can use the
- @code{--with-python} option to request Python, and pass either the
- file name of the relevant @code{python} executable, or the name of the
- directory in which Python is installed, to choose a particular
- installation of Python.
- @item zlib
- @cindex compressed debug sections
- @value{GDBN} will use the @samp{zlib} library, if available, to read
- compressed debug sections. Some linkers, such as GNU gold, are capable
- of producing binaries with compressed debug sections. If @value{GDBN}
- is compiled with @samp{zlib}, it will be able to read the debug
- information in such binaries.
- The @samp{zlib} library is likely included with your operating system
- distribution; if it is not, you can get the latest version from
- @url{http://zlib.net}.
- @end table
- @node Running Configure
- @section Invoking the @value{GDBN} @file{configure} Script
- @cindex configuring @value{GDBN}
- @value{GDBN} comes with a @file{configure} script that automates the process
- of preparing @value{GDBN} for installation; you can then use @code{make} to
- build the @code{gdb} program.
- @iftex
- @c irrelevant in info file; it's as current as the code it lives with.
- @footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
- look at the @file{README} file in the sources; we may have improved the
- installation procedures since publishing this manual.}
- @end iftex
- The @value{GDBN} distribution includes all the source code you need for
- @value{GDBN} in a single directory, whose name is usually composed by
- appending the version number to @samp{gdb}.
- For example, the @value{GDBN} version @value{GDBVN} distribution is in the
- @file{gdb-@value{GDBVN}} directory. That directory contains:
- @table @code
- @item gdb-@value{GDBVN}/configure @r{(and supporting files)}
- script for configuring @value{GDBN} and all its supporting libraries
- @item gdb-@value{GDBVN}/gdb
- the source specific to @value{GDBN} itself
- @item gdb-@value{GDBVN}/bfd
- source for the Binary File Descriptor library
- @item gdb-@value{GDBVN}/include
- @sc{gnu} include files
- @item gdb-@value{GDBVN}/libiberty
- source for the @samp{-liberty} free software library
- @item gdb-@value{GDBVN}/opcodes
- source for the library of opcode tables and disassemblers
- @item gdb-@value{GDBVN}/readline
- source for the @sc{gnu} command-line interface
- @end table
- There may be other subdirectories as well.
- The simplest way to configure and build @value{GDBN} is to run @file{configure}
- from the @file{gdb-@var{version-number}} source directory, which in
- this example is the @file{gdb-@value{GDBVN}} directory.
- First switch to the @file{gdb-@var{version-number}} source directory
- if you are not already in it; then run @file{configure}. Pass the
- identifier for the platform on which @value{GDBN} will run as an
- argument.
- For example:
- @smallexample
- cd gdb-@value{GDBVN}
- ./configure
- make
- @end smallexample
- Running @samp{configure} and then running @code{make} builds the
- included supporting libraries, then @code{gdb} itself. The configured
- source files, and the binaries, are left in the corresponding source
- directories.
- @need 750
- @file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
- system does not recognize this automatically when you run a different
- shell, you may need to run @code{sh} on it explicitly:
- @smallexample
- sh configure
- @end smallexample
- You should run the @file{configure} script from the top directory in the
- source tree, the @file{gdb-@var{version-number}} directory. If you run
- @file{configure} from one of the subdirectories, you will configure only
- that subdirectory. That is usually not what you want. In particular,
- if you run the first @file{configure} from the @file{gdb} subdirectory
- of the @file{gdb-@var{version-number}} directory, you will omit the
- configuration of @file{bfd}, @file{readline}, and other sibling
- directories of the @file{gdb} subdirectory. This leads to build errors
- about missing include files such as @file{bfd/bfd.h}.
- You can install @code{@value{GDBN}} anywhere. The best way to do this
- is to pass the @code{--prefix} option to @code{configure}, and then
- install it with @code{make install}.
- @node Separate Objdir
- @section Compiling @value{GDBN} in Another Directory
- If you want to run @value{GDBN} versions for several host or target machines,
- you need a different @code{gdb} compiled for each combination of
- host and target. @file{configure} is designed to make this easy by
- allowing you to generate each configuration in a separate subdirectory,
- rather than in the source directory. If your @code{make} program
- handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
- @code{make} in each of these directories builds the @code{gdb}
- program specified there.
- To build @code{gdb} in a separate directory, run @file{configure}
- with the @samp{--srcdir} option to specify where to find the source.
- (You also need to specify a path to find @file{configure}
- itself from your working directory. If the path to @file{configure}
- would be the same as the argument to @samp{--srcdir}, you can leave out
- the @samp{--srcdir} option; it is assumed.)
- For example, with version @value{GDBVN}, you can build @value{GDBN} in a
- separate directory for a Sun 4 like this:
- @smallexample
- @group
- cd gdb-@value{GDBVN}
- mkdir ../gdb-sun4
- cd ../gdb-sun4
- ../gdb-@value{GDBVN}/configure
- make
- @end group
- @end smallexample
- When @file{configure} builds a configuration using a remote source
- directory, it creates a tree for the binaries with the same structure
- (and using the same names) as the tree under the source directory. In
- the example, you'd find the Sun 4 library @file{libiberty.a} in the
- directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
- @file{gdb-sun4/gdb}.
- Make sure that your path to the @file{configure} script has just one
- instance of @file{gdb} in it. If your path to @file{configure} looks
- like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only
- one subdirectory of @value{GDBN}, not the whole package. This leads to
- build errors about missing include files such as @file{bfd/bfd.h}.
- One popular reason to build several @value{GDBN} configurations in separate
- directories is to configure @value{GDBN} for cross-compiling (where
- @value{GDBN} runs on one machine---the @dfn{host}---while debugging
- programs that run on another machine---the @dfn{target}).
- You specify a cross-debugging target by
- giving the @samp{--target=@var{target}} option to @file{configure}.
- When you run @code{make} to build a program or library, you must run
- it in a configured directory---whatever directory you were in when you
- called @file{configure} (or one of its subdirectories).
- The @code{Makefile} that @file{configure} generates in each source
- directory also runs recursively. If you type @code{make} in a source
- directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
- directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
- will build all the required libraries, and then build GDB.
- When you have multiple hosts or targets configured in separate
- directories, you can run @code{make} on them in parallel (for example,
- if they are NFS-mounted on each of the hosts); they will not interfere
- with each other.
- @node Config Names
- @section Specifying Names for Hosts and Targets
- The specifications used for hosts and targets in the @file{configure}
- script are based on a three-part naming scheme, but some short predefined
- aliases are also supported. The full naming scheme encodes three pieces
- of information in the following pattern:
- @smallexample
- @var{architecture}-@var{vendor}-@var{os}
- @end smallexample
- For example, you can use the alias @code{sun4} as a @var{host} argument,
- or as the value for @var{target} in a @code{--target=@var{target}}
- option. The equivalent full name is @samp{sparc-sun-sunos4}.
- The @file{configure} script accompanying @value{GDBN} does not provide
- any query facility to list all supported host and target names or
- aliases. @file{configure} calls the Bourne shell script
- @code{config.sub} to map abbreviations to full names; you can read the
- script, if you wish, or you can use it to test your guesses on
- abbreviations---for example:
- @smallexample
- % sh config.sub i386-linux
- i386-pc-linux-gnu
- % sh config.sub alpha-linux
- alpha-unknown-linux-gnu
- % sh config.sub hp9k700
- hppa1.1-hp-hpux
- % sh config.sub sun4
- sparc-sun-sunos4.1.1
- % sh config.sub sun3
- m68k-sun-sunos4.1.1
- % sh config.sub i986v
- Invalid configuration `i986v': machine `i986v' not recognized
- @end smallexample
- @noindent
- @code{config.sub} is also distributed in the @value{GDBN} source
- directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
- @node Configure Options
- @section @file{configure} Options
- Here is a summary of the @file{configure} options and arguments that
- are most often useful for building @value{GDBN}. @file{configure}
- also has several other options not listed here. @xref{Running
- configure Scripts,,,autoconf}, for a full
- explanation of @file{configure}.
- @smallexample
- configure @r{[}--help@r{]}
- @r{[}--prefix=@var{dir}@r{]}
- @r{[}--exec-prefix=@var{dir}@r{]}
- @r{[}--srcdir=@var{dirname}@r{]}
- @r{[}--target=@var{target}@r{]}
- @end smallexample
- @noindent
- You may introduce options with a single @samp{-} rather than
- @samp{--} if you prefer; but you may abbreviate option names if you use
- @samp{--}.
- @table @code
- @item --help
- Display a quick summary of how to invoke @file{configure}.
- @item --prefix=@var{dir}
- Configure the source to install programs and files under directory
- @file{@var{dir}}.
- @item --exec-prefix=@var{dir}
- Configure the source to install programs under directory
- @file{@var{dir}}.
- @c avoid splitting the warning from the explanation:
- @need 2000
- @item --srcdir=@var{dirname}
- Use this option to make configurations in directories separate from the
- @value{GDBN} source directories. Among other things, you can use this to
- build (or maintain) several configurations simultaneously, in separate
- directories. @file{configure} writes configuration-specific files in
- the current directory, but arranges for them to use the source in the
- directory @var{dirname}. @file{configure} creates directories under
- the working directory in parallel to the source directories below
- @var{dirname}.
- @item --target=@var{target}
- Configure @value{GDBN} for cross-debugging programs running on the specified
- @var{target}. Without this option, @value{GDBN} is configured to debug
- programs that run on the same machine (@var{host}) as @value{GDBN} itself.
- There is no convenient way to generate a list of all available
- targets. Also see the @code{--enable-targets} option, below.
- @end table
- There are many other options that are specific to @value{GDBN}. This
- lists just the most common ones; there are some very specialized
- options not described here.
- @table @code
- @item --enable-targets=@r{[}@var{target}@r{]}@dots{}
- @itemx --enable-targets=all
- Configure @value{GDBN} for cross-debugging programs running on the
- specified list of targets. The special value @samp{all} configures
- @value{GDBN} for debugging programs running on any target it supports.
- @item --with-gdb-datadir=@var{path}
- Set the @value{GDBN}-specific data directory. @value{GDBN} will look
- here for certain supporting files or scripts. This defaults to the
- @file{gdb} subdirectory of @samp{datadir} (which can be set using
- @code{--datadir}).
- @item --with-relocated-sources=@var{dir}
- Sets up the default source path substitution rule so that directory
- names recorded in debug information will be automatically adjusted for
- any directory under @var{dir}. @var{dir} should be a subdirectory of
- @value{GDBN}'s configured prefix, the one mentioned in the
- @code{--prefix} or @code{--exec-prefix} options to configure. This
- option is useful if GDB is supposed to be moved to a different place
- after it is built.
- @item --enable-64-bit-bfd
- Enable 64-bit support in BFD on 32-bit hosts.
- @item --disable-gdbmi
- Build @value{GDBN} without the GDB/MI machine interface
- (@pxref{GDB/MI}).
- @item --enable-tui
- Build @value{GDBN} with the text-mode full-screen user interface
- (TUI). Requires a curses library (ncurses and cursesX are also
- supported).
- @item --with-curses
- Use the curses library instead of the termcap library, for text-mode
- terminal operations.
- @item --with-debuginfod
- Build @value{GDBN} with @file{libdebuginfod}, the @code{debuginfod} client
- library. Used to automatically fetch ELF, DWARF and source files from
- @code{debuginfod} servers using build IDs associated with any missing
- files. Enabled by default if @file{libdebuginfod} is installed and found
- at configure time. For more information regarding @code{debuginfod} see
- @ref{Debuginfod}.
- @item --with-libunwind-ia64
- Use the libunwind library for unwinding function call stack on ia64
- target platforms. See http://www.nongnu.org/libunwind/index.html for
- details.
- @item --with-system-readline
- Use the readline library installed on the host, rather than the
- library supplied as part of @value{GDBN}. Readline 7 or newer is
- required; this is enforced by the build system.
- @item --with-system-zlib
- Use the zlib library installed on the host, rather than the library
- supplied as part of @value{GDBN}.
- @item --with-expat
- Build @value{GDBN} with Expat, a library for XML parsing. (Done by
- default if libexpat is installed and found at configure time.) This
- library is used to read XML files supplied with @value{GDBN}. If it
- is unavailable, some features, such as remote protocol memory maps,
- target descriptions, and shared library lists, that are based on XML
- files, will not be available in @value{GDBN}. If your host does not
- have libexpat installed, you can get the latest version from
- `http://expat.sourceforge.net'.
- @item --with-libiconv-prefix@r{[}=@var{dir}@r{]}
- Build @value{GDBN} with GNU libiconv, a character set encoding
- conversion library. This is not done by default, as on GNU systems
- the @code{iconv} that is built in to the C library is sufficient. If
- your host does not have a working @code{iconv}, you can get the latest
- version of GNU iconv from `https://www.gnu.org/software/libiconv/'.
- @value{GDBN}'s build system also supports building GNU libiconv as
- part of the overall build. @xref{Requirements}.
- @item --with-lzma
- Build @value{GDBN} with LZMA, a compression library. (Done by default
- if liblzma is installed and found at configure time.) LZMA is used by
- @value{GDBN}'s "mini debuginfo" feature, which is only useful on
- platforms using the ELF object file format. If your host does not
- have liblzma installed, you can get the latest version from
- `https://tukaani.org/xz/'.
- @item --with-mpfr
- Build @value{GDBN} with GNU MPFR, a library for multiple-precision
- floating-point computation with correct rounding. (Done by default if
- GNU MPFR is installed and found at configure time.) This library is
- used to emulate target floating-point arithmetic during expression
- evaluation when the target uses different floating-point formats than
- the host. If GNU MPFR is not available, @value{GDBN} will fall back
- to using host floating-point arithmetic. If your host does not have
- GNU MPFR installed, you can get the latest version from
- `http://www.mpfr.org'.
- @item --with-python@r{[}=@var{python}@r{]}
- Build @value{GDBN} with Python scripting support. (Done by default if
- libpython is present and found at configure time.) Python makes
- @value{GDBN} scripting much more powerful than the restricted CLI
- scripting language. If your host does not have Python installed, you
- can find it on `http://www.python.org/download/'. The oldest version
- of Python supported by GDB is 2.6. The optional argument @var{python}
- is used to find the Python headers and libraries. It can be either
- the name of a Python executable, or the name of the directory in which
- Python is installed.
- @item --with-guile[=GUILE]'
- Build @value{GDBN} with GNU Guile scripting support. (Done by default
- if libguile is present and found at configure time.) If your host
- does not have Guile installed, you can find it at
- `https://www.gnu.org/software/guile/'. The optional argument GUILE
- can be a version number, which will cause @code{configure} to try to
- use that version of Guile; or the file name of a @code{pkg-config}
- executable, which will be queried to find the information needed to
- compile and link against Guile.
- @item --without-included-regex
- Don't use the regex library included with @value{GDBN} (as part of the
- libiberty library). This is the default on hosts with version 2 of
- the GNU C library.
- @item --with-sysroot=@var{dir}
- Use @var{dir} as the default system root directory for libraries whose
- file names begin with @file{/lib}' or @file{/usr/lib'}. (The value of
- @var{dir} can be modified at run time by using the @command{set
- sysroot} command.) If @var{dir} is under the @value{GDBN} configured
- prefix (set with @code{--prefix} or @code{--exec-prefix options}, the
- default system root will be automatically adjusted if and when
- @value{GDBN} is moved to a different location.
- @item --with-system-gdbinit=@var{file}
- Configure @value{GDBN} to automatically load a system-wide init file.
- @var{file} should be an absolute file name. If @var{file} is in a
- directory under the configured prefix, and @value{GDBN} is moved to
- another location after being built, the location of the system-wide
- init file will be adjusted accordingly.
- @item --with-system-gdbinit-dir=@var{directory}
- Configure @value{GDBN} to automatically load init files from a
- system-wide directory. @var{directory} should be an absolute directory
- name. If @var{directory} is in a directory under the configured
- prefix, and @value{GDBN} is moved to another location after being
- built, the location of the system-wide init directory will be
- adjusted accordingly.
- @item --enable-build-warnings
- When building the @value{GDBN} sources, ask the compiler to warn about
- any code which looks even vaguely suspicious. It passes many
- different warning flags, depending on the exact version of the
- compiler you are using.
- @item --enable-werror
- Treat compiler warnings as errors. It adds the @code{-Werror} flag
- to the compiler, which will fail the compilation if the compiler
- outputs any warning messages.
- @item --enable-ubsan
- Enable the GCC undefined behavior sanitizer. This is disabled by
- default, but passing @code{--enable-ubsan=yes} or
- @code{--enable-ubsan=auto} to @code{configure} will enable it. The
- undefined behavior sanitizer checks for C@t{++} undefined behavior.
- It has a performance cost, so if you are looking at @value{GDBN}'s
- performance, you should disable it. The undefined behavior sanitizer
- was first introduced in GCC 4.9.
- @end table
- @node System-wide configuration
- @section System-wide configuration and settings
- @cindex system-wide init file
- @value{GDBN} can be configured to have a system-wide init file and a
- system-wide init file directory; this file and files in that directory
- (if they have a recognized file extension) will be read and executed at
- startup (@pxref{Startup, , What @value{GDBN} does during startup}).
- Here are the corresponding configure options:
- @table @code
- @item --with-system-gdbinit=@var{file}
- Specify that the default location of the system-wide init file is
- @var{file}.
- @item --with-system-gdbinit-dir=@var{directory}
- Specify that the default location of the system-wide init file directory
- is @var{directory}.
- @end table
- If @value{GDBN} has been configured with the option @option{--prefix=$prefix},
- they may be subject to relocation. Two possible cases:
- @itemize @bullet
- @item
- If the default location of this init file/directory contains @file{$prefix},
- it will be subject to relocation. Suppose that the configure options
- are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit};
- if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system
- init file is looked for as @file{$install/etc/gdbinit} instead of
- @file{$prefix/etc/gdbinit}.
- @item
- By contrast, if the default location does not contain the prefix,
- it will not be relocated. E.g.@: if @value{GDBN} has been configured with
- @option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit},
- then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit},
- wherever @value{GDBN} is installed.
- @end itemize
- If the configured location of the system-wide init file (as given by the
- @option{--with-system-gdbinit} option at configure time) is in the
- data-directory (as specified by @option{--with-gdb-datadir} at configure
- time) or in one of its subdirectories, then @value{GDBN} will look for the
- system-wide init file in the directory specified by the
- @option{--data-directory} command-line option.
- Note that the system-wide init file is only read once, during @value{GDBN}
- initialization. If the data-directory is changed after @value{GDBN} has
- started with the @code{set data-directory} command, the file will not be
- reread.
- This applies similarly to the system-wide directory specified in
- @option{--with-system-gdbinit-dir}.
- Any supported scripting language can be used for these init files, as long
- as the file extension matches the scripting language. To be interpreted
- as regular @value{GDBN} commands, the files needs to have a @file{.gdb}
- extension.
- @menu
- * System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
- @end menu
- @node System-wide Configuration Scripts
- @subsection Installed System-wide Configuration Scripts
- @cindex system-wide configuration scripts
- The @file{system-gdbinit} directory, located inside the data-directory
- (as specified by @option{--with-gdb-datadir} at configure time) contains
- a number of scripts which can be used as system-wide init files. To
- automatically source those scripts at startup, @value{GDBN} should be
- configured with @option{--with-system-gdbinit}. Otherwise, any user
- should be able to source them by hand as needed.
- The following scripts are currently available:
- @itemize @bullet
- @item @file{elinos.py}
- @pindex elinos.py
- @cindex ELinOS system-wide configuration script
- This script is useful when debugging a program on an ELinOS target.
- It takes advantage of the environment variables defined in a standard
- ELinOS environment in order to determine the location of the system
- shared libraries, and then sets the @samp{solib-absolute-prefix}
- and @samp{solib-search-path} variables appropriately.
- @item @file{wrs-linux.py}
- @pindex wrs-linux.py
- @cindex Wind River Linux system-wide configuration script
- This script is useful when debugging a program on a target running
- Wind River Linux. It expects the @env{ENV_PREFIX} to be set to
- the host-side sysroot used by the target system.
- @end itemize
- @node Maintenance Commands
- @appendix Maintenance Commands
- @cindex maintenance commands
- @cindex internal commands
- In addition to commands intended for @value{GDBN} users, @value{GDBN}
- includes a number of commands intended for @value{GDBN} developers,
- that are not documented elsewhere in this manual. These commands are
- provided here for reference. (For commands that turn on debugging
- messages, see @ref{Debugging Output}.)
- @table @code
- @kindex maint agent
- @kindex maint agent-eval
- @item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression}
- @itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression}
- Translate the given @var{expression} into remote agent bytecodes.
- This command is useful for debugging the Agent Expression mechanism
- (@pxref{Agent Expressions}). The @samp{agent} version produces an
- expression useful for data collection, such as by tracepoints, while
- @samp{maint agent-eval} produces an expression that evaluates directly
- to a result. For instance, a collection expression for @code{globa +
- globb} will include bytecodes to record four bytes of memory at each
- of the addresses of @code{globa} and @code{globb}, while discarding
- the result of the addition, while an evaluation expression will do the
- addition and return the sum.
- If @code{-at} is given, generate remote agent bytecode for @var{location}.
- If not, generate remote agent bytecode for current frame PC address.
- @kindex maint agent-printf
- @item maint agent-printf @var{format},@var{expr},...
- Translate the given format string and list of argument expressions
- into remote agent bytecodes and display them as a disassembled list.
- This command is useful for debugging the agent version of dynamic
- printf (@pxref{Dynamic Printf}).
- @kindex maint info breakpoints
- @item @anchor{maint info breakpoints}maint info breakpoints
- Using the same format as @samp{info breakpoints}, display both the
- breakpoints you've set explicitly, and those @value{GDBN} is using for
- internal purposes. Internal breakpoints are shown with negative
- breakpoint numbers. The type column identifies what kind of breakpoint
- is shown:
- @table @code
- @item breakpoint
- Normal, explicitly set breakpoint.
- @item watchpoint
- Normal, explicitly set watchpoint.
- @item longjmp
- Internal breakpoint, used to handle correctly stepping through
- @code{longjmp} calls.
- @item longjmp resume
- Internal breakpoint at the target of a @code{longjmp}.
- @item until
- Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
- @item finish
- Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
- @item shlib events
- Shared library events.
- @end table
- @kindex maint info btrace
- @item maint info btrace
- Pint information about raw branch tracing data.
- @kindex maint btrace packet-history
- @item maint btrace packet-history
- Print the raw branch trace packets that are used to compute the
- execution history for the @samp{record btrace} command. Both the
- information and the format in which it is printed depend on the btrace
- recording format.
- @table @code
- @item bts
- For the BTS recording format, print a list of blocks of sequential
- code. For each block, the following information is printed:
- @table @asis
- @item Block number
- Newer blocks have higher numbers. The oldest block has number zero.
- @item Lowest @samp{PC}
- @item Highest @samp{PC}
- @end table
- @item pt
- For the Intel Processor Trace recording format, print a list of
- Intel Processor Trace packets. For each packet, the following
- information is printed:
- @table @asis
- @item Packet number
- Newer packets have higher numbers. The oldest packet has number zero.
- @item Trace offset
- The packet's offset in the trace stream.
- @item Packet opcode and payload
- @end table
- @end table
- @kindex maint btrace clear-packet-history
- @item maint btrace clear-packet-history
- Discards the cached packet history printed by the @samp{maint btrace
- packet-history} command. The history will be computed again when
- needed.
- @kindex maint btrace clear
- @item maint btrace clear
- Discard the branch trace data. The data will be fetched anew and the
- branch trace will be recomputed when needed.
- This implicitly truncates the branch trace to a single branch trace
- buffer. When updating branch trace incrementally, the branch trace
- available to @value{GDBN} may be bigger than a single branch trace
- buffer.
- @kindex maint set btrace pt skip-pad
- @item maint set btrace pt skip-pad
- @kindex maint show btrace pt skip-pad
- @item maint show btrace pt skip-pad
- Control whether @value{GDBN} will skip PAD packets when computing the
- packet history.
- @kindex maint info jit
- @item maint info jit
- Print information about JIT code objects loaded in the current inferior.
- @kindex set displaced-stepping
- @kindex show displaced-stepping
- @cindex displaced stepping support
- @cindex out-of-line single-stepping
- @item set displaced-stepping
- @itemx show displaced-stepping
- Control whether or not @value{GDBN} will do @dfn{displaced stepping}
- if the target supports it. Displaced stepping is a way to single-step
- over breakpoints without removing them from the inferior, by executing
- an out-of-line copy of the instruction that was originally at the
- breakpoint location. It is also known as out-of-line single-stepping.
- @table @code
- @item set displaced-stepping on
- If the target architecture supports it, @value{GDBN} will use
- displaced stepping to step over breakpoints.
- @item set displaced-stepping off
- @value{GDBN} will not use displaced stepping to step over breakpoints,
- even if such is supported by the target architecture.
- @cindex non-stop mode, and @samp{set displaced-stepping}
- @item set displaced-stepping auto
- This is the default mode. @value{GDBN} will use displaced stepping
- only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target
- architecture supports displaced stepping.
- @end table
- @kindex maint check-psymtabs
- @item maint check-psymtabs
- Check the consistency of currently expanded psymtabs versus symtabs.
- Use this to check, for example, whether a symbol is in one but not the other.
- @kindex maint check-symtabs
- @item maint check-symtabs
- Check the consistency of currently expanded symtabs.
- @kindex maint expand-symtabs
- @item maint expand-symtabs [@var{regexp}]
- Expand symbol tables.
- If @var{regexp} is specified, only expand symbol tables for file
- names matching @var{regexp}.
- @kindex maint set catch-demangler-crashes
- @kindex maint show catch-demangler-crashes
- @cindex demangler crashes
- @item maint set catch-demangler-crashes [on|off]
- @itemx maint show catch-demangler-crashes
- Control whether @value{GDBN} should attempt to catch crashes in the
- symbol name demangler. The default is to attempt to catch crashes.
- If enabled, the first time a crash is caught, a core file is created,
- the offending symbol is displayed and the user is presented with the
- option to terminate the current session.
- @kindex maint cplus first_component
- @item maint cplus first_component @var{name}
- Print the first C@t{++} class/namespace component of @var{name}.
- @kindex maint cplus namespace
- @item maint cplus namespace
- Print the list of possible C@t{++} namespaces.
- @kindex maint deprecate
- @kindex maint undeprecate
- @cindex deprecated commands
- @item maint deprecate @var{command} @r{[}@var{replacement}@r{]}
- @itemx maint undeprecate @var{command}
- Deprecate or undeprecate the named @var{command}. Deprecated commands
- cause @value{GDBN} to issue a warning when you use them. The optional
- argument @var{replacement} says which newer command should be used in
- favor of the deprecated one; if it is given, @value{GDBN} will mention
- the replacement as part of the warning.
- @kindex maint dump-me
- @item maint dump-me
- @cindex @code{SIGQUIT} signal, dump core of @value{GDBN}
- Cause a fatal signal in the debugger and force it to dump its core.
- This is supported only on systems which support aborting a program
- with the @code{SIGQUIT} signal.
- @kindex maint internal-error
- @kindex maint internal-warning
- @kindex maint demangler-warning
- @cindex demangler crashes
- @item maint internal-error @r{[}@var{message-text}@r{]}
- @itemx maint internal-warning @r{[}@var{message-text}@r{]}
- @itemx maint demangler-warning @r{[}@var{message-text}@r{]}
- Cause @value{GDBN} to call the internal function @code{internal_error},
- @code{internal_warning} or @code{demangler_warning} and hence behave
- as though an internal problem has been detected. In addition to
- reporting the internal problem, these functions give the user the
- opportunity to either quit @value{GDBN} or (for @code{internal_error}
- and @code{internal_warning}) create a core file of the current
- @value{GDBN} session.
- These commands take an optional parameter @var{message-text} that is
- used as the text of the error or warning message.
- Here's an example of using @code{internal-error}:
- @smallexample
- (@value{GDBP}) @kbd{maint internal-error testing, 1, 2}
- @dots{}/maint.c:121: internal-error: testing, 1, 2
- A problem internal to GDB has been detected. Further
- debugging may prove unreliable.
- Quit this debugging session? (y or n) @kbd{n}
- Create a core file? (y or n) @kbd{n}
- (@value{GDBP})
- @end smallexample
- @cindex @value{GDBN} internal error
- @cindex internal errors, control of @value{GDBN} behavior
- @cindex demangler crashes
- @kindex maint set internal-error
- @kindex maint show internal-error
- @kindex maint set internal-warning
- @kindex maint show internal-warning
- @kindex maint set demangler-warning
- @kindex maint show demangler-warning
- @item maint set internal-error @var{action} [ask|yes|no]
- @itemx maint show internal-error @var{action}
- @itemx maint set internal-warning @var{action} [ask|yes|no]
- @itemx maint show internal-warning @var{action}
- @itemx maint set demangler-warning @var{action} [ask|yes|no]
- @itemx maint show demangler-warning @var{action}
- When @value{GDBN} reports an internal problem (error or warning) it
- gives the user the opportunity to both quit @value{GDBN} and create a
- core file of the current @value{GDBN} session. These commands let you
- override the default behaviour for each particular @var{action},
- described in the table below.
- @table @samp
- @item quit
- You can specify that @value{GDBN} should always (yes) or never (no)
- quit. The default is to ask the user what to do.
- @item corefile
- You can specify that @value{GDBN} should always (yes) or never (no)
- create a core file. The default is to ask the user what to do. Note
- that there is no @code{corefile} option for @code{demangler-warning}:
- demangler warnings always create a core file and this cannot be
- disabled.
- @end table
- @kindex maint set internal-error
- @kindex maint show internal-error
- @kindex maint set internal-warning
- @kindex maint show internal-warning
- @item maint set internal-error backtrace @r{[}on|off@r{]}
- @itemx maint show internal-error backtrace
- @itemx maint set internal-warning backtrace @r{[}on|off@r{]}
- @itemx maint show internal-warning backtrace
- When @value{GDBN} reports an internal problem (error or warning) it is
- possible to have a backtrace of @value{GDBN} printed to the standard
- error stream. This is @samp{on} by default for @code{internal-error}
- and @samp{off} by default for @code{internal-warning}.
- @anchor{maint packet}
- @kindex maint packet
- @item maint packet @var{text}
- If @value{GDBN} is talking to an inferior via the serial protocol,
- then this command sends the string @var{text} to the inferior, and
- displays the response packet. @value{GDBN} supplies the initial
- @samp{$} character, the terminating @samp{#} character, and the
- checksum.
- Any non-printable characters in the reply are printed as escaped hex,
- e.g. @samp{\x00}, @samp{\x01}, etc.
- @kindex maint print architecture
- @item maint print architecture @r{[}@var{file}@r{]}
- Print the entire architecture configuration. The optional argument
- @var{file} names the file where the output goes.
- @kindex maint print c-tdesc
- @item maint print c-tdesc @r{[}-single-feature@r{]} @r{[}@var{file}@r{]}
- Print the target description (@pxref{Target Descriptions}) as
- a C source file. By default, the target description is for the current
- target, but if the optional argument @var{file} is provided, that file
- is used to produce the description. The @var{file} should be an XML
- document, of the form described in @ref{Target Description Format}.
- The created source file is built into @value{GDBN} when @value{GDBN} is
- built again. This command is used by developers after they add or
- modify XML target descriptions.
- When the optional flag @samp{-single-feature} is provided then the
- target description being processed (either the default, or from
- @var{file}) must only contain a single feature. The source file
- produced is different in this case.
- @kindex maint print xml-tdesc
- @item maint print xml-tdesc @r{[}@var{file}@r{]}
- Print the target description (@pxref{Target Descriptions}) as an XML
- file. By default print the target description for the current target,
- but if the optional argument @var{file} is provided, then that file is
- read in by GDB and then used to produce the description. The
- @var{file} should be an XML document, of the form described in
- @ref{Target Description Format}.
- @kindex maint check xml-descriptions
- @item maint check xml-descriptions @var{dir}
- Check that the target descriptions dynamically created by @value{GDBN}
- equal the descriptions created from XML files found in @var{dir}.
- @anchor{maint check libthread-db}
- @kindex maint check libthread-db
- @item maint check libthread-db
- Run integrity checks on the current inferior's thread debugging
- library. This exercises all @code{libthread_db} functionality used by
- @value{GDBN} on GNU/Linux systems, and by extension also exercises the
- @code{proc_service} functions provided by @value{GDBN} that
- @code{libthread_db} uses. Note that parts of the test may be skipped
- on some platforms when debugging core files.
- @kindex maint print core-file-backed-mappings
- @cindex memory address space mappings
- @item maint print core-file-backed-mappings
- Print the file-backed mappings which were loaded from a core file note.
- This output represents state internal to @value{GDBN} and should be
- similar to the mappings displayed by the @code{info proc mappings}
- command.
- @kindex maint print dummy-frames
- @item maint print dummy-frames
- Prints the contents of @value{GDBN}'s internal dummy-frame stack.
- @smallexample
- (@value{GDBP}) @kbd{b add}
- @dots{}
- (@value{GDBP}) @kbd{print add(2,3)}
- Breakpoint 2, add (a=2, b=3) at @dots{}
- 58 return (a + b);
- The program being debugged stopped while in a function called from GDB.
- @dots{}
- (@value{GDBP}) @kbd{maint print dummy-frames}
- 0xa8206d8: id=@{stack=0xbfffe734,code=0xbfffe73f,!special@}, ptid=process 9353
- (@value{GDBP})
- @end smallexample
- Takes an optional file parameter.
- @kindex maint print registers
- @kindex maint print raw-registers
- @kindex maint print cooked-registers
- @kindex maint print register-groups
- @kindex maint print remote-registers
- @item maint print registers @r{[}@var{file}@r{]}
- @itemx maint print raw-registers @r{[}@var{file}@r{]}
- @itemx maint print cooked-registers @r{[}@var{file}@r{]}
- @itemx maint print register-groups @r{[}@var{file}@r{]}
- @itemx maint print remote-registers @r{[}@var{file}@r{]}
- Print @value{GDBN}'s internal register data structures.
- The command @code{maint print raw-registers} includes the contents of
- the raw register cache; the command @code{maint print
- cooked-registers} includes the (cooked) value of all registers,
- including registers which aren't available on the target nor visible
- to user; the command @code{maint print register-groups} includes the
- groups that each register is a member of; and the command @code{maint
- print remote-registers} includes the remote target's register numbers
- and offsets in the `G' packets.
- These commands take an optional parameter, a file name to which to
- write the information.
- @kindex maint print reggroups
- @item maint print reggroups @r{[}@var{file}@r{]}
- Print @value{GDBN}'s internal register group data structures. The
- optional argument @var{file} tells to what file to write the
- information.
- The register groups info looks like this:
- @smallexample
- (@value{GDBP}) @kbd{maint print reggroups}
- Group Type
- general user
- float user
- all user
- vector user
- system user
- save internal
- restore internal
- @end smallexample
- @kindex maint flush register-cache
- @kindex flushregs
- @cindex register cache, flushing
- @item maint flush register-cache
- @itemx flushregs
- Flush the contents of the register cache and as a consequence the
- frame cache. This command is useful when debugging issues related to
- register fetching, or frame unwinding. The command @code{flushregs}
- is deprecated in favor of @code{maint flush register-cache}.
- @kindex maint flush source-cache
- @cindex source code, caching
- @item maint flush source-cache
- Flush @value{GDBN}'s cache of source code file contents. After
- @value{GDBN} reads a source file, and optionally applies styling
- (@pxref{Output Styling}), the file contents are cached. This command
- clears that cache. The next time @value{GDBN} wants to show lines
- from a source file, the content will be re-read.
- This command is useful when debugging issues related to source code
- styling. After flushing the cache any source code displayed by
- @value{GDBN} will be re-read and re-styled.
- @kindex maint print objfiles
- @cindex info for known object files
- @item maint print objfiles @r{[}@var{regexp}@r{]}
- Print a dump of all known object files.
- If @var{regexp} is specified, only print object files whose names
- match @var{regexp}. For each object file, this command prints its name,
- address in memory, and all of its psymtabs and symtabs.
- @kindex maint print user-registers
- @cindex user registers
- @item maint print user-registers
- List all currently available @dfn{user registers}. User registers
- typically provide alternate names for actual hardware registers. They
- include the four ``standard'' registers @code{$fp}, @code{$pc},
- @code{$sp}, and @code{$ps}. @xref{standard registers}. User
- registers can be used in expressions in the same way as the canonical
- register names, but only the latter are listed by the @code{info
- registers} and @code{maint print registers} commands.
- @kindex maint print section-scripts
- @cindex info for known .debug_gdb_scripts-loaded scripts
- @item maint print section-scripts [@var{regexp}]
- Print a dump of scripts specified in the @code{.debug_gdb_section} section.
- If @var{regexp} is specified, only print scripts loaded by object files
- matching @var{regexp}.
- For each script, this command prints its name as specified in the objfile,
- and the full path if known.
- @xref{dotdebug_gdb_scripts section}.
- @kindex maint print statistics
- @cindex bcache statistics
- @item maint print statistics
- This command prints, for each object file in the program, various data
- about that object file followed by the byte cache (@dfn{bcache})
- statistics for the object file. The objfile data includes the number
- of minimal, partial, full, and stabs symbols, the number of types
- defined by the objfile, the number of as yet unexpanded psym tables,
- the number of line tables and string tables, and the amount of memory
- used by the various tables. The bcache statistics include the counts,
- sizes, and counts of duplicates of all and unique objects, max,
- average, and median entry size, total memory used and its overhead and
- savings, and various measures of the hash table size and chain
- lengths.
- @kindex maint print target-stack
- @cindex target stack description
- @item maint print target-stack
- A @dfn{target} is an interface between the debugger and a particular
- kind of file or process. Targets can be stacked in @dfn{strata},
- so that more than one target can potentially respond to a request.
- In particular, memory accesses will walk down the stack of targets
- until they find a target that is interested in handling that particular
- address.
- This command prints a short description of each layer that was pushed on
- the @dfn{target stack}, starting from the top layer down to the bottom one.
- @kindex maint print type
- @cindex type chain of a data type
- @item maint print type @var{expr}
- Print the type chain for a type specified by @var{expr}. The argument
- can be either a type name or a symbol. If it is a symbol, the type of
- that symbol is described. The type chain produced by this command is
- a recursive definition of the data type as stored in @value{GDBN}'s
- data structures, including its flags and contained types.
- @kindex maint selftest
- @cindex self tests
- @item maint selftest @r{[}-verbose@r{]} @r{[}@var{filter}@r{]}
- Run any self tests that were compiled in to @value{GDBN}. This will
- print a message showing how many tests were run, and how many failed.
- If a @var{filter} is passed, only the tests with @var{filter} in their
- name will be ran. If @code{-verbose} is passed, the self tests can be
- more verbose.
- @kindex maint set selftest verbose
- @kindex maint show selftest verbose
- @cindex self tests
- @item maint set selftest verbose
- @item maint show selftest verbose
- Control whether self tests are run verbosely or not.
- @kindex maint info selftests
- @cindex self tests
- @item maint info selftests
- List the selftests compiled in to @value{GDBN}.
- @kindex maint set dwarf always-disassemble
- @kindex maint show dwarf always-disassemble
- @item maint set dwarf always-disassemble
- @item maint show dwarf always-disassemble
- Control the behavior of @code{info address} when using DWARF debugging
- information.
- The default is @code{off}, which means that @value{GDBN} should try to
- describe a variable's location in an easily readable format. When
- @code{on}, @value{GDBN} will instead display the DWARF location
- expression in an assembly-like format. Note that some locations are
- too complex for @value{GDBN} to describe simply; in this case you will
- always see the disassembly form.
- Here is an example of the resulting disassembly:
- @smallexample
- (gdb) info addr argc
- Symbol "argc" is a complex DWARF expression:
- 1: DW_OP_fbreg 0
- @end smallexample
- For more information on these expressions, see
- @uref{http://www.dwarfstd.org/, the DWARF standard}.
- @kindex maint set dwarf max-cache-age
- @kindex maint show dwarf max-cache-age
- @item maint set dwarf max-cache-age
- @itemx maint show dwarf max-cache-age
- Control the DWARF compilation unit cache.
- @cindex DWARF compilation units cache
- In object files with inter-compilation-unit references, such as those
- produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF
- reader needs to frequently refer to previously read compilation units.
- This setting controls how long a compilation unit will remain in the
- cache if it is not referenced. A higher limit means that cached
- compilation units will be stored in memory longer, and more total
- memory will be used. Setting it to zero disables caching, which will
- slow down @value{GDBN} startup, but reduce memory consumption.
- @kindex maint set dwarf unwinders
- @kindex maint show dwarf unwinders
- @item maint set dwarf unwinders
- @itemx maint show dwarf unwinders
- Control use of the DWARF frame unwinders.
- @cindex DWARF frame unwinders
- Many targets that support DWARF debugging use @value{GDBN}'s DWARF
- frame unwinders to build the backtrace. Many of these targets will
- also have a second mechanism for building the backtrace for use in
- cases where DWARF information is not available, this second mechanism
- is often an analysis of a function's prologue.
- In order to extend testing coverage of the second level stack
- unwinding mechanisms it is helpful to be able to disable the DWARF
- stack unwinders, this can be done with this switch.
- In normal use of @value{GDBN} disabling the DWARF unwinders is not
- advisable, there are cases that are better handled through DWARF than
- prologue analysis, and the debug experience is likely to be better
- with the DWARF frame unwinders enabled.
- If DWARF frame unwinders are not supported for a particular target
- architecture, then enabling this flag does not cause them to be used.
- @kindex maint set worker-threads
- @kindex maint show worker-threads
- @item maint set worker-threads
- @item maint show worker-threads
- Control the number of worker threads that may be used by @value{GDBN}.
- On capable hosts, @value{GDBN} may use multiple threads to speed up
- certain CPU-intensive operations, such as demangling symbol names.
- While the number of threads used by @value{GDBN} may vary, this
- command can be used to set an upper bound on this number. The default
- is @code{unlimited}, which lets @value{GDBN} choose a reasonable
- number. Note that this only controls worker threads started by
- @value{GDBN} itself; libraries used by @value{GDBN} may start threads
- of their own.
- @kindex maint set profile
- @kindex maint show profile
- @cindex profiling GDB
- @item maint set profile
- @itemx maint show profile
- Control profiling of @value{GDBN}.
- Profiling will be disabled until you use the @samp{maint set profile}
- command to enable it. When you enable profiling, the system will begin
- collecting timing and execution count data; when you disable profiling or
- exit @value{GDBN}, the results will be written to a log file. Remember that
- if you use profiling, @value{GDBN} will overwrite the profiling log file
- (often called @file{gmon.out}). If you have a record of important profiling
- data in a @file{gmon.out} file, be sure to move it to a safe location.
- Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
- compiled with the @samp{-pg} compiler option.
- @kindex maint set show-debug-regs
- @kindex maint show show-debug-regs
- @cindex hardware debug registers
- @item maint set show-debug-regs
- @itemx maint show show-debug-regs
- Control whether to show variables that mirror the hardware debug
- registers. Use @code{on} to enable, @code{off} to disable. If
- enabled, the debug registers values are shown when @value{GDBN} inserts or
- removes a hardware breakpoint or watchpoint, and when the inferior
- triggers a hardware-assisted breakpoint or watchpoint.
- @kindex maint set show-all-tib
- @kindex maint show show-all-tib
- @item maint set show-all-tib
- @itemx maint show show-all-tib
- Control whether to show all non zero areas within a 1k block starting
- at thread local base, when using the @samp{info w32 thread-information-block}
- command.
- @kindex maint set target-async
- @kindex maint show target-async
- @item maint set target-async
- @itemx maint show target-async
- This controls whether @value{GDBN} targets operate in synchronous or
- asynchronous mode (@pxref{Background Execution}). Normally the
- default is asynchronous, if it is available; but this can be changed
- to more easily debug problems occurring only in synchronous mode.
- @kindex maint set target-non-stop @var{mode} [on|off|auto]
- @kindex maint show target-non-stop
- @item maint set target-non-stop
- @itemx maint show target-non-stop
- This controls whether @value{GDBN} targets always operate in non-stop
- mode even if @code{set non-stop} is @code{off} (@pxref{Non-Stop
- Mode}). The default is @code{auto}, meaning non-stop mode is enabled
- if supported by the target.
- @table @code
- @item maint set target-non-stop auto
- This is the default mode. @value{GDBN} controls the target in
- non-stop mode if the target supports it.
- @item maint set target-non-stop on
- @value{GDBN} controls the target in non-stop mode even if the target
- does not indicate support.
- @item maint set target-non-stop off
- @value{GDBN} does not control the target in non-stop mode even if the
- target supports it.
- @end table
- @kindex maint set tui-resize-message
- @kindex maint show tui-resize-message
- @item maint set tui-resize-message
- @item maint show tui-resize-message
- Control whether @value{GDBN} displays a message each time the terminal
- is resized when in TUI mode. The default is @code{off}, which means
- that @value{GDBN} is silent during resizes. When @code{on},
- @value{GDBN} will display a message after a resize is completed; the
- message will include a number indicating how many times the terminal
- has been resized. This setting is intended for use by the test suite,
- where it would otherwise be difficult to determine when a resize and
- refresh has been completed.
- @kindex maint set per-command
- @kindex maint show per-command
- @item maint set per-command
- @itemx maint show per-command
- @cindex resources used by commands
- @value{GDBN} can display the resources used by each command.
- This is useful in debugging performance problems.
- @table @code
- @item maint set per-command space [on|off]
- @itemx maint show per-command space
- Enable or disable the printing of the memory used by GDB for each command.
- If enabled, @value{GDBN} will display how much memory each command
- took, following the command's own output.
- This can also be requested by invoking @value{GDBN} with the
- @option{--statistics} command-line switch (@pxref{Mode Options}).
- @item maint set per-command time [on|off]
- @itemx maint show per-command time
- Enable or disable the printing of the execution time of @value{GDBN}
- for each command.
- If enabled, @value{GDBN} will display how much time it
- took to execute each command, following the command's own output.
- Both CPU time and wallclock time are printed.
- Printing both is useful when trying to determine whether the cost is
- CPU or, e.g., disk/network latency.
- Note that the CPU time printed is for @value{GDBN} only, it does not include
- the execution time of the inferior because there's no mechanism currently
- to compute how much time was spent by @value{GDBN} and how much time was
- spent by the program been debugged.
- This can also be requested by invoking @value{GDBN} with the
- @option{--statistics} command-line switch (@pxref{Mode Options}).
- @item maint set per-command symtab [on|off]
- @itemx maint show per-command symtab
- Enable or disable the printing of basic symbol table statistics
- for each command.
- If enabled, @value{GDBN} will display the following information:
- @enumerate a
- @item
- number of symbol tables
- @item
- number of primary symbol tables
- @item
- number of blocks in the blockvector
- @end enumerate
- @end table
- @kindex maint set check-libthread-db
- @kindex maint show check-libthread-db
- @item maint set check-libthread-db [on|off]
- @itemx maint show check-libthread-db
- Control whether @value{GDBN} should run integrity checks on inferior
- specific thread debugging libraries as they are loaded. The default
- is not to perform such checks. If any check fails @value{GDBN} will
- unload the library and continue searching for a suitable candidate as
- described in @ref{set libthread-db-search-path}. For more information
- about the tests, see @ref{maint check libthread-db}.
- @kindex maint set gnu-source-highlight enabled
- @kindex maint show gnu-source-highlight enabled
- @item maint set gnu-source-highlight enabled @r{[}on|off@r{]}
- @itemx maint show gnu-source-highlight enabled
- Control whether @value{GDBN} should use the GNU Source Highlight
- library for applying styling to source code (@pxref{Output Styling}).
- This will be @samp{on} by default if the GNU Source Highlight library
- is available. If the GNU Source Highlight library is not available,
- then this will be @samp{off} by default, and attempting to change this
- value to @samp{on} will give an error.
- If the GNU Source Highlight library is not being used, then
- @value{GDBN} will use the Python Pygments package for source code
- styling, if it is available.
- This option is useful for debugging @value{GDBN}'s use of the Pygments
- library when @value{GDBN} is linked against the GNU Source Highlight
- library.
- @kindex maint space
- @cindex memory used by commands
- @item maint space @var{value}
- An alias for @code{maint set per-command space}.
- A non-zero value enables it, zero disables it.
- @kindex maint time
- @cindex time of command execution
- @item maint time @var{value}
- An alias for @code{maint set per-command time}.
- A non-zero value enables it, zero disables it.
- @kindex maint translate-address
- @item maint translate-address @r{[}@var{section}@r{]} @var{addr}
- Find the symbol stored at the location specified by the address
- @var{addr} and an optional section name @var{section}. If found,
- @value{GDBN} prints the name of the closest symbol and an offset from
- the symbol's location to the specified address. This is similar to
- the @code{info address} command (@pxref{Symbols}), except that this
- command also allows to find symbols in other sections.
- If section was not specified, the section in which the symbol was found
- is also printed. For dynamically linked executables, the name of
- executable or shared library containing the symbol is printed as well.
- @kindex maint test-options
- @item maint test-options require-delimiter
- @itemx maint test-options unknown-is-error
- @itemx maint test-options unknown-is-operand
- These commands are used by the testsuite to validate the command
- options framework. The @code{require-delimiter} variant requires a
- double-dash delimiter to indicate end of options. The
- @code{unknown-is-error} and @code{unknown-is-operand} do not. The
- @code{unknown-is-error} variant throws an error on unknown option,
- while @code{unknown-is-operand} treats unknown options as the start of
- the command's operands. When run, the commands output the result of
- the processed options. When completed, the commands store the
- internal result of completion in a variable exposed by the @code{maint
- show test-options-completion-result} command.
- @kindex maint show test-options-completion-result
- @item maint show test-options-completion-result
- Shows the result of completing the @code{maint test-options}
- subcommands. This is used by the testsuite to validate completion
- support in the command options framework.
- @kindex maint set test-settings
- @kindex maint show test-settings
- @item maint set test-settings @var{kind}
- @itemx maint show test-settings @var{kind}
- These are representative commands for each @var{kind} of setting type
- @value{GDBN} supports. They are used by the testsuite for exercising
- the settings infrastructure.
- @kindex maint set backtrace-on-fatal-signal
- @kindex maint show backtrace-on-fatal-signal
- @item maint set backtrace-on-fatal-signal [on|off]
- @itemx maint show backtrace-on-fatal-signal
- When this setting is @code{on}, if @value{GDBN} itself terminates with
- a fatal signal (e.g.@: SIGSEGV), then a limited backtrace will be
- printed to the standard error stream. This backtrace can be used to
- help diagnose crashes within @value{GDBN} in situations where a user
- is unable to share a corefile with the @value{GDBN} developers.
- If the functionality to provide this backtrace is not available for
- the platform on which GDB is running then this feature will be
- @code{off} by default, and attempting to turn this feature on will
- give an error.
- For platforms that do support creating the backtrace this feature is
- @code{on} by default.
- @kindex maint with
- @item maint with @var{setting} [@var{value}] [-- @var{command}]
- Like the @code{with} command, but works with @code{maintenance set}
- variables. This is used by the testsuite to exercise the @code{with}
- command's infrastructure.
- @end table
- The following command is useful for non-interactive invocations of
- @value{GDBN}, such as in the test suite.
- @table @code
- @item set watchdog @var{nsec}
- @kindex set watchdog
- @cindex watchdog timer
- @cindex timeout for commands
- Set the maximum number of seconds @value{GDBN} will wait for the
- target operation to finish. If this time expires, @value{GDBN}
- reports and error and the command is aborted.
- @item show watchdog
- Show the current setting of the target wait timeout.
- @end table
- @node Remote Protocol
- @appendix @value{GDBN} Remote Serial Protocol
- @menu
- * Overview::
- * Packets::
- * Stop Reply Packets::
- * General Query Packets::
- * Architecture-Specific Protocol Details::
- * Tracepoint Packets::
- * Host I/O Packets::
- * Interrupts::
- * Notification Packets::
- * Remote Non-Stop::
- * Packet Acknowledgment::
- * Examples::
- * File-I/O Remote Protocol Extension::
- * Library List Format::
- * Library List Format for SVR4 Targets::
- * Memory Map Format::
- * Thread List Format::
- * Traceframe Info Format::
- * Branch Trace Format::
- * Branch Trace Configuration Format::
- @end menu
- @node Overview
- @section Overview
- There may be occasions when you need to know something about the
- protocol---for example, if there is only one serial port to your target
- machine, you might want your program to do something special if it
- recognizes a packet meant for @value{GDBN}.
- In the examples below, @samp{->} and @samp{<-} are used to indicate
- transmitted and received data, respectively.
- @cindex protocol, @value{GDBN} remote serial
- @cindex serial protocol, @value{GDBN} remote
- @cindex remote serial protocol
- All @value{GDBN} commands and responses (other than acknowledgments
- and notifications, see @ref{Notification Packets}) are sent as a
- @var{packet}. A @var{packet} is introduced with the character
- @samp{$}, the actual @var{packet-data}, and the terminating character
- @samp{#} followed by a two-digit @var{checksum}:
- @smallexample
- @code{$}@var{packet-data}@code{#}@var{checksum}
- @end smallexample
- @noindent
- @cindex checksum, for @value{GDBN} remote
- @noindent
- The two-digit @var{checksum} is computed as the modulo 256 sum of all
- characters between the leading @samp{$} and the trailing @samp{#} (an
- eight bit unsigned checksum).
- Implementors should note that prior to @value{GDBN} 5.0 the protocol
- specification also included an optional two-digit @var{sequence-id}:
- @smallexample
- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
- @end smallexample
- @cindex sequence-id, for @value{GDBN} remote
- @noindent
- That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
- has never output @var{sequence-id}s. Stubs that handle packets added
- since @value{GDBN} 5.0 must not accept @var{sequence-id}.
- When either the host or the target machine receives a packet, the first
- response expected is an acknowledgment: either @samp{+} (to indicate
- the package was received correctly) or @samp{-} (to request
- retransmission):
- @smallexample
- -> @code{$}@var{packet-data}@code{#}@var{checksum}
- <- @code{+}
- @end smallexample
- @noindent
- The @samp{+}/@samp{-} acknowledgments can be disabled
- once a connection is established.
- @xref{Packet Acknowledgment}, for details.
- The host (@value{GDBN}) sends @var{command}s, and the target (the
- debugging stub incorporated in your program) sends a @var{response}. In
- the case of step and continue @var{command}s, the response is only sent
- when the operation has completed, and the target has again stopped all
- threads in all attached processes. This is the default all-stop mode
- behavior, but the remote protocol also supports @value{GDBN}'s non-stop
- execution mode; see @ref{Remote Non-Stop}, for details.
- @var{packet-data} consists of a sequence of characters with the
- exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
- exceptions).
- @cindex remote protocol, field separator
- Fields within the packet should be separated using @samp{,} @samp{;} or
- @samp{:}. Except where otherwise noted all numbers are represented in
- @sc{hex} with leading zeros suppressed.
- Implementors should note that prior to @value{GDBN} 5.0, the character
- @samp{:} could not appear as the third character in a packet (as it
- would potentially conflict with the @var{sequence-id}).
- @cindex remote protocol, binary data
- @anchor{Binary Data}
- Binary data in most packets is encoded either as two hexadecimal
- digits per byte of binary data. This allowed the traditional remote
- protocol to work over connections which were only seven-bit clean.
- Some packets designed more recently assume an eight-bit clean
- connection, and use a more efficient encoding to send and receive
- binary data.
- The binary data representation uses @code{7d} (@sc{ascii} @samp{@}})
- as an escape character. Any escaped byte is transmitted as the escape
- character followed by the original character XORed with @code{0x20}.
- For example, the byte @code{0x7d} would be transmitted as the two
- bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}),
- @code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii}
- @samp{@}}) must always be escaped. Responses sent by the stub
- must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it
- is not interpreted as the start of a run-length encoded sequence
- (described next).
- Response @var{data} can be run-length encoded to save space.
- Run-length encoding replaces runs of identical characters with one
- instance of the repeated character, followed by a @samp{*} and a
- repeat count. The repeat count is itself sent encoded, to avoid
- binary characters in @var{data}: a value of @var{n} is sent as
- @code{@var{n}+29}. For a repeat count greater or equal to 3, this
- produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii}
- code 32) for a repeat count of 3. (This is because run-length
- encoding starts to win for counts 3 or more.) Thus, for example,
- @samp{0* } is a run-length encoding of ``0000'': the space character
- after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 =
- 3}} more times.
- The printable characters @samp{#} and @samp{$} or with a numeric value
- greater than 126 must not be used. Runs of six repeats (@samp{#}) or
- seven repeats (@samp{$}) can be expanded using a repeat count of only
- five (@samp{"}). For example, @samp{00000000} can be encoded as
- @samp{0*"00}.
- The error response returned for some packets includes a two character
- error number. That number is not well defined.
- @cindex empty response, for unsupported packets
- For any @var{command} not supported by the stub, an empty response
- (@samp{$#00}) should be returned. That way it is possible to extend the
- protocol. A newer @value{GDBN} can tell if a packet is supported based
- on that response.
- At a minimum, a stub is required to support the @samp{?} command to
- tell @value{GDBN} the reason for halting, @samp{g} and @samp{G}
- commands for register access, and the @samp{m} and @samp{M} commands
- for memory access. Stubs that only control single-threaded targets
- can implement run control with the @samp{c} (continue) command, and if
- the target architecture supports hardware-assisted single-stepping,
- the @samp{s} (step) command. Stubs that support multi-threading
- targets should support the @samp{vCont} command. All other commands
- are optional.
- @node Packets
- @section Packets
- The following table provides a complete list of all currently defined
- @var{command}s and their corresponding response @var{data}.
- @xref{File-I/O Remote Protocol Extension}, for details about the File
- I/O extension of the remote protocol.
- Each packet's description has a template showing the packet's overall
- syntax, followed by an explanation of the packet's meaning. We
- include spaces in some of the templates for clarity; these are not
- part of the packet's syntax. No @value{GDBN} packet uses spaces to
- separate its components. For example, a template like @samp{foo
- @var{bar} @var{baz}} describes a packet beginning with the three ASCII
- bytes @samp{foo}, followed by a @var{bar}, followed directly by a
- @var{baz}. @value{GDBN} does not transmit a space character between the
- @samp{foo} and the @var{bar}, or between the @var{bar} and the
- @var{baz}.
- @cindex @var{thread-id}, in remote protocol
- @anchor{thread-id syntax}
- Several packets and replies include a @var{thread-id} field to identify
- a thread. Normally these are positive numbers with a target-specific
- interpretation, formatted as big-endian hex strings. A @var{thread-id}
- can also be a literal @samp{-1} to indicate all threads, or @samp{0} to
- pick any thread.
- In addition, the remote protocol supports a multiprocess feature in
- which the @var{thread-id} syntax is extended to optionally include both
- process and thread ID fields, as @samp{p@var{pid}.@var{tid}}.
- The @var{pid} (process) and @var{tid} (thread) components each have the
- format described above: a positive number with target-specific
- interpretation formatted as a big-endian hex string, literal @samp{-1}
- to indicate all processes or threads (respectively), or @samp{0} to
- indicate an arbitrary process or thread. Specifying just a process, as
- @samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}. It is an
- error to specify all processes but a specific thread, such as
- @samp{p-1.@var{tid}}. Note that the @samp{p} prefix is @emph{not} used
- for those packets and replies explicitly documented to include a process
- ID, rather than a @var{thread-id}.
- The multiprocess @var{thread-id} syntax extensions are only used if both
- @value{GDBN} and the stub report support for the @samp{multiprocess}
- feature using @samp{qSupported}. @xref{multiprocess extensions}, for
- more information.
- Note that all packet forms beginning with an upper- or lower-case
- letter, other than those described here, are reserved for future use.
- Here are the packet descriptions.
- @table @samp
- @item !
- @cindex @samp{!} packet
- @anchor{extended mode}
- Enable extended mode. In extended mode, the remote server is made
- persistent. The @samp{R} packet is used to restart the program being
- debugged.
- Reply:
- @table @samp
- @item OK
- The remote target both supports and has enabled extended mode.
- @end table
- @item ?
- @cindex @samp{?} packet
- @anchor{? packet}
- This is sent when connection is first established to query the reason
- the target halted. The reply is the same as for step and continue.
- This packet has a special interpretation when the target is in
- non-stop mode; see @ref{Remote Non-Stop}.
- Reply:
- @xref{Stop Reply Packets}, for the reply specifications.
- @item A @var{arglen},@var{argnum},@var{arg},@dots{}
- @cindex @samp{A} packet
- Initialized @code{argv[]} array passed into program. @var{arglen}
- specifies the number of bytes in the hex encoded byte stream
- @var{arg}. See @code{gdbserver} for more details.
- Reply:
- @table @samp
- @item OK
- The arguments were set.
- @item E @var{NN}
- An error occurred.
- @end table
- @item b @var{baud}
- @cindex @samp{b} packet
- (Don't use this packet; its behavior is not well-defined.)
- Change the serial line speed to @var{baud}.
- JTC: @emph{When does the transport layer state change? When it's
- received, or after the ACK is transmitted. In either case, there are
- problems if the command or the acknowledgment packet is dropped.}
- Stan: @emph{If people really wanted to add something like this, and get
- it working for the first time, they ought to modify ser-unix.c to send
- some kind of out-of-band message to a specially-setup stub and have the
- switch happen "in between" packets, so that from remote protocol's point
- of view, nothing actually happened.}
- @item B @var{addr},@var{mode}
- @cindex @samp{B} packet
- Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
- breakpoint at @var{addr}.
- Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
- (@pxref{insert breakpoint or watchpoint packet}).
- @cindex @samp{bc} packet
- @anchor{bc}
- @item bc
- Backward continue. Execute the target system in reverse. No parameter.
- @xref{Reverse Execution}, for more information.
- Reply:
- @xref{Stop Reply Packets}, for the reply specifications.
- @cindex @samp{bs} packet
- @anchor{bs}
- @item bs
- Backward single step. Execute one instruction in reverse. No parameter.
- @xref{Reverse Execution}, for more information.
- Reply:
- @xref{Stop Reply Packets}, for the reply specifications.
- @item c @r{[}@var{addr}@r{]}
- @cindex @samp{c} packet
- Continue at @var{addr}, which is the address to resume. If @var{addr}
- is omitted, resume at current address.
- This packet is deprecated for multi-threading support. @xref{vCont
- packet}.
- Reply:
- @xref{Stop Reply Packets}, for the reply specifications.
- @item C @var{sig}@r{[};@var{addr}@r{]}
- @cindex @samp{C} packet
- Continue with signal @var{sig} (hex signal number). If
- @samp{;@var{addr}} is omitted, resume at same address.
- This packet is deprecated for multi-threading support. @xref{vCont
- packet}.
- Reply:
- @xref{Stop Reply Packets}, for the reply specifications.
- @item d
- @cindex @samp{d} packet
- Toggle debug flag.
- Don't use this packet; instead, define a general set packet
- (@pxref{General Query Packets}).
- @item D
- @itemx D;@var{pid}
- @cindex @samp{D} packet
- The first form of the packet is used to detach @value{GDBN} from the
- remote system. It is sent to the remote target
- before @value{GDBN} disconnects via the @code{detach} command.
- The second form, including a process ID, is used when multiprocess
- protocol extensions are enabled (@pxref{multiprocess extensions}), to
- detach only a specific process. The @var{pid} is specified as a
- big-endian hex string.
- Reply:
- @table @samp
- @item OK
- for success
- @item E @var{NN}
- for an error
- @end table
- @item F @var{RC},@var{EE},@var{CF};@var{XX}
- @cindex @samp{F} packet
- A reply from @value{GDBN} to an @samp{F} packet sent by the target.
- This is part of the File-I/O protocol extension. @xref{File-I/O
- Remote Protocol Extension}, for the specification.
- @item g
- @anchor{read registers packet}
- @cindex @samp{g} packet
- Read general registers.
- Reply:
- @table @samp
- @item @var{XX@dots{}}
- Each byte of register data is described by two hex digits. The bytes
- with the register are transmitted in target byte order. The size of
- each register and their position within the @samp{g} packet are
- determined by the @value{GDBN} internal gdbarch functions
- @code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}.
- When reading registers from a trace frame (@pxref{Analyze Collected
- Data,,Using the Collected Data}), the stub may also return a string of
- literal @samp{x}'s in place of the register data digits, to indicate
- that the corresponding register has not been collected, thus its value
- is unavailable. For example, for an architecture with 4 registers of
- 4 bytes each, the following reply indicates to @value{GDBN} that
- registers 0 and 2 have not been collected, while registers 1 and 3
- have been collected, and both have zero value:
- @smallexample
- -> @code{g}
- <- @code{xxxxxxxx00000000xxxxxxxx00000000}
- @end smallexample
- @item E @var{NN}
- for an error.
- @end table
- @item G @var{XX@dots{}}
- @cindex @samp{G} packet
- Write general registers. @xref{read registers packet}, for a
- description of the @var{XX@dots{}} data.
- Reply:
- @table @samp
- @item OK
- for success
- @item E @var{NN}
- for an error
- @end table
- @item H @var{op} @var{thread-id}
- @cindex @samp{H} packet
- Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
- @samp{G}, et.al.). Depending on the operation to be performed, @var{op}
- should be @samp{c} for step and continue operations (note that this
- is deprecated, supporting the @samp{vCont} command is a better
- option), and @samp{g} for other operations. The thread designator
- @var{thread-id} has the format and interpretation described in
- @ref{thread-id syntax}.
- Reply:
- @table @samp
- @item OK
- for success
- @item E @var{NN}
- for an error
- @end table
- @c FIXME: JTC:
- @c 'H': How restrictive (or permissive) is the thread model. If a
- @c thread is selected and stopped, are other threads allowed
- @c to continue to execute? As I mentioned above, I think the
- @c semantics of each command when a thread is selected must be
- @c described. For example:
- @c
- @c 'g': If the stub supports threads and a specific thread is
- @c selected, returns the register block from that thread;
- @c otherwise returns current registers.
- @c
- @c 'G' If the stub supports threads and a specific thread is
- @c selected, sets the registers of the register block of
- @c that thread; otherwise sets current registers.
- @item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]}
- @anchor{cycle step packet}
- @cindex @samp{i} packet
- Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is
- present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
- step starting at that address.
- @item I
- @cindex @samp{I} packet
- Signal, then cycle step. @xref{step with signal packet}. @xref{cycle
- step packet}.
- @item k
- @cindex @samp{k} packet
- Kill request.
- The exact effect of this packet is not specified.
- For a bare-metal target, it may power cycle or reset the target
- system. For that reason, the @samp{k} packet has no reply.
- For a single-process target, it may kill that process if possible.
- A multiple-process target may choose to kill just one process, or all
- that are under @value{GDBN}'s control. For more precise control, use
- the vKill packet (@pxref{vKill packet}).
- If the target system immediately closes the connection in response to
- @samp{k}, @value{GDBN} does not consider the lack of packet
- acknowledgment to be an error, and assumes the kill was successful.
- If connected using @kbd{target extended-remote}, and the target does
- not close the connection in response to a kill request, @value{GDBN}
- probes the target state as if a new connection was opened
- (@pxref{? packet}).
- @item m @var{addr},@var{length}
- @cindex @samp{m} packet
- Read @var{length} addressable memory units starting at address @var{addr}
- (@pxref{addressable memory unit}). Note that @var{addr} may not be aligned to
- any particular boundary.
- The stub need not use any particular size or alignment when gathering
- data from memory for the response; even if @var{addr} is word-aligned
- and @var{length} is a multiple of the word size, the stub is free to
- use byte accesses, or not. For this reason, this packet may not be
- suitable for accessing memory-mapped I/O devices.
- @cindex alignment of remote memory accesses
- @cindex size of remote memory accesses
- @cindex memory, alignment and size of remote accesses
- Reply:
- @table @samp
- @item @var{XX@dots{}}
- Memory contents; each byte is transmitted as a two-digit hexadecimal number.
- The reply may contain fewer addressable memory units than requested if the
- server was able to read only part of the region of memory.
- @item E @var{NN}
- @var{NN} is errno
- @end table
- @item M @var{addr},@var{length}:@var{XX@dots{}}
- @cindex @samp{M} packet
- Write @var{length} addressable memory units starting at address @var{addr}
- (@pxref{addressable memory unit}). The data is given by @var{XX@dots{}}; each
- byte is transmitted as a two-digit hexadecimal number.
- Reply:
- @table @samp
- @item OK
- for success
- @item E @var{NN}
- for an error (this includes the case where only part of the data was
- written).
- @end table
- @item p @var{n}
- @cindex @samp{p} packet
- Read the value of register @var{n}; @var{n} is in hex.
- @xref{read registers packet}, for a description of how the returned
- register value is encoded.
- Reply:
- @table @samp
- @item @var{XX@dots{}}
- the register's value
- @item E @var{NN}
- for an error
- @item @w{}
- Indicating an unrecognized @var{query}.
- @end table
- @item P @var{n@dots{}}=@var{r@dots{}}
- @anchor{write register packet}
- @cindex @samp{P} packet
- Write register @var{n@dots{}} with value @var{r@dots{}}. The register
- number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex
- digits for each byte in the register (target byte order).
- Reply:
- @table @samp
- @item OK
- for success
- @item E @var{NN}
- for an error
- @end table
- @item q @var{name} @var{params}@dots{}
- @itemx Q @var{name} @var{params}@dots{}
- @cindex @samp{q} packet
- @cindex @samp{Q} packet
- General query (@samp{q}) and set (@samp{Q}). These packets are
- described fully in @ref{General Query Packets}.
- @item r
- @cindex @samp{r} packet
- Reset the entire system.
- Don't use this packet; use the @samp{R} packet instead.
- @item R @var{XX}
- @cindex @samp{R} packet
- Restart the program being debugged. The @var{XX}, while needed, is ignored.
- This packet is only available in extended mode (@pxref{extended mode}).
- The @samp{R} packet has no reply.
- @item s @r{[}@var{addr}@r{]}
- @cindex @samp{s} packet
- Single step, resuming at @var{addr}. If
- @var{addr} is omitted, resume at same address.
- This packet is deprecated for multi-threading support. @xref{vCont
- packet}.
- Reply:
- @xref{Stop Reply Packets}, for the reply specifications.
- @item S @var{sig}@r{[};@var{addr}@r{]}
- @anchor{step with signal packet}
- @cindex @samp{S} packet
- Step with signal. This is analogous to the @samp{C} packet, but
- requests a single-step, rather than a normal resumption of execution.
- This packet is deprecated for multi-threading support. @xref{vCont
- packet}.
- Reply:
- @xref{Stop Reply Packets}, for the reply specifications.
- @item t @var{addr}:@var{PP},@var{MM}
- @cindex @samp{t} packet
- Search backwards starting at address @var{addr} for a match with pattern
- @var{PP} and mask @var{MM}, both of which are are 4 byte long.
- There must be at least 3 digits in @var{addr}.
- @item T @var{thread-id}
- @cindex @samp{T} packet
- Find out if the thread @var{thread-id} is alive. @xref{thread-id syntax}.
- Reply:
- @table @samp
- @item OK
- thread is still alive
- @item E @var{NN}
- thread is dead
- @end table
- @item v
- Packets starting with @samp{v} are identified by a multi-letter name,
- up to the first @samp{;} or @samp{?} (or the end of the packet).
- @item vAttach;@var{pid}
- @cindex @samp{vAttach} packet
- Attach to a new process with the specified process ID @var{pid}.
- The process ID is a
- hexadecimal integer identifying the process. In all-stop mode, all
- threads in the attached process are stopped; in non-stop mode, it may be
- attached without being stopped if that is supported by the target.
- @c In non-stop mode, on a successful vAttach, the stub should set the
- @c current thread to a thread of the newly-attached process. After
- @c attaching, GDB queries for the attached process's thread ID with qC.
- @c Also note that, from a user perspective, whether or not the
- @c target is stopped on attach in non-stop mode depends on whether you
- @c use the foreground or background version of the attach command, not
- @c on what vAttach does; GDB does the right thing with respect to either
- @c stopping or restarting threads.
- This packet is only available in extended mode (@pxref{extended mode}).
- Reply:
- @table @samp
- @item E @var{nn}
- for an error
- @item @r{Any stop packet}
- for success in all-stop mode (@pxref{Stop Reply Packets})
- @item OK
- for success in non-stop mode (@pxref{Remote Non-Stop})
- @end table
- @item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{}
- @cindex @samp{vCont} packet
- @anchor{vCont packet}
- Resume the inferior, specifying different actions for each thread.
- For each inferior thread, the leftmost action with a matching
- @var{thread-id} is applied. Threads that don't match any action
- remain in their current state. Thread IDs are specified using the
- syntax described in @ref{thread-id syntax}. If multiprocess
- extensions (@pxref{multiprocess extensions}) are supported, actions
- can be specified to match all threads in a process by using the
- @samp{p@var{pid}.-1} form of the @var{thread-id}. An action with no
- @var{thread-id} matches all threads. Specifying no actions is an
- error.
- Currently supported actions are:
- @table @samp
- @item c
- Continue.
- @item C @var{sig}
- Continue with signal @var{sig}. The signal @var{sig} should be two hex digits.
- @item s
- Step.
- @item S @var{sig}
- Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
- @item t
- Stop.
- @item r @var{start},@var{end}
- Step once, and then keep stepping as long as the thread stops at
- addresses between @var{start} (inclusive) and @var{end} (exclusive).
- The remote stub reports a stop reply when either the thread goes out
- of the range or is stopped due to an unrelated reason, such as hitting
- a breakpoint. @xref{range stepping}.
- If the range is empty (@var{start} == @var{end}), then the action
- becomes equivalent to the @samp{s} action. In other words,
- single-step once, and report the stop (even if the stepped instruction
- jumps to @var{start}).
- (A stop reply may be sent at any point even if the PC is still within
- the stepping range; for example, it is valid to implement this packet
- in a degenerate way as a single instruction step operation.)
- @end table
- The optional argument @var{addr} normally associated with the
- @samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is
- not supported in @samp{vCont}.
- The @samp{t} action is only relevant in non-stop mode
- (@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise.
- A stop reply should be generated for any affected thread not already stopped.
- When a thread is stopped by means of a @samp{t} action,
- the corresponding stop reply should indicate that the thread has stopped with
- signal @samp{0}, regardless of whether the target uses some other signal
- as an implementation detail.
- The server must ignore @samp{c}, @samp{C}, @samp{s}, @samp{S}, and
- @samp{r} actions for threads that are already running. Conversely,
- the server must ignore @samp{t} actions for threads that are already
- stopped.
- @emph{Note:} In non-stop mode, a thread is considered running until
- @value{GDBN} acknowledges an asynchronous stop notification for it with
- the @samp{vStopped} packet (@pxref{Remote Non-Stop}).
- The stub must support @samp{vCont} if it reports support for
- multiprocess extensions (@pxref{multiprocess extensions}).
- Reply:
- @xref{Stop Reply Packets}, for the reply specifications.
- @item vCont?
- @cindex @samp{vCont?} packet
- Request a list of actions supported by the @samp{vCont} packet.
- Reply:
- @table @samp
- @item vCont@r{[};@var{action}@dots{}@r{]}
- The @samp{vCont} packet is supported. Each @var{action} is a supported
- command in the @samp{vCont} packet.
- @item @w{}
- The @samp{vCont} packet is not supported.
- @end table
- @anchor{vCtrlC packet}
- @item vCtrlC
- @cindex @samp{vCtrlC} packet
- Interrupt remote target as if a control-C was pressed on the remote
- terminal. This is the equivalent to reacting to the @code{^C}
- (@samp{\003}, the control-C character) character in all-stop mode
- while the target is running, except this works in non-stop mode.
- @xref{interrupting remote targets}, for more info on the all-stop
- variant.
- Reply:
- @table @samp
- @item E @var{nn}
- for an error
- @item OK
- for success
- @end table
- @item vFile:@var{operation}:@var{parameter}@dots{}
- @cindex @samp{vFile} packet
- Perform a file operation on the target system. For details,
- see @ref{Host I/O Packets}.
- @item vFlashErase:@var{addr},@var{length}
- @cindex @samp{vFlashErase} packet
- Direct the stub to erase @var{length} bytes of flash starting at
- @var{addr}. The region may enclose any number of flash blocks, but
- its start and end must fall on block boundaries, as indicated by the
- flash block size appearing in the memory map (@pxref{Memory Map
- Format}). @value{GDBN} groups flash memory programming operations
- together, and sends a @samp{vFlashDone} request after each group; the
- stub is allowed to delay erase operation until the @samp{vFlashDone}
- packet is received.
- Reply:
- @table @samp
- @item OK
- for success
- @item E @var{NN}
- for an error
- @end table
- @item vFlashWrite:@var{addr}:@var{XX@dots{}}
- @cindex @samp{vFlashWrite} packet
- Direct the stub to write data to flash address @var{addr}. The data
- is passed in binary form using the same encoding as for the @samp{X}
- packet (@pxref{Binary Data}). The memory ranges specified by
- @samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
- not overlap, and must appear in order of increasing addresses
- (although @samp{vFlashErase} packets for higher addresses may already
- have been received; the ordering is guaranteed only between
- @samp{vFlashWrite} packets). If a packet writes to an address that was
- neither erased by a preceding @samp{vFlashErase} packet nor by some other
- target-specific method, the results are unpredictable.
- Reply:
- @table @samp
- @item OK
- for success
- @item E.memtype
- for vFlashWrite addressing non-flash memory
- @item E @var{NN}
- for an error
- @end table
- @item vFlashDone
- @cindex @samp{vFlashDone} packet
- Indicate to the stub that flash programming operation is finished.
- The stub is permitted to delay or batch the effects of a group of
- @samp{vFlashErase} and @samp{vFlashWrite} packets until a
- @samp{vFlashDone} packet is received. The contents of the affected
- regions of flash memory are unpredictable until the @samp{vFlashDone}
- request is completed.
- @item vKill;@var{pid}
- @cindex @samp{vKill} packet
- @anchor{vKill packet}
- Kill the process with the specified process ID @var{pid}, which is a
- hexadecimal integer identifying the process. This packet is used in
- preference to @samp{k} when multiprocess protocol extensions are
- supported; see @ref{multiprocess extensions}.
- Reply:
- @table @samp
- @item E @var{nn}
- for an error
- @item OK
- for success
- @end table
- @item vMustReplyEmpty
- @cindex @samp{vMustReplyEmpty} packet
- The correct reply to an unknown @samp{v} packet is to return the empty
- string, however, some older versions of @command{gdbserver} would
- incorrectly return @samp{OK} for unknown @samp{v} packets.
- The @samp{vMustReplyEmpty} is used as a feature test to check how
- @command{gdbserver} handles unknown packets, it is important that this
- packet be handled in the same way as other unknown @samp{v} packets.
- If this packet is handled differently to other unknown @samp{v}
- packets then it is possible that @value{GDBN} may run into problems in
- other areas, specifically around use of @samp{vFile:setfs:}.
- @item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
- @cindex @samp{vRun} packet
- Run the program @var{filename}, passing it each @var{argument} on its
- command line. The file and arguments are hex-encoded strings. If
- @var{filename} is an empty string, the stub may use a default program
- (e.g.@: the last program run). The program is created in the stopped
- state.
- @c FIXME: What about non-stop mode?
- This packet is only available in extended mode (@pxref{extended mode}).
- Reply:
- @table @samp
- @item E @var{nn}
- for an error
- @item @r{Any stop packet}
- for success (@pxref{Stop Reply Packets})
- @end table
- @item vStopped
- @cindex @samp{vStopped} packet
- @xref{Notification Packets}.
- @item X @var{addr},@var{length}:@var{XX@dots{}}
- @anchor{X packet}
- @cindex @samp{X} packet
- Write data to memory, where the data is transmitted in binary.
- Memory is specified by its address @var{addr} and number of addressable memory
- units @var{length} (@pxref{addressable memory unit});
- @samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
- Reply:
- @table @samp
- @item OK
- for success
- @item E @var{NN}
- for an error
- @end table
- @item z @var{type},@var{addr},@var{kind}
- @itemx Z @var{type},@var{addr},@var{kind}
- @anchor{insert breakpoint or watchpoint packet}
- @cindex @samp{z} packet
- @cindex @samp{Z} packets
- Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or
- watchpoint starting at address @var{address} of kind @var{kind}.
- Each breakpoint and watchpoint packet @var{type} is documented
- separately.
- @emph{Implementation notes: A remote target shall return an empty string
- for an unrecognized breakpoint or watchpoint packet @var{type}. A
- remote target shall support either both or neither of a given
- @samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To
- avoid potential problems with duplicate packets, the operations should
- be implemented in an idempotent way.}
- @item z0,@var{addr},@var{kind}
- @itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]}
- @cindex @samp{z0} packet
- @cindex @samp{Z0} packet
- Insert (@samp{Z0}) or remove (@samp{z0}) a software breakpoint at address
- @var{addr} of type @var{kind}.
- A software breakpoint is implemented by replacing the instruction at
- @var{addr} with a software breakpoint or trap instruction. The
- @var{kind} is target-specific and typically indicates the size of the
- breakpoint in bytes that should be inserted. E.g., the @sc{arm} and
- @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
- architectures have additional meanings for @var{kind}
- (@pxref{Architecture-Specific Protocol Details}); if no
- architecture-specific value is being used, it should be @samp{0}.
- @var{kind} is hex-encoded. @var{cond_list} is an optional list of
- conditional expressions in bytecode form that should be evaluated on
- the target's side. These are the conditions that should be taken into
- consideration when deciding if the breakpoint trigger should be
- reported back to @value{GDBN}.
- See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason})
- for how to best report a software breakpoint event to @value{GDBN}.
- The @var{cond_list} parameter is comprised of a series of expressions,
- concatenated without separators. Each expression has the following form:
- @table @samp
- @item X @var{len},@var{expr}
- @var{len} is the length of the bytecode expression and @var{expr} is the
- actual conditional expression in bytecode form.
- @end table
- The optional @var{cmd_list} parameter introduces commands that may be
- run on the target, rather than being reported back to @value{GDBN}.
- The parameter starts with a numeric flag @var{persist}; if the flag is
- nonzero, then the breakpoint may remain active and the commands
- continue to be run even when @value{GDBN} disconnects from the target.
- Following this flag is a series of expressions concatenated with no
- separators. Each expression has the following form:
- @table @samp
- @item X @var{len},@var{expr}
- @var{len} is the length of the bytecode expression and @var{expr} is the
- actual commands expression in bytecode form.
- @end table
- @emph{Implementation note: It is possible for a target to copy or move
- code that contains software breakpoints (e.g., when implementing
- overlays). The behavior of this packet, in the presence of such a
- target, is not defined.}
- Reply:
- @table @samp
- @item OK
- success
- @item @w{}
- not supported
- @item E @var{NN}
- for an error
- @end table
- @item z1,@var{addr},@var{kind}
- @itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]}
- @cindex @samp{z1} packet
- @cindex @samp{Z1} packet
- Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
- address @var{addr}.
- A hardware breakpoint is implemented using a mechanism that is not
- dependent on being able to modify the target's memory. The
- @var{kind}, @var{cond_list}, and @var{cmd_list} arguments have the
- same meaning as in @samp{Z0} packets.
- @emph{Implementation note: A hardware breakpoint is not affected by code
- movement.}
- Reply:
- @table @samp
- @item OK
- success
- @item @w{}
- not supported
- @item E @var{NN}
- for an error
- @end table
- @item z2,@var{addr},@var{kind}
- @itemx Z2,@var{addr},@var{kind}
- @cindex @samp{z2} packet
- @cindex @samp{Z2} packet
- Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}.
- The number of bytes to watch is specified by @var{kind}.
- Reply:
- @table @samp
- @item OK
- success
- @item @w{}
- not supported
- @item E @var{NN}
- for an error
- @end table
- @item z3,@var{addr},@var{kind}
- @itemx Z3,@var{addr},@var{kind}
- @cindex @samp{z3} packet
- @cindex @samp{Z3} packet
- Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}.
- The number of bytes to watch is specified by @var{kind}.
- Reply:
- @table @samp
- @item OK
- success
- @item @w{}
- not supported
- @item E @var{NN}
- for an error
- @end table
- @item z4,@var{addr},@var{kind}
- @itemx Z4,@var{addr},@var{kind}
- @cindex @samp{z4} packet
- @cindex @samp{Z4} packet
- Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}.
- The number of bytes to watch is specified by @var{kind}.
- Reply:
- @table @samp
- @item OK
- success
- @item @w{}
- not supported
- @item E @var{NN}
- for an error
- @end table
- @end table
- @node Stop Reply Packets
- @section Stop Reply Packets
- @cindex stop reply packets
- The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont},
- @samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can
- receive any of the below as a reply. Except for @samp{?}
- and @samp{vStopped}, that reply is only returned
- when the target halts. In the below the exact meaning of @dfn{signal
- number} is defined by the header @file{include/gdb/signals.h} in the
- @value{GDBN} source code.
- In non-stop mode, the server will simply reply @samp{OK} to commands
- such as @samp{vCont}; any stop will be the subject of a future
- notification. @xref{Remote Non-Stop}.
- As in the description of request packets, we include spaces in the
- reply templates for clarity; these are not part of the reply packet's
- syntax. No @value{GDBN} stop reply packet uses spaces to separate its
- components.
- @table @samp
- @item S @var{AA}
- The program received signal number @var{AA} (a two-digit hexadecimal
- number). This is equivalent to a @samp{T} response with no
- @var{n}:@var{r} pairs.
- @item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
- @cindex @samp{T} packet reply
- The program received signal number @var{AA} (a two-digit hexadecimal
- number). This is equivalent to an @samp{S} response, except that the
- @samp{@var{n}:@var{r}} pairs can carry values of important registers
- and other information directly in the stop reply packet, reducing
- round-trip latency. Single-step and breakpoint traps are reported
- this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
- @itemize @bullet
- @item
- If @var{n} is a hexadecimal number, it is a register number, and the
- corresponding @var{r} gives that register's value. The data @var{r} is a
- series of bytes in target byte order, with each byte given by a
- two-digit hex number.
- @item
- If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of
- the stopped thread, as specified in @ref{thread-id syntax}.
- @item
- If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of
- the core on which the stop event was detected.
- @item
- If @var{n} is a recognized @dfn{stop reason}, it describes a more
- specific event that stopped the target. The currently defined stop
- reasons are listed below. The @var{aa} should be @samp{05}, the trap
- signal. At most one stop reason should be present.
- @item
- Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair
- and go on to the next; this allows us to extend the protocol in the
- future.
- @end itemize
- The currently defined stop reasons are:
- @table @samp
- @item watch
- @itemx rwatch
- @itemx awatch
- The packet indicates a watchpoint hit, and @var{r} is the data address, in
- hex.
- @item syscall_entry
- @itemx syscall_return
- The packet indicates a syscall entry or return, and @var{r} is the
- syscall number, in hex.
- @cindex shared library events, remote reply
- @item library
- The packet indicates that the loaded libraries have changed.
- @value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
- list of loaded libraries. The @var{r} part is ignored.
- @cindex replay log events, remote reply
- @item replaylog
- The packet indicates that the target cannot continue replaying
- logged execution events, because it has reached the end (or the
- beginning when executing backward) of the log. The value of @var{r}
- will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
- for more information.
- @item swbreak
- @anchor{swbreak stop reason}
- The packet indicates a software breakpoint instruction was executed,
- irrespective of whether it was @value{GDBN} that planted the
- breakpoint or the breakpoint is hardcoded in the program. The @var{r}
- part must be left empty.
- On some architectures, such as x86, at the architecture level, when a
- breakpoint instruction executes the program counter points at the
- breakpoint address plus an offset. On such targets, the stub is
- responsible for adjusting the PC to point back at the breakpoint
- address.
- This packet should not be sent by default; older @value{GDBN} versions
- did not support it. @value{GDBN} requests it, by supplying an
- appropriate @samp{qSupported} feature (@pxref{qSupported}). The
- remote stub must also supply the appropriate @samp{qSupported} feature
- indicating support.
- This packet is required for correct non-stop mode operation.
- @item hwbreak
- The packet indicates the target stopped for a hardware breakpoint.
- The @var{r} part must be left empty.
- The same remarks about @samp{qSupported} and non-stop mode above
- apply.
- @cindex fork events, remote reply
- @item fork
- The packet indicates that @code{fork} was called, and @var{r}
- is the thread ID of the new child process. Refer to
- @ref{thread-id syntax} for the format of the @var{thread-id}
- field. This packet is only applicable to targets that support
- fork events.
- This packet should not be sent by default; older @value{GDBN} versions
- did not support it. @value{GDBN} requests it, by supplying an
- appropriate @samp{qSupported} feature (@pxref{qSupported}). The
- remote stub must also supply the appropriate @samp{qSupported} feature
- indicating support.
- @cindex vfork events, remote reply
- @item vfork
- The packet indicates that @code{vfork} was called, and @var{r}
- is the thread ID of the new child process. Refer to
- @ref{thread-id syntax} for the format of the @var{thread-id}
- field. This packet is only applicable to targets that support
- vfork events.
- This packet should not be sent by default; older @value{GDBN} versions
- did not support it. @value{GDBN} requests it, by supplying an
- appropriate @samp{qSupported} feature (@pxref{qSupported}). The
- remote stub must also supply the appropriate @samp{qSupported} feature
- indicating support.
- @cindex vforkdone events, remote reply
- @item vforkdone
- The packet indicates that a child process created by a vfork
- has either called @code{exec} or terminated, so that the
- address spaces of the parent and child process are no longer
- shared. The @var{r} part is ignored. This packet is only
- applicable to targets that support vforkdone events.
- This packet should not be sent by default; older @value{GDBN} versions
- did not support it. @value{GDBN} requests it, by supplying an
- appropriate @samp{qSupported} feature (@pxref{qSupported}). The
- remote stub must also supply the appropriate @samp{qSupported} feature
- indicating support.
- @cindex exec events, remote reply
- @item exec
- The packet indicates that @code{execve} was called, and @var{r}
- is the absolute pathname of the file that was executed, in hex.
- This packet is only applicable to targets that support exec events.
- This packet should not be sent by default; older @value{GDBN} versions
- did not support it. @value{GDBN} requests it, by supplying an
- appropriate @samp{qSupported} feature (@pxref{qSupported}). The
- remote stub must also supply the appropriate @samp{qSupported} feature
- indicating support.
- @cindex thread create event, remote reply
- @anchor{thread create event}
- @item create
- The packet indicates that the thread was just created. The new thread
- is stopped until @value{GDBN} sets it running with a resumption packet
- (@pxref{vCont packet}). This packet should not be sent by default;
- @value{GDBN} requests it with the @ref{QThreadEvents} packet. See
- also the @samp{w} (@pxref{thread exit event}) remote reply below. The
- @var{r} part is ignored.
- @end table
- @item W @var{AA}
- @itemx W @var{AA} ; process:@var{pid}
- The process exited, and @var{AA} is the exit status. This is only
- applicable to certain targets.
- The second form of the response, including the process ID of the
- exited process, can be used only when @value{GDBN} has reported
- support for multiprocess protocol extensions; see @ref{multiprocess
- extensions}. Both @var{AA} and @var{pid} are formatted as big-endian
- hex strings.
- @item X @var{AA}
- @itemx X @var{AA} ; process:@var{pid}
- The process terminated with signal @var{AA}.
- The second form of the response, including the process ID of the
- terminated process, can be used only when @value{GDBN} has reported
- support for multiprocess protocol extensions; see @ref{multiprocess
- extensions}. Both @var{AA} and @var{pid} are formatted as big-endian
- hex strings.
- @anchor{thread exit event}
- @cindex thread exit event, remote reply
- @item w @var{AA} ; @var{tid}
- The thread exited, and @var{AA} is the exit status. This response
- should not be sent by default; @value{GDBN} requests it with the
- @ref{QThreadEvents} packet. See also @ref{thread create event} above.
- @var{AA} is formatted as a big-endian hex string.
- @item N
- There are no resumed threads left in the target. In other words, even
- though the process is alive, the last resumed thread has exited. For
- example, say the target process has two threads: thread 1 and thread
- 2. The client leaves thread 1 stopped, and resumes thread 2, which
- subsequently exits. At this point, even though the process is still
- alive, and thus no @samp{W} stop reply is sent, no thread is actually
- executing either. The @samp{N} stop reply thus informs the client
- that it can stop waiting for stop replies. This packet should not be
- sent by default; older @value{GDBN} versions did not support it.
- @value{GDBN} requests it, by supplying an appropriate
- @samp{qSupported} feature (@pxref{qSupported}). The remote stub must
- also supply the appropriate @samp{qSupported} feature indicating
- support.
- @item O @var{XX}@dots{}
- @samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
- written as the program's console output. This can happen at any time
- while the program is running and the debugger should continue to wait
- for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode.
- @item F @var{call-id},@var{parameter}@dots{}
- @var{call-id} is the identifier which says which host system call should
- be called. This is just the name of the function. Translation into the
- correct system call is only applicable as it's defined in @value{GDBN}.
- @xref{File-I/O Remote Protocol Extension}, for a list of implemented
- system calls.
- @samp{@var{parameter}@dots{}} is a list of parameters as defined for
- this very system call.
- The target replies with this packet when it expects @value{GDBN} to
- call a host system call on behalf of the target. @value{GDBN} replies
- with an appropriate @samp{F} packet and keeps up waiting for the next
- reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S}
- or @samp{s} action is expected to be continued. @xref{File-I/O Remote
- Protocol Extension}, for more details.
- @end table
- @node General Query Packets
- @section General Query Packets
- @cindex remote query requests
- Packets starting with @samp{q} are @dfn{general query packets};
- packets starting with @samp{Q} are @dfn{general set packets}. General
- query and set packets are a semi-unified form for retrieving and
- sending information to and from the stub.
- The initial letter of a query or set packet is followed by a name
- indicating what sort of thing the packet applies to. For example,
- @value{GDBN} may use a @samp{qSymbol} packet to exchange symbol
- definitions with the stub. These packet names follow some
- conventions:
- @itemize @bullet
- @item
- The name must not contain commas, colons or semicolons.
- @item
- Most @value{GDBN} query and set packets have a leading upper case
- letter.
- @item
- The names of custom vendor packets should use a company prefix, in
- lower case, followed by a period. For example, packets designed at
- the Acme Corporation might begin with @samp{qacme.foo} (for querying
- foos) or @samp{Qacme.bar} (for setting bars).
- @end itemize
- The name of a query or set packet should be separated from any
- parameters by a @samp{:}; the parameters themselves should be
- separated by @samp{,} or @samp{;}. Stubs must be careful to match the
- full packet name, and check for a separator or the end of the packet,
- in case two packet names share a common prefix. New packets should not begin
- with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL}
- packets predate these conventions, and have arguments without any terminator
- for the packet name; we suspect they are in widespread use in places that
- are difficult to upgrade. The @samp{qC} packet has no arguments, but some
- existing stubs (e.g.@: RedBoot) are known to not check for the end of the
- packet.}.
- Like the descriptions of the other packets, each description here
- has a template showing the packet's overall syntax, followed by an
- explanation of the packet's meaning. We include spaces in some of the
- templates for clarity; these are not part of the packet's syntax. No
- @value{GDBN} packet uses spaces to separate its components.
- Here are the currently defined query and set packets:
- @table @samp
- @item QAgent:1
- @itemx QAgent:0
- Turn on or off the agent as a helper to perform some debugging operations
- delegated from @value{GDBN} (@pxref{Control Agent}).
- @item QAllow:@var{op}:@var{val}@dots{}
- @cindex @samp{QAllow} packet
- Specify which operations @value{GDBN} expects to request of the
- target, as a semicolon-separated list of operation name and value
- pairs. Possible values for @var{op} include @samp{WriteReg},
- @samp{WriteMem}, @samp{InsertBreak}, @samp{InsertTrace},
- @samp{InsertFastTrace}, and @samp{Stop}. @var{val} is either 0,
- indicating that @value{GDBN} will not request the operation, or 1,
- indicating that it may. (The target can then use this to set up its
- own internals optimally, for instance if the debugger never expects to
- insert breakpoints, it may not need to install its own trap handler.)
- @item qC
- @cindex current thread, remote request
- @cindex @samp{qC} packet
- Return the current thread ID.
- Reply:
- @table @samp
- @item QC @var{thread-id}
- Where @var{thread-id} is a thread ID as documented in
- @ref{thread-id syntax}.
- @item @r{(anything else)}
- Any other reply implies the old thread ID.
- @end table
- @item qCRC:@var{addr},@var{length}
- @cindex CRC of memory block, remote request
- @cindex @samp{qCRC} packet
- @anchor{qCRC packet}
- Compute the CRC checksum of a block of memory using CRC-32 defined in
- IEEE 802.3. The CRC is computed byte at a time, taking the most
- significant bit of each byte first. The initial pattern code
- @code{0xffffffff} is used to ensure leading zeros affect the CRC.
- @emph{Note:} This is the same CRC used in validating separate debug
- files (@pxref{Separate Debug Files, , Debugging Information in Separate
- Files}). However the algorithm is slightly different. When validating
- separate debug files, the CRC is computed taking the @emph{least}
- significant bit of each byte first, and the final result is inverted to
- detect trailing zeros.
- Reply:
- @table @samp
- @item E @var{NN}
- An error (such as memory fault)
- @item C @var{crc32}
- The specified memory region's checksum is @var{crc32}.
- @end table
- @item QDisableRandomization:@var{value}
- @cindex disable address space randomization, remote request
- @cindex @samp{QDisableRandomization} packet
- Some target operating systems will randomize the virtual address space
- of the inferior process as a security feature, but provide a feature
- to disable such randomization, e.g.@: to allow for a more deterministic
- debugging experience. On such systems, this packet with a @var{value}
- of 1 directs the target to disable address space randomization for
- processes subsequently started via @samp{vRun} packets, while a packet
- with a @var{value} of 0 tells the target to enable address space
- randomization.
- This packet is only available in extended mode (@pxref{extended mode}).
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @item E @var{nn}
- An error occurred. The error number @var{nn} is given as hex digits.
- @item @w{}
- An empty reply indicates that @samp{QDisableRandomization} is not supported
- by the stub.
- @end table
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- This should only be done on targets that actually support disabling
- address space randomization.
- @item QStartupWithShell:@var{value}
- @cindex startup with shell, remote request
- @cindex @samp{QStartupWithShell} packet
- On UNIX-like targets, it is possible to start the inferior using a
- shell program. This is the default behavior on both @value{GDBN} and
- @command{gdbserver} (@pxref{set startup-with-shell}). This packet is
- used to inform @command{gdbserver} whether it should start the
- inferior using a shell or not.
- If @var{value} is @samp{0}, @command{gdbserver} will not use a shell
- to start the inferior. If @var{value} is @samp{1},
- @command{gdbserver} will use a shell to start the inferior. All other
- values are considered an error.
- This packet is only available in extended mode (@pxref{extended
- mode}).
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @item E @var{nn}
- An error occurred. The error number @var{nn} is given as hex digits.
- @end table
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response
- (@pxref{qSupported}). This should only be done on targets that
- actually support starting the inferior using a shell.
- Use of this packet is controlled by the @code{set startup-with-shell}
- command; @pxref{set startup-with-shell}.
- @item QEnvironmentHexEncoded:@var{hex-value}
- @anchor{QEnvironmentHexEncoded}
- @cindex set environment variable, remote request
- @cindex @samp{QEnvironmentHexEncoded} packet
- On UNIX-like targets, it is possible to set environment variables that
- will be passed to the inferior during the startup process. This
- packet is used to inform @command{gdbserver} of an environment
- variable that has been defined by the user on @value{GDBN} (@pxref{set
- environment}).
- The packet is composed by @var{hex-value}, an hex encoded
- representation of the @var{name=value} format representing an
- environment variable. The name of the environment variable is
- represented by @var{name}, and the value to be assigned to the
- environment variable is represented by @var{value}. If the variable
- has no value (i.e., the value is @code{null}), then @var{value} will
- not be present.
- This packet is only available in extended mode (@pxref{extended
- mode}).
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @end table
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response
- (@pxref{qSupported}). This should only be done on targets that
- actually support passing environment variables to the starting
- inferior.
- This packet is related to the @code{set environment} command;
- @pxref{set environment}.
- @item QEnvironmentUnset:@var{hex-value}
- @anchor{QEnvironmentUnset}
- @cindex unset environment variable, remote request
- @cindex @samp{QEnvironmentUnset} packet
- On UNIX-like targets, it is possible to unset environment variables
- before starting the inferior in the remote target. This packet is
- used to inform @command{gdbserver} of an environment variable that has
- been unset by the user on @value{GDBN} (@pxref{unset environment}).
- The packet is composed by @var{hex-value}, an hex encoded
- representation of the name of the environment variable to be unset.
- This packet is only available in extended mode (@pxref{extended
- mode}).
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @end table
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response
- (@pxref{qSupported}). This should only be done on targets that
- actually support passing environment variables to the starting
- inferior.
- This packet is related to the @code{unset environment} command;
- @pxref{unset environment}.
- @item QEnvironmentReset
- @anchor{QEnvironmentReset}
- @cindex reset environment, remote request
- @cindex @samp{QEnvironmentReset} packet
- On UNIX-like targets, this packet is used to reset the state of
- environment variables in the remote target before starting the
- inferior. In this context, reset means unsetting all environment
- variables that were previously set by the user (i.e., were not
- initially present in the environment). It is sent to
- @command{gdbserver} before the @samp{QEnvironmentHexEncoded}
- (@pxref{QEnvironmentHexEncoded}) and the @samp{QEnvironmentUnset}
- (@pxref{QEnvironmentUnset}) packets.
- This packet is only available in extended mode (@pxref{extended
- mode}).
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @end table
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response
- (@pxref{qSupported}). This should only be done on targets that
- actually support passing environment variables to the starting
- inferior.
- @item QSetWorkingDir:@r{[}@var{directory}@r{]}
- @anchor{QSetWorkingDir packet}
- @cindex set working directory, remote request
- @cindex @samp{QSetWorkingDir} packet
- This packet is used to inform the remote server of the intended
- current working directory for programs that are going to be executed.
- The packet is composed by @var{directory}, an hex encoded
- representation of the directory that the remote inferior will use as
- its current working directory. If @var{directory} is an empty string,
- the remote server should reset the inferior's current working
- directory to its original, empty value.
- This packet is only available in extended mode (@pxref{extended
- mode}).
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @end table
- @item qfThreadInfo
- @itemx qsThreadInfo
- @cindex list active threads, remote request
- @cindex @samp{qfThreadInfo} packet
- @cindex @samp{qsThreadInfo} packet
- Obtain a list of all active thread IDs from the target (OS). Since there
- may be too many active threads to fit into one reply packet, this query
- works iteratively: it may require more than one query/reply sequence to
- obtain the entire list of threads. The first query of the sequence will
- be the @samp{qfThreadInfo} query; subsequent queries in the
- sequence will be the @samp{qsThreadInfo} query.
- NOTE: This packet replaces the @samp{qL} query (see below).
- Reply:
- @table @samp
- @item m @var{thread-id}
- A single thread ID
- @item m @var{thread-id},@var{thread-id}@dots{}
- a comma-separated list of thread IDs
- @item l
- (lower case letter @samp{L}) denotes end of list.
- @end table
- In response to each query, the target will reply with a list of one or
- more thread IDs, separated by commas.
- @value{GDBN} will respond to each reply with a request for more thread
- ids (using the @samp{qs} form of the query), until the target responds
- with @samp{l} (lower-case ell, for @dfn{last}).
- Refer to @ref{thread-id syntax}, for the format of the @var{thread-id}
- fields.
- @emph{Note: @value{GDBN} will send the @code{qfThreadInfo} query during the
- initial connection with the remote target, and the very first thread ID
- mentioned in the reply will be stopped by @value{GDBN} in a subsequent
- message. Therefore, the stub should ensure that the first thread ID in
- the @code{qfThreadInfo} reply is suitable for being stopped by @value{GDBN}.}
- @item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
- @cindex get thread-local storage address, remote request
- @cindex @samp{qGetTLSAddr} packet
- Fetch the address associated with thread local storage specified
- by @var{thread-id}, @var{offset}, and @var{lm}.
- @var{thread-id} is the thread ID associated with the
- thread for which to fetch the TLS address. @xref{thread-id syntax}.
- @var{offset} is the (big endian, hex encoded) offset associated with the
- thread local variable. (This offset is obtained from the debug
- information associated with the variable.)
- @var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the
- load module associated with the thread local storage. For example,
- a @sc{gnu}/Linux system will pass the link map address of the shared
- object associated with the thread local storage under consideration.
- Other operating environments may choose to represent the load module
- differently, so the precise meaning of this parameter will vary.
- Reply:
- @table @samp
- @item @var{XX}@dots{}
- Hex encoded (big endian) bytes representing the address of the thread
- local storage requested.
- @item E @var{nn}
- An error occurred. The error number @var{nn} is given as hex digits.
- @item @w{}
- An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
- @end table
- @item qGetTIBAddr:@var{thread-id}
- @cindex get thread information block address
- @cindex @samp{qGetTIBAddr} packet
- Fetch address of the Windows OS specific Thread Information Block.
- @var{thread-id} is the thread ID associated with the thread.
- Reply:
- @table @samp
- @item @var{XX}@dots{}
- Hex encoded (big endian) bytes representing the linear address of the
- thread information block.
- @item E @var{nn}
- An error occured. This means that either the thread was not found, or the
- address could not be retrieved.
- @item @w{}
- An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub.
- @end table
- @item qL @var{startflag} @var{threadcount} @var{nextthread}
- Obtain thread information from RTOS. Where: @var{startflag} (one hex
- digit) is one to indicate the first query and zero to indicate a
- subsequent query; @var{threadcount} (two hex digits) is the maximum
- number of threads the response packet can contain; and @var{nextthread}
- (eight hex digits), for subsequent queries (@var{startflag} is zero), is
- returned in the response as @var{argthread}.
- Don't use this packet; use the @samp{qfThreadInfo} query instead (see above).
- Reply:
- @table @samp
- @item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{}
- Where: @var{count} (two hex digits) is the number of threads being
- returned; @var{done} (one hex digit) is zero to indicate more threads
- and one indicates no further threads; @var{argthreadid} (eight hex
- digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
- is a sequence of thread IDs, @var{threadid} (eight hex
- digits), from the target. See @code{remote.c:parse_threadlist_response()}.
- @end table
- @item qMemTags:@var{start address},@var{length}:@var{type}
- @anchor{qMemTags}
- @cindex fetch memory tags
- @cindex @samp{qMemTags} packet
- Fetch memory tags of type @var{type} from the address range
- @w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}. The
- target is responsible for calculating how many tags will be returned, as this
- is architecture-specific.
- @var{start address} is the starting address of the memory range.
- @var{length} is the length, in bytes, of the memory range.
- @var{type} is the type of tag the request wants to fetch. The type is a signed
- integer.
- Reply:
- @table @samp
- @item @var{mxx}@dots{}
- Hex encoded sequence of uninterpreted bytes, @var{xx}@dots{}, representing the
- tags found in the requested memory range.
- @item E @var{nn}
- An error occured. This means that fetching of memory tags failed for some
- reason.
- @item @w{}
- An empty reply indicates that @samp{qMemTags} is not supported by the stub,
- although this should not happen given @value{GDBN} will only send this packet
- if the stub has advertised support for memory tagging via @samp{qSupported}.
- @end table
- @item QMemTags:@var{start address},@var{length}:@var{type}:@var{tag bytes}
- @anchor{QMemTags}
- @cindex store memory tags
- @cindex @samp{QMemTags} packet
- Store memory tags of type @var{type} to the address range
- @w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}. The
- target is responsible for interpreting the type, the tag bytes and modifying
- the memory tag granules accordingly, given this is architecture-specific.
- The interpretation of how many tags (@var{nt}) should be written to how many
- memory tag granules (@var{ng}) is also architecture-specific. The behavior is
- implementation-specific, but the following is suggested.
- If the number of memory tags, @var{nt}, is greater than or equal to the
- number of memory tag granules, @var{ng}, only @var{ng} tags will be
- stored.
- If @var{nt} is less than @var{ng}, the behavior is that of a fill operation,
- and the tag bytes will be used as a pattern that will get repeated until
- @var{ng} tags are stored.
- @var{start address} is the starting address of the memory range. The address
- does not have any restriction on alignment or size.
- @var{length} is the length, in bytes, of the memory range.
- @var{type} is the type of tag the request wants to fetch. The type is a signed
- integer.
- @var{tag bytes} is a sequence of hex encoded uninterpreted bytes which will be
- interpreted by the target. Each pair of hex digits is interpreted as a
- single byte.
- Reply:
- @table @samp
- @item OK
- The request was successful and the memory tag granules were modified
- accordingly.
- @item E @var{nn}
- An error occured. This means that modifying the memory tag granules failed
- for some reason.
- @item @w{}
- An empty reply indicates that @samp{QMemTags} is not supported by the stub,
- although this should not happen given @value{GDBN} will only send this packet
- if the stub has advertised support for memory tagging via @samp{qSupported}.
- @end table
- @item qOffsets
- @cindex section offsets, remote request
- @cindex @samp{qOffsets} packet
- Get section offsets that the target used when relocating the downloaded
- image.
- Reply:
- @table @samp
- @item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]}
- Relocate the @code{Text} section by @var{xxx} from its original address.
- Relocate the @code{Data} section by @var{yyy} from its original address.
- If the object file format provides segment information (e.g.@: @sc{elf}
- @samp{PT_LOAD} program headers), @value{GDBN} will relocate entire
- segments by the supplied offsets.
- @emph{Note: while a @code{Bss} offset may be included in the response,
- @value{GDBN} ignores this and instead applies the @code{Data} offset
- to the @code{Bss} section.}
- @item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]}
- Relocate the first segment of the object file, which conventionally
- contains program code, to a starting address of @var{xxx}. If
- @samp{DataSeg} is specified, relocate the second segment, which
- conventionally contains modifiable data, to a starting address of
- @var{yyy}. @value{GDBN} will report an error if the object file
- does not contain segment information, or does not contain at least
- as many segments as mentioned in the reply. Extra segments are
- kept at fixed offsets relative to the last relocated segment.
- @end table
- @item qP @var{mode} @var{thread-id}
- @cindex thread information, remote request
- @cindex @samp{qP} packet
- Returns information on @var{thread-id}. Where: @var{mode} is a hex
- encoded 32 bit mode; @var{thread-id} is a thread ID
- (@pxref{thread-id syntax}).
- Don't use this packet; use the @samp{qThreadExtraInfo} query instead
- (see below).
- Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
- @item QNonStop:1
- @itemx QNonStop:0
- @cindex non-stop mode, remote request
- @cindex @samp{QNonStop} packet
- @anchor{QNonStop}
- Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode.
- @xref{Remote Non-Stop}, for more information.
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @item E @var{nn}
- An error occurred. The error number @var{nn} is given as hex digits.
- @item @w{}
- An empty reply indicates that @samp{QNonStop} is not supported by
- the stub.
- @end table
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- Use of this packet is controlled by the @code{set non-stop} command;
- @pxref{Non-Stop Mode}.
- @item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{}
- @itemx QCatchSyscalls:0
- @cindex catch syscalls from inferior, remote request
- @cindex @samp{QCatchSyscalls} packet
- @anchor{QCatchSyscalls}
- Enable (@samp{QCatchSyscalls:1}) or disable (@samp{QCatchSyscalls:0})
- catching syscalls from the inferior process.
- For @samp{QCatchSyscalls:1}, each listed syscall @var{sysno} (encoded
- in hex) should be reported to @value{GDBN}. If no syscall @var{sysno}
- is listed, every system call should be reported.
- Note that if a syscall not in the list is reported, @value{GDBN} will
- still filter the event according to its own list from all corresponding
- @code{catch syscall} commands. However, it is more efficient to only
- report the requested syscalls.
- Multiple @samp{QCatchSyscalls:1} packets do not combine; any earlier
- @samp{QCatchSyscalls:1} list is completely replaced by the new list.
- If the inferior process execs, the state of @samp{QCatchSyscalls} is
- kept for the new process too. On targets where exec may affect syscall
- numbers, for example with exec between 32 and 64-bit processes, the
- client should send a new packet with the new syscall list.
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @item E @var{nn}
- An error occurred. @var{nn} are hex digits.
- @item @w{}
- An empty reply indicates that @samp{QCatchSyscalls} is not supported by
- the stub.
- @end table
- Use of this packet is controlled by the @code{set remote catch-syscalls}
- command (@pxref{Remote Configuration, set remote catch-syscalls}).
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
- @cindex pass signals to inferior, remote request
- @cindex @samp{QPassSignals} packet
- @anchor{QPassSignals}
- Each listed @var{signal} should be passed directly to the inferior process.
- Signals are numbered identically to continue packets and stop replies
- (@pxref{Stop Reply Packets}). Each @var{signal} list item should be
- strictly greater than the previous item. These signals do not need to stop
- the inferior, or be reported to @value{GDBN}. All other signals should be
- reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not
- combine; any earlier @samp{QPassSignals} list is completely replaced by the
- new list. This packet improves performance when using @samp{handle
- @var{signal} nostop noprint pass}.
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @item E @var{nn}
- An error occurred. The error number @var{nn} is given as hex digits.
- @item @w{}
- An empty reply indicates that @samp{QPassSignals} is not supported by
- the stub.
- @end table
- Use of this packet is controlled by the @code{set remote pass-signals}
- command (@pxref{Remote Configuration, set remote pass-signals}).
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item QProgramSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
- @cindex signals the inferior may see, remote request
- @cindex @samp{QProgramSignals} packet
- @anchor{QProgramSignals}
- Each listed @var{signal} may be delivered to the inferior process.
- Others should be silently discarded.
- In some cases, the remote stub may need to decide whether to deliver a
- signal to the program or not without @value{GDBN} involvement. One
- example of that is while detaching --- the program's threads may have
- stopped for signals that haven't yet had a chance of being reported to
- @value{GDBN}, and so the remote stub can use the signal list specified
- by this packet to know whether to deliver or ignore those pending
- signals.
- This does not influence whether to deliver a signal as requested by a
- resumption packet (@pxref{vCont packet}).
- Signals are numbered identically to continue packets and stop replies
- (@pxref{Stop Reply Packets}). Each @var{signal} list item should be
- strictly greater than the previous item. Multiple
- @samp{QProgramSignals} packets do not combine; any earlier
- @samp{QProgramSignals} list is completely replaced by the new list.
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @item E @var{nn}
- An error occurred. The error number @var{nn} is given as hex digits.
- @item @w{}
- An empty reply indicates that @samp{QProgramSignals} is not supported
- by the stub.
- @end table
- Use of this packet is controlled by the @code{set remote program-signals}
- command (@pxref{Remote Configuration, set remote program-signals}).
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @anchor{QThreadEvents}
- @item QThreadEvents:1
- @itemx QThreadEvents:0
- @cindex thread create/exit events, remote request
- @cindex @samp{QThreadEvents} packet
- Enable (@samp{QThreadEvents:1}) or disable (@samp{QThreadEvents:0})
- reporting of thread create and exit events. @xref{thread create
- event}, for the reply specifications. For example, this is used in
- non-stop mode when @value{GDBN} stops a set of threads and
- synchronously waits for the their corresponding stop replies. Without
- exit events, if one of the threads exits, @value{GDBN} would hang
- forever not knowing that it should no longer expect a stop for that
- same thread. @value{GDBN} does not enable this feature unless the
- stub reports that it supports it by including @samp{QThreadEvents+} in
- its @samp{qSupported} reply.
- Reply:
- @table @samp
- @item OK
- The request succeeded.
- @item E @var{nn}
- An error occurred. The error number @var{nn} is given as hex digits.
- @item @w{}
- An empty reply indicates that @samp{QThreadEvents} is not supported by
- the stub.
- @end table
- Use of this packet is controlled by the @code{set remote thread-events}
- command (@pxref{Remote Configuration, set remote thread-events}).
- @item qRcmd,@var{command}
- @cindex execute remote command, remote request
- @cindex @samp{qRcmd} packet
- @var{command} (hex encoded) is passed to the local interpreter for
- execution. Invalid commands should be reported using the output
- string. Before the final result packet, the target may also respond
- with a number of intermediate @samp{O@var{output}} console output
- packets. @emph{Implementors should note that providing access to a
- stubs's interpreter may have security implications}.
- Reply:
- @table @samp
- @item OK
- A command response with no output.
- @item @var{OUTPUT}
- A command response with the hex encoded output string @var{OUTPUT}.
- @item E @var{NN}
- Indicate a badly formed request. The error number @var{NN} is given as
- hex digits.
- @item @w{}
- An empty reply indicates that @samp{qRcmd} is not recognized.
- @end table
- (Note that the @code{qRcmd} packet's name is separated from the
- command by a @samp{,}, not a @samp{:}, contrary to the naming
- conventions above. Please don't use this packet as a model for new
- packets.)
- @item qSearch:memory:@var{address};@var{length};@var{search-pattern}
- @cindex searching memory, in remote debugging
- @ifnotinfo
- @cindex @samp{qSearch:memory} packet
- @end ifnotinfo
- @cindex @samp{qSearch memory} packet
- @anchor{qSearch memory}
- Search @var{length} bytes at @var{address} for @var{search-pattern}.
- Both @var{address} and @var{length} are encoded in hex;
- @var{search-pattern} is a sequence of bytes, also hex encoded.
- Reply:
- @table @samp
- @item 0
- The pattern was not found.
- @item 1,address
- The pattern was found at @var{address}.
- @item E @var{NN}
- A badly formed request or an error was encountered while searching memory.
- @item @w{}
- An empty reply indicates that @samp{qSearch:memory} is not recognized.
- @end table
- @item QStartNoAckMode
- @cindex @samp{QStartNoAckMode} packet
- @anchor{QStartNoAckMode}
- Request that the remote stub disable the normal @samp{+}/@samp{-}
- protocol acknowledgments (@pxref{Packet Acknowledgment}).
- Reply:
- @table @samp
- @item OK
- The stub has switched to no-acknowledgment mode.
- @value{GDBN} acknowledges this response,
- but neither the stub nor @value{GDBN} shall send or expect further
- @samp{+}/@samp{-} acknowledgments in the current connection.
- @item @w{}
- An empty reply indicates that the stub does not support no-acknowledgment mode.
- @end table
- @item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]}
- @cindex supported packets, remote query
- @cindex features of the remote protocol
- @cindex @samp{qSupported} packet
- @anchor{qSupported}
- Tell the remote stub about features supported by @value{GDBN}, and
- query the stub for features it supports. This packet allows
- @value{GDBN} and the remote stub to take advantage of each others'
- features. @samp{qSupported} also consolidates multiple feature probes
- at startup, to improve @value{GDBN} performance---a single larger
- packet performs better than multiple smaller probe packets on
- high-latency links. Some features may enable behavior which must not
- be on by default, e.g.@: because it would confuse older clients or
- stubs. Other features may describe packets which could be
- automatically probed for, but are not. These features must be
- reported before @value{GDBN} will use them. This ``default
- unsupported'' behavior is not appropriate for all packets, but it
- helps to keep the initial connection time under control with new
- versions of @value{GDBN} which support increasing numbers of packets.
- Reply:
- @table @samp
- @item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{}
- The stub supports or does not support each returned @var{stubfeature},
- depending on the form of each @var{stubfeature} (see below for the
- possible forms).
- @item @w{}
- An empty reply indicates that @samp{qSupported} is not recognized,
- or that no features needed to be reported to @value{GDBN}.
- @end table
- The allowed forms for each feature (either a @var{gdbfeature} in the
- @samp{qSupported} packet, or a @var{stubfeature} in the response)
- are:
- @table @samp
- @item @var{name}=@var{value}
- The remote protocol feature @var{name} is supported, and associated
- with the specified @var{value}. The format of @var{value} depends
- on the feature, but it must not include a semicolon.
- @item @var{name}+
- The remote protocol feature @var{name} is supported, and does not
- need an associated value.
- @item @var{name}-
- The remote protocol feature @var{name} is not supported.
- @item @var{name}?
- The remote protocol feature @var{name} may be supported, and
- @value{GDBN} should auto-detect support in some other way when it is
- needed. This form will not be used for @var{gdbfeature} notifications,
- but may be used for @var{stubfeature} responses.
- @end table
- Whenever the stub receives a @samp{qSupported} request, the
- supplied set of @value{GDBN} features should override any previous
- request. This allows @value{GDBN} to put the stub in a known
- state, even if the stub had previously been communicating with
- a different version of @value{GDBN}.
- The following values of @var{gdbfeature} (for the packet sent by @value{GDBN})
- are defined:
- @table @samp
- @item multiprocess
- This feature indicates whether @value{GDBN} supports multiprocess
- extensions to the remote protocol. @value{GDBN} does not use such
- extensions unless the stub also reports that it supports them by
- including @samp{multiprocess+} in its @samp{qSupported} reply.
- @xref{multiprocess extensions}, for details.
- @item xmlRegisters
- This feature indicates that @value{GDBN} supports the XML target
- description. If the stub sees @samp{xmlRegisters=} with target
- specific strings separated by a comma, it will report register
- description.
- @item qRelocInsn
- This feature indicates whether @value{GDBN} supports the
- @samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate
- instruction reply packet}).
- @item swbreak
- This feature indicates whether @value{GDBN} supports the swbreak stop
- reason in stop replies. @xref{swbreak stop reason}, for details.
- @item hwbreak
- This feature indicates whether @value{GDBN} supports the hwbreak stop
- reason in stop replies. @xref{swbreak stop reason}, for details.
- @item fork-events
- This feature indicates whether @value{GDBN} supports fork event
- extensions to the remote protocol. @value{GDBN} does not use such
- extensions unless the stub also reports that it supports them by
- including @samp{fork-events+} in its @samp{qSupported} reply.
- @item vfork-events
- This feature indicates whether @value{GDBN} supports vfork event
- extensions to the remote protocol. @value{GDBN} does not use such
- extensions unless the stub also reports that it supports them by
- including @samp{vfork-events+} in its @samp{qSupported} reply.
- @item exec-events
- This feature indicates whether @value{GDBN} supports exec event
- extensions to the remote protocol. @value{GDBN} does not use such
- extensions unless the stub also reports that it supports them by
- including @samp{exec-events+} in its @samp{qSupported} reply.
- @item vContSupported
- This feature indicates whether @value{GDBN} wants to know the
- supported actions in the reply to @samp{vCont?} packet.
- @end table
- Stubs should ignore any unknown values for
- @var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported}
- packet supports receiving packets of unlimited length (earlier
- versions of @value{GDBN} may reject overly long responses). Additional values
- for @var{gdbfeature} may be defined in the future to let the stub take
- advantage of new features in @value{GDBN}, e.g.@: incompatible
- improvements in the remote protocol---the @samp{multiprocess} feature is
- an example of such a feature. The stub's reply should be independent
- of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN}
- describes all the features it supports, and then the stub replies with
- all the features it supports.
- Similarly, @value{GDBN} will silently ignore unrecognized stub feature
- responses, as long as each response uses one of the standard forms.
- Some features are flags. A stub which supports a flag feature
- should respond with a @samp{+} form response. Other features
- require values, and the stub should respond with an @samp{=}
- form response.
- Each feature has a default value, which @value{GDBN} will use if
- @samp{qSupported} is not available or if the feature is not mentioned
- in the @samp{qSupported} response. The default values are fixed; a
- stub is free to omit any feature responses that match the defaults.
- Not all features can be probed, but for those which can, the probing
- mechanism is useful: in some cases, a stub's internal
- architecture may not allow the protocol layer to know some information
- about the underlying target in advance. This is especially common in
- stubs which may be configured for multiple targets.
- These are the currently defined stub features and their properties:
- @multitable @columnfractions 0.35 0.2 0.12 0.2
- @c NOTE: The first row should be @headitem, but we do not yet require
- @c a new enough version of Texinfo (4.7) to use @headitem.
- @item Feature Name
- @tab Value Required
- @tab Default
- @tab Probe Allowed
- @item @samp{PacketSize}
- @tab Yes
- @tab @samp{-}
- @tab No
- @item @samp{qXfer:auxv:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:btrace:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:btrace-conf:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:exec-file:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:features:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:libraries:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:libraries-svr4:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{augmented-libraries-svr4-read}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{qXfer:memory-map:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:sdata:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:siginfo:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:siginfo:write}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:threads:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:traceframe-info:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:uib:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{qXfer:fdpic:read}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{Qbtrace:off}
- @tab Yes
- @tab @samp{-}
- @tab Yes
- @item @samp{Qbtrace:bts}
- @tab Yes
- @tab @samp{-}
- @tab Yes
- @item @samp{Qbtrace:pt}
- @tab Yes
- @tab @samp{-}
- @tab Yes
- @item @samp{Qbtrace-conf:bts:size}
- @tab Yes
- @tab @samp{-}
- @tab Yes
- @item @samp{Qbtrace-conf:pt:size}
- @tab Yes
- @tab @samp{-}
- @tab Yes
- @item @samp{QNonStop}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{QCatchSyscalls}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{QPassSignals}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{QStartNoAckMode}
- @tab No
- @tab @samp{-}
- @tab Yes
- @item @samp{multiprocess}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{ConditionalBreakpoints}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{ConditionalTracepoints}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{ReverseContinue}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{ReverseStep}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{TracepointSource}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{QAgent}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{QAllow}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{QDisableRandomization}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{EnableDisableTracepoints}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{QTBuffer:size}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{tracenz}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{BreakpointCommands}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{swbreak}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{hwbreak}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{fork-events}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{vfork-events}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{exec-events}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{QThreadEvents}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{no-resumed}
- @tab No
- @tab @samp{-}
- @tab No
- @item @samp{memory-tagging}
- @tab No
- @tab @samp{-}
- @tab No
- @end multitable
- These are the currently defined stub features, in more detail:
- @table @samp
- @cindex packet size, remote protocol
- @item PacketSize=@var{bytes}
- The remote stub can accept packets up to at least @var{bytes} in
- length. @value{GDBN} will send packets up to this size for bulk
- transfers, and will never send larger packets. This is a limit on the
- data characters in the packet, including the frame and checksum.
- There is no trailing NUL byte in a remote protocol packet; if the stub
- stores packets in a NUL-terminated format, it should allow an extra
- byte in its buffer for the NUL. If this stub feature is not supported,
- @value{GDBN} guesses based on the size of the @samp{g} packet response.
- @item qXfer:auxv:read
- The remote stub understands the @samp{qXfer:auxv:read} packet
- (@pxref{qXfer auxiliary vector read}).
- @item qXfer:btrace:read
- The remote stub understands the @samp{qXfer:btrace:read}
- packet (@pxref{qXfer btrace read}).
- @item qXfer:btrace-conf:read
- The remote stub understands the @samp{qXfer:btrace-conf:read}
- packet (@pxref{qXfer btrace-conf read}).
- @item qXfer:exec-file:read
- The remote stub understands the @samp{qXfer:exec-file:read} packet
- (@pxref{qXfer executable filename read}).
- @item qXfer:features:read
- The remote stub understands the @samp{qXfer:features:read} packet
- (@pxref{qXfer target description read}).
- @item qXfer:libraries:read
- The remote stub understands the @samp{qXfer:libraries:read} packet
- (@pxref{qXfer library list read}).
- @item qXfer:libraries-svr4:read
- The remote stub understands the @samp{qXfer:libraries-svr4:read} packet
- (@pxref{qXfer svr4 library list read}).
- @item augmented-libraries-svr4-read
- The remote stub understands the augmented form of the
- @samp{qXfer:libraries-svr4:read} packet
- (@pxref{qXfer svr4 library list read}).
- @item qXfer:memory-map:read
- The remote stub understands the @samp{qXfer:memory-map:read} packet
- (@pxref{qXfer memory map read}).
- @item qXfer:sdata:read
- The remote stub understands the @samp{qXfer:sdata:read} packet
- (@pxref{qXfer sdata read}).
- @item qXfer:siginfo:read
- The remote stub understands the @samp{qXfer:siginfo:read} packet
- (@pxref{qXfer siginfo read}).
- @item qXfer:siginfo:write
- The remote stub understands the @samp{qXfer:siginfo:write} packet
- (@pxref{qXfer siginfo write}).
- @item qXfer:threads:read
- The remote stub understands the @samp{qXfer:threads:read} packet
- (@pxref{qXfer threads read}).
- @item qXfer:traceframe-info:read
- The remote stub understands the @samp{qXfer:traceframe-info:read}
- packet (@pxref{qXfer traceframe info read}).
- @item qXfer:uib:read
- The remote stub understands the @samp{qXfer:uib:read}
- packet (@pxref{qXfer unwind info block}).
- @item qXfer:fdpic:read
- The remote stub understands the @samp{qXfer:fdpic:read}
- packet (@pxref{qXfer fdpic loadmap read}).
- @item QNonStop
- The remote stub understands the @samp{QNonStop} packet
- (@pxref{QNonStop}).
- @item QCatchSyscalls
- The remote stub understands the @samp{QCatchSyscalls} packet
- (@pxref{QCatchSyscalls}).
- @item QPassSignals
- The remote stub understands the @samp{QPassSignals} packet
- (@pxref{QPassSignals}).
- @item QStartNoAckMode
- The remote stub understands the @samp{QStartNoAckMode} packet and
- prefers to operate in no-acknowledgment mode. @xref{Packet Acknowledgment}.
- @item multiprocess
- @anchor{multiprocess extensions}
- @cindex multiprocess extensions, in remote protocol
- The remote stub understands the multiprocess extensions to the remote
- protocol syntax. The multiprocess extensions affect the syntax of
- thread IDs in both packets and replies (@pxref{thread-id syntax}), and
- add process IDs to the @samp{D} packet and @samp{W} and @samp{X}
- replies. Note that reporting this feature indicates support for the
- syntactic extensions only, not that the stub necessarily supports
- debugging of more than one process at a time. The stub must not use
- multiprocess extensions in packet replies unless @value{GDBN} has also
- indicated it supports them in its @samp{qSupported} request.
- @item qXfer:osdata:read
- The remote stub understands the @samp{qXfer:osdata:read} packet
- ((@pxref{qXfer osdata read}).
- @item ConditionalBreakpoints
- The target accepts and implements evaluation of conditional expressions
- defined for breakpoints. The target will only report breakpoint triggers
- when such conditions are true (@pxref{Conditions, ,Break Conditions}).
- @item ConditionalTracepoints
- The remote stub accepts and implements conditional expressions defined
- for tracepoints (@pxref{Tracepoint Conditions}).
- @item ReverseContinue
- The remote stub accepts and implements the reverse continue packet
- (@pxref{bc}).
- @item ReverseStep
- The remote stub accepts and implements the reverse step packet
- (@pxref{bs}).
- @item TracepointSource
- The remote stub understands the @samp{QTDPsrc} packet that supplies
- the source form of tracepoint definitions.
- @item QAgent
- The remote stub understands the @samp{QAgent} packet.
- @item QAllow
- The remote stub understands the @samp{QAllow} packet.
- @item QDisableRandomization
- The remote stub understands the @samp{QDisableRandomization} packet.
- @item StaticTracepoint
- @cindex static tracepoints, in remote protocol
- The remote stub supports static tracepoints.
- @item InstallInTrace
- @anchor{install tracepoint in tracing}
- The remote stub supports installing tracepoint in tracing.
- @item EnableDisableTracepoints
- The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and
- @samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints
- to be enabled and disabled while a trace experiment is running.
- @item QTBuffer:size
- The remote stub supports the @samp{QTBuffer:size} (@pxref{QTBuffer-size})
- packet that allows to change the size of the trace buffer.
- @item tracenz
- @cindex string tracing, in remote protocol
- The remote stub supports the @samp{tracenz} bytecode for collecting strings.
- See @ref{Bytecode Descriptions} for details about the bytecode.
- @item BreakpointCommands
- @cindex breakpoint commands, in remote protocol
- The remote stub supports running a breakpoint's command list itself,
- rather than reporting the hit to @value{GDBN}.
- @item Qbtrace:off
- The remote stub understands the @samp{Qbtrace:off} packet.
- @item Qbtrace:bts
- The remote stub understands the @samp{Qbtrace:bts} packet.
- @item Qbtrace:pt
- The remote stub understands the @samp{Qbtrace:pt} packet.
- @item Qbtrace-conf:bts:size
- The remote stub understands the @samp{Qbtrace-conf:bts:size} packet.
- @item Qbtrace-conf:pt:size
- The remote stub understands the @samp{Qbtrace-conf:pt:size} packet.
- @item swbreak
- The remote stub reports the @samp{swbreak} stop reason for memory
- breakpoints.
- @item hwbreak
- The remote stub reports the @samp{hwbreak} stop reason for hardware
- breakpoints.
- @item fork-events
- The remote stub reports the @samp{fork} stop reason for fork events.
- @item vfork-events
- The remote stub reports the @samp{vfork} stop reason for vfork events
- and vforkdone events.
- @item exec-events
- The remote stub reports the @samp{exec} stop reason for exec events.
- @item vContSupported
- The remote stub reports the supported actions in the reply to
- @samp{vCont?} packet.
- @item QThreadEvents
- The remote stub understands the @samp{QThreadEvents} packet.
- @item no-resumed
- The remote stub reports the @samp{N} stop reply.
- @item memory-tagging
- The remote stub supports and implements the required memory tagging
- functionality and understands the @samp{qMemTags} (@pxref{qMemTags}) and
- @samp{QMemTags} (@pxref{QMemTags}) packets.
- For AArch64 GNU/Linux systems, this feature also requires access to the
- @file{/proc/@var{pid}/smaps} file so memory mapping page flags can be inspected.
- This is done via the @samp{vFile} requests.
- @end table
- @item qSymbol::
- @cindex symbol lookup, remote request
- @cindex @samp{qSymbol} packet
- Notify the target that @value{GDBN} is prepared to serve symbol lookup
- requests. Accept requests from the target for the values of symbols.
- Reply:
- @table @samp
- @item OK
- The target does not need to look up any (more) symbols.
- @item qSymbol:@var{sym_name}
- The target requests the value of symbol @var{sym_name} (hex encoded).
- @value{GDBN} may provide the value by using the
- @samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described
- below.
- @end table
- @item qSymbol:@var{sym_value}:@var{sym_name}
- Set the value of @var{sym_name} to @var{sym_value}.
- @var{sym_name} (hex encoded) is the name of a symbol whose value the
- target has previously requested.
- @var{sym_value} (hex) is the value for symbol @var{sym_name}. If
- @value{GDBN} cannot supply a value for @var{sym_name}, then this field
- will be empty.
- Reply:
- @table @samp
- @item OK
- The target does not need to look up any (more) symbols.
- @item qSymbol:@var{sym_name}
- The target requests the value of a new symbol @var{sym_name} (hex
- encoded). @value{GDBN} will continue to supply the values of symbols
- (if available), until the target ceases to request them.
- @end table
- @item qTBuffer
- @itemx QTBuffer
- @itemx QTDisconnected
- @itemx QTDP
- @itemx QTDPsrc
- @itemx QTDV
- @itemx qTfP
- @itemx qTfV
- @itemx QTFrame
- @itemx qTMinFTPILen
- @xref{Tracepoint Packets}.
- @anchor{qThreadExtraInfo}
- @item qThreadExtraInfo,@var{thread-id}
- @cindex thread attributes info, remote request
- @cindex @samp{qThreadExtraInfo} packet
- Obtain from the target OS a printable string description of thread
- attributes for the thread @var{thread-id}; see @ref{thread-id syntax},
- for the forms of @var{thread-id}. This
- string may contain anything that the target OS thinks is interesting
- for @value{GDBN} to tell the user about the thread. The string is
- displayed in @value{GDBN}'s @code{info threads} display. Some
- examples of possible thread extra info strings are @samp{Runnable}, or
- @samp{Blocked on Mutex}.
- Reply:
- @table @samp
- @item @var{XX}@dots{}
- Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data,
- comprising the printable string containing the extra information about
- the thread's attributes.
- @end table
- (Note that the @code{qThreadExtraInfo} packet's name is separated from
- the command by a @samp{,}, not a @samp{:}, contrary to the naming
- conventions above. Please don't use this packet as a model for new
- packets.)
- @item QTNotes
- @itemx qTP
- @itemx QTSave
- @itemx qTsP
- @itemx qTsV
- @itemx QTStart
- @itemx QTStop
- @itemx QTEnable
- @itemx QTDisable
- @itemx QTinit
- @itemx QTro
- @itemx qTStatus
- @itemx qTV
- @itemx qTfSTM
- @itemx qTsSTM
- @itemx qTSTMat
- @xref{Tracepoint Packets}.
- @item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
- @cindex read special object, remote request
- @cindex @samp{qXfer} packet
- @anchor{qXfer read}
- Read uninterpreted bytes from the target's special data area
- identified by the keyword @var{object}. Request @var{length} bytes
- starting at @var{offset} bytes into the data. The content and
- encoding of @var{annex} is specific to @var{object}; it can supply
- additional details about what data to access.
- Reply:
- @table @samp
- @item m @var{data}
- Data @var{data} (@pxref{Binary Data}) has been read from the
- target. There may be more data at a higher address (although
- it is permitted to return @samp{m} even for the last valid
- block of data, as long as at least one byte of data was read).
- It is possible for @var{data} to have fewer bytes than the @var{length} in the
- request.
- @item l @var{data}
- Data @var{data} (@pxref{Binary Data}) has been read from the target.
- There is no more data to be read. It is possible for @var{data} to
- have fewer bytes than the @var{length} in the request.
- @item l
- The @var{offset} in the request is at the end of the data.
- There is no more data to be read.
- @item E00
- The request was malformed, or @var{annex} was invalid.
- @item E @var{nn}
- The offset was invalid, or there was an error encountered reading the data.
- The @var{nn} part is a hex-encoded @code{errno} value.
- @item @w{}
- An empty reply indicates the @var{object} string was not recognized by
- the stub, or that the object does not support reading.
- @end table
- Here are the specific requests of this form defined so far. All the
- @samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
- formats, listed above.
- @table @samp
- @item qXfer:auxv:read::@var{offset},@var{length}
- @anchor{qXfer auxiliary vector read}
- Access the target's @dfn{auxiliary vector}. @xref{OS Information,
- auxiliary vector}. Note @var{annex} must be empty.
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:btrace:read:@var{annex}:@var{offset},@var{length}
- @anchor{qXfer btrace read}
- Return a description of the current branch trace.
- @xref{Branch Trace Format}. The annex part of the generic @samp{qXfer}
- packet may have one of the following values:
- @table @code
- @item all
- Returns all available branch trace.
- @item new
- Returns all available branch trace if the branch trace changed since
- the last read request.
- @item delta
- Returns the new branch trace since the last read request. Adds a new
- block to the end of the trace that begins at zero and ends at the source
- location of the first branch in the trace buffer. This extra block is
- used to stitch traces together.
- If the trace buffer overflowed, returns an error indicating the overflow.
- @end table
- This packet is not probed by default; the remote stub must request it
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:btrace-conf:read::@var{offset},@var{length}
- @anchor{qXfer btrace-conf read}
- Return a description of the current branch trace configuration.
- @xref{Branch Trace Configuration Format}.
- This packet is not probed by default; the remote stub must request it
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:exec-file:read:@var{annex}:@var{offset},@var{length}
- @anchor{qXfer executable filename read}
- Return the full absolute name of the file that was executed to create
- a process running on the remote system. The annex specifies the
- numeric process ID of the process to query, encoded as a hexadecimal
- number. If the annex part is empty the remote stub should return the
- filename corresponding to the currently executing process.
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:features:read:@var{annex}:@var{offset},@var{length}
- @anchor{qXfer target description read}
- Access the @dfn{target description}. @xref{Target Descriptions}. The
- annex specifies which XML document to access. The main description is
- always loaded from the @samp{target.xml} annex.
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:libraries:read:@var{annex}:@var{offset},@var{length}
- @anchor{qXfer library list read}
- Access the target's list of loaded libraries. @xref{Library List Format}.
- The annex part of the generic @samp{qXfer} packet must be empty
- (@pxref{qXfer read}).
- Targets which maintain a list of libraries in the program's memory do
- not need to implement this packet; it is designed for platforms where
- the operating system manages the list of loaded libraries.
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:libraries-svr4:read:@var{annex}:@var{offset},@var{length}
- @anchor{qXfer svr4 library list read}
- Access the target's list of loaded libraries when the target is an SVR4
- platform. @xref{Library List Format for SVR4 Targets}. The annex part
- of the generic @samp{qXfer} packet must be empty unless the remote
- stub indicated it supports the augmented form of this packet
- by supplying an appropriate @samp{qSupported} response
- (@pxref{qXfer read}, @ref{qSupported}).
- This packet is optional for better performance on SVR4 targets.
- @value{GDBN} uses memory read packets to read the SVR4 library list otherwise.
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- If the remote stub indicates it supports the augmented form of this
- packet then the annex part of the generic @samp{qXfer} packet may
- contain a semicolon-separated list of @samp{@var{name}=@var{value}}
- arguments. The currently supported arguments are:
- @table @code
- @item start=@var{address}
- A hexadecimal number specifying the address of the @samp{struct
- link_map} to start reading the library list from. If unset or zero
- then the first @samp{struct link_map} in the library list will be
- chosen as the starting point.
- @item prev=@var{address}
- A hexadecimal number specifying the address of the @samp{struct
- link_map} immediately preceding the @samp{struct link_map}
- specified by the @samp{start} argument. If unset or zero then
- the remote stub will expect that no @samp{struct link_map}
- exists prior to the starting point.
- @end table
- Arguments that are not understood by the remote stub will be silently
- ignored.
- @item qXfer:memory-map:read::@var{offset},@var{length}
- @anchor{qXfer memory map read}
- Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The
- annex part of the generic @samp{qXfer} packet must be empty
- (@pxref{qXfer read}).
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:sdata:read::@var{offset},@var{length}
- @anchor{qXfer sdata read}
- Read contents of the extra collected static tracepoint marker
- information. The annex part of the generic @samp{qXfer} packet must
- be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint
- Action Lists}.
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response
- (@pxref{qSupported}).
- @item qXfer:siginfo:read::@var{offset},@var{length}
- @anchor{qXfer siginfo read}
- Read contents of the extra signal information on the target
- system. The annex part of the generic @samp{qXfer} packet must be
- empty (@pxref{qXfer read}).
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response
- (@pxref{qSupported}).
- @item qXfer:threads:read::@var{offset},@var{length}
- @anchor{qXfer threads read}
- Access the list of threads on target. @xref{Thread List Format}. The
- annex part of the generic @samp{qXfer} packet must be empty
- (@pxref{qXfer read}).
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:traceframe-info:read::@var{offset},@var{length}
- @anchor{qXfer traceframe info read}
- Return a description of the current traceframe's contents.
- @xref{Traceframe Info Format}. The annex part of the generic
- @samp{qXfer} packet must be empty (@pxref{qXfer read}).
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:uib:read:@var{pc}:@var{offset},@var{length}
- @anchor{qXfer unwind info block}
- Return the unwind information block for @var{pc}. This packet is used
- on OpenVMS/ia64 to ask the kernel unwind information.
- This packet is not probed by default.
- @item qXfer:fdpic:read:@var{annex}:@var{offset},@var{length}
- @anchor{qXfer fdpic loadmap read}
- Read contents of @code{loadmap}s on the target system. The
- annex, either @samp{exec} or @samp{interp}, specifies which @code{loadmap},
- executable @code{loadmap} or interpreter @code{loadmap} to read.
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
- @item qXfer:osdata:read::@var{offset},@var{length}
- @anchor{qXfer osdata read}
- Access the target's @dfn{operating system information}.
- @xref{Operating System Information}.
- @end table
- @item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
- @cindex write data into object, remote request
- @anchor{qXfer write}
- Write uninterpreted bytes into the target's special data area
- identified by the keyword @var{object}, starting at @var{offset} bytes
- into the data. The binary-encoded data (@pxref{Binary Data}) to be
- written is given by @var{data}@dots{}. The content and encoding of @var{annex}
- is specific to @var{object}; it can supply additional details about what data
- to access.
- Reply:
- @table @samp
- @item @var{nn}
- @var{nn} (hex encoded) is the number of bytes written.
- This may be fewer bytes than supplied in the request.
- @item E00
- The request was malformed, or @var{annex} was invalid.
- @item E @var{nn}
- The offset was invalid, or there was an error encountered writing the data.
- The @var{nn} part is a hex-encoded @code{errno} value.
- @item @w{}
- An empty reply indicates the @var{object} string was not
- recognized by the stub, or that the object does not support writing.
- @end table
- Here are the specific requests of this form defined so far. All the
- @samp{qXfer:@var{object}:write:@dots{}} requests use the same reply
- formats, listed above.
- @table @samp
- @item qXfer:siginfo:write::@var{offset}:@var{data}@dots{}
- @anchor{qXfer siginfo write}
- Write @var{data} to the extra signal information on the target system.
- The annex part of the generic @samp{qXfer} packet must be
- empty (@pxref{qXfer write}).
- This packet is not probed by default; the remote stub must request it,
- by supplying an appropriate @samp{qSupported} response
- (@pxref{qSupported}).
- @end table
- @item qXfer:@var{object}:@var{operation}:@dots{}
- Requests of this form may be added in the future. When a stub does
- not recognize the @var{object} keyword, or its support for
- @var{object} does not recognize the @var{operation} keyword, the stub
- must respond with an empty packet.
- @item qAttached:@var{pid}
- @cindex query attached, remote request
- @cindex @samp{qAttached} packet
- Return an indication of whether the remote server attached to an
- existing process or created a new process. When the multiprocess
- protocol extensions are supported (@pxref{multiprocess extensions}),
- @var{pid} is an integer in hexadecimal format identifying the target
- process. Otherwise, @value{GDBN} will omit the @var{pid} field and
- the query packet will be simplified as @samp{qAttached}.
- This query is used, for example, to know whether the remote process
- should be detached or killed when a @value{GDBN} session is ended with
- the @code{quit} command.
- Reply:
- @table @samp
- @item 1
- The remote server attached to an existing process.
- @item 0
- The remote server created a new process.
- @item E @var{NN}
- A badly formed request or an error was encountered.
- @end table
- @item Qbtrace:bts
- Enable branch tracing for the current thread using Branch Trace Store.
- Reply:
- @table @samp
- @item OK
- Branch tracing has been enabled.
- @item E.errtext
- A badly formed request or an error was encountered.
- @end table
- @item Qbtrace:pt
- Enable branch tracing for the current thread using Intel Processor Trace.
- Reply:
- @table @samp
- @item OK
- Branch tracing has been enabled.
- @item E.errtext
- A badly formed request or an error was encountered.
- @end table
- @item Qbtrace:off
- Disable branch tracing for the current thread.
- Reply:
- @table @samp
- @item OK
- Branch tracing has been disabled.
- @item E.errtext
- A badly formed request or an error was encountered.
- @end table
- @item Qbtrace-conf:bts:size=@var{value}
- Set the requested ring buffer size for new threads that use the
- btrace recording method in bts format.
- Reply:
- @table @samp
- @item OK
- The ring buffer size has been set.
- @item E.errtext
- A badly formed request or an error was encountered.
- @end table
- @item Qbtrace-conf:pt:size=@var{value}
- Set the requested ring buffer size for new threads that use the
- btrace recording method in pt format.
- Reply:
- @table @samp
- @item OK
- The ring buffer size has been set.
- @item E.errtext
- A badly formed request or an error was encountered.
- @end table
- @end table
- @node Architecture-Specific Protocol Details
- @section Architecture-Specific Protocol Details
- This section describes how the remote protocol is applied to specific
- target architectures. Also see @ref{Standard Target Features}, for
- details of XML target descriptions for each architecture.
- @menu
- * ARM-Specific Protocol Details::
- * MIPS-Specific Protocol Details::
- @end menu
- @node ARM-Specific Protocol Details
- @subsection @acronym{ARM}-specific Protocol Details
- @menu
- * ARM Breakpoint Kinds::
- * ARM Memory Tag Types::
- @end menu
- @node ARM Breakpoint Kinds
- @subsubsection @acronym{ARM} Breakpoint Kinds
- @cindex breakpoint kinds, @acronym{ARM}
- These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
- @table @r
- @item 2
- 16-bit Thumb mode breakpoint.
- @item 3
- 32-bit Thumb mode (Thumb-2) breakpoint.
- @item 4
- 32-bit @acronym{ARM} mode breakpoint.
- @end table
- @node ARM Memory Tag Types
- @subsubsection @acronym{ARM} Memory Tag Types
- @cindex memory tag types, @acronym{ARM}
- These memory tag types are defined for the @samp{qMemTag} and @samp{QMemTag}
- packets.
- @table @r
- @item 0
- MTE logical tag
- @item 1
- MTE allocation tag
- @end table
- @node MIPS-Specific Protocol Details
- @subsection @acronym{MIPS}-specific Protocol Details
- @menu
- * MIPS Register packet Format::
- * MIPS Breakpoint Kinds::
- @end menu
- @node MIPS Register packet Format
- @subsubsection @acronym{MIPS} Register Packet Format
- @cindex register packet format, @acronym{MIPS}
- The following @code{g}/@code{G} packets have previously been defined.
- In the below, some thirty-two bit registers are transferred as
- sixty-four bits. Those registers should be zero/sign extended (which?)
- to fill the space allocated. Register bytes are transferred in target
- byte order. The two nibbles within a register byte are transferred
- most-significant -- least-significant.
- @table @r
- @item MIPS32
- All registers are transferred as thirty-two bit quantities in the order:
- 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
- registers; fsr; fir; fp.
- @item MIPS64
- All registers are transferred as sixty-four bit quantities (including
- thirty-two bit registers such as @code{sr}). The ordering is the same
- as @code{MIPS32}.
- @end table
- @node MIPS Breakpoint Kinds
- @subsubsection @acronym{MIPS} Breakpoint Kinds
- @cindex breakpoint kinds, @acronym{MIPS}
- These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
- @table @r
- @item 2
- 16-bit @acronym{MIPS16} mode breakpoint.
- @item 3
- 16-bit @acronym{microMIPS} mode breakpoint.
- @item 4
- 32-bit standard @acronym{MIPS} mode breakpoint.
- @item 5
- 32-bit @acronym{microMIPS} mode breakpoint.
- @end table
- @node Tracepoint Packets
- @section Tracepoint Packets
- @cindex tracepoint packets
- @cindex packets, tracepoint
- Here we describe the packets @value{GDBN} uses to implement
- tracepoints (@pxref{Tracepoints}).
- @table @samp
- @item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]}
- @cindex @samp{QTDP} packet
- Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
- is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
- the tracepoint is disabled. The @var{step} gives the tracepoint's step
- count, and @var{pass} gives its pass count. If an @samp{F} is present,
- then the tracepoint is to be a fast tracepoint, and the @var{flen} is
- the number of bytes that the target should copy elsewhere to make room
- for the tracepoint. If an @samp{X} is present, it introduces a
- tracepoint condition, which consists of a hexadecimal length, followed
- by a comma and hex-encoded bytes, in a manner similar to action
- encodings as described below. If the trailing @samp{-} is present,
- further @samp{QTDP} packets will follow to specify this tracepoint's
- actions.
- Replies:
- @table @samp
- @item OK
- The packet was understood and carried out.
- @item qRelocInsn
- @xref{Tracepoint Packets,,Relocate instruction reply packet}.
- @item @w{}
- The packet was not recognized.
- @end table
- @item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
- Define actions to be taken when a tracepoint is hit. The @var{n} and
- @var{addr} must be the same as in the initial @samp{QTDP} packet for
- this tracepoint. This packet may only be sent immediately after
- another @samp{QTDP} packet that ended with a @samp{-}. If the
- trailing @samp{-} is present, further @samp{QTDP} packets will follow,
- specifying more actions for this tracepoint.
- In the series of action packets for a given tracepoint, at most one
- can have an @samp{S} before its first @var{action}. If such a packet
- is sent, it and the following packets define ``while-stepping''
- actions. Any prior packets define ordinary actions --- that is, those
- taken when the tracepoint is first hit. If no action packet has an
- @samp{S}, then all the packets in the series specify ordinary
- tracepoint actions.
- The @samp{@var{action}@dots{}} portion of the packet is a series of
- actions, concatenated without separators. Each action has one of the
- following forms:
- @table @samp
- @item R @var{mask}
- Collect the registers whose bits are set in @var{mask},
- a hexadecimal number whose @var{i}'th bit is set if register number
- @var{i} should be collected. (The least significant bit is numbered
- zero.) Note that @var{mask} may be any number of digits long; it may
- not fit in a 32-bit word.
- @item M @var{basereg},@var{offset},@var{len}
- Collect @var{len} bytes of memory starting at the address in register
- number @var{basereg}, plus @var{offset}. If @var{basereg} is
- @samp{-1}, then the range has a fixed address: @var{offset} is the
- address of the lowest byte to collect. The @var{basereg},
- @var{offset}, and @var{len} parameters are all unsigned hexadecimal
- values (the @samp{-1} value for @var{basereg} is a special case).
- @item X @var{len},@var{expr}
- Evaluate @var{expr}, whose length is @var{len}, and collect memory as
- it directs. The agent expression @var{expr} is as described in
- @ref{Agent Expressions}. Each byte of the expression is encoded as a
- two-digit hex number in the packet; @var{len} is the number of bytes
- in the expression (and thus one-half the number of hex digits in the
- packet).
- @end table
- Any number of actions may be packed together in a single @samp{QTDP}
- packet, as long as the packet does not exceed the maximum packet
- length (400 bytes, for many stubs). There may be only one @samp{R}
- action per tracepoint, and it must precede any @samp{M} or @samp{X}
- actions. Any registers referred to by @samp{M} and @samp{X} actions
- must be collected by a preceding @samp{R} action. (The
- ``while-stepping'' actions are treated as if they were attached to a
- separate tracepoint, as far as these restrictions are concerned.)
- Replies:
- @table @samp
- @item OK
- The packet was understood and carried out.
- @item qRelocInsn
- @xref{Tracepoint Packets,,Relocate instruction reply packet}.
- @item @w{}
- The packet was not recognized.
- @end table
- @item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes}
- @cindex @samp{QTDPsrc} packet
- Specify a source string of tracepoint @var{n} at address @var{addr}.
- This is useful to get accurate reproduction of the tracepoints
- originally downloaded at the beginning of the trace run. The @var{type}
- is the name of the tracepoint part, such as @samp{cond} for the
- tracepoint's conditional expression (see below for a list of types), while
- @var{bytes} is the string, encoded in hexadecimal.
- @var{start} is the offset of the @var{bytes} within the overall source
- string, while @var{slen} is the total length of the source string.
- This is intended for handling source strings that are longer than will
- fit in a single packet.
- @c Add detailed example when this info is moved into a dedicated
- @c tracepoint descriptions section.
- The available string types are @samp{at} for the location,
- @samp{cond} for the conditional, and @samp{cmd} for an action command.
- @value{GDBN} sends a separate packet for each command in the action
- list, in the same order in which the commands are stored in the list.
- The target does not need to do anything with source strings except
- report them back as part of the replies to the @samp{qTfP}/@samp{qTsP}
- query packets.
- Although this packet is optional, and @value{GDBN} will only send it
- if the target replies with @samp{TracepointSource} @xref{General
- Query Packets}, it makes both disconnected tracing and trace files
- much easier to use. Otherwise the user must be careful that the
- tracepoints in effect while looking at trace frames are identical to
- the ones in effect during the trace run; even a small discrepancy
- could cause @samp{tdump} not to work, or a particular trace frame not
- be found.
- @item QTDV:@var{n}:@var{value}:@var{builtin}:@var{name}
- @cindex define trace state variable, remote request
- @cindex @samp{QTDV} packet
- Create a new trace state variable, number @var{n}, with an initial
- value of @var{value}, which is a 64-bit signed integer. Both @var{n}
- and @var{value} are encoded as hexadecimal values. @value{GDBN} has
- the option of not using this packet for initial values of zero; the
- target should simply create the trace state variables as they are
- mentioned in expressions. The value @var{builtin} should be 1 (one)
- if the trace state variable is builtin and 0 (zero) if it is not builtin.
- @value{GDBN} only sets @var{builtin} to 1 if a previous @samp{qTfV} or
- @samp{qTsV} packet had it set. The contents of @var{name} is the
- hex-encoded name (without the leading @samp{$}) of the trace state
- variable.
- @item QTFrame:@var{n}
- @cindex @samp{QTFrame} packet
- Select the @var{n}'th tracepoint frame from the buffer, and use the
- register and memory contents recorded there to answer subsequent
- request packets from @value{GDBN}.
- A successful reply from the stub indicates that the stub has found the
- requested frame. The response is a series of parts, concatenated
- without separators, describing the frame we selected. Each part has
- one of the following forms:
- @table @samp
- @item F @var{f}
- The selected frame is number @var{n} in the trace frame buffer;
- @var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there
- was no frame matching the criteria in the request packet.
- @item T @var{t}
- The selected trace frame records a hit of tracepoint number @var{t};
- @var{t} is a hexadecimal number.
- @end table
- @item QTFrame:pc:@var{addr}
- Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
- currently selected frame whose PC is @var{addr};
- @var{addr} is a hexadecimal number.
- @item QTFrame:tdp:@var{t}
- Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
- currently selected frame that is a hit of tracepoint @var{t}; @var{t}
- is a hexadecimal number.
- @item QTFrame:range:@var{start}:@var{end}
- Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
- currently selected frame whose PC is between @var{start} (inclusive)
- and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal
- numbers.
- @item QTFrame:outside:@var{start}:@var{end}
- Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
- frame @emph{outside} the given range of addresses (exclusive).
- @item qTMinFTPILen
- @cindex @samp{qTMinFTPILen} packet
- This packet requests the minimum length of instruction at which a fast
- tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on
- the 32-bit x86 architecture, it is possible to use a 4-byte jump, but
- it depends on the target system being able to create trampolines in
- the first 64K of memory, which might or might not be possible for that
- system. So the reply to this packet will be 4 if it is able to
- arrange for that.
- Replies:
- @table @samp
- @item 0
- The minimum instruction length is currently unknown.
- @item @var{length}
- The minimum instruction length is @var{length}, where @var{length}
- is a hexadecimal number greater or equal to 1. A reply
- of 1 means that a fast tracepoint may be placed on any instruction
- regardless of size.
- @item E
- An error has occurred.
- @item @w{}
- An empty reply indicates that the request is not supported by the stub.
- @end table
- @item QTStart
- @cindex @samp{QTStart} packet
- Begin the tracepoint experiment. Begin collecting data from
- tracepoint hits in the trace frame buffer. This packet supports the
- @samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate
- instruction reply packet}).
- @item QTStop
- @cindex @samp{QTStop} packet
- End the tracepoint experiment. Stop collecting trace frames.
- @item QTEnable:@var{n}:@var{addr}
- @anchor{QTEnable}
- @cindex @samp{QTEnable} packet
- Enable tracepoint @var{n} at address @var{addr} in a started tracepoint
- experiment. If the tracepoint was previously disabled, then collection
- of data from it will resume.
- @item QTDisable:@var{n}:@var{addr}
- @anchor{QTDisable}
- @cindex @samp{QTDisable} packet
- Disable tracepoint @var{n} at address @var{addr} in a started tracepoint
- experiment. No more data will be collected from the tracepoint unless
- @samp{QTEnable:@var{n}:@var{addr}} is subsequently issued.
- @item QTinit
- @cindex @samp{QTinit} packet
- Clear the table of tracepoints, and empty the trace frame buffer.
- @item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{}
- @cindex @samp{QTro} packet
- Establish the given ranges of memory as ``transparent''. The stub
- will answer requests for these ranges from memory's current contents,
- if they were not collected as part of the tracepoint hit.
- @value{GDBN} uses this to mark read-only regions of memory, like those
- containing program code. Since these areas never change, they should
- still have the same contents they did when the tracepoint was hit, so
- there's no reason for the stub to refuse to provide their contents.
- @item QTDisconnected:@var{value}
- @cindex @samp{QTDisconnected} packet
- Set the choice to what to do with the tracing run when @value{GDBN}
- disconnects from the target. A @var{value} of 1 directs the target to
- continue the tracing run, while 0 tells the target to stop tracing if
- @value{GDBN} is no longer in the picture.
- @item qTStatus
- @cindex @samp{qTStatus} packet
- Ask the stub if there is a trace experiment running right now.
- The reply has the form:
- @table @samp
- @item T@var{running}@r{[};@var{field}@r{]}@dots{}
- @var{running} is a single digit @code{1} if the trace is presently
- running, or @code{0} if not. It is followed by semicolon-separated
- optional fields that an agent may use to report additional status.
- @end table
- If the trace is not running, the agent may report any of several
- explanations as one of the optional fields:
- @table @samp
- @item tnotrun:0
- No trace has been run yet.
- @item tstop[:@var{text}]:0
- The trace was stopped by a user-originated stop command. The optional
- @var{text} field is a user-supplied string supplied as part of the
- stop command (for instance, an explanation of why the trace was
- stopped manually). It is hex-encoded.
- @item tfull:0
- The trace stopped because the trace buffer filled up.
- @item tdisconnected:0
- The trace stopped because @value{GDBN} disconnected from the target.
- @item tpasscount:@var{tpnum}
- The trace stopped because tracepoint @var{tpnum} exceeded its pass count.
- @item terror:@var{text}:@var{tpnum}
- The trace stopped because tracepoint @var{tpnum} had an error. The
- string @var{text} is available to describe the nature of the error
- (for instance, a divide by zero in the condition expression); it
- is hex encoded.
- @item tunknown:0
- The trace stopped for some other reason.
- @end table
- Additional optional fields supply statistical and other information.
- Although not required, they are extremely useful for users monitoring
- the progress of a trace run. If a trace has stopped, and these
- numbers are reported, they must reflect the state of the just-stopped
- trace.
- @table @samp
- @item tframes:@var{n}
- The number of trace frames in the buffer.
- @item tcreated:@var{n}
- The total number of trace frames created during the run. This may
- be larger than the trace frame count, if the buffer is circular.
- @item tsize:@var{n}
- The total size of the trace buffer, in bytes.
- @item tfree:@var{n}
- The number of bytes still unused in the buffer.
- @item circular:@var{n}
- The value of the circular trace buffer flag. @code{1} means that the
- trace buffer is circular and old trace frames will be discarded if
- necessary to make room, @code{0} means that the trace buffer is linear
- and may fill up.
- @item disconn:@var{n}
- The value of the disconnected tracing flag. @code{1} means that
- tracing will continue after @value{GDBN} disconnects, @code{0} means
- that the trace run will stop.
- @end table
- @item qTP:@var{tp}:@var{addr}
- @cindex tracepoint status, remote request
- @cindex @samp{qTP} packet
- Ask the stub for the current state of tracepoint number @var{tp} at
- address @var{addr}.
- Replies:
- @table @samp
- @item V@var{hits}:@var{usage}
- The tracepoint has been hit @var{hits} times so far during the trace
- run, and accounts for @var{usage} in the trace buffer. Note that
- @code{while-stepping} steps are not counted as separate hits, but the
- steps' space consumption is added into the usage number.
- @end table
- @item qTV:@var{var}
- @cindex trace state variable value, remote request
- @cindex @samp{qTV} packet
- Ask the stub for the value of the trace state variable number @var{var}.
- Replies:
- @table @samp
- @item V@var{value}
- The value of the variable is @var{value}. This will be the current
- value of the variable if the user is examining a running target, or a
- saved value if the variable was collected in the trace frame that the
- user is looking at. Note that multiple requests may result in
- different reply values, such as when requesting values while the
- program is running.
- @item U
- The value of the variable is unknown. This would occur, for example,
- if the user is examining a trace frame in which the requested variable
- was not collected.
- @end table
- @item qTfP
- @cindex @samp{qTfP} packet
- @itemx qTsP
- @cindex @samp{qTsP} packet
- These packets request data about tracepoints that are being used by
- the target. @value{GDBN} sends @code{qTfP} to get the first piece
- of data, and multiple @code{qTsP} to get additional pieces. Replies
- to these packets generally take the form of the @code{QTDP} packets
- that define tracepoints. (FIXME add detailed syntax)
- @item qTfV
- @cindex @samp{qTfV} packet
- @itemx qTsV
- @cindex @samp{qTsV} packet
- These packets request data about trace state variables that are on the
- target. @value{GDBN} sends @code{qTfV} to get the first vari of data,
- and multiple @code{qTsV} to get additional variables. Replies to
- these packets follow the syntax of the @code{QTDV} packets that define
- trace state variables.
- @item qTfSTM
- @itemx qTsSTM
- @anchor{qTfSTM}
- @anchor{qTsSTM}
- @cindex @samp{qTfSTM} packet
- @cindex @samp{qTsSTM} packet
- These packets request data about static tracepoint markers that exist
- in the target program. @value{GDBN} sends @code{qTfSTM} to get the
- first piece of data, and multiple @code{qTsSTM} to get additional
- pieces. Replies to these packets take the following form:
- Reply:
- @table @samp
- @item m @var{address}:@var{id}:@var{extra}
- A single marker
- @item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{}
- a comma-separated list of markers
- @item l
- (lower case letter @samp{L}) denotes end of list.
- @item E @var{nn}
- An error occurred. The error number @var{nn} is given as hex digits.
- @item @w{}
- An empty reply indicates that the request is not supported by the
- stub.
- @end table
- The @var{address} is encoded in hex;
- @var{id} and @var{extra} are strings encoded in hex.
- In response to each query, the target will reply with a list of one or
- more markers, separated by commas. @value{GDBN} will respond to each
- reply with a request for more markers (using the @samp{qs} form of the
- query), until the target responds with @samp{l} (lower-case ell, for
- @dfn{last}).
- @item qTSTMat:@var{address}
- @anchor{qTSTMat}
- @cindex @samp{qTSTMat} packet
- This packets requests data about static tracepoint markers in the
- target program at @var{address}. Replies to this packet follow the
- syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static
- tracepoint markers.
- @item QTSave:@var{filename}
- @cindex @samp{QTSave} packet
- This packet directs the target to save trace data to the file name
- @var{filename} in the target's filesystem. The @var{filename} is encoded
- as a hex string; the interpretation of the file name (relative vs
- absolute, wild cards, etc) is up to the target.
- @item qTBuffer:@var{offset},@var{len}
- @cindex @samp{qTBuffer} packet
- Return up to @var{len} bytes of the current contents of trace buffer,
- starting at @var{offset}. The trace buffer is treated as if it were
- a contiguous collection of traceframes, as per the trace file format.
- The reply consists as many hex-encoded bytes as the target can deliver
- in a packet; it is not an error to return fewer than were asked for.
- A reply consisting of just @code{l} indicates that no bytes are
- available.
- @item QTBuffer:circular:@var{value}
- This packet directs the target to use a circular trace buffer if
- @var{value} is 1, or a linear buffer if the value is 0.
- @item QTBuffer:size:@var{size}
- @anchor{QTBuffer-size}
- @cindex @samp{QTBuffer size} packet
- This packet directs the target to make the trace buffer be of size
- @var{size} if possible. A value of @code{-1} tells the target to
- use whatever size it prefers.
- @item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{}
- @cindex @samp{QTNotes} packet
- This packet adds optional textual notes to the trace run. Allowable
- types include @code{user}, @code{notes}, and @code{tstop}, the
- @var{text} fields are arbitrary strings, hex-encoded.
- @end table
- @subsection Relocate instruction reply packet
- When installing fast tracepoints in memory, the target may need to
- relocate the instruction currently at the tracepoint address to a
- different address in memory. For most instructions, a simple copy is
- enough, but, for example, call instructions that implicitly push the
- return address on the stack, and relative branches or other
- PC-relative instructions require offset adjustment, so that the effect
- of executing the instruction at a different address is the same as if
- it had executed in the original location.
- In response to several of the tracepoint packets, the target may also
- respond with a number of intermediate @samp{qRelocInsn} request
- packets before the final result packet, to have @value{GDBN} handle
- this relocation operation. If a packet supports this mechanism, its
- documentation will explicitly say so. See for example the above
- descriptions for the @samp{QTStart} and @samp{QTDP} packets. The
- format of the request is:
- @table @samp
- @item qRelocInsn:@var{from};@var{to}
- This requests @value{GDBN} to copy instruction at address @var{from}
- to address @var{to}, possibly adjusted so that executing the
- instruction at @var{to} has the same effect as executing it at
- @var{from}. @value{GDBN} writes the adjusted instruction to target
- memory starting at @var{to}.
- @end table
- Replies:
- @table @samp
- @item qRelocInsn:@var{adjusted_size}
- Informs the stub the relocation is complete. The @var{adjusted_size} is
- the length in bytes of resulting relocated instruction sequence.
- @item E @var{NN}
- A badly formed request was detected, or an error was encountered while
- relocating the instruction.
- @end table
- @node Host I/O Packets
- @section Host I/O Packets
- @cindex Host I/O, remote protocol
- @cindex file transfer, remote protocol
- The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O
- operations on the far side of a remote link. For example, Host I/O is
- used to upload and download files to a remote target with its own
- filesystem. Host I/O uses the same constant values and data structure
- layout as the target-initiated File-I/O protocol. However, the
- Host I/O packets are structured differently. The target-initiated
- protocol relies on target memory to store parameters and buffers.
- Host I/O requests are initiated by @value{GDBN}, and the
- target's memory is not involved. @xref{File-I/O Remote Protocol
- Extension}, for more details on the target-initiated protocol.
- The Host I/O request packets all encode a single operation along with
- its arguments. They have this format:
- @table @samp
- @item vFile:@var{operation}: @var{parameter}@dots{}
- @var{operation} is the name of the particular request; the target
- should compare the entire packet name up to the second colon when checking
- for a supported operation. The format of @var{parameter} depends on
- the operation. Numbers are always passed in hexadecimal. Negative
- numbers have an explicit minus sign (i.e.@: two's complement is not
- used). Strings (e.g.@: filenames) are encoded as a series of
- hexadecimal bytes. The last argument to a system call may be a
- buffer of escaped binary data (@pxref{Binary Data}).
- @end table
- The valid responses to Host I/O packets are:
- @table @samp
- @item F @var{result} [, @var{errno}] [; @var{attachment}]
- @var{result} is the integer value returned by this operation, usually
- non-negative for success and -1 for errors. If an error has occured,
- @var{errno} will be included in the result specifying a
- value defined by the File-I/O protocol (@pxref{Errno Values}). For
- operations which return data, @var{attachment} supplies the data as a
- binary buffer. Binary buffers in response packets are escaped in the
- normal way (@pxref{Binary Data}). See the individual packet
- documentation for the interpretation of @var{result} and
- @var{attachment}.
- @item @w{}
- An empty response indicates that this operation is not recognized.
- @end table
- These are the supported Host I/O operations:
- @table @samp
- @item vFile:open: @var{filename}, @var{flags}, @var{mode}
- Open a file at @var{filename} and return a file descriptor for it, or
- return -1 if an error occurs. The @var{filename} is a string,
- @var{flags} is an integer indicating a mask of open flags
- (@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
- of mode bits to use if the file is created (@pxref{mode_t Values}).
- @xref{open}, for details of the open flags and mode values.
- @item vFile:close: @var{fd}
- Close the open file corresponding to @var{fd} and return 0, or
- -1 if an error occurs.
- @item vFile:pread: @var{fd}, @var{count}, @var{offset}
- Read data from the open file corresponding to @var{fd}. Up to
- @var{count} bytes will be read from the file, starting at @var{offset}
- relative to the start of the file. The target may read fewer bytes;
- common reasons include packet size limits and an end-of-file
- condition. The number of bytes read is returned. Zero should only be
- returned for a successful read at the end of the file, or if
- @var{count} was zero.
- The data read should be returned as a binary attachment on success.
- If zero bytes were read, the response should include an empty binary
- attachment (i.e.@: a trailing semicolon). The return value is the
- number of target bytes read; the binary attachment may be longer if
- some characters were escaped.
- @item vFile:pwrite: @var{fd}, @var{offset}, @var{data}
- Write @var{data} (a binary buffer) to the open file corresponding
- to @var{fd}. Start the write at @var{offset} from the start of the
- file. Unlike many @code{write} system calls, there is no
- separate @var{count} argument; the length of @var{data} in the
- packet is used. @samp{vFile:pwrite} returns the number of bytes written,
- which may be shorter than the length of @var{data}, or -1 if an
- error occurred.
- @item vFile:fstat: @var{fd}
- Get information about the open file corresponding to @var{fd}.
- On success the information is returned as a binary attachment
- and the return value is the size of this attachment in bytes.
- If an error occurs the return value is -1. The format of the
- returned binary attachment is as described in @ref{struct stat}.
- @item vFile:unlink: @var{filename}
- Delete the file at @var{filename} on the target. Return 0,
- or -1 if an error occurs. The @var{filename} is a string.
- @item vFile:readlink: @var{filename}
- Read value of symbolic link @var{filename} on the target. Return
- the number of bytes read, or -1 if an error occurs.
- The data read should be returned as a binary attachment on success.
- If zero bytes were read, the response should include an empty binary
- attachment (i.e.@: a trailing semicolon). The return value is the
- number of target bytes read; the binary attachment may be longer if
- some characters were escaped.
- @item vFile:setfs: @var{pid}
- Select the filesystem on which @code{vFile} operations with
- @var{filename} arguments will operate. This is required for
- @value{GDBN} to be able to access files on remote targets where
- the remote stub does not share a common filesystem with the
- inferior(s).
- If @var{pid} is nonzero, select the filesystem as seen by process
- @var{pid}. If @var{pid} is zero, select the filesystem as seen by
- the remote stub. Return 0 on success, or -1 if an error occurs.
- If @code{vFile:setfs:} indicates success, the selected filesystem
- remains selected until the next successful @code{vFile:setfs:}
- operation.
- @end table
- @node Interrupts
- @section Interrupts
- @cindex interrupts (remote protocol)
- @anchor{interrupting remote targets}
- In all-stop mode, when a program on the remote target is running,
- @value{GDBN} may attempt to interrupt it by sending a @samp{Ctrl-C},
- @code{BREAK} or a @code{BREAK} followed by @code{g}, control of which
- is specified via @value{GDBN}'s @samp{interrupt-sequence}.
- The precise meaning of @code{BREAK} is defined by the transport
- mechanism and may, in fact, be undefined. @value{GDBN} does not
- currently define a @code{BREAK} mechanism for any of the network
- interfaces except for TCP, in which case @value{GDBN} sends the
- @code{telnet} BREAK sequence.
- @samp{Ctrl-C}, on the other hand, is defined and implemented for all
- transport mechanisms. It is represented by sending the single byte
- @code{0x03} without any of the usual packet overhead described in
- the Overview section (@pxref{Overview}). When a @code{0x03} byte is
- transmitted as part of a packet, it is considered to be packet data
- and does @emph{not} represent an interrupt. E.g., an @samp{X} packet
- (@pxref{X packet}), used for binary downloads, may include an unescaped
- @code{0x03} as part of its packet.
- @code{BREAK} followed by @code{g} is also known as Magic SysRq g.
- When Linux kernel receives this sequence from serial port,
- it stops execution and connects to gdb.
- In non-stop mode, because packet resumptions are asynchronous
- (@pxref{vCont packet}), @value{GDBN} is always free to send a remote
- command to the remote stub, even when the target is running. For that
- reason, @value{GDBN} instead sends a regular packet (@pxref{vCtrlC
- packet}) with the usual packet framing instead of the single byte
- @code{0x03}.
- Stubs are not required to recognize these interrupt mechanisms and the
- precise meaning associated with receipt of the interrupt is
- implementation defined. If the target supports debugging of multiple
- threads and/or processes, it should attempt to interrupt all
- currently-executing threads and processes.
- If the stub is successful at interrupting the
- running program, it should send one of the stop
- reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
- of successfully stopping the program in all-stop mode, and a stop reply
- for each stopped thread in non-stop mode.
- Interrupts received while the
- program is stopped are queued and the program will be interrupted when
- it is resumed next time.
- @node Notification Packets
- @section Notification Packets
- @cindex notification packets
- @cindex packets, notification
- The @value{GDBN} remote serial protocol includes @dfn{notifications},
- packets that require no acknowledgment. Both the GDB and the stub
- may send notifications (although the only notifications defined at
- present are sent by the stub). Notifications carry information
- without incurring the round-trip latency of an acknowledgment, and so
- are useful for low-impact communications where occasional packet loss
- is not a problem.
- A notification packet has the form @samp{% @var{data} #
- @var{checksum}}, where @var{data} is the content of the notification,
- and @var{checksum} is a checksum of @var{data}, computed and formatted
- as for ordinary @value{GDBN} packets. A notification's @var{data}
- never contains @samp{$}, @samp{%} or @samp{#} characters. Upon
- receiving a notification, the recipient sends no @samp{+} or @samp{-}
- to acknowledge the notification's receipt or to report its corruption.
- Every notification's @var{data} begins with a name, which contains no
- colon characters, followed by a colon character.
- Recipients should silently ignore corrupted notifications and
- notifications they do not understand. Recipients should restart
- timeout periods on receipt of a well-formed notification, whether or
- not they understand it.
- Senders should only send the notifications described here when this
- protocol description specifies that they are permitted. In the
- future, we may extend the protocol to permit existing notifications in
- new contexts; this rule helps older senders avoid confusing newer
- recipients.
- (Older versions of @value{GDBN} ignore bytes received until they see
- the @samp{$} byte that begins an ordinary packet, so new stubs may
- transmit notifications without fear of confusing older clients. There
- are no notifications defined for @value{GDBN} to send at the moment, but we
- assume that most older stubs would ignore them, as well.)
- Each notification is comprised of three parts:
- @table @samp
- @item @var{name}:@var{event}
- The notification packet is sent by the side that initiates the
- exchange (currently, only the stub does that), with @var{event}
- carrying the specific information about the notification, and
- @var{name} specifying the name of the notification.
- @item @var{ack}
- The acknowledge sent by the other side, usually @value{GDBN}, to
- acknowledge the exchange and request the event.
- @end table
- The purpose of an asynchronous notification mechanism is to report to
- @value{GDBN} that something interesting happened in the remote stub.
- The remote stub may send notification @var{name}:@var{event}
- at any time, but @value{GDBN} acknowledges the notification when
- appropriate. The notification event is pending before @value{GDBN}
- acknowledges. Only one notification at a time may be pending; if
- additional events occur before @value{GDBN} has acknowledged the
- previous notification, they must be queued by the stub for later
- synchronous transmission in response to @var{ack} packets from
- @value{GDBN}. Because the notification mechanism is unreliable,
- the stub is permitted to resend a notification if it believes
- @value{GDBN} may not have received it.
- Specifically, notifications may appear when @value{GDBN} is not
- otherwise reading input from the stub, or when @value{GDBN} is
- expecting to read a normal synchronous response or a
- @samp{+}/@samp{-} acknowledgment to a packet it has sent.
- Notification packets are distinct from any other communication from
- the stub so there is no ambiguity.
- After receiving a notification, @value{GDBN} shall acknowledge it by
- sending a @var{ack} packet as a regular, synchronous request to the
- stub. Such acknowledgment is not required to happen immediately, as
- @value{GDBN} is permitted to send other, unrelated packets to the
- stub first, which the stub should process normally.
- Upon receiving a @var{ack} packet, if the stub has other queued
- events to report to @value{GDBN}, it shall respond by sending a
- normal @var{event}. @value{GDBN} shall then send another @var{ack}
- packet to solicit further responses; again, it is permitted to send
- other, unrelated packets as well which the stub should process
- normally.
- If the stub receives a @var{ack} packet and there are no additional
- @var{event} to report, the stub shall return an @samp{OK} response.
- At this point, @value{GDBN} has finished processing a notification
- and the stub has completed sending any queued events. @value{GDBN}
- won't accept any new notifications until the final @samp{OK} is
- received . If further notification events occur, the stub shall send
- a new notification, @value{GDBN} shall accept the notification, and
- the process shall be repeated.
- The process of asynchronous notification can be illustrated by the
- following example:
- @smallexample
- <- @code{%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;}
- @code{...}
- -> @code{vStopped}
- <- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;}
- -> @code{vStopped}
- <- @code{T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;}
- -> @code{vStopped}
- <- @code{OK}
- @end smallexample
- The following notifications are defined:
- @multitable @columnfractions 0.12 0.12 0.38 0.38
- @item Notification
- @tab Ack
- @tab Event
- @tab Description
- @item Stop
- @tab vStopped
- @tab @var{reply}. The @var{reply} has the form of a stop reply, as
- described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop},
- for information on how these notifications are acknowledged by
- @value{GDBN}.
- @tab Report an asynchronous stop event in non-stop mode.
- @end multitable
- @node Remote Non-Stop
- @section Remote Protocol Support for Non-Stop Mode
- @value{GDBN}'s remote protocol supports non-stop debugging of
- multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub
- supports non-stop mode, it should report that to @value{GDBN} by including
- @samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}).
- @value{GDBN} typically sends a @samp{QNonStop} packet only when
- establishing a new connection with the stub. Entering non-stop mode
- does not alter the state of any currently-running threads, but targets
- must stop all threads in any already-attached processes when entering
- all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to
- probe the target state after a mode change.
- In non-stop mode, when an attached process encounters an event that
- would otherwise be reported with a stop reply, it uses the
- asynchronous notification mechanism (@pxref{Notification Packets}) to
- inform @value{GDBN}. In contrast to all-stop mode, where all threads
- in all processes are stopped when a stop reply is sent, in non-stop
- mode only the thread reporting the stop event is stopped. That is,
- when reporting a @samp{S} or @samp{T} response to indicate completion
- of a step operation, hitting a breakpoint, or a fault, only the
- affected thread is stopped; any other still-running threads continue
- to run. When reporting a @samp{W} or @samp{X} response, all running
- threads belonging to other attached processes continue to run.
- In non-stop mode, the target shall respond to the @samp{?} packet as
- follows. First, any incomplete stop reply notification/@samp{vStopped}
- sequence in progress is abandoned. The target must begin a new
- sequence reporting stop events for all stopped threads, whether or not
- it has previously reported those events to @value{GDBN}. The first
- stop reply is sent as a synchronous reply to the @samp{?} packet, and
- subsequent stop replies are sent as responses to @samp{vStopped} packets
- using the mechanism described above. The target must not send
- asynchronous stop reply notifications until the sequence is complete.
- If all threads are running when the target receives the @samp{?} packet,
- or if the target is not attached to any process, it shall respond
- @samp{OK}.
- If the stub supports non-stop mode, it should also support the
- @samp{swbreak} stop reason if software breakpoints are supported, and
- the @samp{hwbreak} stop reason if hardware breakpoints are supported
- (@pxref{swbreak stop reason}). This is because given the asynchronous
- nature of non-stop mode, between the time a thread hits a breakpoint
- and the time the event is finally processed by @value{GDBN}, the
- breakpoint may have already been removed from the target. Due to
- this, @value{GDBN} needs to be able to tell whether a trap stop was
- caused by a delayed breakpoint event, which should be ignored, as
- opposed to a random trap signal, which should be reported to the user.
- Note the @samp{swbreak} feature implies that the target is responsible
- for adjusting the PC when a software breakpoint triggers, if
- necessary, such as on the x86 architecture.
- @node Packet Acknowledgment
- @section Packet Acknowledgment
- @cindex acknowledgment, for @value{GDBN} remote
- @cindex packet acknowledgment, for @value{GDBN} remote
- By default, when either the host or the target machine receives a packet,
- the first response expected is an acknowledgment: either @samp{+} (to indicate
- the package was received correctly) or @samp{-} (to request retransmission).
- This mechanism allows the @value{GDBN} remote protocol to operate over
- unreliable transport mechanisms, such as a serial line.
- In cases where the transport mechanism is itself reliable (such as a pipe or
- TCP connection), the @samp{+}/@samp{-} acknowledgments are redundant.
- It may be desirable to disable them in that case to reduce communication
- overhead, or for other reasons. This can be accomplished by means of the
- @samp{QStartNoAckMode} packet; @pxref{QStartNoAckMode}.
- When in no-acknowledgment mode, neither the stub nor @value{GDBN} shall send or
- expect @samp{+}/@samp{-} protocol acknowledgments. The packet
- and response format still includes the normal checksum, as described in
- @ref{Overview}, but the checksum may be ignored by the receiver.
- If the stub supports @samp{QStartNoAckMode} and prefers to operate in
- no-acknowledgment mode, it should report that to @value{GDBN}
- by including @samp{QStartNoAckMode+} in its response to @samp{qSupported};
- @pxref{qSupported}.
- If @value{GDBN} also supports @samp{QStartNoAckMode} and it has not been
- disabled via the @code{set remote noack-packet off} command
- (@pxref{Remote Configuration}),
- @value{GDBN} may then send a @samp{QStartNoAckMode} packet to the stub.
- Only then may the stub actually turn off packet acknowledgments.
- @value{GDBN} sends a final @samp{+} acknowledgment of the stub's @samp{OK}
- response, which can be safely ignored by the stub.
- Note that @code{set remote noack-packet} command only affects negotiation
- between @value{GDBN} and the stub when subsequent connections are made;
- it does not affect the protocol acknowledgment state for any current
- connection.
- Since @samp{+}/@samp{-} acknowledgments are enabled by default when a
- new connection is established,
- there is also no protocol request to re-enable the acknowledgments
- for the current connection, once disabled.
- @node Examples
- @section Examples
- Example sequence of a target being re-started. Notice how the restart
- does not get any direct output:
- @smallexample
- -> @code{R00}
- <- @code{+}
- @emph{target restarts}
- -> @code{?}
- <- @code{+}
- <- @code{T001:1234123412341234}
- -> @code{+}
- @end smallexample
- Example sequence of a target being stepped by a single instruction:
- @smallexample
- -> @code{G1445@dots{}}
- <- @code{+}
- -> @code{s}
- <- @code{+}
- @emph{time passes}
- <- @code{T001:1234123412341234}
- -> @code{+}
- -> @code{g}
- <- @code{+}
- <- @code{1455@dots{}}
- -> @code{+}
- @end smallexample
- @node File-I/O Remote Protocol Extension
- @section File-I/O Remote Protocol Extension
- @cindex File-I/O remote protocol extension
- @menu
- * File-I/O Overview::
- * Protocol Basics::
- * The F Request Packet::
- * The F Reply Packet::
- * The Ctrl-C Message::
- * Console I/O::
- * List of Supported Calls::
- * Protocol-specific Representation of Datatypes::
- * Constants::
- * File-I/O Examples::
- @end menu
- @node File-I/O Overview
- @subsection File-I/O Overview
- @cindex file-i/o overview
- The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the
- target to use the host's file system and console I/O to perform various
- system calls. System calls on the target system are translated into a
- remote protocol packet to the host system, which then performs the needed
- actions and returns a response packet to the target system.
- This simulates file system operations even on targets that lack file systems.
- The protocol is defined to be independent of both the host and target systems.
- It uses its own internal representation of datatypes and values. Both
- @value{GDBN} and the target's @value{GDBN} stub are responsible for
- translating the system-dependent value representations into the internal
- protocol representations when data is transmitted.
- The communication is synchronous. A system call is possible only when
- @value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S}
- or @samp{s} packets. While @value{GDBN} handles the request for a system call,
- the target is stopped to allow deterministic access to the target's
- memory. Therefore File-I/O is not interruptible by target signals. On
- the other hand, it is possible to interrupt File-I/O by a user interrupt
- (@samp{Ctrl-C}) within @value{GDBN}.
- The target's request to perform a host system call does not finish
- the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means,
- after finishing the system call, the target returns to continuing the
- previous activity (continue, step). No additional continue or step
- request from @value{GDBN} is required.
- @smallexample
- (@value{GDBP}) continue
- <- target requests 'system call X'
- target is stopped, @value{GDBN} executes system call
- -> @value{GDBN} returns result
- ... target continues, @value{GDBN} returns to wait for the target
- <- target hits breakpoint and sends a Txx packet
- @end smallexample
- The protocol only supports I/O on the console and to regular files on
- the host file system. Character or block special devices, pipes,
- named pipes, sockets or any other communication method on the host
- system are not supported by this protocol.
- File I/O is not supported in non-stop mode.
- @node Protocol Basics
- @subsection Protocol Basics
- @cindex protocol basics, file-i/o
- The File-I/O protocol uses the @code{F} packet as the request as well
- as reply packet. Since a File-I/O system call can only occur when
- @value{GDBN} is waiting for a response from the continuing or stepping target,
- the File-I/O request is a reply that @value{GDBN} has to expect as a result
- of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
- This @code{F} packet contains all information needed to allow @value{GDBN}
- to call the appropriate host system call:
- @itemize @bullet
- @item
- A unique identifier for the requested system call.
- @item
- All parameters to the system call. Pointers are given as addresses
- in the target memory address space. Pointers to strings are given as
- pointer/length pair. Numerical values are given as they are.
- Numerical control flags are given in a protocol-specific representation.
- @end itemize
- At this point, @value{GDBN} has to perform the following actions.
- @itemize @bullet
- @item
- If the parameters include pointer values to data needed as input to a
- system call, @value{GDBN} requests this data from the target with a
- standard @code{m} packet request. This additional communication has to be
- expected by the target implementation and is handled as any other @code{m}
- packet.
- @item
- @value{GDBN} translates all value from protocol representation to host
- representation as needed. Datatypes are coerced into the host types.
- @item
- @value{GDBN} calls the system call.
- @item
- It then coerces datatypes back to protocol representation.
- @item
- If the system call is expected to return data in buffer space specified
- by pointer parameters to the call, the data is transmitted to the
- target using a @code{M} or @code{X} packet. This packet has to be expected
- by the target implementation and is handled as any other @code{M} or @code{X}
- packet.
- @end itemize
- Eventually @value{GDBN} replies with another @code{F} packet which contains all
- necessary information for the target to continue. This at least contains
- @itemize @bullet
- @item
- Return value.
- @item
- @code{errno}, if has been changed by the system call.
- @item
- ``Ctrl-C'' flag.
- @end itemize
- After having done the needed type and value coercion, the target continues
- the latest continue or step action.
- @node The F Request Packet
- @subsection The @code{F} Request Packet
- @cindex file-i/o request packet
- @cindex @code{F} request packet
- The @code{F} request packet has the following format:
- @table @samp
- @item F@var{call-id},@var{parameter@dots{}}
- @var{call-id} is the identifier to indicate the host system call to be called.
- This is just the name of the function.
- @var{parameter@dots{}} are the parameters to the system call.
- Parameters are hexadecimal integer values, either the actual values in case
- of scalar datatypes, pointers to target buffer space in case of compound
- datatypes and unspecified memory areas, or pointer/length pairs in case
- of string parameters. These are appended to the @var{call-id} as a
- comma-delimited list. All values are transmitted in ASCII
- string representation, pointer/length pairs separated by a slash.
- @end table
- @node The F Reply Packet
- @subsection The @code{F} Reply Packet
- @cindex file-i/o reply packet
- @cindex @code{F} reply packet
- The @code{F} reply packet has the following format:
- @table @samp
- @item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}
- @var{retcode} is the return code of the system call as hexadecimal value.
- @var{errno} is the @code{errno} set by the call, in protocol-specific
- representation.
- This parameter can be omitted if the call was successful.
- @var{Ctrl-C flag} is only sent if the user requested a break. In this
- case, @var{errno} must be sent as well, even if the call was successful.
- The @var{Ctrl-C flag} itself consists of the character @samp{C}:
- @smallexample
- F0,0,C
- @end smallexample
- @noindent
- or, if the call was interrupted before the host call has been performed:
- @smallexample
- F-1,4,C
- @end smallexample
- @noindent
- assuming 4 is the protocol-specific representation of @code{EINTR}.
- @end table
- @node The Ctrl-C Message
- @subsection The @samp{Ctrl-C} Message
- @cindex ctrl-c message, in file-i/o protocol
- If the @samp{Ctrl-C} flag is set in the @value{GDBN}
- reply packet (@pxref{The F Reply Packet}),
- the target should behave as if it had
- gotten a break message. The meaning for the target is ``system call
- interrupted by @code{SIGINT}''. Consequentially, the target should actually stop
- (as with a break message) and return to @value{GDBN} with a @code{T02}
- packet.
- It's important for the target to know in which
- state the system call was interrupted. There are two possible cases:
- @itemize @bullet
- @item
- The system call hasn't been performed on the host yet.
- @item
- The system call on the host has been finished.
- @end itemize
- These two states can be distinguished by the target by the value of the
- returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system
- call hasn't been performed. This is equivalent to the @code{EINTR} handling
- on POSIX systems. In any other case, the target may presume that the
- system call has been finished --- successfully or not --- and should behave
- as if the break message arrived right after the system call.
- @value{GDBN} must behave reliably. If the system call has not been called
- yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as
- @code{errno} in the packet. If the system call on the host has been finished
- before the user requests a break, the full action must be finished by
- @value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary.
- The @code{F} packet may only be sent when either nothing has happened
- or the full action has been completed.
- @node Console I/O
- @subsection Console I/O
- @cindex console i/o as part of file-i/o
- By default and if not explicitly closed by the target system, the file
- descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output
- on the @value{GDBN} console is handled as any other file output operation
- (@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled
- by @value{GDBN} so that after the target read request from file descriptor
- 0 all following typing is buffered until either one of the following
- conditions is met:
- @itemize @bullet
- @item
- The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the
- @code{read}
- system call is treated as finished.
- @item
- The user presses @key{RET}. This is treated as end of input with a trailing
- newline.
- @item
- The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing
- character (neither newline nor @samp{Ctrl-D}) is appended to the input.
- @end itemize
- If the user has typed more characters than fit in the buffer given to
- the @code{read} call, the trailing characters are buffered in @value{GDBN} until
- either another @code{read(0, @dots{})} is requested by the target, or debugging
- is stopped at the user's request.
- @node List of Supported Calls
- @subsection List of Supported Calls
- @cindex list of supported file-i/o calls
- @menu
- * open::
- * close::
- * read::
- * write::
- * lseek::
- * rename::
- * unlink::
- * stat/fstat::
- * gettimeofday::
- * isatty::
- * system::
- @end menu
- @node open
- @unnumberedsubsubsec open
- @cindex open, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int open(const char *pathname, int flags);
- int open(const char *pathname, int flags, mode_t mode);
- @end smallexample
- @item Request:
- @samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}}
- @noindent
- @var{flags} is the bitwise @code{OR} of the following values:
- @table @code
- @item O_CREAT
- If the file does not exist it will be created. The host
- rules apply as far as file ownership and time stamps
- are concerned.
- @item O_EXCL
- When used with @code{O_CREAT}, if the file already exists it is
- an error and open() fails.
- @item O_TRUNC
- If the file already exists and the open mode allows
- writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be
- truncated to zero length.
- @item O_APPEND
- The file is opened in append mode.
- @item O_RDONLY
- The file is opened for reading only.
- @item O_WRONLY
- The file is opened for writing only.
- @item O_RDWR
- The file is opened for reading and writing.
- @end table
- @noindent
- Other bits are silently ignored.
- @noindent
- @var{mode} is the bitwise @code{OR} of the following values:
- @table @code
- @item S_IRUSR
- User has read permission.
- @item S_IWUSR
- User has write permission.
- @item S_IRGRP
- Group has read permission.
- @item S_IWGRP
- Group has write permission.
- @item S_IROTH
- Others have read permission.
- @item S_IWOTH
- Others have write permission.
- @end table
- @noindent
- Other bits are silently ignored.
- @item Return value:
- @code{open} returns the new file descriptor or -1 if an error
- occurred.
- @item Errors:
- @table @code
- @item EEXIST
- @var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used.
- @item EISDIR
- @var{pathname} refers to a directory.
- @item EACCES
- The requested access is not allowed.
- @item ENAMETOOLONG
- @var{pathname} was too long.
- @item ENOENT
- A directory component in @var{pathname} does not exist.
- @item ENODEV
- @var{pathname} refers to a device, pipe, named pipe or socket.
- @item EROFS
- @var{pathname} refers to a file on a read-only filesystem and
- write access was requested.
- @item EFAULT
- @var{pathname} is an invalid pointer value.
- @item ENOSPC
- No space on device to create the file.
- @item EMFILE
- The process already has the maximum number of files open.
- @item ENFILE
- The limit on the total number of files open on the system
- has been reached.
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @node close
- @unnumberedsubsubsec close
- @cindex close, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int close(int fd);
- @end smallexample
- @item Request:
- @samp{Fclose,@var{fd}}
- @item Return value:
- @code{close} returns zero on success, or -1 if an error occurred.
- @item Errors:
- @table @code
- @item EBADF
- @var{fd} isn't a valid open file descriptor.
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @node read
- @unnumberedsubsubsec read
- @cindex read, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int read(int fd, void *buf, unsigned int count);
- @end smallexample
- @item Request:
- @samp{Fread,@var{fd},@var{bufptr},@var{count}}
- @item Return value:
- On success, the number of bytes read is returned.
- Zero indicates end of file. If count is zero, read
- returns zero as well. On error, -1 is returned.
- @item Errors:
- @table @code
- @item EBADF
- @var{fd} is not a valid file descriptor or is not open for
- reading.
- @item EFAULT
- @var{bufptr} is an invalid pointer value.
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @node write
- @unnumberedsubsubsec write
- @cindex write, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int write(int fd, const void *buf, unsigned int count);
- @end smallexample
- @item Request:
- @samp{Fwrite,@var{fd},@var{bufptr},@var{count}}
- @item Return value:
- On success, the number of bytes written are returned.
- Zero indicates nothing was written. On error, -1
- is returned.
- @item Errors:
- @table @code
- @item EBADF
- @var{fd} is not a valid file descriptor or is not open for
- writing.
- @item EFAULT
- @var{bufptr} is an invalid pointer value.
- @item EFBIG
- An attempt was made to write a file that exceeds the
- host-specific maximum file size allowed.
- @item ENOSPC
- No space on device to write the data.
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @node lseek
- @unnumberedsubsubsec lseek
- @cindex lseek, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- long lseek (int fd, long offset, int flag);
- @end smallexample
- @item Request:
- @samp{Flseek,@var{fd},@var{offset},@var{flag}}
- @var{flag} is one of:
- @table @code
- @item SEEK_SET
- The offset is set to @var{offset} bytes.
- @item SEEK_CUR
- The offset is set to its current location plus @var{offset}
- bytes.
- @item SEEK_END
- The offset is set to the size of the file plus @var{offset}
- bytes.
- @end table
- @item Return value:
- On success, the resulting unsigned offset in bytes from
- the beginning of the file is returned. Otherwise, a
- value of -1 is returned.
- @item Errors:
- @table @code
- @item EBADF
- @var{fd} is not a valid open file descriptor.
- @item ESPIPE
- @var{fd} is associated with the @value{GDBN} console.
- @item EINVAL
- @var{flag} is not a proper value.
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @node rename
- @unnumberedsubsubsec rename
- @cindex rename, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int rename(const char *oldpath, const char *newpath);
- @end smallexample
- @item Request:
- @samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}}
- @item Return value:
- On success, zero is returned. On error, -1 is returned.
- @item Errors:
- @table @code
- @item EISDIR
- @var{newpath} is an existing directory, but @var{oldpath} is not a
- directory.
- @item EEXIST
- @var{newpath} is a non-empty directory.
- @item EBUSY
- @var{oldpath} or @var{newpath} is a directory that is in use by some
- process.
- @item EINVAL
- An attempt was made to make a directory a subdirectory
- of itself.
- @item ENOTDIR
- A component used as a directory in @var{oldpath} or new
- path is not a directory. Or @var{oldpath} is a directory
- and @var{newpath} exists but is not a directory.
- @item EFAULT
- @var{oldpathptr} or @var{newpathptr} are invalid pointer values.
- @item EACCES
- No access to the file or the path of the file.
- @item ENAMETOOLONG
- @var{oldpath} or @var{newpath} was too long.
- @item ENOENT
- A directory component in @var{oldpath} or @var{newpath} does not exist.
- @item EROFS
- The file is on a read-only filesystem.
- @item ENOSPC
- The device containing the file has no room for the new
- directory entry.
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @node unlink
- @unnumberedsubsubsec unlink
- @cindex unlink, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int unlink(const char *pathname);
- @end smallexample
- @item Request:
- @samp{Funlink,@var{pathnameptr}/@var{len}}
- @item Return value:
- On success, zero is returned. On error, -1 is returned.
- @item Errors:
- @table @code
- @item EACCES
- No access to the file or the path of the file.
- @item EPERM
- The system does not allow unlinking of directories.
- @item EBUSY
- The file @var{pathname} cannot be unlinked because it's
- being used by another process.
- @item EFAULT
- @var{pathnameptr} is an invalid pointer value.
- @item ENAMETOOLONG
- @var{pathname} was too long.
- @item ENOENT
- A directory component in @var{pathname} does not exist.
- @item ENOTDIR
- A component of the path is not a directory.
- @item EROFS
- The file is on a read-only filesystem.
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @node stat/fstat
- @unnumberedsubsubsec stat/fstat
- @cindex fstat, file-i/o system call
- @cindex stat, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int stat(const char *pathname, struct stat *buf);
- int fstat(int fd, struct stat *buf);
- @end smallexample
- @item Request:
- @samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@*
- @samp{Ffstat,@var{fd},@var{bufptr}}
- @item Return value:
- On success, zero is returned. On error, -1 is returned.
- @item Errors:
- @table @code
- @item EBADF
- @var{fd} is not a valid open file.
- @item ENOENT
- A directory component in @var{pathname} does not exist or the
- path is an empty string.
- @item ENOTDIR
- A component of the path is not a directory.
- @item EFAULT
- @var{pathnameptr} is an invalid pointer value.
- @item EACCES
- No access to the file or the path of the file.
- @item ENAMETOOLONG
- @var{pathname} was too long.
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @node gettimeofday
- @unnumberedsubsubsec gettimeofday
- @cindex gettimeofday, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int gettimeofday(struct timeval *tv, void *tz);
- @end smallexample
- @item Request:
- @samp{Fgettimeofday,@var{tvptr},@var{tzptr}}
- @item Return value:
- On success, 0 is returned, -1 otherwise.
- @item Errors:
- @table @code
- @item EINVAL
- @var{tz} is a non-NULL pointer.
- @item EFAULT
- @var{tvptr} and/or @var{tzptr} is an invalid pointer value.
- @end table
- @end table
- @node isatty
- @unnumberedsubsubsec isatty
- @cindex isatty, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int isatty(int fd);
- @end smallexample
- @item Request:
- @samp{Fisatty,@var{fd}}
- @item Return value:
- Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise.
- @item Errors:
- @table @code
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- Note that the @code{isatty} call is treated as a special case: it returns
- 1 to the target if the file descriptor is attached
- to the @value{GDBN} console, 0 otherwise. Implementing through system calls
- would require implementing @code{ioctl} and would be more complex than
- needed.
- @node system
- @unnumberedsubsubsec system
- @cindex system, file-i/o system call
- @table @asis
- @item Synopsis:
- @smallexample
- int system(const char *command);
- @end smallexample
- @item Request:
- @samp{Fsystem,@var{commandptr}/@var{len}}
- @item Return value:
- If @var{len} is zero, the return value indicates whether a shell is
- available. A zero return value indicates a shell is not available.
- For non-zero @var{len}, the value returned is -1 on error and the
- return status of the command otherwise. Only the exit status of the
- command is returned, which is extracted from the host's @code{system}
- return value by calling @code{WEXITSTATUS(retval)}. In case
- @file{/bin/sh} could not be executed, 127 is returned.
- @item Errors:
- @table @code
- @item EINTR
- The call was interrupted by the user.
- @end table
- @end table
- @value{GDBN} takes over the full task of calling the necessary host calls
- to perform the @code{system} call. The return value of @code{system} on
- the host is simplified before it's returned
- to the target. Any termination signal information from the child process
- is discarded, and the return value consists
- entirely of the exit status of the called command.
- Due to security concerns, the @code{system} call is by default refused
- by @value{GDBN}. The user has to allow this call explicitly with the
- @code{set remote system-call-allowed 1} command.
- @table @code
- @item set remote system-call-allowed
- @kindex set remote system-call-allowed
- Control whether to allow the @code{system} calls in the File I/O
- protocol for the remote target. The default is zero (disabled).
- @item show remote system-call-allowed
- @kindex show remote system-call-allowed
- Show whether the @code{system} calls are allowed in the File I/O
- protocol.
- @end table
- @node Protocol-specific Representation of Datatypes
- @subsection Protocol-specific Representation of Datatypes
- @cindex protocol-specific representation of datatypes, in file-i/o protocol
- @menu
- * Integral Datatypes::
- * Pointer Values::
- * Memory Transfer::
- * struct stat::
- * struct timeval::
- @end menu
- @node Integral Datatypes
- @unnumberedsubsubsec Integral Datatypes
- @cindex integral datatypes, in file-i/o protocol
- The integral datatypes used in the system calls are @code{int},
- @code{unsigned int}, @code{long}, @code{unsigned long},
- @code{mode_t}, and @code{time_t}.
- @code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
- implemented as 32 bit values in this protocol.
- @code{long} and @code{unsigned long} are implemented as 64 bit types.
- @xref{Limits}, for corresponding MIN and MAX values (similar to those
- in @file{limits.h}) to allow range checking on host and target.
- @code{time_t} datatypes are defined as seconds since the Epoch.
- All integral datatypes transferred as part of a memory read or write of a
- structured datatype e.g.@: a @code{struct stat} have to be given in big endian
- byte order.
- @node Pointer Values
- @unnumberedsubsubsec Pointer Values
- @cindex pointer values, in file-i/o protocol
- Pointers to target data are transmitted as they are. An exception
- is made for pointers to buffers for which the length isn't
- transmitted as part of the function call, namely strings. Strings
- are transmitted as a pointer/length pair, both as hex values, e.g.@:
- @smallexample
- @code{1aaf/12}
- @end smallexample
- @noindent
- which is a pointer to data of length 18 bytes at position 0x1aaf.
- The length is defined as the full string length in bytes, including
- the trailing null byte. For example, the string @code{"hello world"}
- at address 0x123456 is transmitted as
- @smallexample
- @code{123456/d}
- @end smallexample
- @node Memory Transfer
- @unnumberedsubsubsec Memory Transfer
- @cindex memory transfer, in file-i/o protocol
- Structured data which is transferred using a memory read or write (for
- example, a @code{struct stat}) is expected to be in a protocol-specific format
- with all scalar multibyte datatypes being big endian. Translation to
- this representation needs to be done both by the target before the @code{F}
- packet is sent, and by @value{GDBN} before
- it transfers memory to the target. Transferred pointers to structured
- data should point to the already-coerced data at any time.
- @node struct stat
- @unnumberedsubsubsec struct stat
- @cindex struct stat, in file-i/o protocol
- The buffer of type @code{struct stat} used by the target and @value{GDBN}
- is defined as follows:
- @smallexample
- struct stat @{
- unsigned int st_dev; /* device */
- unsigned int st_ino; /* inode */
- mode_t st_mode; /* protection */
- unsigned int st_nlink; /* number of hard links */
- unsigned int st_uid; /* user ID of owner */
- unsigned int st_gid; /* group ID of owner */
- unsigned int st_rdev; /* device type (if inode device) */
- unsigned long st_size; /* total size, in bytes */
- unsigned long st_blksize; /* blocksize for filesystem I/O */
- unsigned long st_blocks; /* number of blocks allocated */
- time_t st_atime; /* time of last access */
- time_t st_mtime; /* time of last modification */
- time_t st_ctime; /* time of last change */
- @};
- @end smallexample
- The integral datatypes conform to the definitions given in the
- appropriate section (see @ref{Integral Datatypes}, for details) so this
- structure is of size 64 bytes.
- The values of several fields have a restricted meaning and/or
- range of values.
- @table @code
- @item st_dev
- A value of 0 represents a file, 1 the console.
- @item st_ino
- No valid meaning for the target. Transmitted unchanged.
- @item st_mode
- Valid mode bits are described in @ref{Constants}. Any other
- bits have currently no meaning for the target.
- @item st_uid
- @itemx st_gid
- @itemx st_rdev
- No valid meaning for the target. Transmitted unchanged.
- @item st_atime
- @itemx st_mtime
- @itemx st_ctime
- These values have a host and file system dependent
- accuracy. Especially on Windows hosts, the file system may not
- support exact timing values.
- @end table
- The target gets a @code{struct stat} of the above representation and is
- responsible for coercing it to the target representation before
- continuing.
- Note that due to size differences between the host, target, and protocol
- representations of @code{struct stat} members, these members could eventually
- get truncated on the target.
- @node struct timeval
- @unnumberedsubsubsec struct timeval
- @cindex struct timeval, in file-i/o protocol
- The buffer of type @code{struct timeval} used by the File-I/O protocol
- is defined as follows:
- @smallexample
- struct timeval @{
- time_t tv_sec; /* second */
- long tv_usec; /* microsecond */
- @};
- @end smallexample
- The integral datatypes conform to the definitions given in the
- appropriate section (see @ref{Integral Datatypes}, for details) so this
- structure is of size 8 bytes.
- @node Constants
- @subsection Constants
- @cindex constants, in file-i/o protocol
- The following values are used for the constants inside of the
- protocol. @value{GDBN} and target are responsible for translating these
- values before and after the call as needed.
- @menu
- * Open Flags::
- * mode_t Values::
- * Errno Values::
- * Lseek Flags::
- * Limits::
- @end menu
- @node Open Flags
- @unnumberedsubsubsec Open Flags
- @cindex open flags, in file-i/o protocol
- All values are given in hexadecimal representation.
- @smallexample
- O_RDONLY 0x0
- O_WRONLY 0x1
- O_RDWR 0x2
- O_APPEND 0x8
- O_CREAT 0x200
- O_TRUNC 0x400
- O_EXCL 0x800
- @end smallexample
- @node mode_t Values
- @unnumberedsubsubsec mode_t Values
- @cindex mode_t values, in file-i/o protocol
- All values are given in octal representation.
- @smallexample
- S_IFREG 0100000
- S_IFDIR 040000
- S_IRUSR 0400
- S_IWUSR 0200
- S_IXUSR 0100
- S_IRGRP 040
- S_IWGRP 020
- S_IXGRP 010
- S_IROTH 04
- S_IWOTH 02
- S_IXOTH 01
- @end smallexample
- @node Errno Values
- @unnumberedsubsubsec Errno Values
- @cindex errno values, in file-i/o protocol
- All values are given in decimal representation.
- @smallexample
- EPERM 1
- ENOENT 2
- EINTR 4
- EBADF 9
- EACCES 13
- EFAULT 14
- EBUSY 16
- EEXIST 17
- ENODEV 19
- ENOTDIR 20
- EISDIR 21
- EINVAL 22
- ENFILE 23
- EMFILE 24
- EFBIG 27
- ENOSPC 28
- ESPIPE 29
- EROFS 30
- ENAMETOOLONG 91
- EUNKNOWN 9999
- @end smallexample
- @code{EUNKNOWN} is used as a fallback error value if a host system returns
- any error value not in the list of supported error numbers.
- @node Lseek Flags
- @unnumberedsubsubsec Lseek Flags
- @cindex lseek flags, in file-i/o protocol
- @smallexample
- SEEK_SET 0
- SEEK_CUR 1
- SEEK_END 2
- @end smallexample
- @node Limits
- @unnumberedsubsubsec Limits
- @cindex limits, in file-i/o protocol
- All values are given in decimal representation.
- @smallexample
- INT_MIN -2147483648
- INT_MAX 2147483647
- UINT_MAX 4294967295
- LONG_MIN -9223372036854775808
- LONG_MAX 9223372036854775807
- ULONG_MAX 18446744073709551615
- @end smallexample
- @node File-I/O Examples
- @subsection File-I/O Examples
- @cindex file-i/o examples
- Example sequence of a write call, file descriptor 3, buffer is at target
- address 0x1234, 6 bytes should be written:
- @smallexample
- <- @code{Fwrite,3,1234,6}
- @emph{request memory read from target}
- -> @code{m1234,6}
- <- XXXXXX
- @emph{return "6 bytes written"}
- -> @code{F6}
- @end smallexample
- Example sequence of a read call, file descriptor 3, buffer is at target
- address 0x1234, 6 bytes should be read:
- @smallexample
- <- @code{Fread,3,1234,6}
- @emph{request memory write to target}
- -> @code{X1234,6:XXXXXX}
- @emph{return "6 bytes read"}
- -> @code{F6}
- @end smallexample
- Example sequence of a read call, call fails on the host due to invalid
- file descriptor (@code{EBADF}):
- @smallexample
- <- @code{Fread,3,1234,6}
- -> @code{F-1,9}
- @end smallexample
- Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on
- host is called:
- @smallexample
- <- @code{Fread,3,1234,6}
- -> @code{F-1,4,C}
- <- @code{T02}
- @end smallexample
- Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on
- host is called:
- @smallexample
- <- @code{Fread,3,1234,6}
- -> @code{X1234,6:XXXXXX}
- <- @code{T02}
- @end smallexample
- @node Library List Format
- @section Library List Format
- @cindex library list format, remote protocol
- On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the
- same process as your application to manage libraries. In this case,
- @value{GDBN} can use the loader's symbol table and normal memory
- operations to maintain a list of shared libraries. On other
- platforms, the operating system manages loaded libraries.
- @value{GDBN} can not retrieve the list of currently loaded libraries
- through memory operations, so it uses the @samp{qXfer:libraries:read}
- packet (@pxref{qXfer library list read}) instead. The remote stub
- queries the target's operating system and reports which libraries
- are loaded.
- The @samp{qXfer:libraries:read} packet returns an XML document which
- lists loaded libraries and their offsets. Each library has an
- associated name and one or more segment or section base addresses,
- which report where the library was loaded in memory.
- For the common case of libraries that are fully linked binaries, the
- library should have a list of segments. If the target supports
- dynamic linking of a relocatable object file, its library XML element
- should instead include a list of allocated sections. The segment or
- section bases are start addresses, not relocation offsets; they do not
- depend on the library's link-time base addresses.
- @value{GDBN} must be linked with the Expat library to support XML
- library lists. @xref{Expat}.
- A simple memory map, with one loaded library relocated by a single
- offset, looks like this:
- @smallexample
- <library-list>
- <library name="/lib/libc.so.6">
- <segment address="0x10000000"/>
- </library>
- </library-list>
- @end smallexample
- Another simple memory map, with one loaded library with three
- allocated sections (.text, .data, .bss), looks like this:
- @smallexample
- <library-list>
- <library name="sharedlib.o">
- <section address="0x10000000"/>
- <section address="0x20000000"/>
- <section address="0x30000000"/>
- </library>
- </library-list>
- @end smallexample
- The format of a library list is described by this DTD:
- @smallexample
- <!-- library-list: Root element with versioning -->
- <!ELEMENT library-list (library)*>
- <!ATTLIST library-list version CDATA #FIXED "1.0">
- <!ELEMENT library (segment*, section*)>
- <!ATTLIST library name CDATA #REQUIRED>
- <!ELEMENT segment EMPTY>
- <!ATTLIST segment address CDATA #REQUIRED>
- <!ELEMENT section EMPTY>
- <!ATTLIST section address CDATA #REQUIRED>
- @end smallexample
- In addition, segments and section descriptors cannot be mixed within a
- single library element, and you must supply at least one segment or
- section for each library.
- @node Library List Format for SVR4 Targets
- @section Library List Format for SVR4 Targets
- @cindex library list format, remote protocol
- On SVR4 platforms @value{GDBN} can use the symbol table of a dynamic loader
- (e.g.@: @file{ld.so}) and normal memory operations to maintain a list of
- shared libraries. Still a special library list provided by this packet is
- more efficient for the @value{GDBN} remote protocol.
- The @samp{qXfer:libraries-svr4:read} packet returns an XML document which lists
- loaded libraries and their SVR4 linker parameters. For each library on SVR4
- target, the following parameters are reported:
- @itemize @minus
- @item
- @code{name}, the absolute file name from the @code{l_name} field of
- @code{struct link_map}.
- @item
- @code{lm} with address of @code{struct link_map} used for TLS
- (Thread Local Storage) access.
- @item
- @code{l_addr}, the displacement as read from the field @code{l_addr} of
- @code{struct link_map}. For prelinked libraries this is not an absolute
- memory address. It is a displacement of absolute memory address against
- address the file was prelinked to during the library load.
- @item
- @code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment
- @end itemize
- Additionally the single @code{main-lm} attribute specifies address of
- @code{struct link_map} used for the main executable. This parameter is used
- for TLS access and its presence is optional.
- @value{GDBN} must be linked with the Expat library to support XML
- SVR4 library lists. @xref{Expat}.
- A simple memory map, with two loaded libraries (which do not use prelink),
- looks like this:
- @smallexample
- <library-list-svr4 version="1.0" main-lm="0xe4f8f8">
- <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
- l_ld="0xe4eefc"/>
- <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
- l_ld="0x152350"/>
- </library-list-svr>
- @end smallexample
- The format of an SVR4 library list is described by this DTD:
- @smallexample
- <!-- library-list-svr4: Root element with versioning -->
- <!ELEMENT library-list-svr4 (library)*>
- <!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
- <!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
- <!ELEMENT library EMPTY>
- <!ATTLIST library name CDATA #REQUIRED>
- <!ATTLIST library lm CDATA #REQUIRED>
- <!ATTLIST library l_addr CDATA #REQUIRED>
- <!ATTLIST library l_ld CDATA #REQUIRED>
- @end smallexample
- @node Memory Map Format
- @section Memory Map Format
- @cindex memory map format
- To be able to write into flash memory, @value{GDBN} needs to obtain a
- memory map from the target. This section describes the format of the
- memory map.
- The memory map is obtained using the @samp{qXfer:memory-map:read}
- (@pxref{qXfer memory map read}) packet and is an XML document that
- lists memory regions.
- @value{GDBN} must be linked with the Expat library to support XML
- memory maps. @xref{Expat}.
- The top-level structure of the document is shown below:
- @smallexample
- <?xml version="1.0"?>
- <!DOCTYPE memory-map
- PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
- "http://sourceware.org/gdb/gdb-memory-map.dtd">
- <memory-map>
- region...
- </memory-map>
- @end smallexample
- Each region can be either:
- @itemize
- @item
- A region of RAM starting at @var{addr} and extending for @var{length}
- bytes from there:
- @smallexample
- <memory type="ram" start="@var{addr}" length="@var{length}"/>
- @end smallexample
- @item
- A region of read-only memory:
- @smallexample
- <memory type="rom" start="@var{addr}" length="@var{length}"/>
- @end smallexample
- @item
- A region of flash memory, with erasure blocks @var{blocksize}
- bytes in length:
- @smallexample
- <memory type="flash" start="@var{addr}" length="@var{length}">
- <property name="blocksize">@var{blocksize}</property>
- </memory>
- @end smallexample
- @end itemize
- Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
- by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
- packets to write to addresses in such ranges.
- The formal DTD for memory map format is given below:
- @smallexample
- <!-- ................................................... -->
- <!-- Memory Map XML DTD ................................ -->
- <!-- File: memory-map.dtd .............................. -->
- <!-- .................................... .............. -->
- <!-- memory-map.dtd -->
- <!-- memory-map: Root element with versioning -->
- <!ELEMENT memory-map (memory)*>
- <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
- <!ELEMENT memory (property)*>
- <!-- memory: Specifies a memory region,
- and its type, or device. -->
- <!ATTLIST memory type (ram|rom|flash) #REQUIRED
- start CDATA #REQUIRED
- length CDATA #REQUIRED>
- <!-- property: Generic attribute tag -->
- <!ELEMENT property (#PCDATA | property)*>
- <!ATTLIST property name (blocksize) #REQUIRED>
- @end smallexample
- @node Thread List Format
- @section Thread List Format
- @cindex thread list format
- To efficiently update the list of threads and their attributes,
- @value{GDBN} issues the @samp{qXfer:threads:read} packet
- (@pxref{qXfer threads read}) and obtains the XML document with
- the following structure:
- @smallexample
- <?xml version="1.0"?>
- <threads>
- <thread id="id" core="0" name="name">
- ... description ...
- </thread>
- </threads>
- @end smallexample
- Each @samp{thread} element must have the @samp{id} attribute that
- identifies the thread (@pxref{thread-id syntax}). The
- @samp{core} attribute, if present, specifies which processor core
- the thread was last executing on. The @samp{name} attribute, if
- present, specifies the human-readable name of the thread. The content
- of the of @samp{thread} element is interpreted as human-readable
- auxiliary information. The @samp{handle} attribute, if present,
- is a hex encoded representation of the thread handle.
- @node Traceframe Info Format
- @section Traceframe Info Format
- @cindex traceframe info format
- To be able to know which objects in the inferior can be examined when
- inspecting a tracepoint hit, @value{GDBN} needs to obtain the list of
- memory ranges, registers and trace state variables that have been
- collected in a traceframe.
- This list is obtained using the @samp{qXfer:traceframe-info:read}
- (@pxref{qXfer traceframe info read}) packet and is an XML document.
- @value{GDBN} must be linked with the Expat library to support XML
- traceframe info discovery. @xref{Expat}.
- The top-level structure of the document is shown below:
- @smallexample
- <?xml version="1.0"?>
- <!DOCTYPE traceframe-info
- PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
- "http://sourceware.org/gdb/gdb-traceframe-info.dtd">
- <traceframe-info>
- block...
- </traceframe-info>
- @end smallexample
- Each traceframe block can be either:
- @itemize
- @item
- A region of collected memory starting at @var{addr} and extending for
- @var{length} bytes from there:
- @smallexample
- <memory start="@var{addr}" length="@var{length}"/>
- @end smallexample
- @item
- A block indicating trace state variable numbered @var{number} has been
- collected:
- @smallexample
- <tvar id="@var{number}"/>
- @end smallexample
- @end itemize
- The formal DTD for the traceframe info format is given below:
- @smallexample
- <!ELEMENT traceframe-info (memory | tvar)* >
- <!ATTLIST traceframe-info version CDATA #FIXED "1.0">
- <!ELEMENT memory EMPTY>
- <!ATTLIST memory start CDATA #REQUIRED
- length CDATA #REQUIRED>
- <!ELEMENT tvar>
- <!ATTLIST tvar id CDATA #REQUIRED>
- @end smallexample
- @node Branch Trace Format
- @section Branch Trace Format
- @cindex branch trace format
- In order to display the branch trace of an inferior thread,
- @value{GDBN} needs to obtain the list of branches. This list is
- represented as list of sequential code blocks that are connected via
- branches. The code in each block has been executed sequentially.
- This list is obtained using the @samp{qXfer:btrace:read}
- (@pxref{qXfer btrace read}) packet and is an XML document.
- @value{GDBN} must be linked with the Expat library to support XML
- traceframe info discovery. @xref{Expat}.
- The top-level structure of the document is shown below:
- @smallexample
- <?xml version="1.0"?>
- <!DOCTYPE btrace
- PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
- "http://sourceware.org/gdb/gdb-btrace.dtd">
- <btrace>
- block...
- </btrace>
- @end smallexample
- @itemize
- @item
- A block of sequentially executed instructions starting at @var{begin}
- and ending at @var{end}:
- @smallexample
- <block begin="@var{begin}" end="@var{end}"/>
- @end smallexample
- @end itemize
- The formal DTD for the branch trace format is given below:
- @smallexample
- <!ELEMENT btrace (block* | pt) >
- <!ATTLIST btrace version CDATA #FIXED "1.0">
- <!ELEMENT block EMPTY>
- <!ATTLIST block begin CDATA #REQUIRED
- end CDATA #REQUIRED>
- <!ELEMENT pt (pt-config?, raw?)>
- <!ELEMENT pt-config (cpu?)>
- <!ELEMENT cpu EMPTY>
- <!ATTLIST cpu vendor CDATA #REQUIRED
- family CDATA #REQUIRED
- model CDATA #REQUIRED
- stepping CDATA #REQUIRED>
- <!ELEMENT raw (#PCDATA)>
- @end smallexample
- @node Branch Trace Configuration Format
- @section Branch Trace Configuration Format
- @cindex branch trace configuration format
- For each inferior thread, @value{GDBN} can obtain the branch trace
- configuration using the @samp{qXfer:btrace-conf:read}
- (@pxref{qXfer btrace-conf read}) packet.
- The configuration describes the branch trace format and configuration
- settings for that format. The following information is described:
- @table @code
- @item bts
- This thread uses the @dfn{Branch Trace Store} (@acronym{BTS}) format.
- @table @code
- @item size
- The size of the @acronym{BTS} ring buffer in bytes.
- @end table
- @item pt
- This thread uses the @dfn{Intel Processor Trace} (@acronym{Intel
- PT}) format.
- @table @code
- @item size
- The size of the @acronym{Intel PT} ring buffer in bytes.
- @end table
- @end table
- @value{GDBN} must be linked with the Expat library to support XML
- branch trace configuration discovery. @xref{Expat}.
- The formal DTD for the branch trace configuration format is given below:
- @smallexample
- <!ELEMENT btrace-conf (bts?, pt?)>
- <!ATTLIST btrace-conf version CDATA #FIXED "1.0">
- <!ELEMENT bts EMPTY>
- <!ATTLIST bts size CDATA #IMPLIED>
- <!ELEMENT pt EMPTY>
- <!ATTLIST pt size CDATA #IMPLIED>
- @end smallexample
- @include agentexpr.texi
- @node Target Descriptions
- @appendix Target Descriptions
- @cindex target descriptions
- One of the challenges of using @value{GDBN} to debug embedded systems
- is that there are so many minor variants of each processor
- architecture in use. It is common practice for vendors to start with
- a standard processor core --- ARM, PowerPC, or @acronym{MIPS}, for example ---
- and then make changes to adapt it to a particular market niche. Some
- architectures have hundreds of variants, available from dozens of
- vendors. This leads to a number of problems:
- @itemize @bullet
- @item
- With so many different customized processors, it is difficult for
- the @value{GDBN} maintainers to keep up with the changes.
- @item
- Since individual variants may have short lifetimes or limited
- audiences, it may not be worthwhile to carry information about every
- variant in the @value{GDBN} source tree.
- @item
- When @value{GDBN} does support the architecture of the embedded system
- at hand, the task of finding the correct architecture name to give the
- @command{set architecture} command can be error-prone.
- @end itemize
- To address these problems, the @value{GDBN} remote protocol allows a
- target system to not only identify itself to @value{GDBN}, but to
- actually describe its own features. This lets @value{GDBN} support
- processor variants it has never seen before --- to the extent that the
- descriptions are accurate, and that @value{GDBN} understands them.
- @value{GDBN} must be linked with the Expat library to support XML
- target descriptions. @xref{Expat}.
- @menu
- * Retrieving Descriptions:: How descriptions are fetched from a target.
- * Target Description Format:: The contents of a target description.
- * Predefined Target Types:: Standard types available for target
- descriptions.
- * Enum Target Types:: How to define enum target types.
- * Standard Target Features:: Features @value{GDBN} knows about.
- @end menu
- @node Retrieving Descriptions
- @section Retrieving Descriptions
- Target descriptions can be read from the target automatically, or
- specified by the user manually. The default behavior is to read the
- description from the target. @value{GDBN} retrieves it via the remote
- protocol using @samp{qXfer} requests (@pxref{General Query Packets,
- qXfer}). The @var{annex} in the @samp{qXfer} packet will be
- @samp{target.xml}. The contents of the @samp{target.xml} annex are an
- XML document, of the form described in @ref{Target Description
- Format}.
- Alternatively, you can specify a file to read for the target description.
- If a file is set, the target will not be queried. The commands to
- specify a file are:
- @table @code
- @cindex set tdesc filename
- @item set tdesc filename @var{path}
- Read the target description from @var{path}.
- @cindex unset tdesc filename
- @item unset tdesc filename
- Do not read the XML target description from a file. @value{GDBN}
- will use the description supplied by the current target.
- @cindex show tdesc filename
- @item show tdesc filename
- Show the filename to read for a target description, if any.
- @end table
- @node Target Description Format
- @section Target Description Format
- @cindex target descriptions, XML format
- A target description annex is an @uref{http://www.w3.org/XML/, XML}
- document which complies with the Document Type Definition provided in
- the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This
- means you can use generally available tools like @command{xmllint} to
- check that your feature descriptions are well-formed and valid.
- However, to help people unfamiliar with XML write descriptions for
- their targets, we also describe the grammar here.
- Target descriptions can identify the architecture of the remote target
- and (for some architectures) provide information about custom register
- sets. They can also identify the OS ABI of the remote target.
- @value{GDBN} can use this information to autoconfigure for your
- target, or to warn you if you connect to an unsupported target.
- Here is a simple target description:
- @smallexample
- <target version="1.0">
- <architecture>i386:x86-64</architecture>
- </target>
- @end smallexample
- @noindent
- This minimal description only says that the target uses
- the x86-64 architecture.
- A target description has the following overall form, with [ ] marking
- optional elements and @dots{} marking repeatable elements. The elements
- are explained further below.
- @smallexample
- <?xml version="1.0"?>
- <!DOCTYPE target SYSTEM "gdb-target.dtd">
- <target version="1.0">
- @r{[}@var{architecture}@r{]}
- @r{[}@var{osabi}@r{]}
- @r{[}@var{compatible}@r{]}
- @r{[}@var{feature}@dots{}@r{]}
- </target>
- @end smallexample
- @noindent
- The description is generally insensitive to whitespace and line
- breaks, under the usual common-sense rules. The XML version
- declaration and document type declaration can generally be omitted
- (@value{GDBN} does not require them), but specifying them may be
- useful for XML validation tools. The @samp{version} attribute for
- @samp{<target>} may also be omitted, but we recommend
- including it; if future versions of @value{GDBN} use an incompatible
- revision of @file{gdb-target.dtd}, they will detect and report
- the version mismatch.
- @subsection Inclusion
- @cindex target descriptions, inclusion
- @cindex XInclude
- @ifnotinfo
- @cindex <xi:include>
- @end ifnotinfo
- It can sometimes be valuable to split a target description up into
- several different annexes, either for organizational purposes, or to
- share files between different possible target descriptions. You can
- divide a description into multiple files by replacing any element of
- the target description with an inclusion directive of the form:
- @smallexample
- <xi:include href="@var{document}"/>
- @end smallexample
- @noindent
- When @value{GDBN} encounters an element of this form, it will retrieve
- the named XML @var{document}, and replace the inclusion directive with
- the contents of that document. If the current description was read
- using @samp{qXfer}, then so will be the included document;
- @var{document} will be interpreted as the name of an annex. If the
- current description was read from a file, @value{GDBN} will look for
- @var{document} as a file in the same directory where it found the
- original description.
- @subsection Architecture
- @cindex <architecture>
- An @samp{<architecture>} element has this form:
- @smallexample
- <architecture>@var{arch}</architecture>
- @end smallexample
- @var{arch} is one of the architectures from the set accepted by
- @code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}).
- @subsection OS ABI
- @cindex @code{<osabi>}
- This optional field was introduced in @value{GDBN} version 7.0.
- Previous versions of @value{GDBN} ignore it.
- An @samp{<osabi>} element has this form:
- @smallexample
- <osabi>@var{abi-name}</osabi>
- @end smallexample
- @var{abi-name} is an OS ABI name from the same selection accepted by
- @w{@code{set osabi}} (@pxref{ABI, ,Configuring the Current ABI}).
- @subsection Compatible Architecture
- @cindex @code{<compatible>}
- This optional field was introduced in @value{GDBN} version 7.0.
- Previous versions of @value{GDBN} ignore it.
- A @samp{<compatible>} element has this form:
- @smallexample
- <compatible>@var{arch}</compatible>
- @end smallexample
- @var{arch} is one of the architectures from the set accepted by
- @code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}).
- A @samp{<compatible>} element is used to specify that the target
- is able to run binaries in some other than the main target architecture
- given by the @samp{<architecture>} element. For example, on the
- Cell Broadband Engine, the main architecture is @code{powerpc:common}
- or @code{powerpc:common64}, but the system is able to run binaries
- in the @code{spu} architecture as well. The way to describe this
- capability with @samp{<compatible>} is as follows:
- @smallexample
- <architecture>powerpc:common</architecture>
- <compatible>spu</compatible>
- @end smallexample
- @subsection Features
- @cindex <feature>
- Each @samp{<feature>} describes some logical portion of the target
- system. Features are currently used to describe available CPU
- registers and the types of their contents. A @samp{<feature>} element
- has this form:
- @smallexample
- <feature name="@var{name}">
- @r{[}@var{type}@dots{}@r{]}
- @var{reg}@dots{}
- </feature>
- @end smallexample
- @noindent
- Each feature's name should be unique within the description. The name
- of a feature does not matter unless @value{GDBN} has some special
- knowledge of the contents of that feature; if it does, the feature
- should have its standard name. @xref{Standard Target Features}.
- @subsection Types
- Any register's value is a collection of bits which @value{GDBN} must
- interpret. The default interpretation is a two's complement integer,
- but other types can be requested by name in the register description.
- Some predefined types are provided by @value{GDBN} (@pxref{Predefined
- Target Types}), and the description can define additional composite
- and enum types.
- Each type element must have an @samp{id} attribute, which gives
- a unique (within the containing @samp{<feature>}) name to the type.
- Types must be defined before they are used.
- @cindex <vector>
- Some targets offer vector registers, which can be treated as arrays
- of scalar elements. These types are written as @samp{<vector>} elements,
- specifying the array element type, @var{type}, and the number of elements,
- @var{count}:
- @smallexample
- <vector id="@var{id}" type="@var{type}" count="@var{count}"/>
- @end smallexample
- @cindex <union>
- If a register's value is usefully viewed in multiple ways, define it
- with a union type containing the useful representations. The
- @samp{<union>} element contains one or more @samp{<field>} elements,
- each of which has a @var{name} and a @var{type}:
- @smallexample
- <union id="@var{id}">
- <field name="@var{name}" type="@var{type}"/>
- @dots{}
- </union>
- @end smallexample
- @cindex <struct>
- @cindex <flags>
- If a register's value is composed from several separate values, define
- it with either a structure type or a flags type.
- A flags type may only contain bitfields.
- A structure type may either contain only bitfields or contain no bitfields.
- If the value contains only bitfields, its total size in bytes must be
- specified.
- Non-bitfield values have a @var{name} and @var{type}.
- @smallexample
- <struct id="@var{id}">
- <field name="@var{name}" type="@var{type}"/>
- @dots{}
- </struct>
- @end smallexample
- Both @var{name} and @var{type} values are required.
- No implicit padding is added.
- Bitfield values have a @var{name}, @var{start}, @var{end} and @var{type}.
- @smallexample
- <struct id="@var{id}" size="@var{size}">
- <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/>
- @dots{}
- </struct>
- @end smallexample
- @smallexample
- <flags id="@var{id}" size="@var{size}">
- <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/>
- @dots{}
- </flags>
- @end smallexample
- The @var{name} value is required.
- Bitfield values may be named with the empty string, @samp{""},
- in which case the field is ``filler'' and its value is not printed.
- Not all bits need to be specified, so ``filler'' fields are optional.
- The @var{start} and @var{end} values are required, and @var{type}
- is optional.
- The field's @var{start} must be less than or equal to its @var{end},
- and zero represents the least significant bit.
- The default value of @var{type} is @code{bool} for single bit fields,
- and an unsigned integer otherwise.
- Which to choose? Structures or flags?
- Registers defined with @samp{flags} have these advantages over
- defining them with @samp{struct}:
- @itemize @bullet
- @item
- Arithmetic may be performed on them as if they were integers.
- @item
- They are printed in a more readable fashion.
- @end itemize
- Registers defined with @samp{struct} have one advantage over
- defining them with @samp{flags}:
- @itemize @bullet
- @item
- One can fetch individual fields like in @samp{C}.
- @smallexample
- (gdb) print $my_struct_reg.field3
- $1 = 42
- @end smallexample
- @end itemize
- @subsection Registers
- @cindex <reg>
- Each register is represented as an element with this form:
- @smallexample
- <reg name="@var{name}"
- bitsize="@var{size}"
- @r{[}regnum="@var{num}"@r{]}
- @r{[}save-restore="@var{save-restore}"@r{]}
- @r{[}type="@var{type}"@r{]}
- @r{[}group="@var{group}"@r{]}/>
- @end smallexample
- @noindent
- The components are as follows:
- @table @var
- @item name
- The register's name; it must be unique within the target description.
- @item bitsize
- The register's size, in bits.
- @item regnum
- The register's number. If omitted, a register's number is one greater
- than that of the previous register (either in the current feature or in
- a preceding feature); the first register in the target description
- defaults to zero. This register number is used to read or write
- the register; e.g.@: it is used in the remote @code{p} and @code{P}
- packets, and registers appear in the @code{g} and @code{G} packets
- in order of increasing register number.
- @item save-restore
- Whether the register should be preserved across inferior function
- calls; this must be either @code{yes} or @code{no}. The default is
- @code{yes}, which is appropriate for most registers except for
- some system control registers; this is not related to the target's
- ABI.
- @item type
- The type of the register. It may be a predefined type, a type
- defined in the current feature, or one of the special types @code{int}
- and @code{float}. @code{int} is an integer type of the correct size
- for @var{bitsize}, and @code{float} is a floating point type (in the
- architecture's normal floating point format) of the correct size for
- @var{bitsize}. The default is @code{int}.
- @item group
- The register group to which this register belongs. It can be one of the
- standard register groups @code{general}, @code{float}, @code{vector} or an
- arbitrary string. Group names should be limited to alphanumeric characters.
- If a group name is made up of multiple words the words may be separated by
- hyphens; e.g.@: @code{special-group} or @code{ultra-special-group}. If no
- @var{group} is specified, @value{GDBN} will not display the register in
- @code{info registers}.
- @end table
- @node Predefined Target Types
- @section Predefined Target Types
- @cindex target descriptions, predefined types
- Type definitions in the self-description can build up composite types
- from basic building blocks, but can not define fundamental types. Instead,
- standard identifiers are provided by @value{GDBN} for the fundamental
- types. The currently supported types are:
- @table @code
- @item bool
- Boolean type, occupying a single bit.
- @item int8
- @itemx int16
- @itemx int24
- @itemx int32
- @itemx int64
- @itemx int128
- Signed integer types holding the specified number of bits.
- @item uint8
- @itemx uint16
- @itemx uint24
- @itemx uint32
- @itemx uint64
- @itemx uint128
- Unsigned integer types holding the specified number of bits.
- @item code_ptr
- @itemx data_ptr
- Pointers to unspecified code and data. The program counter and
- any dedicated return address register may be marked as code
- pointers; printing a code pointer converts it into a symbolic
- address. The stack pointer and any dedicated address registers
- may be marked as data pointers.
- @item ieee_half
- Half precision IEEE floating point.
- @item ieee_single
- Single precision IEEE floating point.
- @item ieee_double
- Double precision IEEE floating point.
- @item bfloat16
- The 16-bit @dfn{brain floating point} format used e.g.@: by x86 and ARM.
- @item arm_fpa_ext
- The 12-byte extended precision format used by ARM FPA registers.
- @item i387_ext
- The 10-byte extended precision format used by x87 registers.
- @item i386_eflags
- 32bit @sc{eflags} register used by x86.
- @item i386_mxcsr
- 32bit @sc{mxcsr} register used by x86.
- @end table
- @node Enum Target Types
- @section Enum Target Types
- @cindex target descriptions, enum types
- Enum target types are useful in @samp{struct} and @samp{flags}
- register descriptions. @xref{Target Description Format}.
- Enum types have a name, size and a list of name/value pairs.
- @smallexample
- <enum id="@var{id}" size="@var{size}">
- <evalue name="@var{name}" value="@var{value}"/>
- @dots{}
- </enum>
- @end smallexample
- Enums must be defined before they are used.
- @smallexample
- <enum id="levels_type" size="4">
- <evalue name="low" value="0"/>
- <evalue name="high" value="1"/>
- </enum>
- <flags id="flags_type" size="4">
- <field name="X" start="0"/>
- <field name="LEVEL" start="1" end="1" type="levels_type"/>
- </flags>
- <reg name="flags" bitsize="32" type="flags_type"/>
- @end smallexample
- Given that description, a value of 3 for the @samp{flags} register
- would be printed as:
- @smallexample
- (gdb) info register flags
- flags 0x3 [ X LEVEL=high ]
- @end smallexample
- @node Standard Target Features
- @section Standard Target Features
- @cindex target descriptions, standard features
- A target description must contain either no registers or all the
- target's registers. If the description contains no registers, then
- @value{GDBN} will assume a default register layout, selected based on
- the architecture. If the description contains any registers, the
- default layout will not be used; the standard registers must be
- described in the target description, in such a way that @value{GDBN}
- can recognize them.
- This is accomplished by giving specific names to feature elements
- which contain standard registers. @value{GDBN} will look for features
- with those names and verify that they contain the expected registers;
- if any known feature is missing required registers, or if any required
- feature is missing, @value{GDBN} will reject the target
- description. You can add additional registers to any of the
- standard features --- @value{GDBN} will display them just as if
- they were added to an unrecognized feature.
- This section lists the known features and their expected contents.
- Sample XML documents for these features are included in the
- @value{GDBN} source tree, in the directory @file{gdb/features}.
- Names recognized by @value{GDBN} should include the name of the
- company or organization which selected the name, and the overall
- architecture to which the feature applies; so e.g.@: the feature
- containing ARM core registers is named @samp{org.gnu.gdb.arm.core}.
- The names of registers are not case sensitive for the purpose
- of recognizing standard features, but @value{GDBN} will only display
- registers using the capitalization used in the description.
- @menu
- * AArch64 Features::
- * ARC Features::
- * ARM Features::
- * i386 Features::
- * LoongArch Features::
- * MicroBlaze Features::
- * MIPS Features::
- * M68K Features::
- * NDS32 Features::
- * Nios II Features::
- * OpenRISC 1000 Features::
- * PowerPC Features::
- * RISC-V Features::
- * RX Features::
- * S/390 and System z Features::
- * Sparc Features::
- * TIC6x Features::
- @end menu
- @node AArch64 Features
- @subsection AArch64 Features
- @cindex target descriptions, AArch64 features
- The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64
- targets. It should contain registers @samp{x0} through @samp{x30},
- @samp{sp}, @samp{pc}, and @samp{cpsr}.
- The @samp{org.gnu.gdb.aarch64.fpu} feature is optional. If present,
- it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr},
- and @samp{fpcr}.
- The @samp{org.gnu.gdb.aarch64.sve} feature is optional. If present,
- it should contain registers @samp{z0} through @samp{z31}, @samp{p0}
- through @samp{p15}, @samp{ffr} and @samp{vg}.
- The @samp{org.gnu.gdb.aarch64.pauth} feature is optional. If present,
- it should contain registers @samp{pauth_dmask} and @samp{pauth_cmask}.
- @node ARC Features
- @subsection ARC Features
- @cindex target descriptions, ARC Features
- ARC processors are so configurable that even core registers and their numbers
- are not predetermined completely. Moreover, @emph{flags} and @emph{PC}
- registers, which are important to @value{GDBN}, are not ``core'' registers in
- ARC. Therefore, there are two features that their presence is mandatory:
- @samp{org.gnu.gdb.arc.core} and @samp{org.gnu.gdb.arc.aux}.
- The @samp{org.gnu.gdb.arc.core} feature is required for all targets. It must
- contain registers:
- @itemize @minus
- @item
- @samp{r0} through @samp{r25} for normal register file targets.
- @item
- @samp{r0} through @samp{r3}, and @samp{r10} through @samp{r15} for reduced
- register file targets.
- @item
- @samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}@footnote{Not necessary for ARCv1.},
- @samp{blink}, @samp{lp_count}, @samp{pcl}.
- @end itemize
- In case of an ARCompact target (ARCv1 ISA), the @samp{org.gnu.gdb.arc.core}
- feature may contain registers @samp{ilink1} and @samp{ilink2}. While in case
- of ARC EM and ARC HS targets (ARCv2 ISA), register @samp{ilink} may be present.
- The difference between ARCv1 and ARCv2 is the naming of registers @emph{29th}
- and @emph{30th}. They are called @samp{ilink1} and @samp{ilink2} for ARCv1 and
- are optional. For ARCv2, they are called @samp{ilink} and @samp{r30} and only
- @samp{ilink} is optional. The optionality of @samp{ilink*} registers is
- because of their inaccessibility during user space debugging sessions.
- Extension core registers @samp{r32} through @samp{r59} are optional and their
- existence depends on the configuration. When debugging GNU/Linux applications,
- i.e.@: user space debugging, these core registers are not available.
- The @samp{org.gnu.gdb.arc.aux} feature is required for all ARC targets. Here
- is the list of registers pertinent to this feature:
- @itemize @minus
- @item
- mandatory: @samp{pc} and @samp{status32}.
- @item
- optional: @samp{lp_start}, @samp{lp_end}, and @samp{bta}.
- @end itemize
- @node ARM Features
- @subsection ARM Features
- @cindex target descriptions, ARM features
- The @samp{org.gnu.gdb.arm.core} feature is required for non-M-profile
- ARM targets.
- It should contain registers @samp{r0} through @samp{r13}, @samp{sp},
- @samp{lr}, @samp{pc}, and @samp{cpsr}.
- For M-profile targets (e.g.@: Cortex-M3), the @samp{org.gnu.gdb.arm.core}
- feature is replaced by @samp{org.gnu.gdb.arm.m-profile}. It should contain
- registers @samp{r0} through @samp{r13}, @samp{sp}, @samp{lr}, @samp{pc},
- and @samp{xpsr}.
- The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it
- should contain registers @samp{f0} through @samp{f7} and @samp{fps}.
- The @samp{org.gnu.gdb.arm.m-profile-mve} feature is optional. If present, it
- must contain register @samp{vpr}.
- If the @samp{org.gnu.gdb.arm.m-profile-mve} feature is available, @value{GDBN}
- will synthesize the @samp{p0} pseudo register from @samp{vpr} contents.
- If the @samp{org.gnu.gdb.arm.vfp} feature is available alongside the
- @samp{org.gnu.gdb.arm.m-profile-mve} feature, @value{GDBN} will
- synthesize the @samp{q} pseudo registers from @samp{d} register
- contents.
- The @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present,
- it should contain at least registers @samp{wR0} through @samp{wR15} and
- @samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
- @samp{wCSSF}, and @samp{wCASF} registers are optional.
- The @samp{org.gnu.gdb.arm.vfp} feature is optional. If present, it
- should contain at least registers @samp{d0} through @samp{d15}. If
- they are present, @samp{d16} through @samp{d31} should also be included.
- @value{GDBN} will synthesize the single-precision registers from
- halves of the double-precision registers.
- The @samp{org.gnu.gdb.arm.neon} feature is optional. It does not
- need to contain registers; it instructs @value{GDBN} to display the
- VFP double-precision registers as vectors and to synthesize the
- quad-precision registers from pairs of double-precision registers.
- If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also
- be present and include 32 double-precision registers.
- The @samp{org.gnu.gdb.arm.m-profile-pacbti} feature is optional, and
- acknowledges support for the ARMv8.1-m PACBTI extensions. @value{GDBN}
- will track return address signing states and will decorate backtraces using
- the [PAC] marker, similar to AArch64's PAC extension.
- @xref{AArch64 PAC}.
- @node i386 Features
- @subsection i386 Features
- @cindex target descriptions, i386 features
- The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64
- targets. It should describe the following registers:
- @itemize @minus
- @item
- @samp{eax} through @samp{edi} plus @samp{eip} for i386
- @item
- @samp{rax} through @samp{r15} plus @samp{rip} for amd64
- @item
- @samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es},
- @samp{fs}, @samp{gs}
- @item
- @samp{st0} through @samp{st7}
- @item
- @samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff},
- @samp{foseg}, @samp{fooff} and @samp{fop}
- @end itemize
- The register sets may be different, depending on the target.
- The @samp{org.gnu.gdb.i386.sse} feature is optional. It should
- describe registers:
- @itemize @minus
- @item
- @samp{xmm0} through @samp{xmm7} for i386
- @item
- @samp{xmm0} through @samp{xmm15} for amd64
- @item
- @samp{mxcsr}
- @end itemize
- The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the
- @samp{org.gnu.gdb.i386.sse} feature. It should
- describe the upper 128 bits of @sc{ymm} registers:
- @itemize @minus
- @item
- @samp{ymm0h} through @samp{ymm7h} for i386
- @item
- @samp{ymm0h} through @samp{ymm15h} for amd64
- @end itemize
- The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel
- Memory Protection Extension (MPX). It should describe the following registers:
- @itemize @minus
- @item
- @samp{bnd0raw} through @samp{bnd3raw} for i386 and amd64.
- @item
- @samp{bndcfgu} and @samp{bndstatus} for i386 and amd64.
- @end itemize
- The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
- describe a single register, @samp{orig_eax}.
- The @samp{org.gnu.gdb.i386.segments} feature is optional. It should
- describe two system registers: @samp{fs_base} and @samp{gs_base}.
- The @samp{org.gnu.gdb.i386.avx512} feature is optional and requires the
- @samp{org.gnu.gdb.i386.avx} feature. It should
- describe additional @sc{xmm} registers:
- @itemize @minus
- @item
- @samp{xmm16h} through @samp{xmm31h}, only valid for amd64.
- @end itemize
- It should describe the upper 128 bits of additional @sc{ymm} registers:
- @itemize @minus
- @item
- @samp{ymm16h} through @samp{ymm31h}, only valid for amd64.
- @end itemize
- It should
- describe the upper 256 bits of @sc{zmm} registers:
- @itemize @minus
- @item
- @samp{zmm0h} through @samp{zmm7h} for i386.
- @item
- @samp{zmm0h} through @samp{zmm15h} for amd64.
- @end itemize
- It should
- describe the additional @sc{zmm} registers:
- @itemize @minus
- @item
- @samp{zmm16h} through @samp{zmm31h}, only valid for amd64.
- @end itemize
- The @samp{org.gnu.gdb.i386.pkeys} feature is optional. It should
- describe a single register, @samp{pkru}. It is a 32-bit register
- valid for i386 and amd64.
- @node LoongArch Features
- @subsection LoongArch Features
- @cindex target descriptions, LoongArch Features
- The @samp{org.gnu.gdb.loongarch.base} feature is required for LoongArch
- targets. It should contain the registers @samp{r0} through @samp{r31},
- @samp{pc}, and @samp{badv}. Either the architectural names (@samp{r0},
- @samp{r1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra}, etc).
- @node MicroBlaze Features
- @subsection MicroBlaze Features
- @cindex target descriptions, MicroBlaze features
- The @samp{org.gnu.gdb.microblaze.core} feature is required for MicroBlaze
- targets. It should contain registers @samp{r0} through @samp{r31},
- @samp{rpc}, @samp{rmsr}, @samp{rear}, @samp{resr}, @samp{rfsr}, @samp{rbtr},
- @samp{rpvr}, @samp{rpvr1} through @samp{rpvr11}, @samp{redr}, @samp{rpid},
- @samp{rzpr}, @samp{rtlbx}, @samp{rtlbsx}, @samp{rtlblo}, and @samp{rtlbhi}.
- The @samp{org.gnu.gdb.microblaze.stack-protect} feature is optional.
- If present, it should contain registers @samp{rshr} and @samp{rslr}
- @node MIPS Features
- @subsection @acronym{MIPS} Features
- @cindex target descriptions, @acronym{MIPS} features
- The @samp{org.gnu.gdb.mips.cpu} feature is required for @acronym{MIPS} targets.
- It should contain registers @samp{r0} through @samp{r31}, @samp{lo},
- @samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending
- on the target.
- The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should
- contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause}
- registers. They may be 32-bit or 64-bit depending on the target.
- The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though
- it may be optional in a future version of @value{GDBN}. It should
- contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and
- @samp{fir}. They may be 32-bit or 64-bit depending on the target.
- The @samp{org.gnu.gdb.mips.dsp} feature is optional. It should
- contain registers @samp{hi1} through @samp{hi3}, @samp{lo1} through
- @samp{lo3}, and @samp{dspctl}. The @samp{dspctl} register should
- be 32-bit and the rest may be 32-bit or 64-bit depending on the target.
- The @samp{org.gnu.gdb.mips.linux} feature is optional. It should
- contain a single register, @samp{restart}, which is used by the
- Linux kernel to control restartable syscalls.
- @node M68K Features
- @subsection M68K Features
- @cindex target descriptions, M68K features
- @table @code
- @item @samp{org.gnu.gdb.m68k.core}
- @itemx @samp{org.gnu.gdb.coldfire.core}
- @itemx @samp{org.gnu.gdb.fido.core}
- One of those features must be always present.
- The feature that is present determines which flavor of m68k is
- used. The feature that is present should contain registers
- @samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp},
- @samp{sp}, @samp{ps} and @samp{pc}.
- @item @samp{org.gnu.gdb.coldfire.fp}
- This feature is optional. If present, it should contain registers
- @samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and
- @samp{fpiaddr}.
- Note that, despite the fact that this feature's name says
- @samp{coldfire}, it is used to describe any floating point registers.
- The size of the registers must match the main m68k flavor; so, for
- example, if the primary feature is reported as @samp{coldfire}, then
- 64-bit floating point registers are required.
- @end table
- @node NDS32 Features
- @subsection NDS32 Features
- @cindex target descriptions, NDS32 features
- The @samp{org.gnu.gdb.nds32.core} feature is required for NDS32
- targets. It should contain at least registers @samp{r0} through
- @samp{r10}, @samp{r15}, @samp{fp}, @samp{gp}, @samp{lp}, @samp{sp},
- and @samp{pc}.
- The @samp{org.gnu.gdb.nds32.fpu} feature is optional. If present,
- it should contain 64-bit double-precision floating-point registers
- @samp{fd0} through @emph{fdN}, which should be @samp{fd3}, @samp{fd7},
- @samp{fd15}, or @samp{fd31} based on the FPU configuration implemented.
- @emph{Note:} The first sixteen 64-bit double-precision floating-point
- registers are overlapped with the thirty-two 32-bit single-precision
- floating-point registers. The 32-bit single-precision registers, if
- not being listed explicitly, will be synthesized from halves of the
- overlapping 64-bit double-precision registers. Listing 32-bit
- single-precision registers explicitly is deprecated, and the
- support to it could be totally removed some day.
- @node Nios II Features
- @subsection Nios II Features
- @cindex target descriptions, Nios II features
- The @samp{org.gnu.gdb.nios2.cpu} feature is required for Nios II
- targets. It should contain the 32 core registers (@samp{zero},
- @samp{at}, @samp{r2} through @samp{r23}, @samp{et} through @samp{ra}),
- @samp{pc}, and the 16 control registers (@samp{status} through
- @samp{mpuacc}).
- @node OpenRISC 1000 Features
- @subsection Openrisc 1000 Features
- @cindex target descriptions, OpenRISC 1000 features
- The @samp{org.gnu.gdb.or1k.group0} feature is required for OpenRISC 1000
- targets. It should contain the 32 general purpose registers (@samp{r0}
- through @samp{r31}), @samp{ppc}, @samp{npc} and @samp{sr}.
- @node PowerPC Features
- @subsection PowerPC Features
- @cindex target descriptions, PowerPC features
- The @samp{org.gnu.gdb.power.core} feature is required for PowerPC
- targets. It should contain registers @samp{r0} through @samp{r31},
- @samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and
- @samp{xer}. They may be 32-bit or 64-bit depending on the target.
- The @samp{org.gnu.gdb.power.fpu} feature is optional. It should
- contain registers @samp{f0} through @samp{f31} and @samp{fpscr}.
- The @samp{org.gnu.gdb.power.altivec} feature is optional. It should
- contain registers @samp{vr0} through @samp{vr31}, @samp{vscr}, and
- @samp{vrsave}. @value{GDBN} will define pseudo-registers @samp{v0}
- through @samp{v31} as aliases for the corresponding @samp{vrX}
- registers.
- The @samp{org.gnu.gdb.power.vsx} feature is optional. It should
- contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN} will
- combine these registers with the floating point registers (@samp{f0}
- through @samp{f31}) and the altivec registers (@samp{vr0} through
- @samp{vr31}) to present the 128-bit wide registers @samp{vs0} through
- @samp{vs63}, the set of vector-scalar registers for POWER7.
- Therefore, this feature requires both @samp{org.gnu.gdb.power.fpu} and
- @samp{org.gnu.gdb.power.altivec}.
- The @samp{org.gnu.gdb.power.spe} feature is optional. It should
- contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
- @samp{spefscr}. SPE targets should provide 32-bit registers in
- @samp{org.gnu.gdb.power.core} and provide the upper halves in
- @samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine
- these to present registers @samp{ev0} through @samp{ev31} to the
- user.
- The @samp{org.gnu.gdb.power.ppr} feature is optional. It should
- contain the 64-bit register @samp{ppr}.
- The @samp{org.gnu.gdb.power.dscr} feature is optional. It should
- contain the 64-bit register @samp{dscr}.
- The @samp{org.gnu.gdb.power.tar} feature is optional. It should
- contain the 64-bit register @samp{tar}.
- The @samp{org.gnu.gdb.power.ebb} feature is optional. It should
- contain registers @samp{bescr}, @samp{ebbhr} and @samp{ebbrr}, all
- 64-bit wide.
- The @samp{org.gnu.gdb.power.linux.pmu} feature is optional. It should
- contain registers @samp{mmcr0}, @samp{mmcr2}, @samp{siar}, @samp{sdar}
- and @samp{sier}, all 64-bit wide. This is the subset of the isa 2.07
- server PMU registers provided by @sc{gnu}/Linux.
- The @samp{org.gnu.gdb.power.htm.spr} feature is optional. It should
- contain registers @samp{tfhar}, @samp{texasr} and @samp{tfiar}, all
- 64-bit wide.
- The @samp{org.gnu.gdb.power.htm.core} feature is optional. It should
- contain the checkpointed general-purpose registers @samp{cr0} through
- @samp{cr31}, as well as the checkpointed registers @samp{clr} and
- @samp{cctr}. These registers may all be either 32-bit or 64-bit
- depending on the target. It should also contain the checkpointed
- registers @samp{ccr} and @samp{cxer}, which should both be 32-bit
- wide.
- The @samp{org.gnu.gdb.power.htm.fpu} feature is optional. It should
- contain the checkpointed 64-bit floating-point registers @samp{cf0}
- through @samp{cf31}, as well as the checkpointed 64-bit register
- @samp{cfpscr}.
- The @samp{org.gnu.gdb.power.htm.altivec} feature is optional. It
- should contain the checkpointed altivec registers @samp{cvr0} through
- @samp{cvr31}, all 128-bit wide. It should also contain the
- checkpointed registers @samp{cvscr} and @samp{cvrsave}, both 32-bit
- wide.
- The @samp{org.gnu.gdb.power.htm.vsx} feature is optional. It should
- contain registers @samp{cvs0h} through @samp{cvs31h}. @value{GDBN}
- will combine these registers with the checkpointed floating point
- registers (@samp{cf0} through @samp{cf31}) and the checkpointed
- altivec registers (@samp{cvr0} through @samp{cvr31}) to present the
- 128-bit wide checkpointed vector-scalar registers @samp{cvs0} through
- @samp{cvs63}. Therefore, this feature requires both
- @samp{org.gnu.gdb.power.htm.altivec} and
- @samp{org.gnu.gdb.power.htm.fpu}.
- The @samp{org.gnu.gdb.power.htm.ppr} feature is optional. It should
- contain the 64-bit checkpointed register @samp{cppr}.
- The @samp{org.gnu.gdb.power.htm.dscr} feature is optional. It should
- contain the 64-bit checkpointed register @samp{cdscr}.
- The @samp{org.gnu.gdb.power.htm.tar} feature is optional. It should
- contain the 64-bit checkpointed register @samp{ctar}.
- @node RISC-V Features
- @subsection RISC-V Features
- @cindex target descriptions, RISC-V Features
- The @samp{org.gnu.gdb.riscv.cpu} feature is required for RISC-V
- targets. It should contain the registers @samp{x0} through
- @samp{x31}, and @samp{pc}. Either the architectural names (@samp{x0},
- @samp{x1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra},
- etc).
- The @samp{org.gnu.gdb.riscv.fpu} feature is optional. If present, it
- should contain registers @samp{f0} through @samp{f31}, @samp{fflags},
- @samp{frm}, and @samp{fcsr}. As with the cpu feature, either the
- architectural register names, or the ABI names can be used.
- The @samp{org.gnu.gdb.riscv.virtual} feature is optional. If present,
- it should contain registers that are not backed by real registers on
- the target, but are instead virtual, where the register value is
- derived from other target state. In many ways these are like
- @value{GDBN}s pseudo-registers, except implemented by the target.
- Currently the only register expected in this set is the one byte
- @samp{priv} register that contains the target's privilege level in the
- least significant two bits.
- The @samp{org.gnu.gdb.riscv.csr} feature is optional. If present, it
- should contain all of the target's standard CSRs. Standard CSRs are
- those defined in the RISC-V specification documents. There is some
- overlap between this feature and the fpu feature; the @samp{fflags},
- @samp{frm}, and @samp{fcsr} registers could be in either feature. The
- expectation is that these registers will be in the fpu feature if the
- target has floating point hardware, but can be moved into the csr
- feature if the target has the floating point control registers, but no
- other floating point hardware.
- The @samp{org.gnu.gdb.riscv.vector} feature is optional. If present,
- it should contain registers @samp{v0} through @samp{v31}, all of which
- must be the same size. These requirements are based on the v0.10
- draft vector extension, as the vector extension is not yet final. In
- the event that the register set of the vector extension changes for
- the final specification, the requirements given here could change for
- future releases of @value{GDBN}.
- @node RX Features
- @subsection RX Features
- @cindex target descriptions, RX Features
- The @samp{org.gnu.gdb.rx.core} feature is required for RX
- targets. It should contain the registers @samp{r0} through
- @samp{r15}, @samp{usp}, @samp{isp}, @samp{psw}, @samp{pc}, @samp{intb},
- @samp{bpsw}, @samp{bpc}, @samp{fintv}, @samp{fpsw}, and @samp{acc}.
- @node S/390 and System z Features
- @subsection S/390 and System z Features
- @cindex target descriptions, S/390 features
- @cindex target descriptions, System z features
- The @samp{org.gnu.gdb.s390.core} feature is required for S/390 and
- System z targets. It should contain the PSW and the 16 general
- registers. In particular, System z targets should provide the 64-bit
- registers @samp{pswm}, @samp{pswa}, and @samp{r0} through @samp{r15}.
- S/390 targets should provide the 32-bit versions of these registers.
- A System z target that runs in 31-bit addressing mode should provide
- 32-bit versions of @samp{pswm} and @samp{pswa}, as well as the general
- register's upper halves @samp{r0h} through @samp{r15h}, and their
- lower halves @samp{r0l} through @samp{r15l}.
- The @samp{org.gnu.gdb.s390.fpr} feature is required. It should
- contain the 64-bit registers @samp{f0} through @samp{f15}, and
- @samp{fpc}.
- The @samp{org.gnu.gdb.s390.acr} feature is required. It should
- contain the 32-bit registers @samp{acr0} through @samp{acr15}.
- The @samp{org.gnu.gdb.s390.linux} feature is optional. It should
- contain the register @samp{orig_r2}, which is 64-bit wide on System z
- targets and 32-bit otherwise. In addition, the feature may contain
- the @samp{last_break} register, whose width depends on the addressing
- mode, as well as the @samp{system_call} register, which is always
- 32-bit wide.
- The @samp{org.gnu.gdb.s390.tdb} feature is optional. It should
- contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct},
- @samp{atia}, and @samp{tr0} through @samp{tr15}.
- The @samp{org.gnu.gdb.s390.vx} feature is optional. It should contain
- 64-bit wide registers @samp{v0l} through @samp{v15l}, which will be
- combined by @value{GDBN} with the floating point registers @samp{f0}
- through @samp{f15} to present the 128-bit wide vector registers
- @samp{v0} through @samp{v15}. In addition, this feature should
- contain the 128-bit wide vector registers @samp{v16} through
- @samp{v31}.
- The @samp{org.gnu.gdb.s390.gs} feature is optional. It should contain
- the 64-bit wide guarded-storage-control registers @samp{gsd},
- @samp{gssm}, and @samp{gsepla}.
- The @samp{org.gnu.gdb.s390.gsbc} feature is optional. It should contain
- the 64-bit wide guarded-storage broadcast control registers
- @samp{bc_gsd}, @samp{bc_gssm}, and @samp{bc_gsepla}.
- @node Sparc Features
- @subsection Sparc Features
- @cindex target descriptions, sparc32 features
- @cindex target descriptions, sparc64 features
- The @samp{org.gnu.gdb.sparc.cpu} feature is required for sparc32/sparc64
- targets. It should describe the following registers:
- @itemize @minus
- @item
- @samp{g0} through @samp{g7}
- @item
- @samp{o0} through @samp{o7}
- @item
- @samp{l0} through @samp{l7}
- @item
- @samp{i0} through @samp{i7}
- @end itemize
- They may be 32-bit or 64-bit depending on the target.
- Also the @samp{org.gnu.gdb.sparc.fpu} feature is required for sparc32/sparc64
- targets. It should describe the following registers:
- @itemize @minus
- @item
- @samp{f0} through @samp{f31}
- @item
- @samp{f32} through @samp{f62} for sparc64
- @end itemize
- The @samp{org.gnu.gdb.sparc.cp0} feature is required for sparc32/sparc64
- targets. It should describe the following registers:
- @itemize @minus
- @item
- @samp{y}, @samp{psr}, @samp{wim}, @samp{tbr}, @samp{pc}, @samp{npc},
- @samp{fsr}, and @samp{csr} for sparc32
- @item
- @samp{pc}, @samp{npc}, @samp{state}, @samp{fsr}, @samp{fprs}, and @samp{y}
- for sparc64
- @end itemize
- @node TIC6x Features
- @subsection TMS320C6x Features
- @cindex target descriptions, TIC6x features
- @cindex target descriptions, TMS320C6x features
- The @samp{org.gnu.gdb.tic6x.core} feature is required for TMS320C6x
- targets. It should contain registers @samp{A0} through @samp{A15},
- registers @samp{B0} through @samp{B15}, @samp{CSR} and @samp{PC}.
- The @samp{org.gnu.gdb.tic6x.gp} feature is optional. It should
- contain registers @samp{A16} through @samp{A31} and @samp{B16}
- through @samp{B31}.
- The @samp{org.gnu.gdb.tic6x.c6xp} feature is optional. It should
- contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}.
- @node Operating System Information
- @appendix Operating System Information
- @cindex operating system information
- Users of @value{GDBN} often wish to obtain information about the state of
- the operating system running on the target---for example the list of
- processes, or the list of open files. This section describes the
- mechanism that makes it possible. This mechanism is similar to the
- target features mechanism (@pxref{Target Descriptions}), but focuses
- on a different aspect of target.
- Operating system information is retrieved from the target via the
- remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata
- read}). The object name in the request should be @samp{osdata}, and
- the @var{annex} identifies the data to be fetched.
- @menu
- * Process list::
- @end menu
- @node Process list
- @appendixsection Process list
- @cindex operating system information, process list
- When requesting the process list, the @var{annex} field in the
- @samp{qXfer} request should be @samp{processes}. The returned data is
- an XML document. The formal syntax of this document is defined in
- @file{gdb/features/osdata.dtd}.
- An example document is:
- @smallexample
- <?xml version="1.0"?>
- <!DOCTYPE target SYSTEM "osdata.dtd">
- <osdata type="processes">
- <item>
- <column name="pid">1</column>
- <column name="user">root</column>
- <column name="command">/sbin/init</column>
- <column name="cores">1,2,3</column>
- </item>
- </osdata>
- @end smallexample
- Each item should include a column whose name is @samp{pid}. The value
- of that column should identify the process on the target. The
- @samp{user} and @samp{command} columns are optional, and will be
- displayed by @value{GDBN}. The @samp{cores} column, if present,
- should contain a comma-separated list of cores that this process
- is running on. Target may provide additional columns,
- which @value{GDBN} currently ignores.
- @node Trace File Format
- @appendix Trace File Format
- @cindex trace file format
- The trace file comes in three parts: a header, a textual description
- section, and a trace frame section with binary data.
- The header has the form @code{\x7fTRACE0\n}. The first byte is
- @code{0x7f} so as to indicate that the file contains binary data,
- while the @code{0} is a version number that may have different values
- in the future.
- The description section consists of multiple lines of @sc{ascii} text
- separated by newline characters (@code{0xa}). The lines may include a
- variety of optional descriptive or context-setting information, such
- as tracepoint definitions or register set size. @value{GDBN} will
- ignore any line that it does not recognize. An empty line marks the end
- of this section.
- @table @code
- @item R @var{size}
- Specifies the size of a register block in bytes. This is equal to the
- size of a @code{g} packet payload in the remote protocol. @var{size}
- is an ascii decimal number. There should be only one such line in
- a single trace file.
- @item status @var{status}
- Trace status. @var{status} has the same format as a @code{qTStatus}
- remote packet reply. There should be only one such line in a single trace
- file.
- @item tp @var{payload}
- Tracepoint definition. The @var{payload} has the same format as
- @code{qTfP}/@code{qTsP} remote packet reply payload. A single tracepoint
- may take multiple lines of definition, corresponding to the multiple
- reply packets.
- @item tsv @var{payload}
- Trace state variable definition. The @var{payload} has the same format as
- @code{qTfV}/@code{qTsV} remote packet reply payload. A single variable
- may take multiple lines of definition, corresponding to the multiple
- reply packets.
- @item tdesc @var{payload}
- Target description in XML format. The @var{payload} is a single line of
- the XML file. All such lines should be concatenated together to get
- the original XML file. This file is in the same format as @code{qXfer}
- @code{features} payload, and corresponds to the main @code{target.xml}
- file. Includes are not allowed.
- @end table
- The trace frame section consists of a number of consecutive frames.
- Each frame begins with a two-byte tracepoint number, followed by a
- four-byte size giving the amount of data in the frame. The data in
- the frame consists of a number of blocks, each introduced by a
- character indicating its type (at least register, memory, and trace
- state variable). The data in this section is raw binary, not a
- hexadecimal or other encoding; its endianness matches the target's
- endianness.
- @c FIXME bi-arch may require endianness/arch info in description section
- @table @code
- @item R @var{bytes}
- Register block. The number and ordering of bytes matches that of a
- @code{g} packet in the remote protocol. Note that these are the
- actual bytes, in target order, not a hexadecimal encoding.
- @item M @var{address} @var{length} @var{bytes}...
- Memory block. This is a contiguous block of memory, at the 8-byte
- address @var{address}, with a 2-byte length @var{length}, followed by
- @var{length} bytes.
- @item V @var{number} @var{value}
- Trace state variable block. This records the 8-byte signed value
- @var{value} of trace state variable numbered @var{number}.
- @end table
- Future enhancements of the trace file format may include additional types
- of blocks.
- @node Index Section Format
- @appendix @code{.gdb_index} section format
- @cindex .gdb_index section format
- @cindex index section format
- This section documents the index section that is created by @code{save
- gdb-index} (@pxref{Index Files}). The index section is
- DWARF-specific; some knowledge of DWARF is assumed in this
- description.
- The mapped index file format is designed to be directly
- @code{mmap}able on any architecture. In most cases, a datum is
- represented using a little-endian 32-bit integer value, called an
- @code{offset_type}. Big endian machines must byte-swap the values
- before using them. Exceptions to this rule are noted. The data is
- laid out such that alignment is always respected.
- A mapped index consists of several areas, laid out in order.
- @enumerate
- @item
- The file header. This is a sequence of values, of @code{offset_type}
- unless otherwise noted:
- @enumerate
- @item
- The version number, currently 8. Versions 1, 2 and 3 are obsolete.
- Version 4 uses a different hashing function from versions 5 and 6.
- Version 6 includes symbols for inlined functions, whereas versions 4
- and 5 do not. Version 7 adds attributes to the CU indices in the
- symbol table. Version 8 specifies that symbols from DWARF type units
- (@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the
- compilation unit (@samp{DW_TAG_comp_unit}) using the type.
- @value{GDBN} will only read version 4, 5, or 6 indices
- by specifying @code{set use-deprecated-index-sections on}.
- GDB has a workaround for potentially broken version 7 indices so it is
- currently not flagged as deprecated.
- @item
- The offset, from the start of the file, of the CU list.
- @item
- The offset, from the start of the file, of the types CU list. Note
- that this area can be empty, in which case this offset will be equal
- to the next offset.
- @item
- The offset, from the start of the file, of the address area.
- @item
- The offset, from the start of the file, of the symbol table.
- @item
- The offset, from the start of the file, of the constant pool.
- @end enumerate
- @item
- The CU list. This is a sequence of pairs of 64-bit little-endian
- values, sorted by the CU offset. The first element in each pair is
- the offset of a CU in the @code{.debug_info} section. The second
- element in each pair is the length of that CU. References to a CU
- elsewhere in the map are done using a CU index, which is just the
- 0-based index into this table. Note that if there are type CUs, then
- conceptually CUs and type CUs form a single list for the purposes of
- CU indices.
- @item
- The types CU list. This is a sequence of triplets of 64-bit
- little-endian values. In a triplet, the first value is the CU offset,
- the second value is the type offset in the CU, and the third value is
- the type signature. The types CU list is not sorted.
- @item
- The address area. The address area consists of a sequence of address
- entries. Each address entry has three elements:
- @enumerate
- @item
- The low address. This is a 64-bit little-endian value.
- @item
- The high address. This is a 64-bit little-endian value. Like
- @code{DW_AT_high_pc}, the value is one byte beyond the end.
- @item
- The CU index. This is an @code{offset_type} value.
- @end enumerate
- @item
- The symbol table. This is an open-addressed hash table. The size of
- the hash table is always a power of 2.
- Each slot in the hash table consists of a pair of @code{offset_type}
- values. The first value is the offset of the symbol's name in the
- constant pool. The second value is the offset of the CU vector in the
- constant pool.
- If both values are 0, then this slot in the hash table is empty. This
- is ok because while 0 is a valid constant pool index, it cannot be a
- valid index for both a string and a CU vector.
- The hash value for a table entry is computed by applying an
- iterative hash function to the symbol's name. Starting with an
- initial value of @code{r = 0}, each (unsigned) character @samp{c} in
- the string is incorporated into the hash using the formula depending on the
- index version:
- @table @asis
- @item Version 4
- The formula is @code{r = r * 67 + c - 113}.
- @item Versions 5 to 7
- The formula is @code{r = r * 67 + tolower (c) - 113}.
- @end table
- The terminating @samp{\0} is not incorporated into the hash.
- The step size used in the hash table is computed via
- @code{((hash * 17) & (size - 1)) | 1}, where @samp{hash} is the hash
- value, and @samp{size} is the size of the hash table. The step size
- is used to find the next candidate slot when handling a hash
- collision.
- The names of C@t{++} symbols in the hash table are canonicalized. We
- don't currently have a simple description of the canonicalization
- algorithm; if you intend to create new index sections, you must read
- the code.
- @item
- The constant pool. This is simply a bunch of bytes. It is organized
- so that alignment is correct: CU vectors are stored first, followed by
- strings.
- A CU vector in the constant pool is a sequence of @code{offset_type}
- values. The first value is the number of CU indices in the vector.
- Each subsequent value is the index and symbol attributes of a CU in
- the CU list. This element in the hash table is used to indicate which
- CUs define the symbol and how the symbol is used.
- See below for the format of each CU index+attributes entry.
- A string in the constant pool is zero-terminated.
- @end enumerate
- Attributes were added to CU index values in @code{.gdb_index} version 7.
- If a symbol has multiple uses within a CU then there is one
- CU index+attributes value for each use.
- The format of each CU index+attributes entry is as follows
- (bit 0 = LSB):
- @table @asis
- @item Bits 0-23
- This is the index of the CU in the CU list.
- @item Bits 24-27
- These bits are reserved for future purposes and must be zero.
- @item Bits 28-30
- The kind of the symbol in the CU.
- @table @asis
- @item 0
- This value is reserved and should not be used.
- By reserving zero the full @code{offset_type} value is backwards compatible
- with previous versions of the index.
- @item 1
- The symbol is a type.
- @item 2
- The symbol is a variable or an enum value.
- @item 3
- The symbol is a function.
- @item 4
- Any other kind of symbol.
- @item 5,6,7
- These values are reserved.
- @end table
- @item Bit 31
- This bit is zero if the value is global and one if it is static.
- The determination of whether a symbol is global or static is complicated.
- The authorative reference is the file @file{dwarf2read.c} in
- @value{GDBN} sources.
- @end table
- This pseudo-code describes the computation of a symbol's kind and
- global/static attributes in the index.
- @smallexample
- is_external = get_attribute (die, DW_AT_external);
- language = get_attribute (cu_die, DW_AT_language);
- switch (die->tag)
- @{
- case DW_TAG_typedef:
- case DW_TAG_base_type:
- case DW_TAG_subrange_type:
- kind = TYPE;
- is_static = 1;
- break;
- case DW_TAG_enumerator:
- kind = VARIABLE;
- is_static = language != CPLUS;
- break;
- case DW_TAG_subprogram:
- kind = FUNCTION;
- is_static = ! (is_external || language == ADA);
- break;
- case DW_TAG_constant:
- kind = VARIABLE;
- is_static = ! is_external;
- break;
- case DW_TAG_variable:
- kind = VARIABLE;
- is_static = ! is_external;
- break;
- case DW_TAG_namespace:
- kind = TYPE;
- is_static = 0;
- break;
- case DW_TAG_class_type:
- case DW_TAG_interface_type:
- case DW_TAG_structure_type:
- case DW_TAG_union_type:
- case DW_TAG_enumeration_type:
- kind = TYPE;
- is_static = language != CPLUS;
- break;
- default:
- assert (0);
- @}
- @end smallexample
- @node Debuginfod
- @appendix Download debugging resources with Debuginfod
- @cindex debuginfod
- @code{debuginfod} is an HTTP server for distributing ELF, DWARF and source
- files.
- With the @code{debuginfod} client library, @file{libdebuginfod}, @value{GDBN}
- can query servers using the build IDs associated with missing debug info,
- executables and source files in order to download them on demand.
- For instructions on building @value{GDBN} with @file{libdebuginfod},
- @pxref{Configure Options,,--with-debuginfod}. @code{debuginfod} is packaged
- with @code{elfutils}, starting with version 0.178. See
- @uref{https://sourceware.org/elfutils/Debuginfod.html} for more information
- regarding @code{debuginfod}.
- @menu
- * Debuginfod Settings:: Configuring debuginfod with @value{GDBN}
- @end menu
- @node Debuginfod Settings
- @section Debuginfod Settings
- @value{GDBN} provides the following commands for configuring @code{debuginfod}.
- @table @code
- @kindex set debuginfod enabled
- @anchor{set debuginfod enabled}
- @item set debuginfod enabled
- @itemx set debuginfod enabled on
- @cindex enable debuginfod
- @value{GDBN} will attempt to query @code{debuginfod} servers when missing debug
- info or source files.
- @item set debuginfod enabled off
- @value{GDBN} will not attempt to query @code{debuginfod} servers when missing
- debug info or source files. By default, @code{debuginfod enabled} is set to
- @code{off} for non-interactive sessions.
- @item set debuginfod enabled ask
- @value{GDBN} will prompt the user to enable or disable @code{debuginfod} before
- attempting to perform the next query. By default, @code{debuginfod enabled}
- is set to @code{ask} for interactive sessions.
- @kindex show debuginfod enabled
- @item show debuginfod enabled
- Display whether @code{debuginfod enabled} is set to @code{on}, @code{off} or
- @code{ask}.
- @kindex set debuginfod urls
- @cindex configure debuginfod URLs
- @item set debuginfod urls
- @itemx set debuginfod urls @var{urls}
- Set the space-separated list of URLs that @code{debuginfod} will attempt to
- query. Only @code{http://}, @code{https://} and @code{file://} protocols
- should be used. The default value of @code{debuginfod urls} is copied from
- the @var{DEBUGINFOD_URLS} environment variable.
- @kindex show debuginfod urls
- @item show debuginfod urls
- Display the list of URLs that @code{debuginfod} will attempt to query.
- @kindex set debuginfod verbose
- @cindex debuginfod verbosity
- @item set debuginfod verbose
- @itemx set debuginfod verbose @var{n}
- Enable or disable @code{debuginfod}-related output. Use a non-zero value
- to enable and @code{0} to disable. @code{debuginfod} output is shown by
- default.
- @kindex show debuginfod verbose
- @item show debuginfod verbose
- Show the current verbosity setting.
- @end table
- @node Man Pages
- @appendix Manual pages
- @cindex Man pages
- @menu
- * gdb man:: The GNU Debugger man page
- * gdbserver man:: Remote Server for the GNU Debugger man page
- * gcore man:: Generate a core file of a running program
- * gdbinit man:: gdbinit scripts
- * gdb-add-index man:: Add index files to speed up GDB
- @end menu
- @node gdb man
- @heading gdb man
- @c man title gdb The GNU Debugger
- @c man begin SYNOPSIS gdb
- gdb [OPTIONS] [@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}]
- @c man end
- @c man begin DESCRIPTION gdb
- The purpose of a debugger such as @value{GDBN} is to allow you to see what is
- going on ``inside'' another program while it executes -- or what another
- program was doing at the moment it crashed.
- @value{GDBN} can do four main kinds of things (plus other things in support of
- these) to help you catch bugs in the act:
- @itemize @bullet
- @item
- Start your program, specifying anything that might affect its behavior.
- @item
- Make your program stop on specified conditions.
- @item
- Examine what has happened, when your program has stopped.
- @item
- Change things in your program, so you can experiment with correcting the
- effects of one bug and go on to learn about another.
- @end itemize
- You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and
- Modula-2.
- @value{GDBN} is invoked with the shell command @code{gdb}. Once started, it reads
- commands from the terminal until you tell it to exit with the @value{GDBN}
- command @code{quit} or @code{exit}. You can get online help from @value{GDBN} itself
- by using the command @code{help}.
- You can run @code{gdb} with no arguments or options; but the most
- usual way to start @value{GDBN} is with one argument or two, specifying an
- executable program as the argument:
- @smallexample
- gdb program
- @end smallexample
- You can also start with both an executable program and a core file specified:
- @smallexample
- gdb program core
- @end smallexample
- You can, instead, specify a process ID as a second argument or use option
- @code{-p}, if you want to debug a running process:
- @smallexample
- gdb program 1234
- gdb -p 1234
- @end smallexample
- @noindent
- would attach @value{GDBN} to process @code{1234}. With option @option{-p} you
- can omit the @var{program} filename.
- Here are some of the most frequently needed @value{GDBN} commands:
- @c pod2man highlights the right hand side of the @item lines.
- @table @env
- @item break [@var{file}:][@var{function}|@var{line}]
- Set a breakpoint at @var{function} or @var{line} (in @var{file}).
- @item run [@var{arglist}]
- Start your program (with @var{arglist}, if specified).
- @item bt
- Backtrace: display the program stack.
- @item print @var{expr}
- Display the value of an expression.
- @item c
- Continue running your program (after stopping, e.g.@: at a breakpoint).
- @item next
- Execute next program line (after stopping); step @emph{over} any
- function calls in the line.
- @item edit [@var{file}:]@var{function}
- look at the program line where it is presently stopped.
- @item list [@var{file}:]@var{function}
- type the text of the program in the vicinity of where it is presently stopped.
- @item step
- Execute next program line (after stopping); step @emph{into} any
- function calls in the line.
- @item help [@var{name}]
- Show information about @value{GDBN} command @var{name}, or general information
- about using @value{GDBN}.
- @item quit
- @itemx exit
- Exit from @value{GDBN}.
- @end table
- @ifset man
- For full details on @value{GDBN},
- see @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
- by Richard M. Stallman and Roland H. Pesch. The same text is available online
- as the @code{gdb} entry in the @code{info} program.
- @end ifset
- @c man end
- @c man begin OPTIONS gdb
- Any arguments other than options specify an executable
- file and core file (or process ID); that is, the first argument
- encountered with no
- associated option flag is equivalent to a @option{--se} option, and the second,
- if any, is equivalent to a @option{-c} option if it's the name of a file.
- Many options have
- both long and abbreviated forms; both are shown here. The long forms are also
- recognized if you truncate them, so long as enough of the option is
- present to be unambiguous.
- The abbreviated forms are shown here with @samp{-} and long forms are shown
- with @samp{--} to reflect how they are shown in @option{--help}. However,
- @value{GDBN} recognizes all of the following conventions for most options:
- @table @code
- @item --option=@var{value}
- @item --option @var{value}
- @item -option=@var{value}
- @item -option @var{value}
- @item --o=@var{value}
- @item --o @var{value}
- @item -o=@var{value}
- @item -o @var{value}
- @end table
- All the options and command line arguments you give are processed
- in sequential order. The order makes a difference when the @option{-x}
- option is used.
- @table @env
- @item --help
- @itemx -h
- List all options, with brief explanations.
- @item --symbols=@var{file}
- @itemx -s @var{file}
- Read symbol table from @var{file}.
- @item --write
- Enable writing into executable and core files.
- @item --exec=@var{file}
- @itemx -e @var{file}
- Use @var{file} as the executable file to execute when
- appropriate, and for examining pure data in conjunction with a core
- dump.
- @item --se=@var{file}
- Read symbol table from @var{file} and use it as the executable
- file.
- @item --core=@var{file}
- @itemx -c @var{file}
- Use @var{file} as a core dump to examine.
- @item --command=@var{file}
- @itemx -x @var{file}
- Execute @value{GDBN} commands from @var{file}.
- @item --eval-command=@var{command}
- @item -ex @var{command}
- Execute given @value{GDBN} @var{command}.
- @item --init-eval-command=@var{command}
- @item -iex
- Execute @value{GDBN} @var{command} before loading the inferior.
- @item --directory=@var{directory}
- @itemx -d @var{directory}
- Add @var{directory} to the path to search for source files.
- @item --nh
- Do not execute commands from @file{~/.config/gdb/gdbinit},
- @file{~/.gdbinit}, @file{~/.config/gdb/gdbearlyinit}, or
- @file{~/.gdbearlyinit}
- @item --nx
- @itemx -n
- Do not execute commands from any @file{.gdbinit} or
- @file{.gdbearlyinit} initialization files.
- @item --quiet
- @item --silent
- @itemx -q
- ``Quiet''. Do not print the introductory and copyright messages. These
- messages are also suppressed in batch mode.
- @item --batch
- Run in batch mode. Exit with status @code{0} after processing all the command
- files specified with @option{-x} (and @file{.gdbinit}, if not inhibited).
- Exit with nonzero status if an error occurs in executing the @value{GDBN}
- commands in the command files.
- Batch mode may be useful for running @value{GDBN} as a filter, for example to
- download and run a program on another computer; in order to make this
- more useful, the message
- @smallexample
- Program exited normally.
- @end smallexample
- @noindent
- (which is ordinarily issued whenever a program running under @value{GDBN} control
- terminates) is not issued when running in batch mode.
- @item --batch-silent
- Run in batch mode, just like @option{--batch}, but totally silent. All @value{GDBN}
- output is supressed (stderr is unaffected). This is much quieter than
- @option{--silent} and would be useless for an interactive session.
- This is particularly useful when using targets that give @samp{Loading section}
- messages, for example.
- Note that targets that give their output via @value{GDBN}, as opposed to writing
- directly to @code{stdout}, will also be made silent.
- @item --args @var{prog} [@var{arglist}]
- Change interpretation of command line so that arguments following this
- option are passed as arguments to the inferior. As an example, take
- the following command:
- @smallexample
- gdb ./a.out -q
- @end smallexample
- @noindent
- It would start @value{GDBN} with @option{-q}, not printing the introductory message. On
- the other hand, using:
- @smallexample
- gdb --args ./a.out -q
- @end smallexample
- @noindent
- starts @value{GDBN} with the introductory message, and passes the option to the inferior.
- @item --pid=@var{pid}
- Attach @value{GDBN} to an already running program, with the PID @var{pid}.
- @item --tui
- Open the terminal user interface.
- @item --readnow
- Read all symbols from the given symfile on the first access.
- @item --readnever
- Do not read symbol files.
- @item --return-child-result
- @value{GDBN}'s exit code will be the same as the child's exit code.
- @item --configuration
- Print details about GDB configuration and then exit.
- @item --version
- Print version information and then exit.
- @item --cd=@var{directory}
- Run @value{GDBN} using @var{directory} as its working directory,
- instead of the current directory.
- @item --data-directory=@var{directory}
- @item -D
- Run @value{GDBN} using @var{directory} as its data directory. The data
- directory is where @value{GDBN} searches for its auxiliary files.
- @item --fullname
- @itemx -f
- Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells
- @value{GDBN} to output the full file name and line number in a standard,
- recognizable fashion each time a stack frame is displayed (which
- includes each time the program stops). This recognizable format looks
- like two @samp{\032} characters, followed by the file name, line number
- and character position separated by colons, and a newline. The
- Emacs-to-@value{GDBN} interface program uses the two @samp{\032}
- characters as a signal to display the source code for the frame.
- @item -b @var{baudrate}
- Set the line speed (baud rate or bits per second) of any serial
- interface used by @value{GDBN} for remote debugging.
- @item -l @var{timeout}
- Set timeout, in seconds, for remote debugging.
- @item --tty=@var{device}
- Run using @var{device} for your program's standard input and output.
- @end table
- @c man end
- @c man begin SEEALSO gdb
- @ifset man
- The full documentation for @value{GDBN} is maintained as a Texinfo manual.
- If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
- documentation are properly installed at your site, the command
- @smallexample
- info gdb
- @end smallexample
- @noindent
- should give you access to the complete manual.
- @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
- Richard M. Stallman and Roland H. Pesch, July 1991.
- @end ifset
- @c man end
- @node gdbserver man
- @heading gdbserver man
- @c man title gdbserver Remote Server for the GNU Debugger
- @format
- @c man begin SYNOPSIS gdbserver
- gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
- gdbserver --attach @var{comm} @var{pid}
- gdbserver --multi @var{comm}
- @c man end
- @end format
- @c man begin DESCRIPTION gdbserver
- @command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine
- than the one which is running the program being debugged.
- @ifclear man
- @subheading Usage (server (target) side)
- @end ifclear
- @ifset man
- Usage (server (target) side):
- @end ifset
- First, you need to have a copy of the program you want to debug put onto
- the target system. The program can be stripped to save space if needed, as
- @command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by
- the @value{GDBN} running on the host system.
- To use the server, you log on to the target system, and run the @command{gdbserver}
- program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of
- your program, and (c) its arguments. The general syntax is:
- @smallexample
- target> gdbserver @var{comm} @var{program} [@var{args} ...]
- @end smallexample
- For example, using a serial port, you might say:
- @smallexample
- @ifset man
- @c @file would wrap it as F</dev/com1>.
- target> gdbserver /dev/com1 emacs foo.txt
- @end ifset
- @ifclear man
- target> gdbserver @file{/dev/com1} emacs foo.txt
- @end ifclear
- @end smallexample
- This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and
- to communicate with @value{GDBN} via @file{/dev/com1}. @command{gdbserver} now
- waits patiently for the host @value{GDBN} to communicate with it.
- To use a TCP connection, you could say:
- @smallexample
- target> gdbserver host:2345 emacs foo.txt
- @end smallexample
- This says pretty much the same thing as the last example, except that we are
- going to communicate with the @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means
- that we are expecting to see a TCP connection from @code{host} to local TCP port
- 2345. (Currently, the @code{host} part is ignored.) You can choose any number you
- want for the port number as long as it does not conflict with any existing TCP
- ports on the target system. This same port number must be used in the host
- @value{GDBN}s @code{target remote} command, which will be described shortly. Note that if
- you chose a port number that conflicts with another service, @command{gdbserver} will
- print an error message and exit.
- @command{gdbserver} can also attach to running programs.
- This is accomplished via the @option{--attach} argument. The syntax is:
- @smallexample
- target> gdbserver --attach @var{comm} @var{pid}
- @end smallexample
- @var{pid} is the process ID of a currently running process. It isn't
- necessary to point @command{gdbserver} at a binary for the running process.
- To start @code{gdbserver} without supplying an initial command to run
- or process ID to attach, use the @option{--multi} command line option.
- In such case you should connect using @kbd{target extended-remote} to start
- the program you want to debug.
- @smallexample
- target> gdbserver --multi @var{comm}
- @end smallexample
- @ifclear man
- @subheading Usage (host side)
- @end ifclear
- @ifset man
- Usage (host side):
- @end ifset
- You need an unstripped copy of the target program on your host system, since
- @value{GDBN} needs to examine its symbol tables and such. Start up @value{GDBN} as you normally
- would, with the target program as the first argument. (You may need to use the
- @option{--baud} option if the serial line is running at anything except 9600 baud.)
- That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only
- new command you need to know about is @code{target remote}
- (or @code{target extended-remote}). Its argument is either
- a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT}
- descriptor. For example:
- @smallexample
- @ifset man
- @c @file would wrap it as F</dev/ttyb>.
- (gdb) target remote /dev/ttyb
- @end ifset
- @ifclear man
- (gdb) target remote @file{/dev/ttyb}
- @end ifclear
- @end smallexample
- @noindent
- communicates with the server via serial line @file{/dev/ttyb}, and:
- @smallexample
- (gdb) target remote the-target:2345
- @end smallexample
- @noindent
- communicates via a TCP connection to port 2345 on host `the-target', where
- you previously started up @command{gdbserver} with the same port number. Note that for
- TCP connections, you must start up @command{gdbserver} prior to using the `target remote'
- command, otherwise you may get an error that looks something like
- `Connection refused'.
- @command{gdbserver} can also debug multiple inferiors at once,
- described in
- @ifset man
- the @value{GDBN} manual in node @code{Inferiors Connections and Programs}
- -- shell command @code{info -f gdb -n 'Inferiors Connections and Programs'}.
- @end ifset
- @ifclear man
- @ref{Inferiors Connections and Programs}.
- @end ifclear
- In such case use the @code{extended-remote} @value{GDBN} command variant:
- @smallexample
- (gdb) target extended-remote the-target:2345
- @end smallexample
- The @command{gdbserver} option @option{--multi} may or may not be used in such
- case.
- @c man end
- @c man begin OPTIONS gdbserver
- There are three different modes for invoking @command{gdbserver}:
- @itemize @bullet
- @item
- Debug a specific program specified by its program name:
- @smallexample
- gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
- @end smallexample
- The @var{comm} parameter specifies how should the server communicate
- with @value{GDBN}; it is either a device name (to use a serial line),
- a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use
- stdin/stdout of @code{gdbserver}. Specify the name of the program to
- debug in @var{prog}. Any remaining arguments will be passed to the
- program verbatim. When the program exits, @value{GDBN} will close the
- connection, and @code{gdbserver} will exit.
- @item
- Debug a specific program by specifying the process ID of a running
- program:
- @smallexample
- gdbserver --attach @var{comm} @var{pid}
- @end smallexample
- The @var{comm} parameter is as described above. Supply the process ID
- of a running program in @var{pid}; @value{GDBN} will do everything
- else. Like with the previous mode, when the process @var{pid} exits,
- @value{GDBN} will close the connection, and @code{gdbserver} will exit.
- @item
- Multi-process mode -- debug more than one program/process:
- @smallexample
- gdbserver --multi @var{comm}
- @end smallexample
- In this mode, @value{GDBN} can instruct @command{gdbserver} which
- command(s) to run. Unlike the other 2 modes, @value{GDBN} will not
- close the connection when a process being debugged exits, so you can
- debug several processes in the same session.
- @end itemize
- In each of the modes you may specify these options:
- @table @env
- @item --help
- List all options, with brief explanations.
- @item --version
- This option causes @command{gdbserver} to print its version number and exit.
- @item --attach
- @command{gdbserver} will attach to a running program. The syntax is:
- @smallexample
- target> gdbserver --attach @var{comm} @var{pid}
- @end smallexample
- @var{pid} is the process ID of a currently running process. It isn't
- necessary to point @command{gdbserver} at a binary for the running process.
- @item --multi
- To start @code{gdbserver} without supplying an initial command to run
- or process ID to attach, use this command line option.
- Then you can connect using @kbd{target extended-remote} and start
- the program you want to debug. The syntax is:
- @smallexample
- target> gdbserver --multi @var{comm}
- @end smallexample
- @item --debug
- Instruct @code{gdbserver} to display extra status information about the debugging
- process.
- This option is intended for @code{gdbserver} development and for bug reports to
- the developers.
- @item --remote-debug
- Instruct @code{gdbserver} to display remote protocol debug output.
- This option is intended for @code{gdbserver} development and for bug reports to
- the developers.
- @item --debug-file=@var{filename}
- Instruct @code{gdbserver} to send any debug output to the given @var{filename}.
- This option is intended for @code{gdbserver} development and for bug reports to
- the developers.
- @item --debug-format=option1@r{[},option2,...@r{]}
- Instruct @code{gdbserver} to include extra information in each line
- of debugging output.
- @xref{Other Command-Line Arguments for gdbserver}.
- @item --wrapper
- Specify a wrapper to launch programs
- for debugging. The option should be followed by the name of the
- wrapper, then any command-line arguments to pass to the wrapper, then
- @kbd{--} indicating the end of the wrapper arguments.
- @item --once
- By default, @command{gdbserver} keeps the listening TCP port open, so that
- additional connections are possible. However, if you start @code{gdbserver}
- with the @option{--once} option, it will stop listening for any further
- connection attempts after connecting to the first @value{GDBN} session.
- @c --disable-packet is not documented for users.
- @c --disable-randomization and --no-disable-randomization are superseded by
- @c QDisableRandomization.
- @end table
- @c man end
- @c man begin SEEALSO gdbserver
- @ifset man
- The full documentation for @value{GDBN} is maintained as a Texinfo manual.
- If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
- documentation are properly installed at your site, the command
- @smallexample
- info gdb
- @end smallexample
- should give you access to the complete manual.
- @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
- Richard M. Stallman and Roland H. Pesch, July 1991.
- @end ifset
- @c man end
- @node gcore man
- @heading gcore
- @c man title gcore Generate a core file of a running program
- @format
- @c man begin SYNOPSIS gcore
- gcore [-a] [-o @var{prefix}] @var{pid1} [@var{pid2}...@var{pidN}]
- @c man end
- @end format
- @c man begin DESCRIPTION gcore
- Generate core dumps of one or more running programs with process IDs
- @var{pid1}, @var{pid2}, etc. A core file produced by @command{gcore}
- is equivalent to one produced by the kernel when the process crashes
- (and when @kbd{ulimit -c} was used to set up an appropriate core dump
- limit). However, unlike after a crash, after @command{gcore} finishes
- its job the program remains running without any change.
- @c man end
- @c man begin OPTIONS gcore
- @table @env
- @item -a
- Dump all memory mappings. The actual effect of this option depends on
- the Operating System. On @sc{gnu}/Linux, it will disable
- @code{use-coredump-filter} (@pxref{set use-coredump-filter}) and
- enable @code{dump-excluded-mappings} (@pxref{set
- dump-excluded-mappings}).
- @item -o @var{prefix}
- The optional argument @var{prefix} specifies the prefix to be used
- when composing the file names of the core dumps. The file name is
- composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the
- process ID of the running program being analyzed by @command{gcore}.
- If not specified, @var{prefix} defaults to @var{gcore}.
- @end table
- @c man end
- @c man begin SEEALSO gcore
- @ifset man
- The full documentation for @value{GDBN} is maintained as a Texinfo manual.
- If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
- documentation are properly installed at your site, the command
- @smallexample
- info gdb
- @end smallexample
- @noindent
- should give you access to the complete manual.
- @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
- Richard M. Stallman and Roland H. Pesch, July 1991.
- @end ifset
- @c man end
- @node gdbinit man
- @heading gdbinit
- @c man title gdbinit GDB initialization scripts
- @format
- @c man begin SYNOPSIS gdbinit
- @ifset SYSTEM_GDBINIT
- @value{SYSTEM_GDBINIT}
- @end ifset
- @ifset SYSTEM_GDBINIT_DIR
- @value{SYSTEM_GDBINIT_DIR}/*
- @end ifset
- ~/.config/gdb/gdbinit
- ~/.gdbinit
- ./.gdbinit
- @c man end
- @end format
- @c man begin DESCRIPTION gdbinit
- These files contain @value{GDBN} commands to automatically execute during
- @value{GDBN} startup. The lines of contents are canned sequences of commands,
- described in
- @ifset man
- the @value{GDBN} manual in node @code{Sequences}
- -- shell command @code{info -f gdb -n Sequences}.
- @end ifset
- @ifclear man
- @ref{Sequences}.
- @end ifclear
- Please read more in
- @ifset man
- the @value{GDBN} manual in node @code{Startup}
- -- shell command @code{info -f gdb -n Startup}.
- @end ifset
- @ifclear man
- @ref{Startup}.
- @end ifclear
- @table @env
- @ifset SYSTEM_GDBINIT
- @item @value{SYSTEM_GDBINIT}
- @end ifset
- @ifclear SYSTEM_GDBINIT
- @item (not enabled with @code{--with-system-gdbinit} during compilation)
- @end ifclear
- System-wide initialization file. It is executed unless user specified
- @value{GDBN} option @code{-nx} or @code{-n}.
- See more in
- @ifset man
- the @value{GDBN} manual in node @code{System-wide configuration}
- -- shell command @code{info -f gdb -n 'System-wide configuration'}.
- @end ifset
- @ifset SYSTEM_GDBINIT_DIR
- @item @value{SYSTEM_GDBINIT_DIR}
- @end ifset
- @ifclear SYSTEM_GDBINIT_DIR
- @item (not enabled with @code{--with-system-gdbinit-dir} during compilation)
- @end ifclear
- System-wide initialization directory. All files in this directory are
- executed on startup unless user specified @value{GDBN} option @code{-nx} or
- @code{-n}, as long as they have a recognized file extension.
- See more in
- @ifset man
- the @value{GDBN} manual in node @code{System-wide configuration}
- -- shell command @code{info -f gdb -n 'System-wide configuration'}.
- @end ifset
- @ifclear man
- @ref{System-wide configuration}.
- @end ifclear
- @item @file{~/.config/gdb/gdbinit} or @file{~/.gdbinit}
- User initialization file. It is executed unless user specified
- @value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}.
- @item @file{.gdbinit}
- Initialization file for current directory. It may need to be enabled with
- @value{GDBN} security command @code{set auto-load local-gdbinit}.
- See more in
- @ifset man
- the @value{GDBN} manual in node @code{Init File in the Current Directory}
- -- shell command @code{info -f gdb -n 'Init File in the Current Directory'}.
- @end ifset
- @ifclear man
- @ref{Init File in the Current Directory}.
- @end ifclear
- @end table
- @c man end
- @c man begin SEEALSO gdbinit
- @ifset man
- gdb(1), @code{info -f gdb -n Startup}
- The full documentation for @value{GDBN} is maintained as a Texinfo manual.
- If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
- documentation are properly installed at your site, the command
- @smallexample
- info gdb
- @end smallexample
- should give you access to the complete manual.
- @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
- Richard M. Stallman and Roland H. Pesch, July 1991.
- @end ifset
- @c man end
- @node gdb-add-index man
- @heading gdb-add-index
- @pindex gdb-add-index
- @anchor{gdb-add-index}
- @c man title gdb-add-index Add index files to speed up GDB
- @c man begin SYNOPSIS gdb-add-index
- gdb-add-index @var{filename}
- @c man end
- @c man begin DESCRIPTION gdb-add-index
- When @value{GDBN} finds a symbol file, it scans the symbols in the
- file in order to construct an internal symbol table. This lets most
- @value{GDBN} operations work quickly--at the cost of a delay early on.
- For large programs, this delay can be quite lengthy, so @value{GDBN}
- provides a way to build an index, which speeds up startup.
- To determine whether a file contains such an index, use the command
- @kbd{readelf -S filename}: the index is stored in a section named
- @code{.gdb_index}. The index file can only be produced on systems
- which use ELF binaries and DWARF debug information (i.e., sections
- named @code{.debug_*}).
- @command{gdb-add-index} uses @value{GDBN} and @command{objdump} found
- in the @env{PATH} environment variable. If you want to use different
- versions of these programs, you can specify them through the
- @env{GDB} and @env{OBJDUMP} environment variables.
- See more in
- @ifset man
- the @value{GDBN} manual in node @code{Index Files}
- -- shell command @kbd{info -f gdb -n "Index Files"}.
- @end ifset
- @ifclear man
- @ref{Index Files}.
- @end ifclear
- @c man end
- @c man begin SEEALSO gdb-add-index
- @ifset man
- The full documentation for @value{GDBN} is maintained as a Texinfo manual.
- If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
- documentation are properly installed at your site, the command
- @smallexample
- info gdb
- @end smallexample
- should give you access to the complete manual.
- @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
- Richard M. Stallman and Roland H. Pesch, July 1991.
- @end ifset
- @c man end
- @include gpl.texi
- @node GNU Free Documentation License
- @appendix GNU Free Documentation License
- @include fdl.texi
- @node Concept Index
- @unnumbered Concept Index
- @printindex cp
- @node Command and Variable Index
- @unnumbered Command, Variable, and Function Index
- @printindex fn
- @tex
- % I think something like @@colophon should be in texinfo. In the
- % meantime:
- \long\def\colophon{\hbox to0pt{}\vfill
- \centerline{The body of this manual is set in}
- \centerline{\fontname\tenrm,}
- \centerline{with headings in {\bf\fontname\tenbf}}
- \centerline{and examples in {\tt\fontname\tentt}.}
- \centerline{{\it\fontname\tenit\/},}
- \centerline{{\bf\fontname\tenbf}, and}
- \centerline{{\sl\fontname\tensl\/}}
- \centerline{are used for emphasis.}\vfill}
- \page\colophon
- % Blame: doc@@cygnus.com, 1991.
- @end tex
- @bye
|