| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916 |
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html>
- <!-- This file documents the GNU linker LD
- (Arm GNU Toolchain 13.3.Rel1 (Build arm-13.24))
- version 2.42.0.
- Copyright (C) 1991-2024 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 no Invariant Sections, with no Front-Cover Texts, and with no
- Back-Cover Texts. A copy of the license is included in the
- section entitled "GNU Free Documentation License". -->
- <!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>LD</title>
- <meta name="description" content="LD">
- <meta name="keywords" content="LD">
- <meta name="resource-type" content="document">
- <meta name="distribution" content="global">
- <meta name="Generator" content="makeinfo">
- <link href="#Top" rel="start" title="Top">
- <link href="#LD-Index" rel="index" title="LD Index">
- <link href="#SEC_Contents" rel="contents" title="Table of Contents">
- <style type="text/css">
- <!--
- a.summary-letter {text-decoration: none}
- blockquote.indentedblock {margin-right: 0em}
- div.display {margin-left: 3.2em}
- div.example {margin-left: 3.2em}
- div.lisp {margin-left: 3.2em}
- kbd {font-style: oblique}
- pre.display {font-family: inherit}
- pre.format {font-family: inherit}
- pre.menu-comment {font-family: serif}
- pre.menu-preformatted {font-family: serif}
- span.nolinebreak {white-space: nowrap}
- span.roman {font-family: initial; font-weight: normal}
- span.sansserif {font-family: sans-serif; font-weight: normal}
- ul.no-bullet {list-style: none}
- -->
- </style>
- </head>
- <body lang="en">
- <span id="SEC_Contents"></span>
- <h2 class="contents-heading">Table of Contents</h2>
- <div class="contents">
- <ul class="no-bullet">
- <li><a id="toc-Overview-1" href="#Overview">1 Overview</a></li>
- <li><a id="toc-Invocation-1" href="#Invocation">2 Invocation</a>
- <ul class="no-bullet">
- <li><a id="toc-Command_002dline-Options" href="#Options">2.1 Command-line Options</a>
- <ul class="no-bullet">
- <li><a id="toc-Options-Specific-to-i386-PE-Targets" href="#Options-Specific-to-i386-PE-Targets">2.1.1 Options Specific to i386 PE Targets</a></li>
- <li><a id="toc-Options-specific-to-C6X-uClinux-targets" href="#Options-specific-to-C6X-uClinux-targets">2.1.2 Options specific to C6X uClinux targets</a></li>
- <li><a id="toc-Options-specific-to-C_002dSKY-targets" href="#Options-specific-to-C_002dSKY-targets">2.1.3 Options specific to C-SKY targets</a></li>
- <li><a id="toc-Options-specific-to-Motorola-68HC11-and-68HC12-targets" href="#Options-specific-to-Motorola-68HC11-and-68HC12-targets">2.1.4 Options specific to Motorola 68HC11 and 68HC12 targets</a></li>
- <li><a id="toc-Options-specific-to-Motorola-68K-target" href="#Options-specific-to-Motorola-68K-target">2.1.5 Options specific to Motorola 68K target</a></li>
- <li><a id="toc-Options-specific-to-MIPS-targets" href="#Options-specific-to-MIPS-targets">2.1.6 Options specific to MIPS targets</a></li>
- <li><a id="toc-Options-specific-to-PDP11-targets" href="#Options-specific-to-PDP11-targets">2.1.7 Options specific to PDP11 targets</a></li>
- </ul></li>
- <li><a id="toc-Environment-Variables" href="#Environment">2.2 Environment Variables</a></li>
- </ul></li>
- <li><a id="toc-Linker-Scripts" href="#Scripts">3 Linker Scripts</a>
- <ul class="no-bullet">
- <li><a id="toc-Basic-Linker-Script-Concepts" href="#Basic-Script-Concepts">3.1 Basic Linker Script Concepts</a></li>
- <li><a id="toc-Linker-Script-Format" href="#Script-Format">3.2 Linker Script Format</a></li>
- <li><a id="toc-Simple-Linker-Script-Example" href="#Simple-Example">3.3 Simple Linker Script Example</a></li>
- <li><a id="toc-Simple-Linker-Script-Commands" href="#Simple-Commands">3.4 Simple Linker Script Commands</a>
- <ul class="no-bullet">
- <li><a id="toc-Setting-the-Entry-Point" href="#Entry-Point">3.4.1 Setting the Entry Point</a></li>
- <li><a id="toc-Commands-Dealing-with-Files" href="#File-Commands">3.4.2 Commands Dealing with Files</a></li>
- <li><a id="toc-Commands-Dealing-with-Object-File-Formats" href="#Format-Commands">3.4.3 Commands Dealing with Object File Formats</a></li>
- <li><a id="toc-Assign-alias-names-to-memory-regions" href="#REGION_005fALIAS">3.4.4 Assign alias names to memory regions</a></li>
- <li><a id="toc-Other-Linker-Script-Commands" href="#Miscellaneous-Commands">3.4.5 Other Linker Script Commands</a></li>
- </ul></li>
- <li><a id="toc-Assigning-Values-to-Symbols" href="#Assignments">3.5 Assigning Values to Symbols</a>
- <ul class="no-bullet">
- <li><a id="toc-Simple-Assignments-1" href="#Simple-Assignments">3.5.1 Simple Assignments</a></li>
- <li><a id="toc-HIDDEN-1" href="#HIDDEN">3.5.2 HIDDEN</a></li>
- <li><a id="toc-PROVIDE-1" href="#PROVIDE">3.5.3 PROVIDE</a></li>
- <li><a id="toc-PROVIDE_005fHIDDEN-1" href="#PROVIDE_005fHIDDEN">3.5.4 PROVIDE_HIDDEN</a></li>
- <li><a id="toc-Source-Code-Reference-1" href="#Source-Code-Reference">3.5.5 Source Code Reference</a></li>
- </ul></li>
- <li><a id="toc-SECTIONS-Command" href="#SECTIONS">3.6 SECTIONS Command</a>
- <ul class="no-bullet">
- <li><a id="toc-Output-Section-Description-1" href="#Output-Section-Description">3.6.1 Output Section Description</a></li>
- <li><a id="toc-Output-Section-Name-1" href="#Output-Section-Name">3.6.2 Output Section Name</a></li>
- <li><a id="toc-Output-Section-Address-1" href="#Output-Section-Address">3.6.3 Output Section Address</a></li>
- <li><a id="toc-Input-Section-Description" href="#Input-Section">3.6.4 Input Section Description</a>
- <ul class="no-bullet">
- <li><a id="toc-Input-Section-Basics-1" href="#Input-Section-Basics">3.6.4.1 Input Section Basics</a></li>
- <li><a id="toc-Input-Section-Wildcard-Patterns" href="#Input-Section-Wildcards">3.6.4.2 Input Section Wildcard Patterns</a></li>
- <li><a id="toc-Input-Section-for-Common-Symbols" href="#Input-Section-Common">3.6.4.3 Input Section for Common Symbols</a></li>
- <li><a id="toc-Input-Section-and-Garbage-Collection" href="#Input-Section-Keep">3.6.4.4 Input Section and Garbage Collection</a></li>
- <li><a id="toc-Input-Section-Example-1" href="#Input-Section-Example">3.6.4.5 Input Section Example</a></li>
- </ul></li>
- <li><a id="toc-Output-Section-Data-1" href="#Output-Section-Data">3.6.5 Output Section Data</a></li>
- <li><a id="toc-Output-Section-Keywords-1" href="#Output-Section-Keywords">3.6.6 Output Section Keywords</a></li>
- <li><a id="toc-Output-Section-Discarding-1" href="#Output-Section-Discarding">3.6.7 Output Section Discarding</a></li>
- <li><a id="toc-Output-Section-Attributes-1" href="#Output-Section-Attributes">3.6.8 Output Section Attributes</a>
- <ul class="no-bullet">
- <li><a id="toc-Output-Section-Type-1" href="#Output-Section-Type">3.6.8.1 Output Section Type</a></li>
- <li><a id="toc-Output-Section-LMA-1" href="#Output-Section-LMA">3.6.8.2 Output Section LMA</a></li>
- <li><a id="toc-Forced-Output-Alignment-1" href="#Forced-Output-Alignment">3.6.8.3 Forced Output Alignment</a></li>
- <li><a id="toc-Forced-Input-Alignment-1" href="#Forced-Input-Alignment">3.6.8.4 Forced Input Alignment</a></li>
- <li><a id="toc-Output-Section-Constraint-1" href="#Output-Section-Constraint">3.6.8.5 Output Section Constraint</a></li>
- <li><a id="toc-Output-Section-Region-1" href="#Output-Section-Region">3.6.8.6 Output Section Region</a></li>
- <li><a id="toc-Output-Section-Phdr-1" href="#Output-Section-Phdr">3.6.8.7 Output Section Phdr</a></li>
- <li><a id="toc-Output-Section-Fill-1" href="#Output-Section-Fill">3.6.8.8 Output Section Fill</a></li>
- </ul></li>
- <li><a id="toc-Overlay-Description-1" href="#Overlay-Description">3.6.9 Overlay Description</a></li>
- </ul></li>
- <li><a id="toc-MEMORY-Command" href="#MEMORY">3.7 MEMORY Command</a></li>
- <li><a id="toc-PHDRS-Command" href="#PHDRS">3.8 PHDRS Command</a></li>
- <li><a id="toc-VERSION-Command" href="#VERSION">3.9 VERSION Command</a></li>
- <li><a id="toc-Expressions-in-Linker-Scripts" href="#Expressions">3.10 Expressions in Linker Scripts</a>
- <ul class="no-bullet">
- <li><a id="toc-Constants-1" href="#Constants">3.10.1 Constants</a></li>
- <li><a id="toc-Symbolic-Constants-1" href="#Symbolic-Constants">3.10.2 Symbolic Constants</a></li>
- <li><a id="toc-Symbol-Names" href="#Symbols">3.10.3 Symbol Names</a></li>
- <li><a id="toc-Orphan-Sections-1" href="#Orphan-Sections">3.10.4 Orphan Sections</a></li>
- <li><a id="toc-The-Location-Counter" href="#Location-Counter">3.10.5 The Location Counter</a></li>
- <li><a id="toc-Operators-1" href="#Operators">3.10.6 Operators</a></li>
- <li><a id="toc-Evaluation-1" href="#Evaluation">3.10.7 Evaluation</a></li>
- <li><a id="toc-The-Section-of-an-Expression" href="#Expression-Section">3.10.8 The Section of an Expression</a></li>
- <li><a id="toc-Builtin-Functions-1" href="#Builtin-Functions">3.10.9 Builtin Functions</a></li>
- </ul></li>
- <li><a id="toc-Implicit-Linker-Scripts-1" href="#Implicit-Linker-Scripts">3.11 Implicit Linker Scripts</a></li>
- </ul></li>
- <li><a id="toc-Linker-Plugins" href="#Plugins">4 Linker Plugins</a>
- <ul class="no-bullet">
- <li><a id="toc-Static-Library-Dependencies-Plugin" href="#libdep-Plugin">4.1 Static Library Dependencies Plugin</a></li>
- </ul></li>
- <li><a id="toc-Special-Sections-1" href="#Special-Sections">5 Special Sections</a></li>
- <li><a id="toc-Machine-Dependent-Features" href="#Machine-Dependent">6 Machine Dependent Features</a>
- <ul class="no-bullet">
- <li><a id="toc-ld-and-the-H8_002f300" href="#H8_002f300">6.1 <code>ld</code> and the H8/300</a></li>
- <li><a id="toc-ld-and-the-Motorola-68HC11-and-68HC12-families" href="#M68HC11_002f68HC12">6.2 <code>ld</code> and the Motorola 68HC11 and 68HC12 families</a>
- <ul class="no-bullet">
- <li><a id="toc-Linker-Relaxation" href="#Linker-Relaxation">6.2.1 Linker Relaxation</a></li>
- <li><a id="toc-Trampoline-Generation" href="#Trampoline-Generation">6.2.2 Trampoline Generation</a></li>
- </ul></li>
- <li><a id="toc-ld-and-the-ARM-family" href="#ARM">6.3 <code>ld</code> and the ARM family</a></li>
- <li><a id="toc-ld-and-HPPA-32_002dbit-ELF-Support" href="#HPPA-ELF32">6.4 <code>ld</code> and HPPA 32-bit ELF Support</a></li>
- <li><a id="toc-ld-and-the-Motorola-68K-family" href="#M68K">6.5 <code>ld</code> and the Motorola 68K family</a></li>
- <li><a id="toc-ld-and-the-MIPS-family" href="#MIPS">6.6 <code>ld</code> and the MIPS family</a></li>
- <li><a id="toc-ld-and-MMIX" href="#MMIX">6.7 <code>ld</code> and MMIX</a></li>
- <li><a id="toc-ld-and-MSP430" href="#MSP430">6.8 <code>ld</code> and MSP430</a></li>
- <li><a id="toc-ld-and-NDS32" href="#NDS32">6.9 <code>ld</code> and NDS32</a></li>
- <li><a id="toc-ld-and-the-Altera-Nios-II" href="#Nios-II">6.10 <code>ld</code> and the Altera Nios II</a></li>
- <li><a id="toc-ld-and-PowerPC-32_002dbit-ELF-Support" href="#PowerPC-ELF32">6.11 <code>ld</code> and PowerPC 32-bit ELF Support</a></li>
- <li><a id="toc-ld-and-PowerPC64-64_002dbit-ELF-Support" href="#PowerPC64-ELF64">6.12 <code>ld</code> and PowerPC64 64-bit ELF Support</a></li>
- <li><a id="toc-ld-and-S_002f390-ELF-Support" href="#S_002f390-ELF">6.13 <code>ld</code> and S/390 ELF Support</a></li>
- <li><a id="toc-ld-and-SPU-ELF-Support" href="#SPU-ELF">6.14 <code>ld</code> and SPU ELF Support</a></li>
- <li><a id="toc-ld_0027s-Support-for-Various-TI-COFF-Versions" href="#TI-COFF">6.15 <code>ld</code>’s Support for Various TI COFF Versions</a></li>
- <li><a id="toc-ld-and-WIN32-_0028cygwin_002fmingw_0029" href="#WIN32">6.16 <code>ld</code> and WIN32 (cygwin/mingw)</a></li>
- <li><a id="toc-ld-and-Xtensa-Processors" href="#Xtensa">6.17 <code>ld</code> and Xtensa Processors</a></li>
- </ul></li>
- <li><a id="toc-BFD-1" href="#BFD">7 BFD</a>
- <ul class="no-bullet">
- <li><a id="toc-How-It-Works_003a-An-Outline-of-BFD" href="#BFD-outline">7.1 How It Works: An Outline of BFD</a>
- <ul class="no-bullet">
- <li><a id="toc-Information-Loss" href="#BFD-information-loss">7.1.1 Information Loss</a></li>
- <li><a id="toc-The-BFD-canonical-object_002dfile-format" href="#Canonical-format">7.1.2 The BFD canonical object-file format</a></li>
- </ul></li>
- </ul></li>
- <li><a id="toc-Reporting-Bugs-1" href="#Reporting-Bugs">8 Reporting Bugs</a>
- <ul class="no-bullet">
- <li><a id="toc-Have-You-Found-a-Bug_003f" href="#Bug-Criteria">8.1 Have You Found a Bug?</a></li>
- <li><a id="toc-How-to-Report-Bugs" href="#Bug-Reporting">8.2 How to Report Bugs</a></li>
- </ul></li>
- <li><a id="toc-MRI-Compatible-Script-Files" href="#MRI">Appendix A MRI Compatible Script Files</a></li>
- <li><a id="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix B GNU Free Documentation License</a></li>
- <li><a id="toc-LD-Index-1" href="#LD-Index" rel="index">LD Index</a></li>
- </ul>
- </div>
- <span id="Top"></span><div class="header">
- <p>
- Next: <a href="#Overview" accesskey="n" rel="next">Overview</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="LD"></span><h1 class="top">LD</h1>
- <p>This file documents the <small>GNU</small> linker ld
- (Arm GNU Toolchain 13.3.Rel1 (Build arm-13.24))
- version 2.42.0.
- </p>
- <p>This document is distributed under the terms of the GNU Free
- Documentation License version 1.3. A copy of the license is included
- in the section entitled “GNU Free Documentation License”.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Overview" accesskey="1">Overview</a></td><td> </td><td align="left" valign="top">Overview
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Invocation" accesskey="2">Invocation</a></td><td> </td><td align="left" valign="top">Invocation
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Scripts" accesskey="3">Scripts</a></td><td> </td><td align="left" valign="top">Linker Scripts
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Plugins" accesskey="4">Plugins</a></td><td> </td><td align="left" valign="top">Linker Plugins
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Special-Sections" accesskey="5">Special Sections</a></td><td> </td><td align="left" valign="top">Special Sections
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Machine-Dependent" accesskey="6">Machine Dependent</a></td><td> </td><td align="left" valign="top">Machine Dependent Features
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#BFD" accesskey="7">BFD</a></td><td> </td><td align="left" valign="top">BFD
- </td></tr>
- <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
- </pre></th></tr><tr><td align="left" valign="top">• <a href="#Reporting-Bugs" accesskey="8">Reporting Bugs</a></td><td> </td><td align="left" valign="top">Reporting Bugs
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#MRI" accesskey="9">MRI</a></td><td> </td><td align="left" valign="top">MRI Compatible Script Files
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></td><td> </td><td align="left" valign="top">GNU Free Documentation License
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#LD-Index" rel="index">LD Index</a></td><td> </td><td align="left" valign="top">LD Index
- </td></tr>
- </table>
- <hr>
- <span id="Overview"></span><div class="header">
- <p>
- Next: <a href="#Invocation" accesskey="n" rel="next">Invocation</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Overview-1"></span><h2 class="chapter">1 Overview</h2>
- <span id="index-GNU-linker"></span>
- <span id="index-what-is-this_003f"></span>
- <p><code>ld</code> combines a number of object and archive files, relocates
- their data and ties up symbol references. Usually the last step in
- compiling a program is to run <code>ld</code>.
- </p>
- <p><code>ld</code> accepts Linker Command Language files written in
- a superset of AT&T’s Link Editor Command Language syntax,
- to provide explicit and total control over the linking process.
- </p>
- <p>This version of <code>ld</code> uses the general purpose BFD libraries
- to operate on object files. This allows <code>ld</code> to read, combine, and
- write object files in many different formats—for example, COFF or
- <code>a.out</code>. Different formats may be linked together to produce any
- available kind of object file. See <a href="#BFD">BFD</a>, for more information.
- </p>
- <p>Aside from its flexibility, the <small>GNU</small> linker is more helpful than other
- linkers in providing diagnostic information. Many linkers abandon
- execution immediately upon encountering an error; whenever possible,
- <code>ld</code> continues executing, allowing you to identify other errors
- (or, in some cases, to get an output file in spite of the error).
- </p>
- <hr>
- <span id="Invocation"></span><div class="header">
- <p>
- Next: <a href="#Scripts" accesskey="n" rel="next">Scripts</a>, Previous: <a href="#Overview" accesskey="p" rel="prev">Overview</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Invocation-1"></span><h2 class="chapter">2 Invocation</h2>
- <p>The <small>GNU</small> linker <code>ld</code> is meant to cover a broad range of situations,
- and to be as compatible as possible with other linkers. As a result,
- you have many choices to control its behavior.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Options" accesskey="1">Options</a></td><td> </td><td align="left" valign="top">Command-line Options
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Environment" accesskey="2">Environment</a></td><td> </td><td align="left" valign="top">Environment Variables
- </td></tr>
- </table>
- <hr>
- <span id="Options"></span><div class="header">
- <p>
- Next: <a href="#Environment" accesskey="n" rel="next">Environment</a>, Up: <a href="#Invocation" accesskey="u" rel="up">Invocation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Command_002dline-Options"></span><h3 class="section">2.1 Command-line Options</h3>
- <span id="index-command-line"></span>
- <span id="index-options"></span>
- <p>The linker supports a plethora of command-line options, but in actual
- practice few of them are used in any particular context.
- <span id="index-standard-Unix-system"></span>
- For instance, a frequent use of <code>ld</code> is to link standard Unix
- object files on a standard, supported Unix system. On such a system, to
- link a file <code>hello.o</code>:
- </p>
- <div class="example">
- <pre class="example">ld -o <var>output</var> /lib/crt0.o hello.o -lc
- </pre></div>
- <p>This tells <code>ld</code> to produce a file called <var>output</var> as the
- result of linking the file <code>/lib/crt0.o</code> with <code>hello.o</code> and
- the library <code>libc.a</code>, which will come from the standard search
- directories. (See the discussion of the ‘<samp>-l</samp>’ option below.)
- </p>
- <p>Some of the command-line options to <code>ld</code> may be specified at any
- point in the command line. However, options which refer to files, such
- as ‘<samp>-l</samp>’ or ‘<samp>-T</samp>’, cause the file to be read at the point at
- which the option appears in the command line, relative to the object
- files and other file options. Repeating non-file options with a
- different argument will either have no further effect, or override prior
- occurrences (those further to the left on the command line) of that
- option. Options which may be meaningfully specified more than once are
- noted in the descriptions below.
- </p>
- <span id="index-object-files"></span>
- <p>Non-option arguments are object files or archives which are to be linked
- together. They may follow, precede, or be mixed in with command-line
- options, except that an object file argument may not be placed between
- an option and its argument.
- </p>
- <p>Usually the linker is invoked with at least one object file, but you can
- specify other forms of binary input files using ‘<samp>-l</samp>’, ‘<samp>-R</samp>’,
- and the script command language. If <em>no</em> binary input files at all
- are specified, the linker does not produce any output, and issues the
- message ‘<samp>No input files</samp>’.
- </p>
- <p>If the linker cannot recognize the format of an object file, it will
- assume that it is a linker script. A script specified in this way
- augments the main linker script used for the link (either the default
- linker script or the one specified by using ‘<samp>-T</samp>’). This feature
- permits the linker to link against a file which appears to be an object
- or an archive, but actually merely defines some symbol values, or uses
- <code>INPUT</code> or <code>GROUP</code> to load other objects. Specifying a
- script in this way merely augments the main linker script, with the
- extra commands placed after the main script; use the ‘<samp>-T</samp>’ option
- to replace the default linker script entirely, but note the effect of
- the <code>INSERT</code> command. See <a href="#Scripts">Scripts</a>.
- </p>
- <p>For options whose names are a single letter,
- option arguments must either follow the option letter without intervening
- whitespace, or be given as separate arguments immediately following the
- option that requires them.
- </p>
- <p>For options whose names are multiple letters, either one dash or two can
- precede the option name; for example, ‘<samp>-trace-symbol</samp>’ and
- ‘<samp>--trace-symbol</samp>’ are equivalent. Note—there is one exception to
- this rule. Multiple letter options that start with a lower case ’o’ can
- only be preceded by two dashes. This is to reduce confusion with the
- ‘<samp>-o</samp>’ option. So for example ‘<samp>-omagic</samp>’ sets the output file
- name to ‘<samp>magic</samp>’ whereas ‘<samp>--omagic</samp>’ sets the NMAGIC flag on the
- output.
- </p>
- <p>Arguments to multiple-letter options must either be separated from the
- option name by an equals sign, or be given as separate arguments
- immediately following the option that requires them. For example,
- ‘<samp>--trace-symbol foo</samp>’ and ‘<samp>--trace-symbol=foo</samp>’ are equivalent.
- Unique abbreviations of the names of multiple-letter options are
- accepted.
- </p>
- <p>Note—if the linker is being invoked indirectly, via a compiler driver
- (e.g. ‘<samp>gcc</samp>’) then all the linker command-line options should be
- prefixed by ‘<samp>-Wl,</samp>’ (or whatever is appropriate for the particular
- compiler driver) like this:
- </p>
- <div class="example">
- <pre class="example"> gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
- </pre></div>
- <p>This is important, because otherwise the compiler driver program may
- silently drop the linker options, resulting in a bad link. Confusion
- may also arise when passing options that require values through a
- driver, as the use of a space between option and argument acts as
- a separator, and causes the driver to pass only the option to the linker
- and the argument to the compiler. In this case, it is simplest to use
- the joined forms of both single- and multiple-letter options, such as:
- </p>
- <div class="example">
- <pre class="example"> gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
- </pre></div>
- <p>Here is a table of the generic command-line switches accepted by the GNU
- linker:
- </p>
- <dl compact="compact">
- <dt><code>@<var>file</var></code></dt>
- <dd><p>Read command-line options from <var>file</var>. The options read are
- inserted in place of the original @<var>file</var> option. If <var>file</var>
- does not exist, or cannot be read, then the option will be treated
- literally, and not removed.
- </p>
- <p>Options in <var>file</var> are separated by whitespace. A whitespace
- character may be included in an option by surrounding the entire
- option in either single or double quotes. Any character (including a
- backslash) may be included by prefixing the character to be included
- with a backslash. The <var>file</var> may itself contain additional
- @<var>file</var> options; any such options will be processed recursively.
- </p>
- <span id="index-_002da-keyword"></span>
- </dd>
- <dt><code>-a <var>keyword</var></code></dt>
- <dd><p>This option is supported for HP/UX compatibility. The <var>keyword</var>
- argument must be one of the strings ‘<samp>archive</samp>’, ‘<samp>shared</samp>’, or
- ‘<samp>default</samp>’. ‘<samp>-aarchive</samp>’ is functionally equivalent to
- ‘<samp>-Bstatic</samp>’, and the other two keywords are functionally equivalent
- to ‘<samp>-Bdynamic</samp>’. This option may be used any number of times.
- </p>
- <span id="index-_002d_002daudit-AUDITLIB"></span>
- </dd>
- <dt><code>--audit <var>AUDITLIB</var></code></dt>
- <dd><p>Adds <var>AUDITLIB</var> to the <code>DT_AUDIT</code> entry of the dynamic section.
- <var>AUDITLIB</var> is not checked for existence, nor will it use the DT_SONAME
- specified in the library. If specified multiple times <code>DT_AUDIT</code>
- will contain a colon separated list of audit interfaces to use. If the linker
- finds an object with an audit entry while searching for shared libraries,
- it will add a corresponding <code>DT_DEPAUDIT</code> entry in the output file.
- This option is only meaningful on ELF platforms supporting the rtld-audit
- interface.
- </p>
- <span id="index-binary-input-format"></span>
- <span id="index-_002db-format"></span>
- <span id="index-_002d_002dformat_003dformat"></span>
- <span id="index-input-format"></span>
- <span id="index-input-format-1"></span>
- </dd>
- <dt><code>-b <var>input-format</var></code></dt>
- <dt><code>--format=<var>input-format</var></code></dt>
- <dd><p><code>ld</code> may be configured to support more than one kind of object
- file. If your <code>ld</code> is configured this way, you can use the
- ‘<samp>-b</samp>’ option to specify the binary format for input object files
- that follow this option on the command line. Even when <code>ld</code> is
- configured to support alternative object formats, you don’t usually need
- to specify this, as <code>ld</code> should be configured to expect as a
- default input format the most usual format on each machine.
- <var>input-format</var> is a text string, the name of a particular format
- supported by the BFD libraries. (You can list the available binary
- formats with ‘<samp>objdump -i</samp>’.)
- See <a href="#BFD">BFD</a>.
- </p>
- <p>You may want to use this option if you are linking files with an unusual
- binary format. You can also use ‘<samp>-b</samp>’ to switch formats explicitly (when
- linking object files of different formats), by including
- ‘<samp>-b <var>input-format</var></samp>’ before each group of object files in a
- particular format.
- </p>
- <p>The default format is taken from the environment variable
- <code>GNUTARGET</code>.
- See <a href="#Environment">Environment</a>.
- You can also define the input format from a script, using the command
- <code>TARGET</code>;
- see <a href="#Format-Commands">Format Commands</a>.
- </p>
- <span id="index-_002dc-MRI_002dcmdfile"></span>
- <span id="index-_002d_002dmri_002dscript_003dMRI_002dcmdfile"></span>
- <span id="index-compatibility_002c-MRI"></span>
- </dd>
- <dt><code>-c <var>MRI-commandfile</var></code></dt>
- <dt><code>--mri-script=<var>MRI-commandfile</var></code></dt>
- <dd><p>For compatibility with linkers produced by MRI, <code>ld</code> accepts script
- files written in an alternate, restricted command language, described in
- <a href="#MRI">MRI Compatible Script Files</a>.
- Introduce MRI script files with
- the option ‘<samp>-c</samp>’; use the ‘<samp>-T</samp>’ option to run linker
- scripts written in the general-purpose <code>ld</code> scripting language.
- If <var>MRI-cmdfile</var> does not exist, <code>ld</code> looks for it in the directories
- specified by any ‘<samp>-L</samp>’ options.
- </p>
- <span id="index-common-allocation"></span>
- <span id="index-_002dd"></span>
- <span id="index-_002ddc"></span>
- <span id="index-_002ddp"></span>
- </dd>
- <dt><code>-d</code></dt>
- <dt><code>-dc</code></dt>
- <dt><code>-dp</code></dt>
- <dd><p>These three options are equivalent; multiple forms are supported for
- compatibility with other linkers. They assign space to common symbols
- even if a relocatable output file is specified (with ‘<samp>-r</samp>’). The
- script command <code>FORCE_COMMON_ALLOCATION</code> has the same effect.
- See <a href="#Miscellaneous-Commands">Miscellaneous Commands</a>.
- </p>
- <span id="index-_002d_002ddepaudit-AUDITLIB"></span>
- <span id="index-_002dP-AUDITLIB"></span>
- </dd>
- <dt><code>--depaudit <var>AUDITLIB</var></code></dt>
- <dt><code>-P <var>AUDITLIB</var></code></dt>
- <dd><p>Adds <var>AUDITLIB</var> to the <code>DT_DEPAUDIT</code> entry of the dynamic section.
- <var>AUDITLIB</var> is not checked for existence, nor will it use the DT_SONAME
- specified in the library. If specified multiple times <code>DT_DEPAUDIT</code>
- will contain a colon separated list of audit interfaces to use. This
- option is only meaningful on ELF platforms supporting the rtld-audit interface.
- The -P option is provided for Solaris compatibility.
- </p>
- <span id="index-_002d_002denable_002dlinker_002dversion"></span>
- </dd>
- <dt><code>--enable-linker-version</code></dt>
- <dd><p>Enables the <code>LINKER_VERSION</code> linker script directive, described
- in <a href="#Output-Section-Data">Output Section Data</a>. If this directive is used in a linker
- script and this option has been enabled then a string containing the
- linker version will be inserted at the current point.
- </p>
- <p>Note - this location of this option on the linker command line is
- significant. It will only affect linker scripts that come after it on
- the command line, or which are built into the linker.
- </p>
- <span id="index-_002d_002ddisable_002dlinker_002dversion"></span>
- </dd>
- <dt><code>--disable-linker-version</code></dt>
- <dd><p>Disables the <code>LINKER_VERSION</code> linker script directive, so that it
- does not insert a version string. This is the default.
- </p>
- <span id="index-_002d_002denable_002dnon_002dcontiguous_002dregions"></span>
- </dd>
- <dt><code>--enable-non-contiguous-regions</code></dt>
- <dd><p>This option avoids generating an error if an input section does not
- fit a matching output section. The linker tries to allocate the input
- section to subseque nt matching output sections, and generates an
- error only if no output section is large enough. This is useful when
- several non-contiguous memory regions are available and the input
- section does not require a particular one. The order in which input
- sections are evaluated does not change, for instance:
- </p>
- <div class="example">
- <pre class="example"> MEMORY {
- MEM1 (rwx) : ORIGIN = 0x1000, LENGTH = 0x14
- MEM2 (rwx) : ORIGIN = 0x1000, LENGTH = 0x40
- MEM3 (rwx) : ORIGIN = 0x2000, LENGTH = 0x40
- }
- SECTIONS {
- mem1 : { *(.data.*); } > MEM1
- mem2 : { *(.data.*); } > MEM2
- mem3 : { *(.data.*); } > MEM3
- }
- with input sections:
- .data.1: size 8
- .data.2: size 0x10
- .data.3: size 4
- results in .data.1 affected to mem1, and .data.2 and .data.3
- affected to mem2, even though .data.3 would fit in mem3.
- </pre></div>
- <p>This option is incompatible with INSERT statements because it changes
- the way input sections are mapped to output sections.
- </p>
- <span id="index-_002d_002denable_002dnon_002dcontiguous_002dregions_002dwarnings"></span>
- </dd>
- <dt><code>--enable-non-contiguous-regions-warnings</code></dt>
- <dd><p>This option enables warnings when
- <code>--enable-non-contiguous-regions</code> allows possibly unexpected
- matches in sections mapping, potentially leading to silently
- discarding a section instead of failing because it does not fit any
- output region.
- </p>
- <span id="index-entry-point_002c-from-command-line"></span>
- <span id="index-_002de-entry"></span>
- <span id="index-_002d_002dentry_003dentry"></span>
- </dd>
- <dt><code>-e <var>entry</var></code></dt>
- <dt><code>--entry=<var>entry</var></code></dt>
- <dd><p>Use <var>entry</var> as the explicit symbol for beginning execution of your
- program, rather than the default entry point. If there is no symbol
- named <var>entry</var>, the linker will try to parse <var>entry</var> as a number,
- and use that as the entry address (the number will be interpreted in
- base 10; you may use a leading ‘<samp>0x</samp>’ for base 16, or a leading
- ‘<samp>0</samp>’ for base 8). See <a href="#Entry-Point">Entry Point</a>, for a discussion of defaults
- and other ways of specifying the entry point.
- </p>
- <span id="index-_002d_002dexclude_002dlibs"></span>
- </dd>
- <dt><code>--exclude-libs <var>lib</var>,<var>lib</var>,...</code></dt>
- <dd><p>Specifies a list of archive libraries from which symbols should not be automatically
- exported. The library names may be delimited by commas or colons. Specifying
- <code>--exclude-libs ALL</code> excludes symbols in all archive libraries from
- automatic export. This option is available only for the i386 PE targeted
- port of the linker and for ELF targeted ports. For i386 PE, symbols
- explicitly listed in a .def file are still exported, regardless of this
- option. For ELF targeted ports, symbols affected by this option will
- be treated as hidden.
- </p>
- <span id="index-_002d_002dexclude_002dmodules_002dfor_002dimplib"></span>
- </dd>
- <dt><code>--exclude-modules-for-implib <var>module</var>,<var>module</var>,...</code></dt>
- <dd><p>Specifies a list of object files or archive members, from which symbols
- should not be automatically exported, but which should be copied wholesale
- into the import library being generated during the link. The module names
- may be delimited by commas or colons, and must match exactly the filenames
- used by <code>ld</code> to open the files; for archive members, this is simply
- the member name, but for object files the name listed must include and
- match precisely any path used to specify the input file on the linker’s
- command-line. This option is available only for the i386 PE targeted port
- of the linker. Symbols explicitly listed in a .def file are still exported,
- regardless of this option.
- </p>
- <span id="index-dynamic-symbol-table"></span>
- <span id="index-_002dE"></span>
- <span id="index-_002d_002dexport_002ddynamic"></span>
- <span id="index-_002d_002dno_002dexport_002ddynamic"></span>
- </dd>
- <dt><code>-E</code></dt>
- <dt><code>--export-dynamic</code></dt>
- <dt><code>--no-export-dynamic</code></dt>
- <dd><p>When creating a dynamically linked executable, using the <samp>-E</samp>
- option or the <samp>--export-dynamic</samp> option causes the linker to add
- all symbols to the dynamic symbol table. The dynamic symbol table is the
- set of symbols which are visible from dynamic objects at run time.
- </p>
- <p>If you do not use either of these options (or use the
- <samp>--no-export-dynamic</samp> option to restore the default behavior), the
- dynamic symbol table will normally contain only those symbols which are
- referenced by some dynamic object mentioned in the link.
- </p>
- <p>If you use <code>dlopen</code> to load a dynamic object which needs to refer
- back to the symbols defined by the program, rather than some other
- dynamic object, then you will probably need to use this option when
- linking the program itself.
- </p>
- <p>You can also use the dynamic list to control what symbols should
- be added to the dynamic symbol table if the output format supports it.
- See the description of ‘<samp>--dynamic-list</samp>’.
- </p>
- <p>Note that this option is specific to ELF targeted ports. PE targets
- support a similar function to export all symbols from a DLL or EXE; see
- the description of ‘<samp>--export-all-symbols</samp>’ below.
- </p>
- <span id="index-_002d_002dexport_002ddynamic_002dsymbol_003dglob"></span>
- <span id="index-export-dynamic-symbol"></span>
- </dd>
- <dt><code>--export-dynamic-symbol=<var>glob</var></code></dt>
- <dd><p>When creating a dynamically linked executable, symbols matching
- <var>glob</var> will be added to the dynamic symbol table. When creating a
- shared library, references to symbols matching <var>glob</var> will not be
- bound to the definitions within the shared library. This option is a
- no-op when creating a shared library and ‘<samp>-Bsymbolic</samp>’ or
- ‘<samp>--dynamic-list</samp>’ are not specified. This option is only meaningful
- on ELF platforms which support shared libraries.
- </p>
- <span id="index-_002d_002dexport_002ddynamic_002dsymbol_002dlist_003dfile"></span>
- <span id="index-export-dynamic-symbol-list"></span>
- </dd>
- <dt><code>--export-dynamic-symbol-list=<var>file</var></code></dt>
- <dd><p>Specify a ‘<samp>--export-dynamic-symbol</samp>’ for each pattern in the file.
- The format of the file is the same as the version node without
- scope and node name. See <a href="#VERSION">VERSION</a> for more information.
- </p>
- <span id="index-big_002dendian-objects"></span>
- <span id="index-endianness"></span>
- <span id="index-_002dEB"></span>
- </dd>
- <dt><code>-EB</code></dt>
- <dd><p>Link big-endian objects. This affects the default output format.
- </p>
- <span id="index-little_002dendian-objects"></span>
- <span id="index-_002dEL"></span>
- </dd>
- <dt><code>-EL</code></dt>
- <dd><p>Link little-endian objects. This affects the default output format.
- </p>
- <span id="index-_002df-name"></span>
- <span id="index-_002d_002dauxiliary_003dname"></span>
- </dd>
- <dt><code>-f <var>name</var></code></dt>
- <dt><code>--auxiliary=<var>name</var></code></dt>
- <dd><p>When creating an ELF shared object, set the internal DT_AUXILIARY field
- to the specified name. This tells the dynamic linker that the symbol
- table of the shared object should be used as an auxiliary filter on the
- symbol table of the shared object <var>name</var>.
- </p>
- <p>If you later link a program against this filter object, then, when you
- run the program, the dynamic linker will see the DT_AUXILIARY field. If
- the dynamic linker resolves any symbols from the filter object, it will
- first check whether there is a definition in the shared object
- <var>name</var>. If there is one, it will be used instead of the definition
- in the filter object. The shared object <var>name</var> need not exist.
- Thus the shared object <var>name</var> may be used to provide an alternative
- implementation of certain functions, perhaps for debugging or for
- machine-specific performance.
- </p>
- <p>This option may be specified more than once. The DT_AUXILIARY entries
- will be created in the order in which they appear on the command line.
- </p>
- <span id="index-_002dF-name"></span>
- <span id="index-_002d_002dfilter_003dname"></span>
- </dd>
- <dt><code>-F <var>name</var></code></dt>
- <dt><code>--filter=<var>name</var></code></dt>
- <dd><p>When creating an ELF shared object, set the internal DT_FILTER field to
- the specified name. This tells the dynamic linker that the symbol table
- of the shared object which is being created should be used as a filter
- on the symbol table of the shared object <var>name</var>.
- </p>
- <p>If you later link a program against this filter object, then, when you
- run the program, the dynamic linker will see the DT_FILTER field. The
- dynamic linker will resolve symbols according to the symbol table of the
- filter object as usual, but it will actually link to the definitions
- found in the shared object <var>name</var>. Thus the filter object can be
- used to select a subset of the symbols provided by the object
- <var>name</var>.
- </p>
- <p>Some older linkers used the <samp>-F</samp> option throughout a compilation
- toolchain for specifying object-file format for both input and output
- object files.
- The <small>GNU</small> linker uses other mechanisms for this purpose: the
- <samp>-b</samp>, <samp>--format</samp>, <samp>--oformat</samp> options, the
- <code>TARGET</code> command in linker scripts, and the <code>GNUTARGET</code>
- environment variable.
- The <small>GNU</small> linker will ignore the <samp>-F</samp> option when not
- creating an ELF shared object.
- </p>
- <span id="index-finalization-function"></span>
- <span id="index-_002dfini_003dname"></span>
- </dd>
- <dt><code>-fini=<var>name</var></code></dt>
- <dd><p>When creating an ELF executable or shared object, call NAME when the
- executable or shared object is unloaded, by setting DT_FINI to the
- address of the function. By default, the linker uses <code>_fini</code> as
- the function to call.
- </p>
- <span id="index-_002dg"></span>
- </dd>
- <dt><code>-g</code></dt>
- <dd><p>Ignored. Provided for compatibility with other tools.
- </p>
- <span id="index-_002dG-value"></span>
- <span id="index-_002d_002dgpsize_003dvalue"></span>
- <span id="index-object-size"></span>
- </dd>
- <dt><code>-G <var>value</var></code></dt>
- <dt><code>--gpsize=<var>value</var></code></dt>
- <dd><p>Set the maximum size of objects to be optimized using the GP register to
- <var>size</var>. This is only meaningful for object file formats such as
- MIPS ELF that support putting large and small objects into different
- sections. This is ignored for other object file formats.
- </p>
- <span id="index-runtime-library-name"></span>
- <span id="index-_002dh-name"></span>
- <span id="index-_002dsoname_003dname"></span>
- </dd>
- <dt><code>-h <var>name</var></code></dt>
- <dt><code>-soname=<var>name</var></code></dt>
- <dd><p>When creating an ELF shared object, set the internal DT_SONAME field to
- the specified name. When an executable is linked with a shared object
- which has a DT_SONAME field, then when the executable is run the dynamic
- linker will attempt to load the shared object specified by the DT_SONAME
- field rather than using the file name given to the linker.
- </p>
- <span id="index-_002di"></span>
- <span id="index-incremental-link"></span>
- </dd>
- <dt><code>-i</code></dt>
- <dd><p>Perform an incremental link (same as option ‘<samp>-r</samp>’).
- </p>
- <span id="index-initialization-function"></span>
- <span id="index-_002dinit_003dname"></span>
- </dd>
- <dt><code>-init=<var>name</var></code></dt>
- <dd><p>When creating an ELF executable or shared object, call NAME when the
- executable or shared object is loaded, by setting DT_INIT to the address
- of the function. By default, the linker uses <code>_init</code> as the
- function to call.
- </p>
- <span id="index-archive-files_002c-from-cmd-line"></span>
- <span id="index-_002dl-namespec"></span>
- <span id="index-_002d_002dlibrary_003dnamespec"></span>
- </dd>
- <dt><code>-l <var>namespec</var></code></dt>
- <dt><code>--library=<var>namespec</var></code></dt>
- <dd><p>Add the archive or object file specified by <var>namespec</var> to the
- list of files to link. This option may be used any number of times.
- If <var>namespec</var> is of the form <samp>:<var>filename</var></samp>, <code>ld</code>
- will search the library path for a file called <var>filename</var>, otherwise it
- will search the library path for a file called <samp>lib<var>namespec</var>.a</samp>.
- </p>
- <p>On systems which support shared libraries, <code>ld</code> may also search for
- files other than <samp>lib<var>namespec</var>.a</samp>. Specifically, on ELF
- and SunOS systems, <code>ld</code> will search a directory for a library
- called <samp>lib<var>namespec</var>.so</samp> before searching for one called
- <samp>lib<var>namespec</var>.a</samp>. (By convention, a <code>.so</code> extension
- indicates a shared library.) Note that this behavior does not apply
- to <samp>:<var>filename</var></samp>, which always specifies a file called
- <var>filename</var>.
- </p>
- <p>The linker will search an archive only once, at the location where it is
- specified on the command line. If the archive defines a symbol which
- was undefined in some object which appeared before the archive on the
- command line, the linker will include the appropriate file(s) from the
- archive. However, an undefined symbol in an object appearing later on
- the command line will not cause the linker to search the archive again.
- </p>
- <p>See the <samp>-(</samp> option for a way to force the linker to search
- archives multiple times.
- </p>
- <p>You may list the same archive multiple times on the command line.
- </p>
- <p>This type of archive searching is standard for Unix linkers. However,
- if you are using <code>ld</code> on AIX, note that it is different from the
- behaviour of the AIX linker.
- </p>
- <span id="index-search-directory_002c-from-cmd-line"></span>
- <span id="index-_002dL-dir"></span>
- <span id="index-_002d_002dlibrary_002dpath_003ddir"></span>
- </dd>
- <dt><code>-L <var>searchdir</var></code></dt>
- <dt><code>--library-path=<var>searchdir</var></code></dt>
- <dd><p>Add path <var>searchdir</var> to the list of paths that <code>ld</code> will search
- for archive libraries and <code>ld</code> control scripts. You may use this
- option any number of times. The directories are searched in the order
- in which they are specified on the command line. Directories specified
- on the command line are searched before the default directories. All
- <samp>-L</samp> options apply to all <samp>-l</samp> options, regardless of the
- order in which the options appear. <samp>-L</samp> options do not affect
- how <code>ld</code> searches for a linker script unless <samp>-T</samp>
- option is specified.
- </p>
- <p>If <var>searchdir</var> begins with <code>=</code> or <code>$SYSROOT</code>, then this
- prefix will be replaced by the <em>sysroot prefix</em>, controlled by the
- ‘<samp>--sysroot</samp>’ option, or specified when the linker is configured.
- </p>
- <p>The default set of paths searched (without being specified with
- ‘<samp>-L</samp>’) depends on which emulation mode <code>ld</code> is using, and in
- some cases also on how it was configured. See <a href="#Environment">Environment</a>.
- </p>
- <p>The paths can also be specified in a link script with the
- <code>SEARCH_DIR</code> command. Directories specified this way are searched
- at the point in which the linker script appears in the command line.
- </p>
- <span id="index-emulation"></span>
- <span id="index-_002dm-emulation"></span>
- </dd>
- <dt><code>-m <var>emulation</var></code></dt>
- <dd><p>Emulate the <var>emulation</var> linker. You can list the available
- emulations with the ‘<samp>--verbose</samp>’ or ‘<samp>-V</samp>’ options.
- </p>
- <p>If the ‘<samp>-m</samp>’ option is not used, the emulation is taken from the
- <code>LDEMULATION</code> environment variable, if that is defined.
- </p>
- <p>Otherwise, the default emulation depends upon how the linker was
- configured.
- </p>
- <span id="index-remapping-inputs"></span>
- <span id="index-_002d_002dremap_002dinputs_003dpattern_003dfilename"></span>
- <span id="index-_002d_002dremap_002dinputs_002dfile_003dfile"></span>
- </dd>
- <dt><code>--remap-inputs=<samp>pattern</samp>=<samp>filename</samp></code></dt>
- <dt><code>--remap-inputs-file=<samp>file</samp></code></dt>
- <dd><p>These options allow the names of input files to be changed before the
- linker attempts to open them. The option
- <samp>--remap-inputs=foo.o=bar.o</samp> will cause any attempt to load a
- file called <samp>foo.o</samp> to instead try to load a file called
- <samp>bar.o</samp>. Wildcard patterns are permitted in the first filename,
- so <samp>--remap-inputs=foo*.o=bar.o</samp> will rename any input file that
- matches <samp>foo*.o</samp> to <samp>bar.o</samp>.
- </p>
- <p>An alternative form of the option
- <samp>--remap-inputs-file=filename</samp> allows the remappings to be read
- from a file. Each line in the file can contain a single remapping.
- Blank lines are ignored. Anything from a hash character (‘<samp>#</samp>’) to
- the end of a line is considered to be a comment and is also ignored.
- The mapping pattern can be separated from the filename by whitespace
- or an equals (‘<samp>=</samp>’) character.
- </p>
- <p>The options can be specified multiple times. Their contents
- accumulate. The remappings will be processed in the order in which
- they occur on the command line, and if they come from a file, in the
- order in which they occur in the file. If a match is made, no further
- checking for that filename will be performed.
- </p>
- <p>If the replacement filename is <samp>/dev/null</samp> or just <samp>NUL</samp>
- then the remapping will actually cause the input file to be ignored.
- This can be a convenient way to experiment with removing input files
- from a complicated build environment.
- </p>
- <p>Note that this option is position dependent and only affects filenames
- that come after it on the command line. Thus:
- </p>
- <div class="example">
- <pre class="example"> ld foo.o --remap-inputs=foo.o=bar.o
- </pre></div>
- <p>Will have no effect, whereas:
- </p>
- <div class="example">
- <pre class="example"> ld --remap-inputs=foo.o=bar.o foo.o
- </pre></div>
- <p>Will rename the input file <samp>foo.o</samp> to <samp>bar.o</samp>.
- </p>
- <p>Note - these options also affect files referenced by <em>INPUT</em>
- statements in linker scripts. But since linker scripts are processed
- after the entire command line is read, the position of the remap
- options on the command line is not significant.
- </p>
- <p>If the <samp>verbose</samp> option is enabled then any mappings that match
- will be reported, although again the <samp>verbose</samp> option needs to
- be enabled on the command line <em>before</em> the remaped filenames
- appear.
- </p>
- <p>If the <samp>-Map</samp> or <samp>--print-map</samp> options are enabled then
- the remapping list will be included in the map output.
- </p>
- <span id="index-link-map"></span>
- <span id="index-_002dM"></span>
- <span id="index-_002d_002dprint_002dmap"></span>
- </dd>
- <dt><code>-M</code></dt>
- <dt><code>--print-map</code></dt>
- <dd><p>Print a link map to the standard output. A link map provides
- information about the link, including the following:
- </p>
- <ul>
- <li> Where object files are mapped into memory.
- </li><li> How common symbols are allocated.
- </li><li> All archive members included in the link, with a mention of the symbol
- which caused the archive member to be brought in.
- </li><li> The values assigned to symbols.
- <p>Note - symbols whose values are computed by an expression which
- involves a reference to a previous value of the same symbol may not
- have correct result displayed in the link map. This is because the
- linker discards intermediate results and only retains the final value
- of an expression. Under such circumstances the linker will display
- the final value enclosed by square brackets. Thus for example a
- linker script containing:
- </p>
- <div class="example">
- <pre class="example"> foo = 1
- foo = foo * 4
- foo = foo + 8
- </pre></div>
- <p>will produce the following output in the link map if the <samp>-M</samp>
- option is used:
- </p>
- <div class="example">
- <pre class="example"> 0x00000001 foo = 0x1
- [0x0000000c] foo = (foo * 0x4)
- [0x0000000c] foo = (foo + 0x8)
- </pre></div>
- <p>See <a href="#Expressions">Expressions</a> for more information about expressions in linker
- scripts.
- </p>
- </li><li> How GNU properties are merged.
- <p>When the linker merges input .note.gnu.property sections into one output
- .note.gnu.property section, some properties are removed or updated.
- These actions are reported in the link map. For example:
- </p>
- <div class="example">
- <pre class="example">Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
- </pre></div>
- <p>This indicates that property 0xc0000002 is removed from output when
- merging properties in <samp>foo.o</samp>, whose property 0xc0000002 value
- is 0x1, and <samp>bar.o</samp>, which doesn’t have property 0xc0000002.
- </p>
- <div class="example">
- <pre class="example">Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1)
- </pre></div>
- <p>This indicates that property 0xc0010001 value is updated to 0x1 in output
- when merging properties in <samp>foo.o</samp>, whose 0xc0010001 property value
- is 0x1, and <samp>bar.o</samp>, whose 0xc0010001 property value is 0x1.
- </p>
- </li><li> On some ELF targets, a list of fixups inserted by <samp>--relax</samp>
- <div class="example">
- <pre class="example">foo.o: Adjusting branch at 0x00000008 towards "far" in section .text
- </pre></div>
- <p>This indicates that the branch at 0x00000008 in foo.o, targeting
- the symbol "far" in section .text, has been replaced by a trampoline.
- </p>
- </li></ul>
- <span id="index-link-map-discarded"></span>
- <span id="index-_002d_002dprint_002dmap_002ddiscarded"></span>
- <span id="index-_002d_002dno_002dprint_002dmap_002ddiscarded"></span>
- </dd>
- <dt><code>--print-map-discarded</code></dt>
- <dt><code>--no-print-map-discarded</code></dt>
- <dd><p>Print (or do not print) the list of discarded and garbage collected sections
- in the link map. Enabled by default.
- </p>
- <span id="index-_002d_002dprint_002dmap_002dlocals"></span>
- <span id="index-_002d_002dno_002dprint_002dmap_002dlocals"></span>
- </dd>
- <dt><code>--print-map-locals</code></dt>
- <dt><code>--no-print-map-locals</code></dt>
- <dd><p>Print (or do not print) local symbols in the link map. Local symbols
- will have the text ‘<samp>(local)</samp>’ printed before their name, and will
- be listed after all of the global symbols in a given section.
- Temporary local symbols (typically those that start with ‘<samp>.L</samp>’)
- will not be included in the output. Disabled by default.
- </p>
- <span id="index-_002dn"></span>
- <span id="index-read_002donly-text"></span>
- <span id="index-NMAGIC"></span>
- <span id="index-_002d_002dnmagic"></span>
- </dd>
- <dt><code>-n</code></dt>
- <dt><code>--nmagic</code></dt>
- <dd><p>Turn off page alignment of sections, and disable linking against shared
- libraries. If the output format supports Unix style magic numbers,
- mark the output as <code>NMAGIC</code>.
- </p>
- <span id="index-_002dN"></span>
- <span id="index-_002d_002domagic"></span>
- <span id="index-read_002fwrite-from-cmd-line"></span>
- <span id="index-OMAGIC"></span>
- </dd>
- <dt><code>-N</code></dt>
- <dt><code>--omagic</code></dt>
- <dd><p>Set the text and data sections to be readable and writable. Also, do
- not page-align the data segment, and disable linking against shared
- libraries. If the output format supports Unix style magic numbers,
- mark the output as <code>OMAGIC</code>. Note: Although a writable text section
- is allowed for PE-COFF targets, it does not conform to the format
- specification published by Microsoft.
- </p>
- <span id="index-_002d_002dno_002domagic"></span>
- <span id="index-OMAGIC-1"></span>
- </dd>
- <dt><code>--no-omagic</code></dt>
- <dd><p>This option negates most of the effects of the <samp>-N</samp> option. It
- sets the text section to be read-only, and forces the data segment to
- be page-aligned. Note - this option does not enable linking against
- shared libraries. Use <samp>-Bdynamic</samp> for this.
- </p>
- <span id="index-_002do-output"></span>
- <span id="index-_002d_002doutput_003doutput"></span>
- <span id="index-naming-the-output-file"></span>
- </dd>
- <dt><code>-o <var>output</var></code></dt>
- <dt><code>--output=<var>output</var></code></dt>
- <dd><p>Use <var>output</var> as the name for the program produced by <code>ld</code>; if this
- option is not specified, the name <samp>a.out</samp> is used by default. The
- script command <code>OUTPUT</code> can also specify the output file name.
- </p>
- <span id="index-_002d_002ddependency_002dfile_003ddepfile"></span>
- <span id="index-dependency-file"></span>
- </dd>
- <dt><code>--dependency-file=<var>depfile</var></code></dt>
- <dd><p>Write a <em>dependency file</em> to <var>depfile</var>. This file contains a rule
- suitable for <code>make</code> describing the output file and all the input files
- that were read to produce it. The output is similar to the compiler’s
- output with ‘<samp>-M -MP</samp>’ (see <a href="https://gcc.gnu.org/onlinedocs/gcc/Preprocessor-Options.html#Preprocessor-Options">Options
- Controlling the Preprocessor</a> in <cite>Using the GNU Compiler
- Collection</cite>). Note that there is no option like the compiler’s ‘<samp>-MM</samp>’,
- to exclude “system files” (which is not a well-specified concept in the
- linker, unlike “system headers” in the compiler). So the output from
- ‘<samp>--dependency-file</samp>’ is always specific to the exact state of the
- installation where it was produced, and should not be copied into
- distributed makefiles without careful editing.
- </p>
- <span id="index-_002dO-level"></span>
- <span id="index-generating-optimized-output"></span>
- </dd>
- <dt><code>-O <var>level</var></code></dt>
- <dd><p>If <var>level</var> is a numeric values greater than zero <code>ld</code> optimizes
- the output. This might take significantly longer and therefore probably
- should only be enabled for the final binary. At the moment this
- option only affects ELF shared library generation. Future releases of
- the linker may make more use of this option. Also currently there is
- no difference in the linker’s behaviour for different non-zero values
- of this option. Again this may change with future releases.
- </p>
- <span id="index-_002dplugin-name"></span>
- </dd>
- <dt><code>-plugin <var>name</var></code></dt>
- <dd><p>Involve a plugin in the linking process. The <var>name</var> parameter is
- the absolute filename of the plugin. Usually this parameter is
- automatically added by the complier, when using link time
- optimization, but users can also add their own plugins if they so
- wish.
- </p>
- <p>Note that the location of the compiler originated plugins is different
- from the place where the <code>ar</code>, <code>nm</code> and
- <code>ranlib</code> programs search for their plugins. In order for
- those commands to make use of a compiler based plugin it must first be
- copied into the <samp>${libdir}/bfd-plugins</samp> directory. All gcc
- based linker plugins are backward compatible, so it is sufficient to
- just copy in the newest one.
- </p>
- <span id="index-_002d_002dpush_002dstate"></span>
- <span id="index-push-state-governing-input-file-handling"></span>
- </dd>
- <dt><code>--push-state</code></dt>
- <dd><p>The <samp>--push-state</samp> allows one to preserve the current state of the
- flags which govern the input file handling so that they can all be
- restored with one corresponding <samp>--pop-state</samp> option.
- </p>
- <p>The option which are covered are: <samp>-Bdynamic</samp>, <samp>-Bstatic</samp>,
- <samp>-dn</samp>, <samp>-dy</samp>, <samp>-call_shared</samp>, <samp>-non_shared</samp>,
- <samp>-static</samp>, <samp>-N</samp>, <samp>-n</samp>, <samp>--whole-archive</samp>,
- <samp>--no-whole-archive</samp>, <samp>-r</samp>, <samp>-Ur</samp>,
- <samp>--copy-dt-needed-entries</samp>, <samp>--no-copy-dt-needed-entries</samp>,
- <samp>--as-needed</samp>, <samp>--no-as-needed</samp>, and <samp>-a</samp>.
- </p>
- <p>One target for this option are specifications for <samp>pkg-config</samp>. When
- used with the <samp>--libs</samp> option all possibly needed libraries are
- listed and then possibly linked with all the time. It is better to return
- something as follows:
- </p>
- <div class="example">
- <pre class="example">-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
- </pre></div>
- <span id="index-_002d_002dpop_002dstate"></span>
- <span id="index-pop-state-governing-input-file-handling"></span>
- </dd>
- <dt><code>--pop-state</code></dt>
- <dd><p>Undoes the effect of –push-state, restores the previous values of the
- flags governing input file handling.
- </p>
- <span id="index-_002dq"></span>
- <span id="index-_002d_002demit_002drelocs"></span>
- <span id="index-retain-relocations-in-final-executable"></span>
- </dd>
- <dt><code>-q</code></dt>
- <dt><code>--emit-relocs</code></dt>
- <dd><p>Leave relocation sections and contents in fully linked executables.
- Post link analysis and optimization tools may need this information in
- order to perform correct modifications of executables. This results
- in larger executables.
- </p>
- <p>This option is currently only supported on ELF platforms.
- </p>
- <span id="index-_002d_002dforce_002ddynamic"></span>
- <span id="index-forcing-the-creation-of-dynamic-sections"></span>
- </dd>
- <dt><code>--force-dynamic</code></dt>
- <dd><p>Force the output file to have dynamic sections. This option is specific
- to VxWorks targets.
- </p>
- <span id="index-partial-link"></span>
- <span id="index-relocatable-output"></span>
- <span id="index-_002dr"></span>
- <span id="index-_002d_002drelocatable"></span>
- </dd>
- <dt><code>-r</code></dt>
- <dt><code>--relocatable</code></dt>
- <dd><p>Generate relocatable output—i.e., generate an output file that can in
- turn serve as input to <code>ld</code>. This is often called <em>partial
- linking</em>. As a side effect, in environments that support standard Unix
- magic numbers, this option also sets the output file’s magic number to
- <code>OMAGIC</code>.
- If this option is not specified, an absolute file is produced. When
- linking C++ programs, this option <em>will not</em> resolve references to
- constructors; to do that, use ‘<samp>-Ur</samp>’.
- </p>
- <p>When an input file does not have the same format as the output file,
- partial linking is only supported if that input file does not contain any
- relocations. Different output formats can have further restrictions; for
- example some <code>a.out</code>-based formats do not support partial linking
- with input files in other formats at all.
- </p>
- <p>This option does the same thing as ‘<samp>-i</samp>’.
- </p>
- <span id="index-_002dR-file"></span>
- <span id="index-_002d_002djust_002dsymbols_003dfile"></span>
- <span id="index-symbol_002donly-input"></span>
- </dd>
- <dt><code>-R <var>filename</var></code></dt>
- <dt><code>--just-symbols=<var>filename</var></code></dt>
- <dd><p>Read symbol names and their addresses from <var>filename</var>, but do not
- relocate it or include it in the output. This allows your output file
- to refer symbolically to absolute locations of memory defined in other
- programs. You may use this option more than once.
- </p>
- <p>For compatibility with other ELF linkers, if the <samp>-R</samp> option is
- followed by a directory name, rather than a file name, it is treated as
- the <samp>-rpath</samp> option.
- </p>
- <span id="index-_002ds"></span>
- <span id="index-_002d_002dstrip_002dall"></span>
- <span id="index-strip-all-symbols"></span>
- </dd>
- <dt><code>-s</code></dt>
- <dt><code>--strip-all</code></dt>
- <dd><p>Omit all symbol information from the output file.
- </p>
- <span id="index-_002dS"></span>
- <span id="index-_002d_002dstrip_002ddebug"></span>
- <span id="index-strip-debugger-symbols"></span>
- </dd>
- <dt><code>-S</code></dt>
- <dt><code>--strip-debug</code></dt>
- <dd><p>Omit debugger symbol information (but not all symbols) from the output file.
- </p>
- <span id="index-_002d_002dstrip_002ddiscarded"></span>
- <span id="index-_002d_002dno_002dstrip_002ddiscarded"></span>
- </dd>
- <dt><code>--strip-discarded</code></dt>
- <dt><code>--no-strip-discarded</code></dt>
- <dd><p>Omit (or do not omit) global symbols defined in discarded sections.
- Enabled by default.
- </p>
- <span id="index-_002dt"></span>
- <span id="index-_002d_002dtrace"></span>
- <span id="index-input-files_002c-displaying"></span>
- </dd>
- <dt><code>-t</code></dt>
- <dt><code>--trace</code></dt>
- <dd><p>Print the names of the input files as <code>ld</code> processes them. If
- ‘<samp>-t</samp>’ is given twice then members within archives are also printed.
- ‘<samp>-t</samp>’ output is useful to generate a list of all the object files
- and scripts involved in linking, for example, when packaging files for
- a linker bug report.
- </p>
- <span id="index-_002dT-script"></span>
- <span id="index-_002d_002dscript_003dscript"></span>
- <span id="index-script-files"></span>
- </dd>
- <dt><code>-T <var>scriptfile</var></code></dt>
- <dt><code>--script=<var>scriptfile</var></code></dt>
- <dd><p>Use <var>scriptfile</var> as the linker script. This script replaces
- <code>ld</code>’s default linker script (rather than adding to it),
- unless the script contains <code>INSERT</code>, so
- <var>commandfile</var> must specify everything necessary to describe the
- output file. See <a href="#Scripts">Scripts</a>. If <var>scriptfile</var> does not exist in
- the current directory, <code>ld</code> looks for it in the directories
- specified by any preceding ‘<samp>-L</samp>’ options. Multiple ‘<samp>-T</samp>’
- options accumulate.
- </p>
- <span id="index-_002ddT-script"></span>
- <span id="index-_002d_002ddefault_002dscript_003dscript"></span>
- <span id="index-script-files-1"></span>
- </dd>
- <dt><code>-dT <var>scriptfile</var></code></dt>
- <dt><code>--default-script=<var>scriptfile</var></code></dt>
- <dd><p>Use <var>scriptfile</var> as the default linker script. See <a href="#Scripts">Scripts</a>.
- </p>
- <p>This option is similar to the <samp>--script</samp> option except that
- processing of the script is delayed until after the rest of the
- command line has been processed. This allows options placed after the
- <samp>--default-script</samp> option on the command line to affect the
- behaviour of the linker script, which can be important when the linker
- command line cannot be directly controlled by the user. (eg because
- the command line is being constructed by another tool, such as
- ‘<samp>gcc</samp>’).
- </p>
- <span id="index-_002du-symbol"></span>
- <span id="index-_002d_002dundefined_003dsymbol"></span>
- <span id="index-undefined-symbol"></span>
- </dd>
- <dt><code>-u <var>symbol</var></code></dt>
- <dt><code>--undefined=<var>symbol</var></code></dt>
- <dd><p>Force <var>symbol</var> to be entered in the output file as an undefined
- symbol. Doing this may, for example, trigger linking of additional
- modules from standard libraries. ‘<samp>-u</samp>’ may be repeated with
- different option arguments to enter additional undefined symbols. This
- option is equivalent to the <code>EXTERN</code> linker script command.
- </p>
- <p>If this option is being used to force additional modules to be pulled
- into the link, and if it is an error for the symbol to remain
- undefined, then the option <samp>--require-defined</samp> should be used
- instead.
- </p>
- <span id="index-_002d_002drequire_002ddefined_003dsymbol"></span>
- <span id="index-symbols_002c-require-defined"></span>
- <span id="index-defined-symbol"></span>
- </dd>
- <dt><code>--require-defined=<var>symbol</var></code></dt>
- <dd><p>Require that <var>symbol</var> is defined in the output file. This option
- is the same as option <samp>--undefined</samp> except that if <var>symbol</var>
- is not defined in the output file then the linker will issue an error
- and exit. The same effect can be achieved in a linker script by using
- <code>EXTERN</code>, <code>ASSERT</code> and <code>DEFINED</code> together. This option
- can be used multiple times to require additional symbols.
- </p>
- <span id="index-_002dUr"></span>
- <span id="index-constructors"></span>
- </dd>
- <dt><code>-Ur</code></dt>
- <dd>
- <p>For programs that do not use constructors or destructors, or for ELF
- based systems this option is equivalent to <samp>-r</samp>: it generates
- relocatable output—i.e., an output file that can in turn serve as
- input to <code>ld</code>. For other binaries however the <samp>-Ur</samp>
- option is similar to <samp>-r</samp> but it also resolves references to
- constructors and destructors.
- </p>
- <p>For those systems where <samp>-r</samp> and <samp>-Ur</samp> behave
- differently, it does not work to use <samp>-Ur</samp> on files that were
- themselves linked with <samp>-Ur</samp>; once the constructor table has
- been built, it cannot be added to. Use <samp>-Ur</samp> only for the last
- partial link, and <samp>-r</samp> for the others.
- </p>
- <span id="index-_002d_002dorphan_002dhandling_003dMODE"></span>
- <span id="index-orphan-sections"></span>
- <span id="index-sections_002c-orphan"></span>
- </dd>
- <dt><code>--orphan-handling=<var>MODE</var></code></dt>
- <dd><p>Control how orphan sections are handled. An orphan section is one not
- specifically mentioned in a linker script. See <a href="#Orphan-Sections">Orphan Sections</a>.
- </p>
- <p><var>MODE</var> can have any of the following values:
- </p>
- <dl compact="compact">
- <dt><code>place</code></dt>
- <dd><p>Orphan sections are placed into a suitable output section following
- the strategy described in <a href="#Orphan-Sections">Orphan Sections</a>. The option
- ‘<samp>--unique</samp>’ also affects how sections are placed.
- </p>
- </dd>
- <dt><code>discard</code></dt>
- <dd><p>All orphan sections are discarded, by placing them in the
- ‘<samp>/DISCARD/</samp>’ section (see <a href="#Output-Section-Discarding">Output Section Discarding</a>).
- </p>
- </dd>
- <dt><code>warn</code></dt>
- <dd><p>The linker will place the orphan section as for <code>place</code> and also
- issue a warning.
- </p>
- </dd>
- <dt><code>error</code></dt>
- <dd><p>The linker will exit with an error if any orphan section is found.
- </p></dd>
- </dl>
- <p>The default if ‘<samp>--orphan-handling</samp>’ is not given is <code>place</code>.
- </p>
- <span id="index-_002d_002dunique_005b_003dSECTION_005d"></span>
- </dd>
- <dt><code>--unique[=<var>SECTION</var>]</code></dt>
- <dd><p>Creates a separate output section for every input section matching
- <var>SECTION</var>, or if the optional wildcard <var>SECTION</var> argument is
- missing, for every orphan input section. An orphan section is one not
- specifically mentioned in a linker script. You may use this option
- multiple times on the command line; It prevents the normal merging of
- input sections with the same name, overriding output section assignments
- in a linker script.
- </p>
- <span id="index-_002dv"></span>
- <span id="index-_002dV"></span>
- <span id="index-_002d_002dversion"></span>
- <span id="index-version"></span>
- </dd>
- <dt><code>-v</code></dt>
- <dt><code>--version</code></dt>
- <dt><code>-V</code></dt>
- <dd><p>Display the version number for <code>ld</code>. The <samp>-V</samp> option also
- lists the supported emulations. See also the description of the
- <samp>--enable-linker-version</samp> in <a href="#Options">Command-line Options</a>
- which can be used to insert the linker version string into a binary.
- </p>
- <span id="index-_002dx"></span>
- <span id="index-_002d_002ddiscard_002dall"></span>
- <span id="index-deleting-local-symbols"></span>
- </dd>
- <dt><code>-x</code></dt>
- <dt><code>--discard-all</code></dt>
- <dd><p>Delete all local symbols.
- </p>
- <span id="index-_002dX"></span>
- <span id="index-_002d_002ddiscard_002dlocals"></span>
- <span id="index-local-symbols_002c-deleting"></span>
- </dd>
- <dt><code>-X</code></dt>
- <dt><code>--discard-locals</code></dt>
- <dd><p>Delete all temporary local symbols. (These symbols start with
- system-specific local label prefixes, typically ‘<samp>.L</samp>’ for ELF systems
- or ‘<samp>L</samp>’ for traditional a.out systems.)
- </p>
- <span id="index-_002dy-symbol"></span>
- <span id="index-_002d_002dtrace_002dsymbol_003dsymbol"></span>
- <span id="index-symbol-tracing"></span>
- </dd>
- <dt><code>-y <var>symbol</var></code></dt>
- <dt><code>--trace-symbol=<var>symbol</var></code></dt>
- <dd><p>Print the name of each linked file in which <var>symbol</var> appears. This
- option may be given any number of times. On many systems it is necessary
- to prepend an underscore.
- </p>
- <p>This option is useful when you have an undefined symbol in your link but
- don’t know where the reference is coming from.
- </p>
- <span id="index-_002dY-path"></span>
- </dd>
- <dt><code>-Y <var>path</var></code></dt>
- <dd><p>Add <var>path</var> to the default library search path. This option exists
- for Solaris compatibility.
- </p>
- <span id="index-_002dz-keyword"></span>
- </dd>
- <dt><code>-z <var>keyword</var></code></dt>
- <dd><p>The recognized keywords are:
- </p><dl compact="compact">
- <dt>‘<samp>call-nop=prefix-addr</samp>’</dt>
- <dt>‘<samp>call-nop=suffix-nop</samp>’</dt>
- <dt>‘<samp>call-nop=prefix-<var>byte</var></samp>’</dt>
- <dt>‘<samp>call-nop=suffix-<var>byte</var></samp>’</dt>
- <dd><p>Specify the 1-byte <code>NOP</code> padding when transforming indirect call
- to a locally defined function, foo, via its GOT slot.
- <samp>call-nop=prefix-addr</samp> generates <code>0x67 call foo</code>.
- <samp>call-nop=suffix-nop</samp> generates <code>call foo 0x90</code>.
- <samp>call-nop=prefix-<var>byte</var></samp> generates <code><var>byte</var> call foo</code>.
- <samp>call-nop=suffix-<var>byte</var></samp> generates <code>call foo <var>byte</var></code>.
- Supported for i386 and x86_64.
- </p>
- </dd>
- <dt>‘<samp>cet-report=none</samp>’</dt>
- <dt>‘<samp>cet-report=warning</samp>’</dt>
- <dt>‘<samp>cet-report=error</samp>’</dt>
- <dd><p>Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT and
- GNU_PROPERTY_X86_FEATURE_1_SHSTK properties in input .note.gnu.property
- section. <samp>cet-report=none</samp>, which is the default, will make the
- linker not report missing properties in input files.
- <samp>cet-report=warning</samp> will make the linker issue a warning for
- missing properties in input files. <samp>cet-report=error</samp> will make
- the linker issue an error for missing properties in input files.
- Note that <samp>ibt</samp> will turn off the missing
- GNU_PROPERTY_X86_FEATURE_1_IBT property report and <samp>shstk</samp> will
- turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report.
- Supported for Linux/i386 and Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>combreloc</samp>’</dt>
- <dt>‘<samp>nocombreloc</samp>’</dt>
- <dd><p>Combine multiple dynamic relocation sections and sort to improve
- dynamic symbol lookup caching. Do not do this if ‘<samp>nocombreloc</samp>’.
- </p>
- </dd>
- <dt>‘<samp>common</samp>’</dt>
- <dt>‘<samp>nocommon</samp>’</dt>
- <dd><p>Generate common symbols with STT_COMMON type during a relocatable
- link. Use STT_OBJECT type if ‘<samp>nocommon</samp>’.
- </p>
- </dd>
- <dt>‘<samp>common-page-size=<var>value</var></samp>’</dt>
- <dd><p>Set the page size most commonly used to <var>value</var>. Memory image
- layout will be optimized to minimize memory pages if the system is
- using pages of this size.
- </p>
- </dd>
- <dt>‘<samp>defs</samp>’</dt>
- <dd><p>Report unresolved symbol references from regular object files. This
- is done even if the linker is creating a non-symbolic shared library.
- This option is the inverse of ‘<samp>-z undefs</samp>’.
- </p>
- </dd>
- <dt>‘<samp>dynamic-undefined-weak</samp>’</dt>
- <dt>‘<samp>nodynamic-undefined-weak</samp>’</dt>
- <dd><p>Make undefined weak symbols dynamic when building a dynamic object,
- if they are referenced from a regular object file and not forced local
- by symbol visibility or versioning. Do not make them dynamic if
- ‘<samp>nodynamic-undefined-weak</samp>’. If neither option is given, a target
- may default to either option being in force, or make some other
- selection of undefined weak symbols dynamic. Not all targets support
- these options.
- </p>
- </dd>
- <dt>‘<samp>execstack</samp>’</dt>
- <dd><p>Marks the object as requiring executable stack.
- </p>
- </dd>
- <dt>‘<samp>global</samp>’</dt>
- <dd><p>This option is only meaningful when building a shared object. It makes
- the symbols defined by this shared object available for symbol resolution
- of subsequently loaded libraries.
- </p>
- </dd>
- <dt>‘<samp>globalaudit</samp>’</dt>
- <dd><p>This option is only meaningful when building a dynamic executable.
- This option marks the executable as requiring global auditing by
- setting the <code>DF_1_GLOBAUDIT</code> bit in the <code>DT_FLAGS_1</code> dynamic
- tag. Global auditing requires that any auditing library defined via
- the <samp>--depaudit</samp> or <samp>-P</samp> command-line options be run for
- all dynamic objects loaded by the application.
- </p>
- </dd>
- <dt>‘<samp>ibtplt</samp>’</dt>
- <dd><p>Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries.
- Supported for Linux/i386 and Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>ibt</samp>’</dt>
- <dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section
- to indicate compatibility with IBT. This also implies <samp>ibtplt</samp>.
- Supported for Linux/i386 and Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>indirect-extern-access</samp>’</dt>
- <dt>‘<samp>noindirect-extern-access</samp>’</dt>
- <dd><p>Generate GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS in
- .note.gnu.property section to indicate that object file requires
- canonical function pointers and cannot be used with copy relocation.
- This option also implies <samp>noextern-protected-data</samp> and
- <samp>nocopyreloc</samp>. Supported for i386 and x86-64.
- </p>
- <p><samp>noindirect-extern-access</samp> removes
- GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS from .note.gnu.property
- section.
- </p>
- </dd>
- <dt>‘<samp>initfirst</samp>’</dt>
- <dd><p>This option is only meaningful when building a shared object.
- It marks the object so that its runtime initialization will occur
- before the runtime initialization of any other objects brought into
- the process at the same time. Similarly the runtime finalization of
- the object will occur after the runtime finalization of any other
- objects.
- </p>
- </dd>
- <dt>‘<samp>interpose</samp>’</dt>
- <dd><p>Specify that the dynamic loader should modify its symbol search order
- so that symbols in this shared library interpose all other shared
- libraries not so marked.
- </p>
- </dd>
- <dt>‘<samp>unique</samp>’</dt>
- <dt>‘<samp>nounique</samp>’</dt>
- <dd><p>When generating a shared library or other dynamically loadable ELF
- object mark it as one that should (by default) only ever be loaded once,
- and only in the main namespace (when using <code>dlmopen</code>). This is
- primarily used to mark fundamental libraries such as libc, libpthread et
- al which do not usually function correctly unless they are the sole instances
- of themselves. This behaviour can be overridden by the <code>dlmopen</code> caller
- and does not apply to certain loading mechanisms (such as audit libraries).
- </p>
- </dd>
- <dt>‘<samp>lam-u48</samp>’</dt>
- <dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U48 in .note.gnu.property section
- to indicate compatibility with Intel LAM_U48. Supported for Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>lam-u57</samp>’</dt>
- <dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U57 in .note.gnu.property section
- to indicate compatibility with Intel LAM_U57. Supported for Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>lam-u48-report=none</samp>’</dt>
- <dt>‘<samp>lam-u48-report=warning</samp>’</dt>
- <dt>‘<samp>lam-u48-report=error</samp>’</dt>
- <dd><p>Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48
- property in input .note.gnu.property section.
- <samp>lam-u48-report=none</samp>, which is the default, will make the
- linker not report missing properties in input files.
- <samp>lam-u48-report=warning</samp> will make the linker issue a warning for
- missing properties in input files. <samp>lam-u48-report=error</samp> will
- make the linker issue an error for missing properties in input files.
- Supported for Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>lam-u57-report=none</samp>’</dt>
- <dt>‘<samp>lam-u57-report=warning</samp>’</dt>
- <dt>‘<samp>lam-u57-report=error</samp>’</dt>
- <dd><p>Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U57
- property in input .note.gnu.property section.
- <samp>lam-u57-report=none</samp>, which is the default, will make the
- linker not report missing properties in input files.
- <samp>lam-u57-report=warning</samp> will make the linker issue a warning for
- missing properties in input files. <samp>lam-u57-report=error</samp> will
- make the linker issue an error for missing properties in input files.
- Supported for Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>lam-report=none</samp>’</dt>
- <dt>‘<samp>lam-report=warning</samp>’</dt>
- <dt>‘<samp>lam-report=error</samp>’</dt>
- <dd><p>Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 and
- GNU_PROPERTY_X86_FEATURE_1_LAM_U57 properties in input .note.gnu.property
- section. <samp>lam-report=none</samp>, which is the default, will make the
- linker not report missing properties in input files.
- <samp>lam-report=warning</samp> will make the linker issue a warning for
- missing properties in input files. <samp>lam-report=error</samp> will make
- the linker issue an error for missing properties in input files.
- Supported for Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>lazy</samp>’</dt>
- <dd><p>When generating an executable or shared library, mark it to tell the
- dynamic linker to defer function call resolution to the point when
- the function is called (lazy binding), rather than at load time.
- Lazy binding is the default.
- </p>
- </dd>
- <dt>‘<samp>loadfltr</samp>’</dt>
- <dd><p>Specify that the object’s filters be processed immediately at runtime.
- </p>
- </dd>
- <dt>‘<samp>max-page-size=<var>value</var></samp>’</dt>
- <dd><p>Set the maximum memory page size supported to <var>value</var>.
- </p>
- </dd>
- <dt>‘<samp>mark-plt</samp>’</dt>
- <dt>‘<samp>nomark-plt</samp>’</dt>
- <dd><p>Mark PLT entries with dynamic tags, DT_X86_64_PLT, DT_X86_64_PLTSZ and
- DT_X86_64_PLTENT. Since this option stores a non-zero value in the
- r_addend field of R_X86_64_JUMP_SLOT relocations, the resulting
- executables and shared libraries are incompatible with dynamic linkers,
- such as those in older versions of glibc without the change to ignore
- r_addend in R_X86_64_GLOB_DAT and R_X86_64_JUMP_SLOT relocations, which
- don’t ignore the r_addend field of R_X86_64_JUMP_SLOT relocations.
- Supported for x86_64.
- </p>
- </dd>
- <dt>‘<samp>muldefs</samp>’</dt>
- <dd><p>Allow multiple definitions.
- </p>
- </dd>
- <dt>‘<samp>nocopyreloc</samp>’</dt>
- <dd><p>Disable linker generated .dynbss variables used in place of variables
- defined in shared libraries. May result in dynamic text relocations.
- </p>
- </dd>
- <dt>‘<samp>nodefaultlib</samp>’</dt>
- <dd><p>Specify that the dynamic loader search for dependencies of this object
- should ignore any default library search paths.
- </p>
- </dd>
- <dt>‘<samp>nodelete</samp>’</dt>
- <dd><p>Specify that the object shouldn’t be unloaded at runtime.
- </p>
- </dd>
- <dt>‘<samp>nodlopen</samp>’</dt>
- <dd><p>Specify that the object is not available to <code>dlopen</code>.
- </p>
- </dd>
- <dt>‘<samp>nodump</samp>’</dt>
- <dd><p>Specify that the object can not be dumped by <code>dldump</code>.
- </p>
- </dd>
- <dt>‘<samp>noexecstack</samp>’</dt>
- <dd><p>Marks the object as not requiring executable stack.
- </p>
- </dd>
- <dt>‘<samp>noextern-protected-data</samp>’</dt>
- <dd><p>Don’t treat protected data symbols as external when building a shared
- library. This option overrides the linker backend default. It can be
- used to work around incorrect relocations against protected data symbols
- generated by compiler. Updates on protected data symbols by another
- module aren’t visible to the resulting shared library. Supported for
- i386 and x86-64.
- </p>
- </dd>
- <dt>‘<samp>noreloc-overflow</samp>’</dt>
- <dd><p>Disable relocation overflow check. This can be used to disable
- relocation overflow check if there will be no dynamic relocation
- overflow at run-time. Supported for x86_64.
- </p>
- </dd>
- <dt>‘<samp>now</samp>’</dt>
- <dd><p>When generating an executable or shared library, mark it to tell the
- dynamic linker to resolve all symbols when the program is started, or
- when the shared library is loaded by dlopen, instead of deferring
- function call resolution to the point when the function is first
- called.
- </p>
- </dd>
- <dt>‘<samp>origin</samp>’</dt>
- <dd><p>Specify that the object requires ‘<samp>$ORIGIN</samp>’ handling in paths.
- </p>
- </dd>
- <dt>‘<samp>pack-relative-relocs</samp>’</dt>
- <dt>‘<samp>nopack-relative-relocs</samp>’</dt>
- <dd><p>Generate compact relative relocation in position-independent executable
- and shared library. It adds <code>DT_RELR</code>, <code>DT_RELRSZ</code> and
- <code>DT_RELRENT</code> entries to the dynamic section. It is ignored when
- building position-dependent executable and relocatable output.
- <samp>nopack-relative-relocs</samp> is the default, which disables compact
- relative relocation. When linked against the GNU C Library, a
- GLIBC_ABI_DT_RELR symbol version dependency on the shared C Library is
- added to the output. Supported for i386 and x86-64.
- </p>
- </dd>
- <dt>‘<samp>relro</samp>’</dt>
- <dt>‘<samp>norelro</samp>’</dt>
- <dd><p>Create an ELF <code>PT_GNU_RELRO</code> segment header in the object. This
- specifies a memory segment that should be made read-only after
- relocation, if supported. Specifying ‘<samp>common-page-size</samp>’ smaller
- than the system page size will render this protection ineffective.
- Don’t create an ELF <code>PT_GNU_RELRO</code> segment if ‘<samp>norelro</samp>’.
- </p>
- </dd>
- <dt>‘<samp>report-relative-reloc</samp>’</dt>
- <dd><p>Report dynamic relative relocations generated by linker. Supported for
- Linux/i386 and Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>sectionheader</samp>’</dt>
- <dt>‘<samp>nosectionheader</samp>’</dt>
- <dd><p>Generate section header. Don’t generate section header if
- ‘<samp>nosectionheader</samp>’ is used. <samp>sectionheader</samp> is the default.
- </p>
- </dd>
- <dt>‘<samp>separate-code</samp>’</dt>
- <dt>‘<samp>noseparate-code</samp>’</dt>
- <dd><p>Create separate code <code>PT_LOAD</code> segment header in the object. This
- specifies a memory segment that should contain only instructions and must
- be in wholly disjoint pages from any other data. Don’t create separate
- code <code>PT_LOAD</code> segment if ‘<samp>noseparate-code</samp>’ is used.
- </p>
- </dd>
- <dt>‘<samp>shstk</samp>’</dt>
- <dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section
- to indicate compatibility with Intel Shadow Stack. Supported for
- Linux/i386 and Linux/x86_64.
- </p>
- </dd>
- <dt>‘<samp>stack-size=<var>value</var></samp>’</dt>
- <dd><p>Specify a stack size for an ELF <code>PT_GNU_STACK</code> segment.
- Specifying zero will override any default non-zero sized
- <code>PT_GNU_STACK</code> segment creation.
- </p>
- </dd>
- <dt>‘<samp>start-stop-gc</samp>’</dt>
- <dt>‘<samp>nostart-stop-gc</samp>’</dt>
- <dd><span id="index-start_002dstop_002dgc"></span>
- <p>When ‘<samp>--gc-sections</samp>’ is in effect, a reference from a retained
- section to <code>__start_SECNAME</code> or <code>__stop_SECNAME</code> causes all
- input sections named <code>SECNAME</code> to also be retained, if
- <code>SECNAME</code> is representable as a C identifier and either
- <code>__start_SECNAME</code> or <code>__stop_SECNAME</code> is synthesized by the
- linker. ‘<samp>-z start-stop-gc</samp>’ disables this effect, allowing
- sections to be garbage collected as if the special synthesized symbols
- were not defined. ‘<samp>-z start-stop-gc</samp>’ has no effect on a
- definition of <code>__start_SECNAME</code> or <code>__stop_SECNAME</code> in an
- object file or linker script. Such a definition will prevent the
- linker providing a synthesized <code>__start_SECNAME</code> or
- <code>__stop_SECNAME</code> respectively, and therefore the special
- treatment by garbage collection for those references.
- </p>
- </dd>
- <dt>‘<samp>start-stop-visibility=<var>value</var></samp>’</dt>
- <dd><span id="index-visibility"></span>
- <span id="index-ELF-symbol-visibility"></span>
- <p>Specify the ELF symbol visibility for synthesized
- <code>__start_SECNAME</code> and <code>__stop_SECNAME</code> symbols (see <a href="#Input-Section-Example">Input Section Example</a>). <var>value</var> must be exactly ‘<samp>default</samp>’,
- ‘<samp>internal</samp>’, ‘<samp>hidden</samp>’, or ‘<samp>protected</samp>’. If no ‘<samp>-z
- start-stop-visibility</samp>’ option is given, ‘<samp>protected</samp>’ is used for
- compatibility with historical practice. However, it’s highly
- recommended to use ‘<samp>-z start-stop-visibility=hidden</samp>’ in new
- programs and shared libraries so that these symbols are not exported
- between shared objects, which is not usually what’s intended.
- </p>
- </dd>
- <dt>‘<samp>text</samp>’</dt>
- <dt>‘<samp>notext</samp>’</dt>
- <dt>‘<samp>textoff</samp>’</dt>
- <dd><p>Report an error if DT_TEXTREL is set, i.e., if the position-independent
- or shared object has dynamic relocations in read-only sections. Don’t
- report an error if ‘<samp>notext</samp>’ or ‘<samp>textoff</samp>’.
- </p>
- </dd>
- <dt>‘<samp>undefs</samp>’</dt>
- <dd><p>Do not report unresolved symbol references from regular object files,
- either when creating an executable, or when creating a shared library.
- This option is the inverse of ‘<samp>-z defs</samp>’.
- </p>
- </dd>
- <dt>‘<samp>unique-symbol</samp>’</dt>
- <dt>‘<samp>nounique-symbol</samp>’</dt>
- <dd><p>Avoid duplicated local symbol names in the symbol string table. Append
- ".<code>number</code>" to duplicated local symbol names if ‘<samp>unique-symbol</samp>’
- is used. <samp>nounique-symbol</samp> is the default.
- </p>
- </dd>
- <dt>‘<samp>x86-64-baseline</samp>’</dt>
- <dt>‘<samp>x86-64-v2</samp>’</dt>
- <dt>‘<samp>x86-64-v3</samp>’</dt>
- <dt>‘<samp>x86-64-v4</samp>’</dt>
- <dd><p>Specify the x86-64 ISA level needed in .note.gnu.property section.
- <samp>x86-64-baseline</samp> generates <code>GNU_PROPERTY_X86_ISA_1_BASELINE</code>.
- <samp>x86-64-v2</samp> generates <code>GNU_PROPERTY_X86_ISA_1_V2</code>.
- <samp>x86-64-v3</samp> generates <code>GNU_PROPERTY_X86_ISA_1_V3</code>.
- <samp>x86-64-v4</samp> generates <code>GNU_PROPERTY_X86_ISA_1_V4</code>.
- Supported for Linux/i386 and Linux/x86_64.
- </p>
- </dd>
- </dl>
- <p>Other keywords are ignored for Solaris compatibility.
- </p>
- <span id="index-_002d_0028"></span>
- <span id="index-groups-of-archives"></span>
- </dd>
- <dt><code>-( <var>archives</var> -)</code></dt>
- <dt><code>--start-group <var>archives</var> --end-group</code></dt>
- <dd><p>The <var>archives</var> should be a list of archive files. They may be
- either explicit file names, or ‘<samp>-l</samp>’ options.
- </p>
- <p>The specified archives are searched repeatedly until no new undefined
- references are created. Normally, an archive is searched only once in
- the order that it is specified on the command line. If a symbol in that
- archive is needed to resolve an undefined symbol referred to by an
- object in an archive that appears later on the command line, the linker
- would not be able to resolve that reference. By grouping the archives,
- they will all be searched repeatedly until all possible references are
- resolved.
- </p>
- <p>Using this option has a significant performance cost. It is best to use
- it only when there are unavoidable circular references between two or
- more archives.
- </p>
- <span id="index-_002d_002daccept_002dunknown_002dinput_002darch"></span>
- <span id="index-_002d_002dno_002daccept_002dunknown_002dinput_002darch"></span>
- </dd>
- <dt><code>--accept-unknown-input-arch</code></dt>
- <dt><code>--no-accept-unknown-input-arch</code></dt>
- <dd><p>Tells the linker to accept input files whose architecture cannot be
- recognised. The assumption is that the user knows what they are doing
- and deliberately wants to link in these unknown input files. This was
- the default behaviour of the linker, before release 2.14. The default
- behaviour from release 2.14 onwards is to reject such input files, and
- so the ‘<samp>--accept-unknown-input-arch</samp>’ option has been added to
- restore the old behaviour.
- </p>
- <span id="index-_002d_002das_002dneeded"></span>
- <span id="index-_002d_002dno_002das_002dneeded"></span>
- </dd>
- <dt><code>--as-needed</code></dt>
- <dt><code>--no-as-needed</code></dt>
- <dd><p>This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
- on the command line after the <samp>--as-needed</samp> option. Normally
- the linker will add a DT_NEEDED tag for each dynamic library mentioned
- on the command line, regardless of whether the library is actually
- needed or not. <samp>--as-needed</samp> causes a DT_NEEDED tag to only be
- emitted for a library that <em>at that point in the link</em> satisfies a
- non-weak undefined symbol reference from a regular object file or, if
- the library is not found in the DT_NEEDED lists of other needed libraries, a
- non-weak undefined symbol reference from another needed dynamic library.
- Object files or libraries appearing on the command line <em>after</em>
- the library in question do not affect whether the library is seen as
- needed. This is similar to the rules for extraction of object files
- from archives. <samp>--no-as-needed</samp> restores the default behaviour.
- </p>
- <p>Note: On Linux based systems the <samp>--as-needed</samp> option also has
- an affect on the behaviour of the <samp>--rpath</samp> and
- <samp>--rpath-link</samp> options. See the description of
- <samp>--rpath-link</samp> for more details.
- </p>
- <span id="index-_002d_002dadd_002dneeded"></span>
- <span id="index-_002d_002dno_002dadd_002dneeded"></span>
- </dd>
- <dt><code>--add-needed</code></dt>
- <dt><code>--no-add-needed</code></dt>
- <dd><p>These two options have been deprecated because of the similarity of
- their names to the <samp>--as-needed</samp> and <samp>--no-as-needed</samp>
- options. They have been replaced by <samp>--copy-dt-needed-entries</samp>
- and <samp>--no-copy-dt-needed-entries</samp>.
- </p>
- <span id="index-_002dassert-keyword"></span>
- </dd>
- <dt><code>-assert <var>keyword</var></code></dt>
- <dd><p>This option is ignored for SunOS compatibility.
- </p>
- <span id="index-_002dBdynamic"></span>
- <span id="index-_002ddy"></span>
- <span id="index-_002dcall_005fshared"></span>
- </dd>
- <dt><code>-Bdynamic</code></dt>
- <dt><code>-dy</code></dt>
- <dt><code>-call_shared</code></dt>
- <dd><p>Link against dynamic libraries. This is only meaningful on platforms
- for which shared libraries are supported. This option is normally the
- default on such platforms. The different variants of this option are
- for compatibility with various systems. You may use this option
- multiple times on the command line: it affects library searching for
- <samp>-l</samp> options which follow it.
- </p>
- <span id="index-_002dBgroup"></span>
- </dd>
- <dt><code>-Bgroup</code></dt>
- <dd><p>Set the <code>DF_1_GROUP</code> flag in the <code>DT_FLAGS_1</code> entry in the dynamic
- section. This causes the runtime linker to handle lookups in this
- object and its dependencies to be performed only inside the group.
- <samp>--unresolved-symbols=report-all</samp> is implied. This option is
- only meaningful on ELF platforms which support shared libraries.
- </p>
- <span id="index-_002dBstatic"></span>
- <span id="index-_002ddn"></span>
- <span id="index-_002dnon_005fshared"></span>
- <span id="index-_002dstatic"></span>
- </dd>
- <dt><code>-Bstatic</code></dt>
- <dt><code>-dn</code></dt>
- <dt><code>-non_shared</code></dt>
- <dt><code>-static</code></dt>
- <dd><p>Do not link against shared libraries. This is only meaningful on
- platforms for which shared libraries are supported. The different
- variants of this option are for compatibility with various systems. You
- may use this option multiple times on the command line: it affects
- library searching for <samp>-l</samp> options which follow it. This
- option also implies <samp>--unresolved-symbols=report-all</samp>. This
- option can be used with <samp>-shared</samp>. Doing so means that a
- shared library is being created but that all of the library’s external
- references must be resolved by pulling in entries from static
- libraries.
- </p>
- <span id="index-_002dBsymbolic"></span>
- </dd>
- <dt><code>-Bsymbolic</code></dt>
- <dd><p>When creating a shared library, bind references to global symbols to the
- definition within the shared library, if any. Normally, it is possible
- for a program linked against a shared library to override the definition
- within the shared library. This option is only meaningful on ELF
- platforms which support shared libraries.
- </p>
- <span id="index-_002dBsymbolic_002dfunctions"></span>
- </dd>
- <dt><code>-Bsymbolic-functions</code></dt>
- <dd><p>When creating a shared library, bind references to global function
- symbols to the definition within the shared library, if any.
- This option is only meaningful on ELF platforms which support shared
- libraries.
- </p>
- <span id="index-_002dBno_002dsymbolic"></span>
- </dd>
- <dt><code>-Bno-symbolic</code></dt>
- <dd><p>This option can cancel previously specified ‘<samp>-Bsymbolic</samp>’ and
- ‘<samp>-Bsymbolic-functions</samp>’.
- </p>
- <span id="index-_002d_002ddynamic_002dlist_003ddynamic_002dlist_002dfile"></span>
- </dd>
- <dt><code>--dynamic-list=<var>dynamic-list-file</var></code></dt>
- <dd><p>Specify the name of a dynamic list file to the linker. This is
- typically used when creating shared libraries to specify a list of
- global symbols whose references shouldn’t be bound to the definition
- within the shared library, or creating dynamically linked executables
- to specify a list of symbols which should be added to the symbol table
- in the executable. This option is only meaningful on ELF platforms
- which support shared libraries.
- </p>
- <p>The format of the dynamic list is the same as the version node without
- scope and node name. See <a href="#VERSION">VERSION</a> for more information.
- </p>
- <span id="index-_002d_002ddynamic_002dlist_002ddata"></span>
- </dd>
- <dt><code>--dynamic-list-data</code></dt>
- <dd><p>Include all global data symbols to the dynamic list.
- </p>
- <span id="index-_002d_002ddynamic_002dlist_002dcpp_002dnew"></span>
- </dd>
- <dt><code>--dynamic-list-cpp-new</code></dt>
- <dd><p>Provide the builtin dynamic list for C++ operator new and delete. It
- is mainly useful for building shared libstdc++.
- </p>
- <span id="index-_002d_002ddynamic_002dlist_002dcpp_002dtypeinfo"></span>
- </dd>
- <dt><code>--dynamic-list-cpp-typeinfo</code></dt>
- <dd><p>Provide the builtin dynamic list for C++ runtime type identification.
- </p>
- <span id="index-_002d_002dcheck_002dsections"></span>
- <span id="index-_002d_002dno_002dcheck_002dsections"></span>
- </dd>
- <dt><code>--check-sections</code></dt>
- <dt><code>--no-check-sections</code></dt>
- <dd><p>Asks the linker <em>not</em> to check section addresses after they have
- been assigned to see if there are any overlaps. Normally the linker will
- perform this check, and if it finds any overlaps it will produce
- suitable error messages. The linker does know about, and does make
- allowances for sections in overlays. The default behaviour can be
- restored by using the command-line switch <samp>--check-sections</samp>.
- Section overlap is not usually checked for relocatable links. You can
- force checking in that case by using the <samp>--check-sections</samp>
- option.
- </p>
- <span id="index-_002d_002dcopy_002ddt_002dneeded_002dentries"></span>
- <span id="index-_002d_002dno_002dcopy_002ddt_002dneeded_002dentries"></span>
- </dd>
- <dt><code>--copy-dt-needed-entries</code></dt>
- <dt><code>--no-copy-dt-needed-entries</code></dt>
- <dd><p>This option affects the treatment of dynamic libraries referred to
- by DT_NEEDED tags <em>inside</em> ELF dynamic libraries mentioned on the
- command line. Normally the linker won’t add a DT_NEEDED tag to the
- output binary for each library mentioned in a DT_NEEDED tag in an
- input dynamic library. With <samp>--copy-dt-needed-entries</samp>
- specified on the command line however any dynamic libraries that
- follow it will have their DT_NEEDED entries added. The default
- behaviour can be restored with <samp>--no-copy-dt-needed-entries</samp>.
- </p>
- <p>This option also has an effect on the resolution of symbols in dynamic
- libraries. With <samp>--copy-dt-needed-entries</samp> dynamic libraries
- mentioned on the command line will be recursively searched, following
- their DT_NEEDED tags to other libraries, in order to resolve symbols
- required by the output binary. With the default setting however
- the searching of dynamic libraries that follow it will stop with the
- dynamic library itself. No DT_NEEDED links will be traversed to resolve
- symbols.
- </p>
- <span id="index-cross-reference-table"></span>
- <span id="index-_002d_002dcref"></span>
- </dd>
- <dt><code>--cref</code></dt>
- <dd><p>Output a cross reference table. If a linker map file is being
- generated, the cross reference table is printed to the map file.
- Otherwise, it is printed on the standard output.
- </p>
- <p>The format of the table is intentionally simple, so that it may be
- easily processed by a script if necessary. The symbols are printed out,
- sorted by name. For each symbol, a list of file names is given. If the
- symbol is defined, the first file listed is the location of the
- definition. If the symbol is defined as a common value then any files
- where this happens appear next. Finally any files that reference the
- symbol are listed.
- </p>
- <span id="index-ctf-variables"></span>
- <span id="index-_002d_002dctf_002dvariables"></span>
- <span id="index-_002d_002dno_002dctf_002dvariables"></span>
- </dd>
- <dt><code>--ctf-variables</code></dt>
- <dt><code>--no-ctf-variables</code></dt>
- <dd><p>The CTF debuginfo format supports a section which encodes the names and
- types of variables found in the program which do not appear in any symbol
- table. These variables clearly cannot be looked up by address by
- conventional debuggers, so the space used for their types and names is
- usually wasted: the types are usually small but the names are often not.
- <samp>--ctf-variables</samp> causes the generation of such a section.
- The default behaviour can be restored with <samp>--no-ctf-variables</samp>.
- </p>
- <span id="index-ctf-type-sharing"></span>
- <span id="index-_002d_002dctf_002dshare_002dtypes"></span>
- </dd>
- <dt><code>--ctf-share-types=<var>method</var></code></dt>
- <dd><p>Adjust the method used to share types between translation units in CTF.
- </p>
- <dl compact="compact">
- <dt>‘<samp>share-unconflicted</samp>’</dt>
- <dd><p>Put all types that do not have ambiguous definitions into the shared dictionary,
- where debuggers can easily access them, even if they only occur in one
- translation unit. This is the default.
- </p>
- </dd>
- <dt>‘<samp>share-duplicated</samp>’</dt>
- <dd><p>Put only types that occur in multiple translation units into the shared
- dictionary: types with only one definition go into per-translation-unit
- dictionaries. Types with ambiguous definitions in multiple translation units
- always go into per-translation-unit dictionaries. This tends to make the CTF
- larger, but may reduce the amount of CTF in the shared dictionary. For very
- large projects this may speed up opening the CTF and save memory in the CTF
- consumer at runtime.
- </p></dd>
- </dl>
- <span id="index-common-allocation-1"></span>
- <span id="index-_002d_002dno_002ddefine_002dcommon"></span>
- </dd>
- <dt><code>--no-define-common</code></dt>
- <dd><p>This option inhibits the assignment of addresses to common symbols.
- The script command <code>INHIBIT_COMMON_ALLOCATION</code> has the same effect.
- See <a href="#Miscellaneous-Commands">Miscellaneous Commands</a>.
- </p>
- <p>The ‘<samp>--no-define-common</samp>’ option allows decoupling
- the decision to assign addresses to Common symbols from the choice
- of the output file type; otherwise a non-Relocatable output type
- forces assigning addresses to Common symbols.
- Using ‘<samp>--no-define-common</samp>’ allows Common symbols that are referenced
- from a shared library to be assigned addresses only in the main program.
- This eliminates the unused duplicate space in the shared library,
- and also prevents any possible confusion over resolving to the wrong
- duplicate when there are many dynamic modules with specialized search
- paths for runtime symbol resolution.
- </p>
- <span id="index-group-allocation-in-linker-script"></span>
- <span id="index-section-groups"></span>
- <span id="index-COMDAT"></span>
- <span id="index-_002d_002dforce_002dgroup_002dallocation"></span>
- </dd>
- <dt><code>--force-group-allocation</code></dt>
- <dd><p>This option causes the linker to place section group members like
- normal input sections, and to delete the section groups. This is the
- default behaviour for a final link but this option can be used to
- change the behaviour of a relocatable link (‘<samp>-r</samp>’). The script
- command <code>FORCE_GROUP_ALLOCATION</code> has the same
- effect. See <a href="#Miscellaneous-Commands">Miscellaneous Commands</a>.
- </p>
- <span id="index-symbols_002c-from-command-line"></span>
- <span id="index-_002d_002ddefsym_003dsymbol_003dexp"></span>
- </dd>
- <dt><code>--defsym=<var>symbol</var>=<var>expression</var></code></dt>
- <dd><p>Create a global symbol in the output file, containing the absolute
- address given by <var>expression</var>. You may use this option as many
- times as necessary to define multiple symbols in the command line. A
- limited form of arithmetic is supported for the <var>expression</var> in this
- context: you may give a hexadecimal constant or the name of an existing
- symbol, or use <code>+</code> and <code>-</code> to add or subtract hexadecimal
- constants or symbols. If you need more elaborate expressions, consider
- using the linker command language from a script (see <a href="#Assignments">Assignments</a>).
- <em>Note:</em> there should be no white space between <var>symbol</var>, the
- equals sign (“<tt class="key">=</tt>”), and <var>expression</var>.
- </p>
- <p>The linker processes ‘<samp>--defsym</samp>’ arguments and ‘<samp>-T</samp>’ arguments
- in order, placing ‘<samp>--defsym</samp>’ before ‘<samp>-T</samp>’ will define the
- symbol before the linker script from ‘<samp>-T</samp>’ is processed, while
- placing ‘<samp>--defsym</samp>’ after ‘<samp>-T</samp>’ will define the symbol after
- the linker script has been processed. This difference has
- consequences for expressions within the linker script that use the
- ‘<samp>--defsym</samp>’ symbols, which order is correct will depend on what
- you are trying to achieve.
- </p>
- <span id="index-demangling_002c-from-command-line"></span>
- <span id="index-_002d_002ddemangle_005b_003dstyle_005d"></span>
- <span id="index-_002d_002dno_002ddemangle"></span>
- </dd>
- <dt><code>--demangle[=<var>style</var>]</code></dt>
- <dt><code>--no-demangle</code></dt>
- <dd><p>These options control whether to demangle symbol names in error messages
- and other output. When the linker is told to demangle, it tries to
- present symbol names in a readable fashion: it strips leading
- underscores if they are used by the object file format, and converts C++
- mangled symbol names into user readable names. Different compilers have
- different mangling styles. The optional demangling style argument can be used
- to choose an appropriate demangling style for your compiler. The linker will
- demangle by default unless the environment variable ‘<samp>COLLECT_NO_DEMANGLE</samp>’
- is set. These options may be used to override the default.
- </p>
- <span id="index-dynamic-linker_002c-from-command-line"></span>
- <span id="index-_002dIfile"></span>
- <span id="index-_002d_002ddynamic_002dlinker_003dfile"></span>
- </dd>
- <dt><code>-I<var>file</var></code></dt>
- <dt><code>--dynamic-linker=<var>file</var></code></dt>
- <dd><p>Set the name of the dynamic linker. This is only meaningful when
- generating dynamically linked ELF executables. The default dynamic
- linker is normally correct; don’t use this unless you know what you are
- doing.
- </p>
- <span id="index-_002d_002dno_002ddynamic_002dlinker"></span>
- </dd>
- <dt><code>--no-dynamic-linker</code></dt>
- <dd><p>When producing an executable file, omit the request for a dynamic
- linker to be used at load-time. This is only meaningful for ELF
- executables that contain dynamic relocations, and usually requires
- entry point code that is capable of processing these relocations.
- </p>
- <span id="index-_002d_002dembedded_002drelocs"></span>
- </dd>
- <dt><code>--embedded-relocs</code></dt>
- <dd><p>This option is similar to the <samp>--emit-relocs</samp> option except
- that the relocs are stored in a target-specific section. This option
- is only supported by the ‘<samp>BFIN</samp>’, ‘<samp>CR16</samp>’ and <em>M68K</em>
- targets.
- </p>
- <span id="index-_002d_002ddisable_002dmultiple_002dabs_002ddefs"></span>
- </dd>
- <dt><code>--disable-multiple-abs-defs</code></dt>
- <dd><p>Do not allow multiple definitions with symbols included
- in filename invoked by -R or –just-symbols
- </p>
- <span id="index-_002d_002dfatal_002dwarnings"></span>
- <span id="index-_002d_002dno_002dfatal_002dwarnings"></span>
- </dd>
- <dt><code>--fatal-warnings</code></dt>
- <dt><code>--no-fatal-warnings</code></dt>
- <dd><p>Treat all warnings as errors. The default behaviour can be restored
- with the option <samp>--no-fatal-warnings</samp>.
- </p>
- <span id="index-_002dw"></span>
- <span id="index-_002d_002dno_002dwarnings"></span>
- </dd>
- <dt><code>-w</code></dt>
- <dt><code>--no-warnings</code></dt>
- <dd><p>Do not display any warning or error messages. This overrides
- <samp>--fatal-warnings</samp> if it has been enabled. This option can be
- used when it is known that the output binary will not work, but there
- is still a need to create it.
- </p>
- <span id="index-_002d_002dforce_002dexe_002dsuffix"></span>
- </dd>
- <dt><code>--force-exe-suffix</code></dt>
- <dd><p>Make sure that an output file has a .exe suffix.
- </p>
- <p>If a successfully built fully linked output file does not have a
- <code>.exe</code> or <code>.dll</code> suffix, this option forces the linker to copy
- the output file to one of the same name with a <code>.exe</code> suffix. This
- option is useful when using unmodified Unix makefiles on a Microsoft
- Windows host, since some versions of Windows won’t run an image unless
- it ends in a <code>.exe</code> suffix.
- </p>
- <span id="index-_002d_002dgc_002dsections"></span>
- <span id="index-_002d_002dno_002dgc_002dsections"></span>
- <span id="index-garbage-collection"></span>
- </dd>
- <dt><code>--gc-sections</code></dt>
- <dt><code>--no-gc-sections</code></dt>
- <dd><p>Enable garbage collection of unused input sections. It is ignored on
- targets that do not support this option. The default behaviour (of not
- performing this garbage collection) can be restored by specifying
- ‘<samp>--no-gc-sections</samp>’ on the command line. Note that garbage
- collection for COFF and PE format targets is supported, but the
- implementation is currently considered to be experimental.
- </p>
- <p>‘<samp>--gc-sections</samp>’ decides which input sections are used by
- examining symbols and relocations. The section containing the entry
- symbol and all sections containing symbols undefined on the
- command-line will be kept, as will sections containing symbols
- referenced by dynamic objects. Note that when building shared
- libraries, the linker must assume that any visible symbol is
- referenced. Once this initial set of sections has been determined,
- the linker recursively marks as used any section referenced by their
- relocations. See ‘<samp>--entry</samp>’, ‘<samp>--undefined</samp>’, and
- ‘<samp>--gc-keep-exported</samp>’.
- </p>
- <p>This option can be set when doing a partial link (enabled with option
- ‘<samp>-r</samp>’). In this case the root of symbols kept must be explicitly
- specified either by one of the options ‘<samp>--entry</samp>’,
- ‘<samp>--undefined</samp>’, or ‘<samp>--gc-keep-exported</samp>’ or by a <code>ENTRY</code>
- command in the linker script.
- </p>
- <p>As a GNU extension, ELF input sections marked with the
- <code>SHF_GNU_RETAIN</code> flag will not be garbage collected.
- </p>
- <span id="index-_002d_002dprint_002dgc_002dsections"></span>
- <span id="index-_002d_002dno_002dprint_002dgc_002dsections"></span>
- <span id="index-garbage-collection-1"></span>
- </dd>
- <dt><code>--print-gc-sections</code></dt>
- <dt><code>--no-print-gc-sections</code></dt>
- <dd><p>List all sections removed by garbage collection. The listing is
- printed on stderr. This option is only effective if garbage
- collection has been enabled via the ‘<samp>--gc-sections</samp>’) option. The
- default behaviour (of not listing the sections that are removed) can
- be restored by specifying ‘<samp>--no-print-gc-sections</samp>’ on the command
- line.
- </p>
- <span id="index-_002d_002dgc_002dkeep_002dexported"></span>
- <span id="index-garbage-collection-2"></span>
- </dd>
- <dt><code>--gc-keep-exported</code></dt>
- <dd><p>When ‘<samp>--gc-sections</samp>’ is enabled, this option prevents garbage
- collection of unused input sections that contain global symbols having
- default or protected visibility. This option is intended to be used for
- executables where unreferenced sections would otherwise be garbage
- collected regardless of the external visibility of contained symbols.
- Note that this option has no effect when linking shared objects since
- it is already the default behaviour. This option is only supported for
- ELF format targets.
- </p>
- <span id="index-_002d_002dprint_002doutput_002dformat"></span>
- <span id="index-output-format"></span>
- </dd>
- <dt><code>--print-output-format</code></dt>
- <dd><p>Print the name of the default output format (perhaps influenced by
- other command-line options). This is the string that would appear
- in an <code>OUTPUT_FORMAT</code> linker script command (see <a href="#File-Commands">File Commands</a>).
- </p>
- <span id="index-_002d_002dprint_002dmemory_002dusage"></span>
- <span id="index-memory-usage"></span>
- </dd>
- <dt><code>--print-memory-usage</code></dt>
- <dd><p>Print used size, total size and used size of memory regions created with
- the <a href="#MEMORY">MEMORY</a> command. This is useful on embedded targets to have a
- quick view of amount of free memory. The format of the output has one
- headline and one line per region. It is both human readable and easily
- parsable by tools. Here is an example of an output:
- </p>
- <div class="example">
- <pre class="example">Memory region Used Size Region Size %age Used
- ROM: 256 KB 1 MB 25.00%
- RAM: 32 B 2 GB 0.00%
- </pre></div>
- <span id="index-help"></span>
- <span id="index-usage"></span>
- <span id="index-_002d_002dhelp"></span>
- </dd>
- <dt><code>--help</code></dt>
- <dd><p>Print a summary of the command-line options on the standard output and exit.
- </p>
- <span id="index-_002d_002dtarget_002dhelp"></span>
- </dd>
- <dt><code>--target-help</code></dt>
- <dd><p>Print a summary of all target-specific options on the standard output and exit.
- </p>
- <span id="index-_002dMap_003dmapfile"></span>
- </dd>
- <dt><code>-Map=<var>mapfile</var></code></dt>
- <dd><p>Print a link map to the file <var>mapfile</var>. See the description of the
- <samp>-M</samp> option, above. If <var>mapfile</var> is just the character
- <code>-</code> then the map will be written to stdout.
- </p>
- <p>Specifying a directory as <var>mapfile</var> causes the linker map to be
- written as a file inside the directory. Normally name of the file
- inside the directory is computed as the basename of the <var>output</var>
- file with <code>.map</code> appended. If however the special character
- <code>%</code> is used then this will be replaced by the full path of the
- output file. Additionally if there are any characters after the
- <var>%</var> symbol then <code>.map</code> will no longer be appended.
- </p>
- <div class="example">
- <pre class="example"> -o foo.exe -Map=bar [Creates ./bar]
- -o ../dir/foo.exe -Map=bar [Creates ./bar]
- -o foo.exe -Map=../dir [Creates ../dir/foo.exe.map]
- -o ../dir2/foo.exe -Map=../dir [Creates ../dir/foo.exe.map]
- -o foo.exe -Map=% [Creates ./foo.exe.map]
- -o ../dir/foo.exe -Map=% [Creates ../dir/foo.exe.map]
- -o foo.exe -Map=%.bar [Creates ./foo.exe.bar]
- -o ../dir/foo.exe -Map=%.bar [Creates ../dir/foo.exe.bar]
- -o ../dir2/foo.exe -Map=../dir/% [Creates ../dir/../dir2/foo.exe.map]
- -o ../dir2/foo.exe -Map=../dir/%.bar [Creates ../dir/../dir2/foo.exe.bar]
- </pre></div>
- <p>It is an error to specify more than one <code>%</code> character.
- </p>
- <p>If the map file already exists then it will be overwritten by this
- operation.
- </p>
- <span id="index-memory-usage-1"></span>
- <span id="index-_002d_002dno_002dkeep_002dmemory"></span>
- </dd>
- <dt><code>--no-keep-memory</code></dt>
- <dd><p><code>ld</code> normally optimizes for speed over memory usage by caching the
- symbol tables of input files in memory. This option tells <code>ld</code> to
- instead optimize for memory usage, by rereading the symbol tables as
- necessary. This may be required if <code>ld</code> runs out of memory space
- while linking a large executable.
- </p>
- <span id="index-_002d_002dno_002dundefined"></span>
- <span id="index-_002dz-defs"></span>
- <span id="index-_002dz-undefs"></span>
- </dd>
- <dt><code>--no-undefined</code></dt>
- <dt><code>-z defs</code></dt>
- <dd><p>Report unresolved symbol references from regular object files. This
- is done even if the linker is creating a non-symbolic shared library.
- The switch <samp>--[no-]allow-shlib-undefined</samp> controls the
- behaviour for reporting unresolved references found in shared
- libraries being linked in.
- </p>
- <p>The effects of this option can be reverted by using <code>-z undefs</code>.
- </p>
- <span id="index-_002d_002dallow_002dmultiple_002ddefinition"></span>
- <span id="index-_002dz-muldefs"></span>
- </dd>
- <dt><code>--allow-multiple-definition</code></dt>
- <dt><code>-z muldefs</code></dt>
- <dd><p>Normally when a symbol is defined multiple times, the linker will
- report a fatal error. These options allow multiple definitions and the
- first definition will be used.
- </p>
- <span id="index-_002d_002dallow_002dshlib_002dundefined"></span>
- <span id="index-_002d_002dno_002dallow_002dshlib_002dundefined"></span>
- </dd>
- <dt><code>--allow-shlib-undefined</code></dt>
- <dt><code>--no-allow-shlib-undefined</code></dt>
- <dd><p>Allows or disallows undefined symbols in shared libraries.
- This switch is similar to <samp>--no-undefined</samp> except that it
- determines the behaviour when the undefined symbols are in a
- shared library rather than a regular object file. It does not affect
- how undefined symbols in regular object files are handled.
- </p>
- <p>The default behaviour is to report errors for any undefined symbols
- referenced in shared libraries if the linker is being used to create
- an executable, but to allow them if the linker is being used to create
- a shared library.
- </p>
- <p>The reasons for allowing undefined symbol references in shared
- libraries specified at link time are that:
- </p>
- <ul>
- <li> A shared library specified at link time may not be the same as the one
- that is available at load time, so the symbol might actually be
- resolvable at load time.
- </li><li> There are some operating systems, eg BeOS and HPPA, where undefined
- symbols in shared libraries are normal.
- <p>The BeOS kernel for example patches shared libraries at load time to
- select whichever function is most appropriate for the current
- architecture. This is used, for example, to dynamically select an
- appropriate memset function.
- </p></li></ul>
- <span id="index-_002d_002derror_002dhandling_002dscript_003dscriptname"></span>
- </dd>
- <dt><code>--error-handling-script=<var>scriptname</var></code></dt>
- <dd><p>If this option is provided then the linker will invoke
- <var>scriptname</var> whenever an error is encountered. Currently however
- only two kinds of error are supported: missing symbols and missing
- libraries. Two arguments will be passed to script: the keyword
- “undefined-symbol” or ‘missing-lib” and the <var>name</var> of the
- undefined symbol or missing library. The intention is that the script
- will provide suggestions to the user as to where the symbol or library
- might be found. After the script has finished then the normal linker
- error message will be displayed.
- </p>
- <p>The availability of this option is controlled by a configure time
- switch, so it may not be present in specific implementations.
- </p>
- <span id="index-_002d_002dno_002dundefined_002dversion"></span>
- </dd>
- <dt><code>--no-undefined-version</code></dt>
- <dd><p>Normally when a symbol has an undefined version, the linker will ignore
- it. This option disallows symbols with undefined version and a fatal error
- will be issued instead.
- </p>
- <span id="index-_002d_002ddefault_002dsymver"></span>
- </dd>
- <dt><code>--default-symver</code></dt>
- <dd><p>Create and use a default symbol version (the soname) for unversioned
- exported symbols.
- </p>
- <span id="index-_002d_002ddefault_002dimported_002dsymver"></span>
- </dd>
- <dt><code>--default-imported-symver</code></dt>
- <dd><p>Create and use a default symbol version (the soname) for unversioned
- imported symbols.
- </p>
- <span id="index-_002d_002dno_002dwarn_002dmismatch"></span>
- </dd>
- <dt><code>--no-warn-mismatch</code></dt>
- <dd><p>Normally <code>ld</code> will give an error if you try to link together input
- files that are mismatched for some reason, perhaps because they have
- been compiled for different processors or for different endiannesses.
- This option tells <code>ld</code> that it should silently permit such possible
- errors. This option should only be used with care, in cases when you
- have taken some special action that ensures that the linker errors are
- inappropriate.
- </p>
- <span id="index-_002d_002dno_002dwarn_002dsearch_002dmismatch"></span>
- </dd>
- <dt><code>--no-warn-search-mismatch</code></dt>
- <dd><p>Normally <code>ld</code> will give a warning if it finds an incompatible
- library during a library search. This option silences the warning.
- </p>
- <span id="index-_002d_002dno_002dwhole_002darchive"></span>
- </dd>
- <dt><code>--no-whole-archive</code></dt>
- <dd><p>Turn off the effect of the <samp>--whole-archive</samp> option for subsequent
- archive files.
- </p>
- <span id="index-output-file-after-errors"></span>
- <span id="index-_002d_002dnoinhibit_002dexec"></span>
- </dd>
- <dt><code>--noinhibit-exec</code></dt>
- <dd><p>Retain the executable output file whenever it is still usable.
- Normally, the linker will not produce an output file if it encounters
- errors during the link process; it exits without writing an output file
- when it issues any error whatsoever.
- </p>
- <span id="index-_002dnostdlib"></span>
- </dd>
- <dt><code>-nostdlib</code></dt>
- <dd><p>Only search library directories explicitly specified on the
- command line. Library directories specified in linker scripts
- (including linker scripts specified on the command line) are ignored.
- </p>
- <span id="index-_002d_002doformat_003doutput_002dformat"></span>
- </dd>
- <dt><code>--oformat=<var>output-format</var></code></dt>
- <dd><p><code>ld</code> may be configured to support more than one kind of object
- file. If your <code>ld</code> is configured this way, you can use the
- ‘<samp>--oformat</samp>’ option to specify the binary format for the output
- object file. Even when <code>ld</code> is configured to support alternative
- object formats, you don’t usually need to specify this, as <code>ld</code>
- should be configured to produce as a default output format the most
- usual format on each machine. <var>output-format</var> is a text string, the
- name of a particular format supported by the BFD libraries. (You can
- list the available binary formats with ‘<samp>objdump -i</samp>’.) The script
- command <code>OUTPUT_FORMAT</code> can also specify the output format, but
- this option overrides it. See <a href="#BFD">BFD</a>.
- </p>
- <span id="index-_002d_002dout_002dimplib"></span>
- </dd>
- <dt><code>--out-implib <var>file</var></code></dt>
- <dd><p>Create an import library in <var>file</var> corresponding to the executable
- the linker is generating (eg. a DLL or ELF program). This import
- library (which should be called <code>*.dll.a</code> or <code>*.a</code> for DLLs)
- may be used to link clients against the generated executable; this
- behaviour makes it possible to skip a separate import library creation
- step (eg. <code>dlltool</code> for DLLs). This option is only available for
- the i386 PE and ELF targetted ports of the linker.
- </p>
- <span id="index-_002dpie"></span>
- <span id="index-_002d_002dpic_002dexecutable"></span>
- </dd>
- <dt><code>-pie</code></dt>
- <dt><code>--pic-executable</code></dt>
- <dd><span id="index-position-independent-executables"></span>
- <p>Create a position independent executable. This is currently only supported on
- ELF platforms. Position independent executables are similar to shared
- libraries in that they are relocated by the dynamic linker to the virtual
- address the OS chooses for them (which can vary between invocations). Like
- normal dynamically linked executables they can be executed and symbols
- defined in the executable cannot be overridden by shared libraries.
- </p>
- <span id="index-_002dno_002dpie"></span>
- </dd>
- <dt><code>-no-pie</code></dt>
- <dd><span id="index-position-dependent-executables"></span>
- <p>Create a position dependent executable. This is the default.
- </p>
- <span id="index-_002dqmagic"></span>
- </dd>
- <dt><code>-qmagic</code></dt>
- <dd><p>This option is ignored for Linux compatibility.
- </p>
- <span id="index-_002dQy"></span>
- </dd>
- <dt><code>-Qy</code></dt>
- <dd><p>This option is ignored for SVR4 compatibility.
- </p>
- <span id="index-_002d_002drelax"></span>
- <span id="index-synthesizing-linker"></span>
- <span id="index-relaxing-addressing-modes"></span>
- <span id="index-_002d_002dno_002drelax"></span>
- </dd>
- <dt><code>--relax</code></dt>
- <dt><code>--no-relax</code></dt>
- <dd><p>An option with machine dependent effects.
- This option is only supported on a few targets.
- See <a href="#H8_002f300"><code>ld</code> and the H8/300</a>.
- See <a href="#Xtensa"><code>ld</code> and Xtensa Processors</a>.
- See <a href="#M68HC11_002f68HC12"><code>ld</code> and the 68HC11 and 68HC12</a>.
- See <a href="#Nios-II"><code>ld</code> and the Altera Nios II</a>.
- See <a href="#PowerPC-ELF32"><code>ld</code> and PowerPC 32-bit ELF Support</a>.
- </p>
- <p>On some platforms the <samp>--relax</samp> option performs target specific,
- global optimizations that become possible when the linker resolves
- addressing in the program, such as relaxing address modes,
- synthesizing new instructions, selecting shorter version of current
- instructions, and combining constant values.
- </p>
- <p>On some platforms these link time global optimizations may make symbolic
- debugging of the resulting executable impossible.
- This is known to be the case for the Matsushita MN10200 and MN10300
- family of processors.
- </p>
- <p>On platforms where the feature is supported, the option
- <samp>--no-relax</samp> will disable it.
- </p>
- <p>On platforms where the feature is not supported, both <samp>--relax</samp>
- and <samp>--no-relax</samp> are accepted, but ignored.
- </p>
- <span id="index-retaining-specified-symbols"></span>
- <span id="index-stripping-all-but-some-symbols"></span>
- <span id="index-symbols_002c-retaining-selectively"></span>
- <span id="index-_002d_002dretain_002dsymbols_002dfile_003dfilename"></span>
- </dd>
- <dt><code>--retain-symbols-file=<var>filename</var></code></dt>
- <dd><p>Retain <em>only</em> the symbols listed in the file <var>filename</var>,
- discarding all others. <var>filename</var> is simply a flat file, with one
- symbol name per line. This option is especially useful in environments
- (such as VxWorks)
- where a large global symbol table is accumulated gradually, to conserve
- run-time memory.
- </p>
- <p>‘<samp>--retain-symbols-file</samp>’ does <em>not</em> discard undefined symbols,
- or symbols needed for relocations.
- </p>
- <p>You may only specify ‘<samp>--retain-symbols-file</samp>’ once in the command
- line. It overrides ‘<samp>-s</samp>’ and ‘<samp>-S</samp>’.
- </p>
- </dd>
- <dt><code>-rpath=<var>dir</var></code></dt>
- <dd><span id="index-runtime-library-search-path"></span>
- <span id="index-_002drpath_003ddir"></span>
- <p>Add a directory to the runtime library search path. This is used when
- linking an ELF executable with shared objects. All <samp>-rpath</samp>
- arguments are concatenated and passed to the runtime linker, which uses
- them to locate shared objects at runtime.
- </p>
- <p>The <samp>-rpath</samp> option is also used when locating shared objects which
- are needed by shared objects explicitly included in the link; see the
- description of the <samp>-rpath-link</samp> option. Searching <samp>-rpath</samp>
- in this way is only supported by native linkers and cross linkers which
- have been configured with the <samp>--with-sysroot</samp> option.
- </p>
- <p>If <samp>-rpath</samp> is not used when linking an ELF executable, the
- contents of the environment variable <code>LD_RUN_PATH</code> will be used if it
- is defined.
- </p>
- <p>The <samp>-rpath</samp> option may also be used on SunOS. By default, on
- SunOS, the linker will form a runtime search path out of all the
- <samp>-L</samp> options it is given. If a <samp>-rpath</samp> option is used, the
- runtime search path will be formed exclusively using the <samp>-rpath</samp>
- options, ignoring the <samp>-L</samp> options. This can be useful when using
- gcc, which adds many <samp>-L</samp> options which may be on NFS mounted
- file systems.
- </p>
- <p>For compatibility with other ELF linkers, if the <samp>-R</samp> option is
- followed by a directory name, rather than a file name, it is treated as
- the <samp>-rpath</samp> option.
- </p>
- <span id="index-link_002dtime-runtime-library-search-path"></span>
- <span id="index-_002drpath_002dlink_003ddir"></span>
- </dd>
- <dt><code>-rpath-link=<var>dir</var></code></dt>
- <dd><p>When using ELF or SunOS, one shared library may require another. This
- happens when an <code>ld -shared</code> link includes a shared library as one
- of the input files.
- </p>
- <p>When the linker encounters such a dependency when doing a non-shared,
- non-relocatable link, it will automatically try to locate the required
- shared library and include it in the link, if it is not included
- explicitly. In such a case, the <samp>-rpath-link</samp> option
- specifies the first set of directories to search. The
- <samp>-rpath-link</samp> option may specify a sequence of directory names
- either by specifying a list of names separated by colons, or by
- appearing multiple times.
- </p>
- <p>The tokens <var>$ORIGIN</var> and <var>$LIB</var> can appear in these search
- directories. They will be replaced by the full path to the directory
- containing the program or shared object in the case of <var>$ORIGIN</var>
- and either ‘<samp>lib</samp>’ - for 32-bit binaries - or ‘<samp>lib64</samp>’ - for
- 64-bit binaries - in the case of <var>$LIB</var>.
- </p>
- <p>The alternative form of these tokens - <var>${ORIGIN}</var> and
- <var>${LIB}</var> can also be used. The token <var>$PLATFORM</var> is not
- supported.
- </p>
- <p>This option should be used with caution as it overrides the search path
- that may have been hard compiled into a shared library. In such a case it
- is possible to use unintentionally a different search path than the
- runtime linker would do.
- </p>
- <p>The linker uses the following search paths to locate required shared
- libraries:
- </p>
- <ol>
- <li> Any directories specified by <samp>-rpath-link</samp> options.
- </li><li> Any directories specified by <samp>-rpath</samp> options. The difference
- between <samp>-rpath</samp> and <samp>-rpath-link</samp> is that directories
- specified by <samp>-rpath</samp> options are included in the executable and
- used at runtime, whereas the <samp>-rpath-link</samp> option is only effective
- at link time. Searching <samp>-rpath</samp> in this way is only supported
- by native linkers and cross linkers which have been configured with
- the <samp>--with-sysroot</samp> option.
- </li><li> On an ELF system, for native linkers, if the <samp>-rpath</samp> and
- <samp>-rpath-link</samp> options were not used, search the contents of the
- environment variable <code>LD_RUN_PATH</code>.
- </li><li> On SunOS, if the <samp>-rpath</samp> option was not used, search any
- directories specified using <samp>-L</samp> options.
- </li><li> For a native linker, search the contents of the environment
- variable <code>LD_LIBRARY_PATH</code>.
- </li><li> For a native ELF linker, the directories in <code>DT_RUNPATH</code> or
- <code>DT_RPATH</code> of a shared library are searched for shared
- libraries needed by it. The <code>DT_RPATH</code> entries are ignored if
- <code>DT_RUNPATH</code> entries exist.
- </li><li> For a linker for a Linux system, if the file <samp>/etc/ld.so.conf</samp>
- exists, the list of directories found in that file. Note: the path
- to this file is prefixed with the <code>sysroot</code> value, if that is
- defined, and then any <code>prefix</code> string if the linker was
- configured with the <code>--prefix=<path></code> option.
- </li><li> For a native linker on a FreeBSD system, any directories specified by
- the <code>_PATH_ELF_HINTS</code> macro defined in the <samp>elf-hints.h</samp>
- header file.
- </li><li> Any directories specified by a <code>SEARCH_DIR</code> command in a
- linker script given on the command line, including scripts specified
- by <samp>-T</samp> (but not <samp>-dT</samp>).
- </li><li> The default directories, normally <samp>/lib</samp> and <samp>/usr/lib</samp>.
- </li><li> Any directories specified by a plugin LDPT_SET_EXTRA_LIBRARY_PATH.
- </li><li> Any directories specified by a <code>SEARCH_DIR</code> command in a default
- linker script.
- </li></ol>
- <p>Note however on Linux based systems there is an additional caveat: If
- the <samp>--as-needed</samp> option is active <em>and</em> a shared library
- is located which would normally satisfy the search <em>and</em> this
- library does not have DT_NEEDED tag for <samp>libc.so</samp>
- <em>and</em> there is a shared library later on in the set of search
- directories which also satisfies the search <em>and</em>
- this second shared library does have a DT_NEEDED tag for
- <samp>libc.so</samp> <em>then</em> the second library will be selected instead
- of the first.
- </p>
- <p>If the required shared library is not found, the linker will issue a
- warning and continue with the link.
- </p>
- <span id="index-_002dshared"></span>
- <span id="index-_002dBshareable"></span>
- </dd>
- <dt><code>-shared</code></dt>
- <dt><code>-Bshareable</code></dt>
- <dd><span id="index-shared-libraries"></span>
- <p>Create a shared library. This is currently only supported on ELF, XCOFF
- and SunOS platforms. On SunOS, the linker will automatically create a
- shared library if the <samp>-e</samp> option is not used and there are
- undefined symbols in the link.
- </p>
- <span id="index-_002d_002dsort_002dcommon"></span>
- </dd>
- <dt><code>--sort-common</code></dt>
- <dt><code>--sort-common=ascending</code></dt>
- <dt><code>--sort-common=descending</code></dt>
- <dd><p>This option tells <code>ld</code> to sort the common symbols by alignment in
- ascending or descending order when it places them in the appropriate output
- sections. The symbol alignments considered are sixteen-byte or larger,
- eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
- between symbols due to alignment constraints. If no sorting order is
- specified, then descending order is assumed.
- </p>
- <span id="index-_002d_002dsort_002dsection_003dname"></span>
- </dd>
- <dt><code>--sort-section=name</code></dt>
- <dd><p>This option will apply <code>SORT_BY_NAME</code> to all wildcard section
- patterns in the linker script.
- </p>
- <span id="index-_002d_002dsort_002dsection_003dalignment"></span>
- </dd>
- <dt><code>--sort-section=alignment</code></dt>
- <dd><p>This option will apply <code>SORT_BY_ALIGNMENT</code> to all wildcard section
- patterns in the linker script.
- </p>
- <span id="index-_002d_002dspare_002ddynamic_002dtags"></span>
- </dd>
- <dt><code>--spare-dynamic-tags=<var>count</var></code></dt>
- <dd><p>This option specifies the number of empty slots to leave in the
- .dynamic section of ELF shared objects. Empty slots may be needed by
- post processing tools, such as the prelinker. The default is 5.
- </p>
- <span id="index-_002d_002dsplit_002dby_002dfile"></span>
- </dd>
- <dt><code>--split-by-file[=<var>size</var>]</code></dt>
- <dd><p>Similar to <samp>--split-by-reloc</samp> but creates a new output section for
- each input file when <var>size</var> is reached. <var>size</var> defaults to a
- size of 1 if not given.
- </p>
- <span id="index-_002d_002dsplit_002dby_002dreloc"></span>
- </dd>
- <dt><code>--split-by-reloc[=<var>count</var>]</code></dt>
- <dd><p>Tries to creates extra sections in the output file so that no single
- output section in the file contains more than <var>count</var> relocations.
- This is useful when generating huge relocatable files for downloading into
- certain real time kernels with the COFF object file format; since COFF
- cannot represent more than 65535 relocations in a single section. Note
- that this will fail to work with object file formats which do not
- support arbitrary sections. The linker will not split up individual
- input sections for redistribution, so if a single input section contains
- more than <var>count</var> relocations one output section will contain that
- many relocations. <var>count</var> defaults to a value of 32768.
- </p>
- <span id="index-_002d_002dstats"></span>
- </dd>
- <dt><code>--stats</code></dt>
- <dd><p>Compute and display statistics about the operation of the linker, such
- as execution time and memory usage.
- </p>
- <span id="index-_002d_002dsysroot_003ddirectory"></span>
- </dd>
- <dt><code>--sysroot=<var>directory</var></code></dt>
- <dd><p>Use <var>directory</var> as the location of the sysroot, overriding the
- configure-time default. This option is only supported by linkers
- that were configured using <samp>--with-sysroot</samp>.
- </p>
- <span id="index-_002d_002dtask_002dlink"></span>
- </dd>
- <dt><code>--task-link</code></dt>
- <dd><p>This is used by COFF/PE based targets to create a task-linked object
- file where all of the global symbols have been converted to statics.
- </p>
- <span id="index-_002d_002dtraditional_002dformat"></span>
- <span id="index-traditional-format"></span>
- </dd>
- <dt><code>--traditional-format</code></dt>
- <dd><p>For some targets, the output of <code>ld</code> is different in some ways from
- the output of some existing linker. This switch requests <code>ld</code> to
- use the traditional format instead.
- </p>
- <span id="index-dbx"></span>
- <p>For example, on SunOS, <code>ld</code> combines duplicate entries in the
- symbol string table. This can reduce the size of an output file with
- full debugging information by over 30 percent. Unfortunately, the SunOS
- <code>dbx</code> program can not read the resulting program (<code>gdb</code> has no
- trouble). The ‘<samp>--traditional-format</samp>’ switch tells <code>ld</code> to not
- combine duplicate entries.
- </p>
- <span id="index-_002d_002dsection_002dstart_003dsectionname_003dorg"></span>
- </dd>
- <dt><code>--section-start=<var>sectionname</var>=<var>org</var></code></dt>
- <dd><p>Locate a section in the output file at the absolute
- address given by <var>org</var>. You may use this option as many
- times as necessary to locate multiple sections in the command
- line.
- <var>org</var> must be a single hexadecimal integer;
- for compatibility with other linkers, you may omit the leading
- ‘<samp>0x</samp>’ usually associated with hexadecimal values. <em>Note:</em> there
- should be no white space between <var>sectionname</var>, the equals
- sign (“<tt class="key">=</tt>”), and <var>org</var>.
- </p>
- <span id="index-_002dTbss_003dorg"></span>
- <span id="index-_002dTdata_003dorg"></span>
- <span id="index-_002dTtext_003dorg"></span>
- <span id="index-segment-origins_002c-cmd-line"></span>
- </dd>
- <dt><code>-Tbss=<var>org</var></code></dt>
- <dt><code>-Tdata=<var>org</var></code></dt>
- <dt><code>-Ttext=<var>org</var></code></dt>
- <dd><p>Same as <samp>--section-start</samp>, with <code>.bss</code>, <code>.data</code> or
- <code>.text</code> as the <var>sectionname</var>.
- </p>
- <span id="index-_002dTtext_002dsegment_003dorg"></span>
- </dd>
- <dt><code>-Ttext-segment=<var>org</var></code></dt>
- <dd><span id="index-text-segment-origin_002c-cmd-line"></span>
- <p>When creating an ELF executable, it will set the address of the first
- byte of the text segment.
- </p>
- <span id="index-_002dTrodata_002dsegment_003dorg"></span>
- </dd>
- <dt><code>-Trodata-segment=<var>org</var></code></dt>
- <dd><span id="index-rodata-segment-origin_002c-cmd-line"></span>
- <p>When creating an ELF executable or shared object for a target where
- the read-only data is in its own segment separate from the executable
- text, it will set the address of the first byte of the read-only data segment.
- </p>
- <span id="index-_002dTldata_002dsegment_003dorg"></span>
- </dd>
- <dt><code>-Tldata-segment=<var>org</var></code></dt>
- <dd><span id="index-ldata-segment-origin_002c-cmd-line"></span>
- <p>When creating an ELF executable or shared object for x86-64 medium memory
- model, it will set the address of the first byte of the ldata segment.
- </p>
- <span id="index-_002d_002dunresolved_002dsymbols"></span>
- </dd>
- <dt><code>--unresolved-symbols=<var>method</var></code></dt>
- <dd><p>Determine how to handle unresolved symbols. There are four possible
- values for ‘<samp>method</samp>’:
- </p>
- <dl compact="compact">
- <dt>‘<samp>ignore-all</samp>’</dt>
- <dd><p>Do not report any unresolved symbols.
- </p>
- </dd>
- <dt>‘<samp>report-all</samp>’</dt>
- <dd><p>Report all unresolved symbols. This is the default.
- </p>
- </dd>
- <dt>‘<samp>ignore-in-object-files</samp>’</dt>
- <dd><p>Report unresolved symbols that are contained in shared libraries, but
- ignore them if they come from regular object files.
- </p>
- </dd>
- <dt>‘<samp>ignore-in-shared-libs</samp>’</dt>
- <dd><p>Report unresolved symbols that come from regular object files, but
- ignore them if they come from shared libraries. This can be useful
- when creating a dynamic binary and it is known that all the shared
- libraries that it should be referencing are included on the linker’s
- command line.
- </p></dd>
- </dl>
- <p>The behaviour for shared libraries on their own can also be controlled
- by the <samp>--[no-]allow-shlib-undefined</samp> option.
- </p>
- <p>Normally the linker will generate an error message for each reported
- unresolved symbol but the option <samp>--warn-unresolved-symbols</samp>
- can change this to a warning.
- </p>
- <span id="index-_002d_002dverbose_005b_003dNUMBER_005d"></span>
- <span id="index-verbose_005b_003dNUMBER_005d"></span>
- </dd>
- <dt><code>--dll-verbose</code></dt>
- <dt><code>--verbose[=<var>NUMBER</var>]</code></dt>
- <dd><p>Display the version number for <code>ld</code> and list the linker emulations
- supported. Display which input files can and cannot be opened. Display
- the linker script being used by the linker. If the optional <var>NUMBER</var>
- argument > 1, plugin symbol status will also be displayed.
- </p>
- <span id="index-_002d_002dversion_002dscript_003dversion_002dscriptfile"></span>
- <span id="index-version-script_002c-symbol-versions"></span>
- </dd>
- <dt><code>--version-script=<var>version-scriptfile</var></code></dt>
- <dd><p>Specify the name of a version script to the linker. This is typically
- used when creating shared libraries to specify additional information
- about the version hierarchy for the library being created. This option
- is only fully supported on ELF platforms which support shared libraries;
- see <a href="#VERSION">VERSION</a>. It is partially supported on PE platforms, which can
- use version scripts to filter symbol visibility in auto-export mode: any
- symbols marked ‘<samp>local</samp>’ in the version script will not be exported.
- See <a href="#WIN32">WIN32</a>.
- </p>
- <span id="index-_002d_002dwarn_002dcommon"></span>
- <span id="index-warnings_002c-on-combining-symbols"></span>
- <span id="index-combining-symbols_002c-warnings-on"></span>
- </dd>
- <dt><code>--warn-common</code></dt>
- <dd><p>Warn when a common symbol is combined with another common symbol or with
- a symbol definition. Unix linkers allow this somewhat sloppy practice,
- but linkers on some other operating systems do not. This option allows
- you to find potential problems from combining global symbols.
- Unfortunately, some C libraries use this practice, so you may get some
- warnings about symbols in the libraries as well as in your programs.
- </p>
- <p>There are three kinds of global symbols, illustrated here by C examples:
- </p>
- <dl compact="compact">
- <dt>‘<samp>int i = 1;</samp>’</dt>
- <dd><p>A definition, which goes in the initialized data section of the output
- file.
- </p>
- </dd>
- <dt>‘<samp>extern int i;</samp>’</dt>
- <dd><p>An undefined reference, which does not allocate space.
- There must be either a definition or a common symbol for the
- variable somewhere.
- </p>
- </dd>
- <dt>‘<samp>int i;</samp>’</dt>
- <dd><p>A common symbol. If there are only (one or more) common symbols for a
- variable, it goes in the uninitialized data area of the output file.
- The linker merges multiple common symbols for the same variable into a
- single symbol. If they are of different sizes, it picks the largest
- size. The linker turns a common symbol into a declaration, if there is
- a definition of the same variable.
- </p></dd>
- </dl>
- <p>The ‘<samp>--warn-common</samp>’ option can produce five kinds of warnings.
- Each warning consists of a pair of lines: the first describes the symbol
- just encountered, and the second describes the previous symbol
- encountered with the same name. One or both of the two symbols will be
- a common symbol.
- </p>
- <ol>
- <li> Turning a common symbol into a reference, because there is already a
- definition for the symbol.
- <div class="example">
- <pre class="example"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>'
- overridden by definition
- <var>file</var>(<var>section</var>): warning: defined here
- </pre></div>
- </li><li> Turning a common symbol into a reference, because a later definition for
- the symbol is encountered. This is the same as the previous case,
- except that the symbols are encountered in a different order.
- <div class="example">
- <pre class="example"><var>file</var>(<var>section</var>): warning: definition of `<var>symbol</var>'
- overriding common
- <var>file</var>(<var>section</var>): warning: common is here
- </pre></div>
- </li><li> Merging a common symbol with a previous same-sized common symbol.
- <div class="example">
- <pre class="example"><var>file</var>(<var>section</var>): warning: multiple common
- of `<var>symbol</var>'
- <var>file</var>(<var>section</var>): warning: previous common is here
- </pre></div>
- </li><li> Merging a common symbol with a previous larger common symbol.
- <div class="example">
- <pre class="example"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>'
- overridden by larger common
- <var>file</var>(<var>section</var>): warning: larger common is here
- </pre></div>
- </li><li> Merging a common symbol with a previous smaller common symbol. This is
- the same as the previous case, except that the symbols are
- encountered in a different order.
- <div class="example">
- <pre class="example"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>'
- overriding smaller common
- <var>file</var>(<var>section</var>): warning: smaller common is here
- </pre></div>
- </li></ol>
- <span id="index-_002d_002dwarn_002dconstructors"></span>
- </dd>
- <dt><code>--warn-constructors</code></dt>
- <dd><p>Warn if any global constructors are used. This is only useful for a few
- object file formats. For formats like COFF or ELF, the linker can not
- detect the use of global constructors.
- </p>
- <span id="index-_002d_002dwarn_002dexecstack"></span>
- <span id="index-warnings_002c-on-executable-stack"></span>
- <span id="index-executable-stack_002c-warnings-on"></span>
- </dd>
- <dt><code>--warn-execstack</code></dt>
- <dt><code>--warn-execstack-objects</code></dt>
- <dt><code>--no-warn-execstack</code></dt>
- <dd><p>On ELF platforms the linker may generate warning messages if it is
- asked to create an output file that contains an executable stack.
- There are three possible states:
- </p><ol>
- <li> Do not generate any warnings.
- </li><li> Always generate warnings, even if the executable stack is requested
- via the <samp>-z execstack</samp> command line option.
- </li><li> Only generate a warning if an object file requests an executable
- stack, but not if the <samp>-z execstack</samp> option is used.
- </li></ol>
- <p>The default state depends upon how the linker was configured when it
- was built. The <samp>--no-warn-execstack</samp> option always puts the
- linker into the no-warnings state. The <samp>--warn-execstack</samp>
- option puts the linker into the warn-always state. The
- <samp>--warn-execstack-objects</samp> option puts the linker into the
- warn-for-object-files-only state.
- </p>
- <p>Note: ELF format input files can specify that they need an executable
- stack by having a <var>.note.GNU-stack</var> section with the executable
- bit set in its section flags. They can specify that they do not need
- an executable stack by having the same section, but without the
- executable flag bit set. If an input file does not have a
- <var>.note.GNU-stack</var> section then the default behaviour is target
- specific. For some targets, then absence of such a section implies
- that an executable stack <em>is</em> required. This is often a problem
- for hand crafted assembler files.
- </p>
- <span id="index-_002d_002derror_002dexecstack"></span>
- </dd>
- <dt><code>--error-execstack</code></dt>
- <dt><code>--no-error-execstack</code></dt>
- <dd><p>If the linker is going to generate a warning message about an
- executable stack then the <samp>--error-execstack</samp> option will
- instead change that warning into an error. Note - this option does
- not change the linker’s execstack warning generation state. Use
- <samp>--warn-execstack</samp> or <samp>--warn-execstack-objects</samp> to set
- a specific warning state.
- </p>
- <p>The <samp>--no-error-execstack</samp> option will restore the default
- behaviour of generating warning messages.
- </p>
- <span id="index-_002d_002dwarn_002dmultiple_002dgp"></span>
- </dd>
- <dt><code>--warn-multiple-gp</code></dt>
- <dd><p>Warn if multiple global pointer values are required in the output file.
- This is only meaningful for certain processors, such as the Alpha.
- Specifically, some processors put large-valued constants in a special
- section. A special register (the global pointer) points into the middle
- of this section, so that constants can be loaded efficiently via a
- base-register relative addressing mode. Since the offset in
- base-register relative mode is fixed and relatively small (e.g., 16
- bits), this limits the maximum size of the constant pool. Thus, in
- large programs, it is often necessary to use multiple global pointer
- values in order to be able to address all possible constants. This
- option causes a warning to be issued whenever this case occurs.
- </p>
- <span id="index-_002d_002dwarn_002donce"></span>
- <span id="index-warnings_002c-on-undefined-symbols"></span>
- <span id="index-undefined-symbols_002c-warnings-on"></span>
- </dd>
- <dt><code>--warn-once</code></dt>
- <dd><p>Only warn once for each undefined symbol, rather than once per module
- which refers to it.
- </p>
- <span id="index-_002d_002dwarn_002drwx_002dsegments"></span>
- <span id="index-warnings_002c-on-writeable-and-exectuable-segments"></span>
- <span id="index-executable-segments_002c-warnings-on"></span>
- </dd>
- <dt><code>--warn-rwx-segments</code></dt>
- <dt><code>--no-warn-rwx-segments</code></dt>
- <dd><p>Warn if the linker creates a loadable, non-zero sized segment that has
- all three of the read, write and execute permission flags set. Such a
- segment represents a potential security vulnerability. In addition
- warnings will be generated if a thread local storage segment is
- created with the execute permission flag set, regardless of whether or
- not it has the read and/or write flags set.
- </p>
- <p>These warnings are enabled by default. They can be disabled via the
- <samp>--no-warn-rwx-segments</samp> option and re-enabled via the
- <samp>--warn-rwx-segments</samp> option.
- </p>
- <span id="index-_002d_002derror_002drwx_002dsegments"></span>
- </dd>
- <dt><code>--error-rwx-segments</code></dt>
- <dt><code>--no-error-rwx-segments</code></dt>
- <dd><p>If the linker is going to generate a warning message about an
- executable, writeable segment, or an executable TLS segment, then the
- <samp>--error-rwx-segments</samp> option will turn this warning into an
- error instead. The <samp>--no-error-rwx-segments</samp> option will
- restore the default behaviour of just generating a warning message.
- </p>
- <p>Note - the <samp>--error-rwx-segments</samp> option does not by itself
- turn on warnings about these segments. These warnings are either
- enabled by default, if the linker was configured that way, or via the
- <samp>--warn-rwx-segments</samp> command line option.
- </p>
- <span id="index-_002d_002dwarn_002dsection_002dalign"></span>
- <span id="index-warnings_002c-on-section-alignment"></span>
- <span id="index-section-alignment_002c-warnings-on"></span>
- </dd>
- <dt><code>--warn-section-align</code></dt>
- <dd><p>Warn if the address of an output section is changed because of
- alignment. Typically, the alignment will be set by an input section.
- The address will only be changed if it not explicitly specified; that
- is, if the <code>SECTIONS</code> command does not specify a start address for
- the section (see <a href="#SECTIONS">SECTIONS</a>).
- </p>
- <span id="index-_002d_002dwarn_002dtextrel"></span>
- </dd>
- <dt><code>--warn-textrel</code></dt>
- <dd><p>Warn if the linker adds DT_TEXTREL to a position-independent executable
- or shared object.
- </p>
- <span id="index-_002d_002dwarn_002dalternate_002dem"></span>
- </dd>
- <dt><code>--warn-alternate-em</code></dt>
- <dd><p>Warn if an object has alternate ELF machine code.
- </p>
- <span id="index-_002d_002dwarn_002dunresolved_002dsymbols"></span>
- </dd>
- <dt><code>--warn-unresolved-symbols</code></dt>
- <dd><p>If the linker is going to report an unresolved symbol (see the option
- <samp>--unresolved-symbols</samp>) it will normally generate an error.
- This option makes it generate a warning instead.
- </p>
- <span id="index-_002d_002derror_002dunresolved_002dsymbols"></span>
- </dd>
- <dt><code>--error-unresolved-symbols</code></dt>
- <dd><p>This restores the linker’s default behaviour of generating errors when
- it is reporting unresolved symbols.
- </p>
- <span id="index-_002d_002dwhole_002darchive"></span>
- <span id="index-including-an-entire-archive"></span>
- </dd>
- <dt><code>--whole-archive</code></dt>
- <dd><p>For each archive mentioned on the command line after the
- <samp>--whole-archive</samp> option, include every object file in the archive
- in the link, rather than searching the archive for the required object
- files. This is normally used to turn an archive file into a shared
- library, forcing every object to be included in the resulting shared
- library. This option may be used more than once.
- </p>
- <p>Two notes when using this option from gcc: First, gcc doesn’t know
- about this option, so you have to use <samp>-Wl,-whole-archive</samp>.
- Second, don’t forget to use <samp>-Wl,-no-whole-archive</samp> after your
- list of archives, because gcc will add its own list of archives to
- your link and you may not want this flag to affect those as well.
- </p>
- <span id="index-_002d_002dwrap_003dsymbol"></span>
- </dd>
- <dt><code>--wrap=<var>symbol</var></code></dt>
- <dd><p>Use a wrapper function for <var>symbol</var>. Any undefined reference to
- <var>symbol</var> will be resolved to <code>__wrap_<var>symbol</var></code>. Any
- undefined reference to <code>__real_<var>symbol</var></code> will be resolved to
- <var>symbol</var>.
- </p>
- <p>This can be used to provide a wrapper for a system function. The
- wrapper function should be called <code>__wrap_<var>symbol</var></code>. If it
- wishes to call the system function, it should call
- <code>__real_<var>symbol</var></code>.
- </p>
- <p>Here is a trivial example:
- </p>
- <div class="example">
- <pre class="example">void *
- __wrap_malloc (size_t c)
- {
- printf ("malloc called with %zu\n", c);
- return __real_malloc (c);
- }
- </pre></div>
- <p>If you link other code with this file using <samp>--wrap malloc</samp>, then
- all calls to <code>malloc</code> will call the function <code>__wrap_malloc</code>
- instead. The call to <code>__real_malloc</code> in <code>__wrap_malloc</code> will
- call the real <code>malloc</code> function.
- </p>
- <p>You may wish to provide a <code>__real_malloc</code> function as well, so that
- links without the <samp>--wrap</samp> option will succeed. If you do this,
- you should not put the definition of <code>__real_malloc</code> in the same
- file as <code>__wrap_malloc</code>; if you do, the assembler may resolve the
- call before the linker has a chance to wrap it to <code>malloc</code>.
- </p>
- <p>Only undefined references are replaced by the linker. So, translation unit
- internal references to <var>symbol</var> are not resolved to
- <code>__wrap_<var>symbol</var></code>. In the next example, the call to <code>f</code> in
- <code>g</code> is not resolved to <code>__wrap_f</code>.
- </p>
- <div class="example">
- <pre class="example">int
- f (void)
- {
- return 123;
- }
- int
- g (void)
- {
- return f();
- }
- </pre></div>
- <span id="index-_002d_002deh_002dframe_002dhdr"></span>
- <span id="index-_002d_002dno_002deh_002dframe_002dhdr"></span>
- </dd>
- <dt><code>--eh-frame-hdr</code></dt>
- <dt><code>--no-eh-frame-hdr</code></dt>
- <dd><p>Request (<samp>--eh-frame-hdr</samp>) or suppress
- (<samp>--no-eh-frame-hdr</samp>) the creation of <code>.eh_frame_hdr</code>
- section and ELF <code>PT_GNU_EH_FRAME</code> segment header.
- </p>
- <span id="index-_002d_002dld_002dgenerated_002dunwind_002dinfo"></span>
- </dd>
- <dt><code>--no-ld-generated-unwind-info</code></dt>
- <dd><p>Request creation of <code>.eh_frame</code> unwind info for linker
- generated code sections like PLT. This option is on by default
- if linker generated unwind info is supported. This option also
- controls the generation of <code>.sframe</code> stack trace info for linker
- generated code sections like PLT.
- </p>
- <span id="index-_002d_002denable_002dnew_002ddtags"></span>
- <span id="index-_002d_002ddisable_002dnew_002ddtags"></span>
- </dd>
- <dt><code>--enable-new-dtags</code></dt>
- <dt><code>--disable-new-dtags</code></dt>
- <dd><p>This linker can create the new dynamic tags in ELF. But the older ELF
- systems may not understand them. If you specify
- <samp>--enable-new-dtags</samp>, the new dynamic tags will be created as needed
- and older dynamic tags will be omitted.
- If you specify <samp>--disable-new-dtags</samp>, no new dynamic tags will be
- created. By default, the new dynamic tags are not created. Note that
- those options are only available for ELF systems.
- </p>
- <span id="index-_002d_002dhash_002dsize_003dnumber"></span>
- </dd>
- <dt><code>--hash-size=<var>number</var></code></dt>
- <dd><p>Set the default size of the linker’s hash tables to a prime number
- close to <var>number</var>. Increasing this value can reduce the length of
- time it takes the linker to perform its tasks, at the expense of
- increasing the linker’s memory requirements. Similarly reducing this
- value can reduce the memory requirements at the expense of speed.
- </p>
- <span id="index-_002d_002dhash_002dstyle_003dstyle"></span>
- </dd>
- <dt><code>--hash-style=<var>style</var></code></dt>
- <dd><p>Set the type of linker’s hash table(s). <var>style</var> can be either
- <code>sysv</code> for classic ELF <code>.hash</code> section, <code>gnu</code> for
- new style GNU <code>.gnu.hash</code> section or <code>both</code> for both
- the classic ELF <code>.hash</code> and new style GNU <code>.gnu.hash</code>
- hash tables. The default depends upon how the linker was configured,
- but for most Linux based systems it will be <code>both</code>.
- </p>
- <span id="index-_002d_002dcompress_002ddebug_002dsections_003dnone"></span>
- <span id="index-_002d_002dcompress_002ddebug_002dsections_003dzlib"></span>
- <span id="index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgnu"></span>
- <span id="index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgabi"></span>
- <span id="index-_002d_002dcompress_002ddebug_002dsections_003dzstd"></span>
- </dd>
- <dt><code>--compress-debug-sections=none</code></dt>
- <dt><code>--compress-debug-sections=zlib</code></dt>
- <dt><code>--compress-debug-sections=zlib-gnu</code></dt>
- <dt><code>--compress-debug-sections=zlib-gabi</code></dt>
- <dt><code>--compress-debug-sections=zstd</code></dt>
- <dd><p>On ELF platforms, these options control how DWARF debug sections are
- compressed using zlib.
- </p>
- <p><samp>--compress-debug-sections=none</samp> doesn’t compress DWARF debug
- sections. <samp>--compress-debug-sections=zlib-gnu</samp> compresses
- DWARF debug sections and renames them to begin with ‘<samp>.zdebug</samp>’
- instead of ‘<samp>.debug</samp>’. <samp>--compress-debug-sections=zlib-gabi</samp>
- also compresses DWARF debug sections, but rather than renaming them it
- sets the SHF_COMPRESSED flag in the sections’ headers.
- </p>
- <p>The <samp>--compress-debug-sections=zlib</samp> option is an alias for
- <samp>--compress-debug-sections=zlib-gabi</samp>.
- </p>
- <p><samp>--compress-debug-sections=zstd</samp> compresses DWARF debug sections using
- zstd.
- </p>
- <p>Note that this option overrides any compression in input debug
- sections, so if a binary is linked with <samp>--compress-debug-sections=none</samp>
- for example, then any compressed debug sections in input files will be
- uncompressed before they are copied into the output binary.
- </p>
- <p>The default compression behaviour varies depending upon the target
- involved and the configure options used to build the toolchain. The
- default can be determined by examining the output from the linker’s
- <samp>--help</samp> option.
- </p>
- <span id="index-_002d_002dreduce_002dmemory_002doverheads"></span>
- </dd>
- <dt><code>--reduce-memory-overheads</code></dt>
- <dd><p>This option reduces memory requirements at ld runtime, at the expense of
- linking speed. This was introduced to select the old O(n^2) algorithm
- for link map file generation, rather than the new O(n) algorithm which uses
- about 40% more memory for symbol storage.
- </p>
- <p>Another effect of the switch is to set the default hash table size to
- 1021, which again saves memory at the cost of lengthening the linker’s
- run time. This is not done however if the <samp>--hash-size</samp> switch
- has been used.
- </p>
- <p>The <samp>--reduce-memory-overheads</samp> switch may be also be used to
- enable other tradeoffs in future versions of the linker.
- </p>
- <span id="index-_002d_002dmax_002dcache_002dsize_003dsize"></span>
- </dd>
- <dt><code>--max-cache-size=<var>size</var></code></dt>
- <dd><p><code>ld</code> normally caches the relocation information and symbol tables
- of input files in memory with the unlimited size. This option sets the
- maximum cache size to <var>size</var>.
- </p>
- <span id="index-_002d_002dbuild_002did"></span>
- <span id="index-_002d_002dbuild_002did_003dstyle"></span>
- </dd>
- <dt><code>--build-id</code></dt>
- <dt><code>--build-id=<var>style</var></code></dt>
- <dd><p>Request the creation of a <code>.note.gnu.build-id</code> ELF note section
- or a <code>.buildid</code> COFF section. The contents of the note are
- unique bits identifying this linked file. <var>style</var> can be
- <code>uuid</code> to use 128 random bits, <code>sha1</code> to use a 160-bit
- <small>SHA1</small> hash on the normative parts of the output contents,
- <code>md5</code> to use a 128-bit <small>MD5</small> hash on the normative parts of
- the output contents, or <code>0x<var>hexstring</var></code> to use a chosen bit
- string specified as an even number of hexadecimal digits (<code>-</code> and
- <code>:</code> characters between digit pairs are ignored). If <var>style</var>
- is omitted, <code>sha1</code> is used.
- </p>
- <p>The <code>md5</code> and <code>sha1</code> styles produces an identifier
- that is always the same in an identical output file, but will be
- unique among all nonidentical output files. It is not intended
- to be compared as a checksum for the file’s contents. A linked
- file may be changed later by other tools, but the build ID bit
- string identifying the original linked file does not change.
- </p>
- <p>Passing <code>none</code> for <var>style</var> disables the setting from any
- <code>--build-id</code> options earlier on the command line.
- </p>
- <span id="index-_002d_002dpackage_002dmetadata_003dJSON"></span>
- </dd>
- <dt><code>--package-metadata=<var>JSON</var></code></dt>
- <dd><p>Request the creation of a <code>.note.package</code> ELF note section. The
- contents of the note are in JSON format, as per the package metadata
- specification. For more information see:
- https://systemd.io/ELF_PACKAGE_METADATA/
- If the JSON argument is missing/empty then this will disable the
- creation of the metadata note, if one had been enabled by an earlier
- occurrence of the –package-metadata option.
- If the linker has been built with libjansson, then the JSON string
- will be validated.
- </p></dd>
- </dl>
- <span id="Options-Specific-to-i386-PE-Targets"></span><h4 class="subsection">2.1.1 Options Specific to i386 PE Targets</h4>
- <p>The i386 PE linker supports the <samp>-shared</samp> option, which causes
- the output to be a dynamically linked library (DLL) instead of a
- normal executable. You should name the output <code>*.dll</code> when you
- use this option. In addition, the linker fully supports the standard
- <code>*.def</code> files, which may be specified on the linker command line
- like an object file (in fact, it should precede archives it exports
- symbols from, to ensure that they get linked in, just like a normal
- object file).
- </p>
- <p>In addition to the options common to all targets, the i386 PE linker
- support additional command-line options that are specific to the i386
- PE target. Options that take values may be separated from their
- values by either a space or an equals sign.
- </p>
- <dl compact="compact">
- <dd>
- <span id="index-_002d_002dadd_002dstdcall_002dalias"></span>
- </dd>
- <dt><code>--add-stdcall-alias</code></dt>
- <dd><p>If given, symbols with a stdcall suffix (@<var>nn</var>) will be exported
- as-is and also with the suffix stripped.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dbase_002dfile"></span>
- </dd>
- <dt><code>--base-file <var>file</var></code></dt>
- <dd><p>Use <var>file</var> as the name of a file in which to save the base
- addresses of all the relocations needed for generating DLLs with
- <samp>dlltool</samp>.
- [This is an i386 PE specific option]
- </p>
- <span id="index-_002d_002ddll"></span>
- </dd>
- <dt><code>--dll</code></dt>
- <dd><p>Create a DLL instead of a regular executable. You may also use
- <samp>-shared</samp> or specify a <code>LIBRARY</code> in a given <code>.def</code>
- file.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002denable_002dlong_002dsection_002dnames"></span>
- <span id="index-_002d_002ddisable_002dlong_002dsection_002dnames"></span>
- </dd>
- <dt><code>--enable-long-section-names</code></dt>
- <dt><code>--disable-long-section-names</code></dt>
- <dd><p>The PE variants of the COFF object format add an extension that permits
- the use of section names longer than eight characters, the normal limit
- for COFF. By default, these names are only allowed in object files, as
- fully-linked executable images do not carry the COFF string table required
- to support the longer names. As a GNU extension, it is possible to
- allow their use in executable images as well, or to (probably pointlessly!)
- disallow it in object files, by using these two options. Executable images
- generated with these long section names are slightly non-standard, carrying
- as they do a string table, and may generate confusing output when examined
- with non-GNU PE-aware tools, such as file viewers and dumpers. However,
- GDB relies on the use of PE long section names to find Dwarf-2 debug
- information sections in an executable image at runtime, and so if neither
- option is specified on the command-line, <code>ld</code> will enable long
- section names, overriding the default and technically correct behaviour,
- when it finds the presence of debug information while linking an executable
- image and not stripping symbols.
- [This option is valid for all PE targeted ports of the linker]
- </p>
- <span id="index-_002d_002denable_002dstdcall_002dfixup"></span>
- <span id="index-_002d_002ddisable_002dstdcall_002dfixup"></span>
- </dd>
- <dt><code>--enable-stdcall-fixup</code></dt>
- <dt><code>--disable-stdcall-fixup</code></dt>
- <dd><p>If the link finds a symbol that it cannot resolve, it will attempt to
- do “fuzzy linking” by looking for another defined symbol that differs
- only in the format of the symbol name (cdecl vs stdcall) and will
- resolve that symbol by linking to the match. For example, the
- undefined symbol <code>_foo</code> might be linked to the function
- <code>_foo@12</code>, or the undefined symbol <code>_bar@16</code> might be linked
- to the function <code>_bar</code>. When the linker does this, it prints a
- warning, since it normally should have failed to link, but sometimes
- import libraries generated from third-party dlls may need this feature
- to be usable. If you specify <samp>--enable-stdcall-fixup</samp>, this
- feature is fully enabled and warnings are not printed. If you specify
- <samp>--disable-stdcall-fixup</samp>, this feature is disabled and such
- mismatches are considered to be errors.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dleading_002dunderscore"></span>
- <span id="index-_002d_002dno_002dleading_002dunderscore"></span>
- </dd>
- <dt><code>--leading-underscore</code></dt>
- <dt><code>--no-leading-underscore</code></dt>
- <dd><p>For most targets default symbol-prefix is an underscore and is defined
- in target’s description. By this option it is possible to
- disable/enable the default underscore symbol-prefix.
- </p>
- <span id="index-DLLs_002c-creating"></span>
- <span id="index-_002d_002dexport_002dall_002dsymbols"></span>
- </dd>
- <dt><code>--export-all-symbols</code></dt>
- <dd><p>If given, all global symbols in the objects used to build a DLL will
- be exported by the DLL. Note that this is the default if there
- otherwise wouldn’t be any exported symbols. When symbols are
- explicitly exported via DEF files or implicitly exported via function
- attributes, the default is to not export anything else unless this
- option is given. Note that the symbols <code>DllMain@12</code>,
- <code>DllEntryPoint@0</code>, <code>DllMainCRTStartup@12</code>, and
- <code>impure_ptr</code> will not be automatically
- exported. Also, symbols imported from other DLLs will not be
- re-exported, nor will symbols specifying the DLL’s internal layout
- such as those beginning with <code>_head_</code> or ending with
- <code>_iname</code>. In addition, no symbols from <code>libgcc</code>,
- <code>libstd++</code>, <code>libmingw32</code>, or <code>crtX.o</code> will be exported.
- Symbols whose names begin with <code>__rtti_</code> or <code>__builtin_</code> will
- not be exported, to help with C++ DLLs. Finally, there is an
- extensive list of cygwin-private symbols that are not exported
- (obviously, this applies on when building DLLs for cygwin targets).
- These cygwin-excludes are: <code>_cygwin_dll_entry@12</code>,
- <code>_cygwin_crt0_common@8</code>, <code>_cygwin_noncygwin_dll_entry@12</code>,
- <code>_fmode</code>, <code>_impure_ptr</code>, <code>cygwin_attach_dll</code>,
- <code>cygwin_premain0</code>, <code>cygwin_premain1</code>, <code>cygwin_premain2</code>,
- <code>cygwin_premain3</code>, and <code>environ</code>.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dexclude_002dsymbols"></span>
- </dd>
- <dt><code>--exclude-symbols <var>symbol</var>,<var>symbol</var>,...</code></dt>
- <dd><p>Specifies a list of symbols which should not be automatically
- exported. The symbol names may be delimited by commas or colons.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dexclude_002dall_002dsymbols"></span>
- </dd>
- <dt><code>--exclude-all-symbols</code></dt>
- <dd><p>Specifies no symbols should be automatically exported.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dfile_002dalignment"></span>
- </dd>
- <dt><code>--file-alignment</code></dt>
- <dd><p>Specify the file alignment. Sections in the file will always begin at
- file offsets which are multiples of this number. This defaults to
- 512.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-heap-size"></span>
- <span id="index-_002d_002dheap"></span>
- </dd>
- <dt><code>--heap <var>reserve</var></code></dt>
- <dt><code>--heap <var>reserve</var>,<var>commit</var></code></dt>
- <dd><p>Specify the number of bytes of memory to reserve (and optionally commit)
- to be used as heap for this program. The default is 1MB reserved, 4K
- committed.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-image-base"></span>
- <span id="index-_002d_002dimage_002dbase"></span>
- </dd>
- <dt><code>--image-base <var>value</var></code></dt>
- <dd><p>Use <var>value</var> as the base address of your program or dll. This is
- the lowest memory location that will be used when your program or dll
- is loaded. To reduce the need to relocate and improve performance of
- your dlls, each should have a unique base address and not overlap any
- other dlls. The default is 0x400000 for executables, and 0x10000000
- for dlls.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dkill_002dat"></span>
- </dd>
- <dt><code>--kill-at</code></dt>
- <dd><p>If given, the stdcall suffixes (@<var>nn</var>) will be stripped from
- symbols before they are exported.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dlarge_002daddress_002daware"></span>
- </dd>
- <dt><code>--large-address-aware</code></dt>
- <dd><p>If given, the appropriate bit in the “Characteristics” field of the COFF
- header is set to indicate that this executable supports virtual addresses
- greater than 2 gigabytes. This should be used in conjunction with the /3GB
- or /USERVA=<var>value</var> megabytes switch in the “[operating systems]”
- section of the BOOT.INI. Otherwise, this bit has no effect.
- [This option is specific to PE targeted ports of the linker]
- </p>
- <span id="index-_002d_002ddisable_002dlarge_002daddress_002daware"></span>
- </dd>
- <dt><code>--disable-large-address-aware</code></dt>
- <dd><p>Reverts the effect of a previous ‘<samp>--large-address-aware</samp>’ option.
- This is useful if ‘<samp>--large-address-aware</samp>’ is always set by the compiler
- driver (e.g. Cygwin gcc) and the executable does not support virtual
- addresses greater than 2 gigabytes.
- [This option is specific to PE targeted ports of the linker]
- </p>
- <span id="index-_002d_002dmajor_002dimage_002dversion"></span>
- </dd>
- <dt><code>--major-image-version <var>value</var></code></dt>
- <dd><p>Sets the major number of the “image version”. Defaults to 1.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dmajor_002dos_002dversion"></span>
- </dd>
- <dt><code>--major-os-version <var>value</var></code></dt>
- <dd><p>Sets the major number of the “os version”. Defaults to 4.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dmajor_002dsubsystem_002dversion"></span>
- </dd>
- <dt><code>--major-subsystem-version <var>value</var></code></dt>
- <dd><p>Sets the major number of the “subsystem version”. Defaults to 4.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dminor_002dimage_002dversion"></span>
- </dd>
- <dt><code>--minor-image-version <var>value</var></code></dt>
- <dd><p>Sets the minor number of the “image version”. Defaults to 0.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dminor_002dos_002dversion"></span>
- </dd>
- <dt><code>--minor-os-version <var>value</var></code></dt>
- <dd><p>Sets the minor number of the “os version”. Defaults to 0.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dminor_002dsubsystem_002dversion"></span>
- </dd>
- <dt><code>--minor-subsystem-version <var>value</var></code></dt>
- <dd><p>Sets the minor number of the “subsystem version”. Defaults to 0.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-DEF-files_002c-creating"></span>
- <span id="index-DLLs_002c-creating-1"></span>
- <span id="index-_002d_002doutput_002ddef"></span>
- </dd>
- <dt><code>--output-def <var>file</var></code></dt>
- <dd><p>The linker will create the file <var>file</var> which will contain a DEF
- file corresponding to the DLL the linker is generating. This DEF file
- (which should be called <code>*.def</code>) may be used to create an import
- library with <code>dlltool</code> or may be used as a reference to
- automatically or implicitly exported symbols.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-DLLs_002c-creating-2"></span>
- <span id="index-_002d_002denable_002dauto_002dimage_002dbase"></span>
- </dd>
- <dt><code>--enable-auto-image-base</code></dt>
- <dt><code>--enable-auto-image-base=<var>value</var></code></dt>
- <dd><p>Automatically choose the image base for DLLs, optionally starting with base
- <var>value</var>, unless one is specified using the <code>--image-base</code> argument.
- By using a hash generated from the dllname to create unique image bases
- for each DLL, in-memory collisions and relocations which can delay program
- execution are avoided.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002ddisable_002dauto_002dimage_002dbase"></span>
- </dd>
- <dt><code>--disable-auto-image-base</code></dt>
- <dd><p>Do not automatically generate a unique image base. If there is no
- user-specified image base (<code>--image-base</code>) then use the platform
- default.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-DLLs_002c-linking-to"></span>
- <span id="index-_002d_002ddll_002dsearch_002dprefix"></span>
- </dd>
- <dt><code>--dll-search-prefix <var>string</var></code></dt>
- <dd><p>When linking dynamically to a dll without an import library,
- search for <code><string><basename>.dll</code> in preference to
- <code>lib<basename>.dll</code>. This behaviour allows easy distinction
- between DLLs built for the various "subplatforms": native, cygwin,
- uwin, pw, etc. For instance, cygwin DLLs typically use
- <code>--dll-search-prefix=cyg</code>.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002denable_002dauto_002dimport"></span>
- </dd>
- <dt><code>--enable-auto-import</code></dt>
- <dd><p>Do sophisticated linking of <code>_symbol</code> to <code>__imp__symbol</code> for
- DATA imports from DLLs, thus making it possible to bypass the dllimport
- mechanism on the user side and to reference unmangled symbol names.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <p>The following remarks pertain to the original implementation of the
- feature and are obsolete nowadays for Cygwin and MinGW targets.
- </p>
- <p>Note: Use of the ’auto-import’ extension will cause the text section
- of the image file to be made writable. This does not conform to the
- PE-COFF format specification published by Microsoft.
- </p>
- <p>Note - use of the ’auto-import’ extension will also cause read only
- data which would normally be placed into the .rdata section to be
- placed into the .data section instead. This is in order to work
- around a problem with consts that is described here:
- http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
- </p>
- <p>Using ’auto-import’ generally will ’just work’ – but sometimes you may
- see this message:
- </p>
- <p>"variable ’<var>’ can’t be auto-imported. Please read the
- documentation for ld’s <code>--enable-auto-import</code> for details."
- </p>
- <p>This message occurs when some (sub)expression accesses an address
- ultimately given by the sum of two constants (Win32 import tables only
- allow one). Instances where this may occur include accesses to member
- fields of struct variables imported from a DLL, as well as using a
- constant index into an array variable imported from a DLL. Any
- multiword variable (arrays, structs, long long, etc) may trigger
- this error condition. However, regardless of the exact data type
- of the offending exported variable, ld will always detect it, issue
- the warning, and exit.
- </p>
- <p>There are several ways to address this difficulty, regardless of the
- data type of the exported variable:
- </p>
- <p>One way is to use –enable-runtime-pseudo-reloc switch. This leaves the task
- of adjusting references in your client code for runtime environment, so
- this method works only when runtime environment supports this feature.
- </p>
- <p>A second solution is to force one of the ’constants’ to be a variable –
- that is, unknown and un-optimizable at compile time. For arrays,
- there are two possibilities: a) make the indexee (the array’s address)
- a variable, or b) make the ’constant’ index a variable. Thus:
- </p>
- <div class="example">
- <pre class="example">extern type extern_array[];
- extern_array[1] -->
- { volatile type *t=extern_array; t[1] }
- </pre></div>
- <p>or
- </p>
- <div class="example">
- <pre class="example">extern type extern_array[];
- extern_array[1] -->
- { volatile int t=1; extern_array[t] }
- </pre></div>
- <p>For structs (and most other multiword data types) the only option
- is to make the struct itself (or the long long, or the ...) variable:
- </p>
- <div class="example">
- <pre class="example">extern struct s extern_struct;
- extern_struct.field -->
- { volatile struct s *t=&extern_struct; t->field }
- </pre></div>
- <p>or
- </p>
- <div class="example">
- <pre class="example">extern long long extern_ll;
- extern_ll -->
- { volatile long long * local_ll=&extern_ll; *local_ll }
- </pre></div>
- <p>A third method of dealing with this difficulty is to abandon
- ’auto-import’ for the offending symbol and mark it with
- <code>__declspec(dllimport)</code>. However, in practice that
- requires using compile-time #defines to indicate whether you are
- building a DLL, building client code that will link to the DLL, or
- merely building/linking to a static library. In making the choice
- between the various methods of resolving the ’direct address with
- constant offset’ problem, you should consider typical real-world usage:
- </p>
- <p>Original:
- </p><div class="example">
- <pre class="example">--foo.h
- extern int arr[];
- --foo.c
- #include "foo.h"
- void main(int argc, char **argv){
- printf("%d\n",arr[1]);
- }
- </pre></div>
- <p>Solution 1:
- </p><div class="example">
- <pre class="example">--foo.h
- extern int arr[];
- --foo.c
- #include "foo.h"
- void main(int argc, char **argv){
- /* This workaround is for win32 and cygwin; do not "optimize" */
- volatile int *parr = arr;
- printf("%d\n",parr[1]);
- }
- </pre></div>
- <p>Solution 2:
- </p><div class="example">
- <pre class="example">--foo.h
- /* Note: auto-export is assumed (no __declspec(dllexport)) */
- #if (defined(_WIN32) || defined(__CYGWIN__)) && \
- !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
- #define FOO_IMPORT __declspec(dllimport)
- #else
- #define FOO_IMPORT
- #endif
- extern FOO_IMPORT int arr[];
- --foo.c
- #include "foo.h"
- void main(int argc, char **argv){
- printf("%d\n",arr[1]);
- }
- </pre></div>
- <p>A fourth way to avoid this problem is to re-code your
- library to use a functional interface rather than a data interface
- for the offending variables (e.g. set_foo() and get_foo() accessor
- functions).
- </p>
- <span id="index-_002d_002ddisable_002dauto_002dimport"></span>
- </dd>
- <dt><code>--disable-auto-import</code></dt>
- <dd><p>Do not attempt to do sophisticated linking of <code>_symbol</code> to
- <code>__imp__symbol</code> for DATA imports from DLLs.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002denable_002druntime_002dpseudo_002dreloc"></span>
- </dd>
- <dt><code>--enable-runtime-pseudo-reloc</code></dt>
- <dd><p>If your code contains expressions described in –enable-auto-import section,
- that is, DATA imports from DLL with non-zero offset, this switch will create
- a vector of ’runtime pseudo relocations’ which can be used by runtime
- environment to adjust references to such data in your client code.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002ddisable_002druntime_002dpseudo_002dreloc"></span>
- </dd>
- <dt><code>--disable-runtime-pseudo-reloc</code></dt>
- <dd><p>Do not create pseudo relocations for non-zero offset DATA imports from DLLs.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002denable_002dextra_002dpe_002ddebug"></span>
- </dd>
- <dt><code>--enable-extra-pe-debug</code></dt>
- <dd><p>Show additional debug info related to auto-import symbol thunking.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dsection_002dalignment"></span>
- </dd>
- <dt><code>--section-alignment</code></dt>
- <dd><p>Sets the section alignment. Sections in memory will always begin at
- addresses which are a multiple of this number. Defaults to 0x1000.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-stack-size"></span>
- <span id="index-_002d_002dstack"></span>
- </dd>
- <dt><code>--stack <var>reserve</var></code></dt>
- <dt><code>--stack <var>reserve</var>,<var>commit</var></code></dt>
- <dd><p>Specify the number of bytes of memory to reserve (and optionally commit)
- to be used as stack for this program. The default is 2MB reserved, 4K
- committed.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <span id="index-_002d_002dsubsystem"></span>
- </dd>
- <dt><code>--subsystem <var>which</var></code></dt>
- <dt><code>--subsystem <var>which</var>:<var>major</var></code></dt>
- <dt><code>--subsystem <var>which</var>:<var>major</var>.<var>minor</var></code></dt>
- <dd><p>Specifies the subsystem under which your program will execute. The
- legal values for <var>which</var> are <code>native</code>, <code>windows</code>,
- <code>console</code>, <code>posix</code>, and <code>xbox</code>. You may optionally set
- the subsystem version also. Numeric values are also accepted for
- <var>which</var>.
- [This option is specific to the i386 PE targeted port of the linker]
- </p>
- <p>The following options set flags in the <code>DllCharacteristics</code> field
- of the PE file header:
- [These options are specific to PE targeted ports of the linker]
- </p>
- <span id="index-_002d_002dhigh_002dentropy_002dva"></span>
- </dd>
- <dt><code>--high-entropy-va</code></dt>
- <dt><code>--disable-high-entropy-va</code></dt>
- <dd><p>Image is compatible with 64-bit address space layout randomization
- (ASLR). This option is enabled by default for 64-bit PE images.
- </p>
- <p>This option also implies <samp>--dynamicbase</samp> and
- <samp>--enable-reloc-section</samp>.
- </p>
- <span id="index-_002d_002ddynamicbase"></span>
- </dd>
- <dt><code>--dynamicbase</code></dt>
- <dt><code>--disable-dynamicbase</code></dt>
- <dd><p>The image base address may be relocated using address space layout
- randomization (ASLR). This feature was introduced with MS Windows
- Vista for i386 PE targets. This option is enabled by default but
- can be disabled via the <samp>--disable-dynamicbase</samp> option.
- This option also implies <samp>--enable-reloc-section</samp>.
- </p>
- <span id="index-_002d_002dforceinteg"></span>
- </dd>
- <dt><code>--forceinteg</code></dt>
- <dt><code>--disable-forceinteg</code></dt>
- <dd><p>Code integrity checks are enforced. This option is disabled by
- default.
- </p>
- <span id="index-_002d_002dnxcompat"></span>
- </dd>
- <dt><code>--nxcompat</code></dt>
- <dt><code>--disable-nxcompat</code></dt>
- <dd><p>The image is compatible with the Data Execution Prevention.
- This feature was introduced with MS Windows XP SP2 for i386 PE
- targets. The option is enabled by default.
- </p>
- <span id="index-_002d_002dno_002disolation"></span>
- </dd>
- <dt><code>--no-isolation</code></dt>
- <dt><code>--disable-no-isolation</code></dt>
- <dd><p>Although the image understands isolation, do not isolate the image.
- This option is disabled by default.
- </p>
- <span id="index-_002d_002dno_002dseh"></span>
- </dd>
- <dt><code>--no-seh</code></dt>
- <dt><code>--disable-no-seh</code></dt>
- <dd><p>The image does not use SEH. No SE handler may be called from
- this image. This option is disabled by default.
- </p>
- <span id="index-_002d_002dno_002dbind"></span>
- </dd>
- <dt><code>--no-bind</code></dt>
- <dt><code>--disable-no-bind</code></dt>
- <dd><p>Do not bind this image. This option is disabled by default.
- </p>
- <span id="index-_002d_002dwdmdriver"></span>
- </dd>
- <dt><code>--wdmdriver</code></dt>
- <dt><code>--disable-wdmdriver</code></dt>
- <dd><p>The driver uses the MS Windows Driver Model. This option is disabled
- by default.
- </p>
- <span id="index-_002d_002dtsaware"></span>
- </dd>
- <dt><code>--tsaware</code></dt>
- <dt><code>--disable-tsaware</code></dt>
- <dd><p>The image is Terminal Server aware. This option is disabled by
- default.
- </p>
- <span id="index-_002d_002dinsert_002dtimestamp"></span>
- </dd>
- <dt><code>--insert-timestamp</code></dt>
- <dt><code>--no-insert-timestamp</code></dt>
- <dd><p>Insert a real timestamp into the image. This is the default behaviour
- as it matches legacy code and it means that the image will work with
- other, proprietary tools. The problem with this default is that it
- will result in slightly different images being produced each time the
- same sources are linked. The option <samp>--no-insert-timestamp</samp>
- can be used to insert a zero value for the timestamp, this ensuring
- that binaries produced from identical sources will compare
- identically.
- </p>
- <p>If <samp>--insert-timestamp</samp> is active then the time inserted is
- either the time that the linking takes place or, if the
- <code>SOURCE_DATE_EPOCH</code> environment variable is defined, the number
- of seconds since Unix epoch as specified by that variable.
- </p>
- <span id="index-_002d_002denable_002dreloc_002dsection"></span>
- </dd>
- <dt><code>--enable-reloc-section</code></dt>
- <dt><code>--disable-reloc-section</code></dt>
- <dd><p>Create the base relocation table, which is necessary if the image
- is loaded at a different image base than specified in the PE header.
- This option is enabled by default.
- </p></dd>
- </dl>
- <span id="Options-specific-to-C6X-uClinux-targets"></span><h4 class="subsection">2.1.2 Options specific to C6X uClinux targets</h4>
- <p>The C6X uClinux target uses a binary format called DSBT to support shared
- libraries. Each shared library in the system needs to have a unique index;
- all executables use an index of 0.
- </p>
- <dl compact="compact">
- <dd>
- <span id="index-_002d_002ddsbt_002dsize"></span>
- </dd>
- <dt><code>--dsbt-size <var>size</var></code></dt>
- <dd><p>This option sets the number of entries in the DSBT of the current executable
- or shared library to <var>size</var>. The default is to create a table with 64
- entries.
- </p>
- <span id="index-_002d_002ddsbt_002dindex"></span>
- </dd>
- <dt><code>--dsbt-index <var>index</var></code></dt>
- <dd><p>This option sets the DSBT index of the current executable or shared library
- to <var>index</var>. The default is 0, which is appropriate for generating
- executables. If a shared library is generated with a DSBT index of 0, the
- <code>R_C6000_DSBT_INDEX</code> relocs are copied into the output file.
- </p>
- <span id="index-_002d_002dno_002dmerge_002dexidx_002dentries"></span>
- <p>The ‘<samp>--no-merge-exidx-entries</samp>’ switch disables the merging of adjacent
- exidx entries in frame unwind info.
- </p>
- </dd>
- </dl>
- <span id="Options-specific-to-C_002dSKY-targets"></span><h4 class="subsection">2.1.3 Options specific to C-SKY targets</h4>
- <dl compact="compact">
- <dd>
- <span id="index-_002d_002dbranch_002dstub-on-C_002dSKY"></span>
- </dd>
- <dt><code>--branch-stub</code></dt>
- <dd><p>This option enables linker branch relaxation by inserting branch stub
- sections when needed to extend the range of branches. This option is
- usually not required since C-SKY supports branch and call instructions that
- can access the full memory range and branch relaxation is normally handled by
- the compiler or assembler.
- </p>
- <span id="index-_002d_002dstub_002dgroup_002dsize-on-C_002dSKY"></span>
- </dd>
- <dt><code>--stub-group-size=<var>N</var></code></dt>
- <dd><p>This option allows finer control of linker branch stub creation.
- It sets the maximum size of a group of input sections that can
- be handled by one stub section. A negative value of <var>N</var> locates
- stub sections after their branches, while a positive value allows stub
- sections to appear either before or after the branches. Values of
- ‘<samp>1</samp>’ or ‘<samp>-1</samp>’ indicate that the
- linker should choose suitable defaults.
- </p>
- </dd>
- </dl>
- <span id="Options-specific-to-Motorola-68HC11-and-68HC12-targets"></span><h4 class="subsection">2.1.4 Options specific to Motorola 68HC11 and 68HC12 targets</h4>
- <p>The 68HC11 and 68HC12 linkers support specific options to control the
- memory bank switching mapping and trampoline code generation.
- </p>
- <dl compact="compact">
- <dd>
- <span id="index-_002d_002dno_002dtrampoline"></span>
- </dd>
- <dt><code>--no-trampoline</code></dt>
- <dd><p>This option disables the generation of trampoline. By default a trampoline
- is generated for each far function which is called using a <code>jsr</code>
- instruction (this happens when a pointer to a far function is taken).
- </p>
- <span id="index-_002d_002dbank_002dwindow"></span>
- </dd>
- <dt><code>--bank-window <var>name</var></code></dt>
- <dd><p>This option indicates to the linker the name of the memory region in
- the ‘<samp>MEMORY</samp>’ specification that describes the memory bank window.
- The definition of such region is then used by the linker to compute
- paging and addresses within the memory window.
- </p>
- </dd>
- </dl>
- <span id="Options-specific-to-Motorola-68K-target"></span><h4 class="subsection">2.1.5 Options specific to Motorola 68K target</h4>
- <p>The following options are supported to control handling of GOT generation
- when linking for 68K targets.
- </p>
- <dl compact="compact">
- <dd>
- <span id="index-_002d_002dgot"></span>
- </dd>
- <dt><code>--got=<var>type</var></code></dt>
- <dd><p>This option tells the linker which GOT generation scheme to use.
- <var>type</var> should be one of ‘<samp>single</samp>’, ‘<samp>negative</samp>’,
- ‘<samp>multigot</samp>’ or ‘<samp>target</samp>’. For more information refer to the
- Info entry for <samp>ld</samp>.
- </p>
- </dd>
- </dl>
- <span id="Options-specific-to-MIPS-targets"></span><h4 class="subsection">2.1.6 Options specific to MIPS targets</h4>
- <p>The following options are supported to control microMIPS instruction
- generation and branch relocation checks for ISA mode transitions when
- linking for MIPS targets.
- </p>
- <dl compact="compact">
- <dd>
- <span id="index-_002d_002dinsn32"></span>
- </dd>
- <dt><code>--insn32</code></dt>
- <dd><span id="index-_002d_002dno_002dinsn32"></span>
- </dd>
- <dt><code>--no-insn32</code></dt>
- <dd><p>These options control the choice of microMIPS instructions used in code
- generated by the linker, such as that in the PLT or lazy binding stubs,
- or in relaxation. If ‘<samp>--insn32</samp>’ is used, then the linker only uses
- 32-bit instruction encodings. By default or if ‘<samp>--no-insn32</samp>’ is
- used, all instruction encodings are used, including 16-bit ones where
- possible.
- </p>
- <span id="index-_002d_002dignore_002dbranch_002disa"></span>
- </dd>
- <dt><code>--ignore-branch-isa</code></dt>
- <dd><span id="index-_002d_002dno_002dignore_002dbranch_002disa"></span>
- </dd>
- <dt><code>--no-ignore-branch-isa</code></dt>
- <dd><p>These options control branch relocation checks for invalid ISA mode
- transitions. If ‘<samp>--ignore-branch-isa</samp>’ is used, then the linker
- accepts any branch relocations and any ISA mode transition required
- is lost in relocation calculation, except for some cases of <code>BAL</code>
- instructions which meet relaxation conditions and are converted to
- equivalent <code>JALX</code> instructions as the associated relocation is
- calculated. By default or if ‘<samp>--no-ignore-branch-isa</samp>’ is used
- a check is made causing the loss of an ISA mode transition to produce
- an error.
- </p>
- <span id="index-_002d_002dcompact_002dbranches"></span>
- </dd>
- <dt><code>--compact-branches</code></dt>
- <dd><span id="index-_002d_002dno_002dcompact_002dbranches"></span>
- </dd>
- <dt><code>--no-compact-branches</code></dt>
- <dd><p>These options control the generation of compact instructions by the linker
- in the PLT entries for MIPS R6.
- </p>
- </dd>
- </dl>
- <span id="Options-specific-to-PDP11-targets"></span><h4 class="subsection">2.1.7 Options specific to PDP11 targets</h4>
- <p>For the pdp11-aout target, three variants of the output format can be
- produced as selected by the following options. The default variant
- for pdp11-aout is the ‘<samp>--omagic</samp>’ option, whereas for other
- targets ‘<samp>--nmagic</samp>’ is the default. The ‘<samp>--imagic</samp>’ option is
- defined only for the pdp11-aout target, while the others are described
- here as they apply to the pdp11-aout target.
- </p>
- <dl compact="compact">
- <dd>
- <span id="index-_002dN-1"></span>
- </dd>
- <dt><code>-N</code></dt>
- <dd><span id="index-_002d_002domagic-1"></span>
- </dd>
- <dt><code>--omagic</code></dt>
- <dd>
- <p>Mark the output as <code>OMAGIC</code> (0407) in the <samp>a.out</samp> header to
- indicate that the text segment is not to be write-protected and
- shared. Since the text and data sections are both readable and
- writable, the data section is allocated immediately contiguous after
- the text segment. This is the oldest format for PDP11 executable
- programs and is the default for <code>ld</code> on PDP11 Unix systems
- from the beginning through 2.11BSD.
- </p>
- <span id="index-_002dn-1"></span>
- </dd>
- <dt><code>-n</code></dt>
- <dd><span id="index-_002d_002dnmagic-1"></span>
- </dd>
- <dt><code>--nmagic</code></dt>
- <dd>
- <p>Mark the output as <code>NMAGIC</code> (0410) in the <samp>a.out</samp> header to
- indicate that when the output file is executed, the text portion will
- be read-only and shareable among all processes executing the same
- file. This involves moving the data areas up to the first possible 8K
- byte page boundary following the end of the text. This option creates
- a <em>pure executable</em> format.
- </p>
- <span id="index-_002dz"></span>
- </dd>
- <dt><code>-z</code></dt>
- <dd><span id="index-_002d_002dimagic"></span>
- </dd>
- <dt><code>--imagic</code></dt>
- <dd>
- <p>Mark the output as <code>IMAGIC</code> (0411) in the <samp>a.out</samp> header to
- indicate that when the output file is executed, the program text and
- data areas will be loaded into separate address spaces using the split
- instruction and data space feature of the memory management unit in
- larger models of the PDP11. This doubles the address space available
- to the program. The text segment is again pure, write-protected, and
- shareable. The only difference in the output format between this
- option and the others, besides the magic number, is that both the text
- and data sections start at location 0. The ‘<samp>-z</samp>’ option selected
- this format in 2.11BSD. This option creates a <em>separate
- executable</em> format.
- </p>
- <span id="index-_002d_002dno_002domagic-1"></span>
- </dd>
- <dt><code>--no-omagic</code></dt>
- <dd>
- <p>Equivalent to ‘<samp>--nmagic</samp>’ for pdp11-aout.
- </p>
- </dd>
- </dl>
- <hr>
- <span id="Environment"></span><div class="header">
- <p>
- Previous: <a href="#Options" accesskey="p" rel="prev">Options</a>, Up: <a href="#Invocation" accesskey="u" rel="up">Invocation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Environment-Variables"></span><h3 class="section">2.2 Environment Variables</h3>
- <p>You can change the behaviour of <code>ld</code> with the environment variables
- <code>GNUTARGET</code>,
- <code>LDEMULATION</code> and <code>COLLECT_NO_DEMANGLE</code>.
- </p>
- <span id="index-GNUTARGET"></span>
- <span id="index-default-input-format"></span>
- <p><code>GNUTARGET</code> determines the input-file object format if you don’t
- use ‘<samp>-b</samp>’ (or its synonym ‘<samp>--format</samp>’). Its value should be one
- of the BFD names for an input format (see <a href="#BFD">BFD</a>). If there is no
- <code>GNUTARGET</code> in the environment, <code>ld</code> uses the natural format
- of the target. If <code>GNUTARGET</code> is set to <code>default</code> then BFD
- attempts to discover the input format by examining binary input files;
- this method often succeeds, but there are potential ambiguities, since
- there is no method of ensuring that the magic number used to specify
- object-file formats is unique. However, the configuration procedure for
- BFD on each system places the conventional format for that system first
- in the search-list, so ambiguities are resolved in favor of convention.
- </p>
- <span id="index-LDEMULATION"></span>
- <span id="index-default-emulation"></span>
- <span id="index-emulation_002c-default"></span>
- <p><code>LDEMULATION</code> determines the default emulation if you don’t use the
- ‘<samp>-m</samp>’ option. The emulation can affect various aspects of linker
- behaviour, particularly the default linker script. You can list the
- available emulations with the ‘<samp>--verbose</samp>’ or ‘<samp>-V</samp>’ options. If
- the ‘<samp>-m</samp>’ option is not used, and the <code>LDEMULATION</code> environment
- variable is not defined, the default emulation depends upon how the
- linker was configured.
- </p>
- <span id="index-COLLECT_005fNO_005fDEMANGLE"></span>
- <span id="index-demangling_002c-default"></span>
- <p>Normally, the linker will default to demangling symbols. However, if
- <code>COLLECT_NO_DEMANGLE</code> is set in the environment, then it will
- default to not demangling symbols. This environment variable is used in
- a similar fashion by the <code>gcc</code> linker wrapper program. The default
- may be overridden by the ‘<samp>--demangle</samp>’ and ‘<samp>--no-demangle</samp>’
- options.
- </p>
- <hr>
- <span id="Scripts"></span><div class="header">
- <p>
- Next: <a href="#Plugins" accesskey="n" rel="next">Plugins</a>, Previous: <a href="#Invocation" accesskey="p" rel="prev">Invocation</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Linker-Scripts"></span><h2 class="chapter">3 Linker Scripts</h2>
- <span id="index-scripts"></span>
- <span id="index-linker-scripts"></span>
- <span id="index-command-files"></span>
- <p>Every link is controlled by a <em>linker script</em>. This script is
- written in the linker command language.
- </p>
- <p>The main purpose of the linker script is to describe how the sections in
- the input files should be mapped into the output file, and to control
- the memory layout of the output file. Most linker scripts do nothing
- more than this. However, when necessary, the linker script can also
- direct the linker to perform many other operations, using the commands
- described below.
- </p>
- <p>The linker always uses a linker script. If you do not supply one
- yourself, the linker will use a default script that is compiled into the
- linker executable. You can use the ‘<samp>--verbose</samp>’ command-line option
- to display the default linker script. Certain command-line options,
- such as ‘<samp>-r</samp>’ or ‘<samp>-N</samp>’, will affect the default linker script.
- </p>
- <p>You may supply your own linker script by using the ‘<samp>-T</samp>’ command
- line option. When you do this, your linker script will replace the
- default linker script.
- </p>
- <p>You may also use linker scripts implicitly by naming them as input files
- to the linker, as though they were files to be linked. See <a href="#Implicit-Linker-Scripts">Implicit Linker Scripts</a>.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Basic-Script-Concepts" accesskey="1">Basic Script Concepts</a></td><td> </td><td align="left" valign="top">Basic Linker Script Concepts
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Script-Format" accesskey="2">Script Format</a></td><td> </td><td align="left" valign="top">Linker Script Format
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Simple-Example" accesskey="3">Simple Example</a></td><td> </td><td align="left" valign="top">Simple Linker Script Example
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Simple-Commands" accesskey="4">Simple Commands</a></td><td> </td><td align="left" valign="top">Simple Linker Script Commands
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Assignments" accesskey="5">Assignments</a></td><td> </td><td align="left" valign="top">Assigning Values to Symbols
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#SECTIONS" accesskey="6">SECTIONS</a></td><td> </td><td align="left" valign="top">SECTIONS Command
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#MEMORY" accesskey="7">MEMORY</a></td><td> </td><td align="left" valign="top">MEMORY Command
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#PHDRS" accesskey="8">PHDRS</a></td><td> </td><td align="left" valign="top">PHDRS Command
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#VERSION" accesskey="9">VERSION</a></td><td> </td><td align="left" valign="top">VERSION Command
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Expressions">Expressions</a></td><td> </td><td align="left" valign="top">Expressions in Linker Scripts
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Implicit-Linker-Scripts">Implicit Linker Scripts</a></td><td> </td><td align="left" valign="top">Implicit Linker Scripts
- </td></tr>
- </table>
- <hr>
- <span id="Basic-Script-Concepts"></span><div class="header">
- <p>
- Next: <a href="#Script-Format" accesskey="n" rel="next">Script Format</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Basic-Linker-Script-Concepts"></span><h3 class="section">3.1 Basic Linker Script Concepts</h3>
- <span id="index-linker-script-concepts"></span>
- <p>We need to define some basic concepts and vocabulary in order to
- describe the linker script language.
- </p>
- <p>The linker combines input files into a single output file. The output
- file and each input file are in a special data format known as an
- <em>object file format</em>. Each file is called an <em>object file</em>.
- The output file is often called an <em>executable</em>, but for our
- purposes we will also call it an object file. Each object file has,
- among other things, a list of <em>sections</em>. We sometimes refer to a
- section in an input file as an <em>input section</em>; similarly, a section
- in the output file is an <em>output section</em>.
- </p>
- <p>Each section in an object file has a name and a size. Most sections
- also have an associated block of data, known as the <em>section
- contents</em>. A section may be marked as <em>loadable</em>, which means that
- the contents should be loaded into memory when the output file is run.
- A section with no contents may be <em>allocatable</em>, which means that an
- area in memory should be set aside, but nothing in particular should be
- loaded there (in some cases this memory must be zeroed out). A section
- which is neither loadable nor allocatable typically contains some sort
- of debugging information.
- </p>
- <p>Every loadable or allocatable output section has two addresses. The
- first is the <em>VMA</em>, or virtual memory address. This is the address
- the section will have when the output file is run. The second is the
- <em>LMA</em>, or load memory address. This is the address at which the
- section will be loaded. In most cases the two addresses will be the
- same. An example of when they might be different is when a data section
- is loaded into ROM, and then copied into RAM when the program starts up
- (this technique is often used to initialize global variables in a ROM
- based system). In this case the ROM address would be the LMA, and the
- RAM address would be the VMA.
- </p>
- <p>You can see the sections in an object file by using the <code>objdump</code>
- program with the ‘<samp>-h</samp>’ option.
- </p>
- <p>Every object file also has a list of <em>symbols</em>, known as the
- <em>symbol table</em>. A symbol may be defined or undefined. Each symbol
- has a name, and each defined symbol has an address, among other
- information. If you compile a C or C++ program into an object file, you
- will get a defined symbol for every defined function and global or
- static variable. Every undefined function or global variable which is
- referenced in the input file will become an undefined symbol.
- </p>
- <p>You can see the symbols in an object file by using the <code>nm</code>
- program, or by using the <code>objdump</code> program with the ‘<samp>-t</samp>’
- option.
- </p>
- <hr>
- <span id="Script-Format"></span><div class="header">
- <p>
- Next: <a href="#Simple-Example" accesskey="n" rel="next">Simple Example</a>, Previous: <a href="#Basic-Script-Concepts" accesskey="p" rel="prev">Basic Script Concepts</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Linker-Script-Format"></span><h3 class="section">3.2 Linker Script Format</h3>
- <span id="index-linker-script-format"></span>
- <p>Linker scripts are text files.
- </p>
- <p>You write a linker script as a series of commands. Each command is
- either a keyword, possibly followed by arguments, or an assignment to a
- symbol. You may separate commands using semicolons. Whitespace is
- generally ignored.
- </p>
- <p>Strings such as file or format names can normally be entered directly.
- If the file name contains a character such as a comma which would
- otherwise serve to separate file names, you may put the file name in
- double quotes. There is no way to use a double quote character in a
- file name.
- </p>
- <p>You may include comments in linker scripts just as in C, delimited by
- ‘<samp>/*</samp>’ and ‘<samp>*/</samp>’. As in C, comments are syntactically equivalent
- to whitespace.
- </p>
- <hr>
- <span id="Simple-Example"></span><div class="header">
- <p>
- Next: <a href="#Simple-Commands" accesskey="n" rel="next">Simple Commands</a>, Previous: <a href="#Script-Format" accesskey="p" rel="prev">Script Format</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Simple-Linker-Script-Example"></span><h3 class="section">3.3 Simple Linker Script Example</h3>
- <span id="index-linker-script-example"></span>
- <span id="index-example-of-linker-script"></span>
- <p>Many linker scripts are fairly simple.
- </p>
- <p>The simplest possible linker script has just one command:
- ‘<samp>SECTIONS</samp>’. You use the ‘<samp>SECTIONS</samp>’ command to describe the
- memory layout of the output file.
- </p>
- <p>The ‘<samp>SECTIONS</samp>’ command is a powerful command. Here we will
- describe a simple use of it. Let’s assume your program consists only of
- code, initialized data, and uninitialized data. These will be in the
- ‘<samp>.text</samp>’, ‘<samp>.data</samp>’, and ‘<samp>.bss</samp>’ sections, respectively.
- Let’s assume further that these are the only sections which appear in
- your input files.
- </p>
- <p>For this example, let’s say that the code should be loaded at address
- 0x10000, and that the data should start at address 0x8000000. Here is a
- linker script which will do that:
- </p><div class="example">
- <pre class="example">SECTIONS
- {
- . = 0x10000;
- .text : { *(.text) }
- . = 0x8000000;
- .data : { *(.data) }
- .bss : { *(.bss) }
- }
- </pre></div>
- <p>You write the ‘<samp>SECTIONS</samp>’ command as the keyword ‘<samp>SECTIONS</samp>’,
- followed by a series of symbol assignments and output section
- descriptions enclosed in curly braces.
- </p>
- <p>The first line inside the ‘<samp>SECTIONS</samp>’ command of the above example
- sets the value of the special symbol ‘<samp>.</samp>’, which is the location
- counter. If you do not specify the address of an output section in some
- other way (other ways are described later), the address is set from the
- current value of the location counter. The location counter is then
- incremented by the size of the output section. At the start of the
- ‘<samp>SECTIONS</samp>’ command, the location counter has the value ‘<samp>0</samp>’.
- </p>
- <p>The second line defines an output section, ‘<samp>.text</samp>’. The colon is
- required syntax which may be ignored for now. Within the curly braces
- after the output section name, you list the names of the input sections
- which should be placed into this output section. The ‘<samp>*</samp>’ is a
- wildcard which matches any file name. The expression ‘<samp>*(.text)</samp>’
- means all ‘<samp>.text</samp>’ input sections in all input files.
- </p>
- <p>Since the location counter is ‘<samp>0x10000</samp>’ when the output section
- ‘<samp>.text</samp>’ is defined, the linker will set the address of the
- ‘<samp>.text</samp>’ section in the output file to be ‘<samp>0x10000</samp>’.
- </p>
- <p>The remaining lines define the ‘<samp>.data</samp>’ and ‘<samp>.bss</samp>’ sections in
- the output file. The linker will place the ‘<samp>.data</samp>’ output section
- at address ‘<samp>0x8000000</samp>’. After the linker places the ‘<samp>.data</samp>’
- output section, the value of the location counter will be
- ‘<samp>0x8000000</samp>’ plus the size of the ‘<samp>.data</samp>’ output section. The
- effect is that the linker will place the ‘<samp>.bss</samp>’ output section
- immediately after the ‘<samp>.data</samp>’ output section in memory.
- </p>
- <p>The linker will ensure that each output section has the required
- alignment, by increasing the location counter if necessary. In this
- example, the specified addresses for the ‘<samp>.text</samp>’ and ‘<samp>.data</samp>’
- sections will probably satisfy any alignment constraints, but the linker
- may have to create a small gap between the ‘<samp>.data</samp>’ and ‘<samp>.bss</samp>’
- sections.
- </p>
- <p>That’s it! That’s a simple and complete linker script.
- </p>
- <hr>
- <span id="Simple-Commands"></span><div class="header">
- <p>
- Next: <a href="#Assignments" accesskey="n" rel="next">Assignments</a>, Previous: <a href="#Simple-Example" accesskey="p" rel="prev">Simple Example</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Simple-Linker-Script-Commands"></span><h3 class="section">3.4 Simple Linker Script Commands</h3>
- <span id="index-linker-script-simple-commands"></span>
- <p>In this section we describe the simple linker script commands.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Entry-Point" accesskey="1">Entry Point</a></td><td> </td><td align="left" valign="top">Setting the entry point
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#File-Commands" accesskey="2">File Commands</a></td><td> </td><td align="left" valign="top">Commands dealing with files
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Format-Commands" accesskey="3">Format Commands</a></td><td> </td><td align="left" valign="top">Commands dealing with object file formats
- </td></tr>
- <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
- </pre></th></tr><tr><td align="left" valign="top">• <a href="#REGION_005fALIAS" accesskey="4">REGION_ALIAS</a></td><td> </td><td align="left" valign="top">Assign alias names to memory regions
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Miscellaneous-Commands" accesskey="5">Miscellaneous Commands</a></td><td> </td><td align="left" valign="top">Other linker script commands
- </td></tr>
- </table>
- <hr>
- <span id="Entry-Point"></span><div class="header">
- <p>
- Next: <a href="#File-Commands" accesskey="n" rel="next">File Commands</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Setting-the-Entry-Point"></span><h4 class="subsection">3.4.1 Setting the Entry Point</h4>
- <span id="index-ENTRY_0028symbol_0029"></span>
- <span id="index-start-of-execution"></span>
- <span id="index-first-instruction"></span>
- <span id="index-entry-point"></span>
- <p>The first instruction to execute in a program is called the <em>entry
- point</em>. You can use the <code>ENTRY</code> linker script command to set the
- entry point. The argument is a symbol name:
- </p><div class="example">
- <pre class="example">ENTRY(<var>symbol</var>)
- </pre></div>
- <p>There are several ways to set the entry point. The linker will set the
- entry point by trying each of the following methods in order, and
- stopping when one of them succeeds:
- </p><ul>
- <li> the ‘<samp>-e</samp>’ <var>entry</var> command-line option;
- </li><li> the <code>ENTRY(<var>symbol</var>)</code> command in a linker script;
- </li><li> the value of a target-specific symbol, if it is defined; For many
- targets this is <code>start</code>, but PE- and BeOS-based systems for example
- check a list of possible entry symbols, matching the first one found.
- </li><li> the address of the first byte of the code section, if present and an
- executable is being created - the code section is usually
- ‘<samp>.text</samp>’, but can be something else;
- </li><li> The address <code>0</code>.
- </li></ul>
- <hr>
- <span id="File-Commands"></span><div class="header">
- <p>
- Next: <a href="#Format-Commands" accesskey="n" rel="next">Format Commands</a>, Previous: <a href="#Entry-Point" accesskey="p" rel="prev">Entry Point</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Commands-Dealing-with-Files"></span><h4 class="subsection">3.4.2 Commands Dealing with Files</h4>
- <span id="index-linker-script-file-commands"></span>
- <p>Several linker script commands deal with files.
- </p>
- <dl compact="compact">
- <dt><code>INCLUDE <var>filename</var></code></dt>
- <dd><span id="index-INCLUDE-filename"></span>
- <span id="index-including-a-linker-script"></span>
- <p>Include the linker script <var>filename</var> at this point. The file will
- be searched for in the current directory, and in any directory specified
- with the <samp>-L</samp> option. You can nest calls to <code>INCLUDE</code> up to
- 10 levels deep.
- </p>
- <p>You can place <code>INCLUDE</code> directives at the top level, in <code>MEMORY</code> or
- <code>SECTIONS</code> commands, or in output section descriptions.
- </p>
- </dd>
- <dt><code>INPUT(<var>file</var>, <var>file</var>, …)</code></dt>
- <dt><code>INPUT(<var>file</var> <var>file</var> …)</code></dt>
- <dd><span id="index-INPUT_0028files_0029"></span>
- <span id="index-input-files-in-linker-scripts"></span>
- <span id="index-input-object-files-in-linker-scripts"></span>
- <span id="index-linker-script-input-object-files"></span>
- <p>The <code>INPUT</code> command directs the linker to include the named files
- in the link, as though they were named on the command line.
- </p>
- <p>For example, if you always want to include <samp>subr.o</samp> any time you do
- a link, but you can’t be bothered to put it on every link command line,
- then you can put ‘<samp>INPUT (subr.o)</samp>’ in your linker script.
- </p>
- <p>In fact, if you like, you can list all of your input files in the linker
- script, and then invoke the linker with nothing but a ‘<samp>-T</samp>’ option.
- </p>
- <p>In case a <em>sysroot prefix</em> is configured, and the filename starts
- with the ‘<samp>/</samp>’ character, and the script being processed was
- located inside the <em>sysroot prefix</em>, the filename will be looked
- for in the <em>sysroot prefix</em>. The <em>sysroot prefix</em> can also be forced by specifying
- <code>=</code> as the first character in the filename path, or prefixing the
- filename path with <code>$SYSROOT</code>. See also the description of
- ‘<samp>-L</samp>’ in <a href="#Options">Command-line Options</a>.
- </p>
- <p>If a <em>sysroot prefix</em> is not used then the linker will try to open
- the file in the directory containing the linker script. If it is not
- found the linker will then search the current directory. If it is still
- not found the linker will search through the archive library search
- path.
- </p>
- <p>If you use ‘<samp>INPUT (-l<var>file</var>)</samp>’, <code>ld</code> will transform the
- name to <code>lib<var>file</var>.a</code>, as with the command-line argument
- ‘<samp>-l</samp>’.
- </p>
- <p>When you use the <code>INPUT</code> command in an implicit linker script, the
- files will be included in the link at the point at which the linker
- script file is included. This can affect archive searching.
- </p>
- </dd>
- <dt><code>GROUP(<var>file</var>, <var>file</var>, …)</code></dt>
- <dt><code>GROUP(<var>file</var> <var>file</var> …)</code></dt>
- <dd><span id="index-GROUP_0028files_0029"></span>
- <span id="index-grouping-input-files"></span>
- <p>The <code>GROUP</code> command is like <code>INPUT</code>, except that the named
- files should all be archives, and they are searched repeatedly until no
- new undefined references are created. See the description of ‘<samp>-(</samp>’
- in <a href="#Options">Command-line Options</a>.
- </p>
- </dd>
- <dt><code>AS_NEEDED(<var>file</var>, <var>file</var>, …)</code></dt>
- <dt><code>AS_NEEDED(<var>file</var> <var>file</var> …)</code></dt>
- <dd><span id="index-AS_005fNEEDED_0028files_0029"></span>
- <p>This construct can appear only inside of the <code>INPUT</code> or <code>GROUP</code>
- commands, among other filenames. The files listed will be handled
- as if they appear directly in the <code>INPUT</code> or <code>GROUP</code> commands,
- with the exception of ELF shared libraries, that will be added only
- when they are actually needed. This construct essentially enables
- <samp>--as-needed</samp> option for all the files listed inside of it
- and restores previous <samp>--as-needed</samp> resp. <samp>--no-as-needed</samp>
- setting afterwards.
- </p>
- </dd>
- <dt><code>OUTPUT(<var>filename</var>)</code></dt>
- <dd><span id="index-OUTPUT_0028filename_0029"></span>
- <span id="index-output-file-name-in-linker-script"></span>
- <p>The <code>OUTPUT</code> command names the output file. Using
- <code>OUTPUT(<var>filename</var>)</code> in the linker script is exactly like using
- ‘<samp>-o <var>filename</var></samp>’ on the command line (see <a href="#Options">Command
- Line Options</a>). If both are used, the command-line option takes
- precedence.
- </p>
- <p>You can use the <code>OUTPUT</code> command to define a default name for the
- output file other than the usual default of <samp>a.out</samp>.
- </p>
- </dd>
- <dt><code>SEARCH_DIR(<var>path</var>)</code></dt>
- <dd><span id="index-SEARCH_005fDIR_0028path_0029"></span>
- <span id="index-library-search-path-in-linker-script"></span>
- <span id="index-archive-search-path-in-linker-script"></span>
- <span id="index-search-path-in-linker-script"></span>
- <p>The <code>SEARCH_DIR</code> command adds <var>path</var> to the list of paths where
- <code>ld</code> looks for archive libraries. Using
- <code>SEARCH_DIR(<var>path</var>)</code> is exactly like using ‘<samp>-L <var>path</var></samp>’
- on the command line (see <a href="#Options">Command-line Options</a>). If both
- are used, then the linker will search both paths. Paths specified using
- the command-line option are searched first.
- </p>
- </dd>
- <dt><code>STARTUP(<var>filename</var>)</code></dt>
- <dd><span id="index-STARTUP_0028filename_0029"></span>
- <span id="index-first-input-file"></span>
- <p>The <code>STARTUP</code> command is just like the <code>INPUT</code> command, except
- that <var>filename</var> will become the first input file to be linked, as
- though it were specified first on the command line. This may be useful
- when using a system in which the entry point is always the start of the
- first file.
- </p></dd>
- </dl>
- <hr>
- <span id="Format-Commands"></span><div class="header">
- <p>
- Next: <a href="#REGION_005fALIAS" accesskey="n" rel="next">REGION_ALIAS</a>, Previous: <a href="#File-Commands" accesskey="p" rel="prev">File Commands</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Commands-Dealing-with-Object-File-Formats"></span><h4 class="subsection">3.4.3 Commands Dealing with Object File Formats</h4>
- <p>A couple of linker script commands deal with object file formats.
- </p>
- <dl compact="compact">
- <dt><code>OUTPUT_FORMAT(<var>bfdname</var>)</code></dt>
- <dt><code>OUTPUT_FORMAT(<var>default</var>, <var>big</var>, <var>little</var>)</code></dt>
- <dd><span id="index-OUTPUT_005fFORMAT_0028bfdname_0029"></span>
- <span id="index-output-file-format-in-linker-script"></span>
- <p>The <code>OUTPUT_FORMAT</code> command names the BFD format to use for the
- output file (see <a href="#BFD">BFD</a>). Using <code>OUTPUT_FORMAT(<var>bfdname</var>)</code> is
- exactly like using ‘<samp>--oformat <var>bfdname</var></samp>’ on the command line
- (see <a href="#Options">Command-line Options</a>). If both are used, the command
- line option takes precedence.
- </p>
- <p>You can use <code>OUTPUT_FORMAT</code> with three arguments to use different
- formats based on the ‘<samp>-EB</samp>’ and ‘<samp>-EL</samp>’ command-line options.
- This permits the linker script to set the output format based on the
- desired endianness.
- </p>
- <p>If neither ‘<samp>-EB</samp>’ nor ‘<samp>-EL</samp>’ are used, then the output format
- will be the first argument, <var>default</var>. If ‘<samp>-EB</samp>’ is used, the
- output format will be the second argument, <var>big</var>. If ‘<samp>-EL</samp>’ is
- used, the output format will be the third argument, <var>little</var>.
- </p>
- <p>For example, the default linker script for the MIPS ELF target uses this
- command:
- </p><div class="example">
- <pre class="example">OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
- </pre></div>
- <p>This says that the default format for the output file is
- ‘<samp>elf32-bigmips</samp>’, but if the user uses the ‘<samp>-EL</samp>’ command-line
- option, the output file will be created in the ‘<samp>elf32-littlemips</samp>’
- format.
- </p>
- </dd>
- <dt><code>TARGET(<var>bfdname</var>)</code></dt>
- <dd><span id="index-TARGET_0028bfdname_0029"></span>
- <span id="index-input-file-format-in-linker-script"></span>
- <p>The <code>TARGET</code> command names the BFD format to use when reading input
- files. It affects subsequent <code>INPUT</code> and <code>GROUP</code> commands.
- This command is like using ‘<samp>-b <var>bfdname</var></samp>’ on the command line
- (see <a href="#Options">Command-line Options</a>). If the <code>TARGET</code> command
- is used but <code>OUTPUT_FORMAT</code> is not, then the last <code>TARGET</code>
- command is also used to set the format for the output file. See <a href="#BFD">BFD</a>.
- </p></dd>
- </dl>
- <hr>
- <span id="REGION_005fALIAS"></span><div class="header">
- <p>
- Next: <a href="#Miscellaneous-Commands" accesskey="n" rel="next">Miscellaneous Commands</a>, Previous: <a href="#Format-Commands" accesskey="p" rel="prev">Format Commands</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Assign-alias-names-to-memory-regions"></span><h4 class="subsection">3.4.4 Assign alias names to memory regions</h4>
- <span id="index-REGION_005fALIAS_0028alias_002c-region_0029"></span>
- <span id="index-region-alias"></span>
- <span id="index-region-names"></span>
- <p>Alias names can be added to existing memory regions created with the
- <a href="#MEMORY">MEMORY</a> command. Each name corresponds to at most one memory region.
- </p>
- <div class="example">
- <pre class="example">REGION_ALIAS(<var>alias</var>, <var>region</var>)
- </pre></div>
- <p>The <code>REGION_ALIAS</code> function creates an alias name <var>alias</var> for the
- memory region <var>region</var>. This allows a flexible mapping of output sections
- to memory regions. An example follows.
- </p>
- <p>Suppose we have an application for embedded systems which come with various
- memory storage devices. All have a general purpose, volatile memory <code>RAM</code>
- that allows code execution or data storage. Some may have a read-only,
- non-volatile memory <code>ROM</code> that allows code execution and read-only data
- access. The last variant is a read-only, non-volatile memory <code>ROM2</code> with
- read-only data access and no code execution capability. We have four output
- sections:
- </p>
- <ul>
- <li> <code>.text</code> program code;
- </li><li> <code>.rodata</code> read-only data;
- </li><li> <code>.data</code> read-write initialized data;
- </li><li> <code>.bss</code> read-write zero initialized data.
- </li></ul>
- <p>The goal is to provide a linker command file that contains a system independent
- part defining the output sections and a system dependent part mapping the
- output sections to the memory regions available on the system. Our embedded
- systems come with three different memory setups <code>A</code>, <code>B</code> and
- <code>C</code>:
- </p><table>
- <tr><td width="25%">Section</td><td width="25%">Variant A</td><td width="25%">Variant B</td><td width="25%">Variant C</td></tr>
- <tr><td width="25%">.text</td><td width="25%">RAM</td><td width="25%">ROM</td><td width="25%">ROM</td></tr>
- <tr><td width="25%">.rodata</td><td width="25%">RAM</td><td width="25%">ROM</td><td width="25%">ROM2</td></tr>
- <tr><td width="25%">.data</td><td width="25%">RAM</td><td width="25%">RAM/ROM</td><td width="25%">RAM/ROM2</td></tr>
- <tr><td width="25%">.bss</td><td width="25%">RAM</td><td width="25%">RAM</td><td width="25%">RAM</td></tr>
- </table>
- <p>The notation <code>RAM/ROM</code> or <code>RAM/ROM2</code> means that this section is
- loaded into region <code>ROM</code> or <code>ROM2</code> respectively. Please note that
- the load address of the <code>.data</code> section starts in all three variants at
- the end of the <code>.rodata</code> section.
- </p>
- <p>The base linker script that deals with the output sections follows. It
- includes the system dependent <code>linkcmds.memory</code> file that describes the
- memory layout:
- </p><div class="example">
- <pre class="example">INCLUDE linkcmds.memory
- SECTIONS
- {
- .text :
- {
- *(.text)
- } > REGION_TEXT
- .rodata :
- {
- *(.rodata)
- rodata_end = .;
- } > REGION_RODATA
- .data : AT (rodata_end)
- {
- data_start = .;
- *(.data)
- } > REGION_DATA
- data_size = SIZEOF(.data);
- data_load_start = LOADADDR(.data);
- .bss :
- {
- *(.bss)
- } > REGION_BSS
- }
- </pre></div>
- <p>Now we need three different <code>linkcmds.memory</code> files to define memory
- regions and alias names. The content of <code>linkcmds.memory</code> for the three
- variants <code>A</code>, <code>B</code> and <code>C</code>:
- </p><dl compact="compact">
- <dt><code>A</code></dt>
- <dd><p>Here everything goes into the <code>RAM</code>.
- </p><div class="example">
- <pre class="example">MEMORY
- {
- RAM : ORIGIN = 0, LENGTH = 4M
- }
- REGION_ALIAS("REGION_TEXT", RAM);
- REGION_ALIAS("REGION_RODATA", RAM);
- REGION_ALIAS("REGION_DATA", RAM);
- REGION_ALIAS("REGION_BSS", RAM);
- </pre></div>
- </dd>
- <dt><code>B</code></dt>
- <dd><p>Program code and read-only data go into the <code>ROM</code>. Read-write data goes
- into the <code>RAM</code>. An image of the initialized data is loaded into the
- <code>ROM</code> and will be copied during system start into the <code>RAM</code>.
- </p><div class="example">
- <pre class="example">MEMORY
- {
- ROM : ORIGIN = 0, LENGTH = 3M
- RAM : ORIGIN = 0x10000000, LENGTH = 1M
- }
- REGION_ALIAS("REGION_TEXT", ROM);
- REGION_ALIAS("REGION_RODATA", ROM);
- REGION_ALIAS("REGION_DATA", RAM);
- REGION_ALIAS("REGION_BSS", RAM);
- </pre></div>
- </dd>
- <dt><code>C</code></dt>
- <dd><p>Program code goes into the <code>ROM</code>. Read-only data goes into the
- <code>ROM2</code>. Read-write data goes into the <code>RAM</code>. An image of the
- initialized data is loaded into the <code>ROM2</code> and will be copied during
- system start into the <code>RAM</code>.
- </p><div class="example">
- <pre class="example">MEMORY
- {
- ROM : ORIGIN = 0, LENGTH = 2M
- ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
- RAM : ORIGIN = 0x20000000, LENGTH = 1M
- }
- REGION_ALIAS("REGION_TEXT", ROM);
- REGION_ALIAS("REGION_RODATA", ROM2);
- REGION_ALIAS("REGION_DATA", RAM);
- REGION_ALIAS("REGION_BSS", RAM);
- </pre></div>
- </dd>
- </dl>
- <p>It is possible to write a common system initialization routine to copy the
- <code>.data</code> section from <code>ROM</code> or <code>ROM2</code> into the <code>RAM</code> if
- necessary:
- </p><div class="example">
- <pre class="example">#include <string.h>
- extern char data_start [];
- extern char data_size [];
- extern char data_load_start [];
- void copy_data(void)
- {
- if (data_start != data_load_start)
- {
- memcpy(data_start, data_load_start, (size_t) data_size);
- }
- }
- </pre></div>
- <hr>
- <span id="Miscellaneous-Commands"></span><div class="header">
- <p>
- Previous: <a href="#REGION_005fALIAS" accesskey="p" rel="prev">REGION_ALIAS</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Other-Linker-Script-Commands"></span><h4 class="subsection">3.4.5 Other Linker Script Commands</h4>
- <p>There are a few other linker scripts commands.
- </p>
- <dl compact="compact">
- <dt><code>ASSERT(<var>exp</var>, <var>message</var>)</code></dt>
- <dd><span id="index-ASSERT"></span>
- <span id="index-assertion-in-linker-script"></span>
- <p>Ensure that <var>exp</var> is non-zero. If it is zero, then exit the linker
- with an error code, and print <var>message</var>.
- </p>
- <p>Note that assertions are checked before the final stages of linking
- take place. This means that expressions involving symbols PROVIDEd
- inside section definitions will fail if the user has not set values
- for those symbols. The only exception to this rule is PROVIDEd
- symbols that just reference dot. Thus an assertion like this:
- </p>
- <div class="example">
- <pre class="example"> .stack :
- {
- PROVIDE (__stack = .);
- PROVIDE (__stack_size = 0x100);
- ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
- }
- </pre></div>
- <p>will fail if <code>__stack_size</code> is not defined elsewhere. Symbols
- PROVIDEd outside of section definitions are evaluated earlier, so they
- can be used inside ASSERTions. Thus:
- </p>
- <div class="example">
- <pre class="example"> PROVIDE (__stack_size = 0x100);
- .stack :
- {
- PROVIDE (__stack = .);
- ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
- }
- </pre></div>
- <p>will work.
- </p>
- </dd>
- <dt><code>EXTERN(<var>symbol</var> <var>symbol</var> …)</code></dt>
- <dd><span id="index-EXTERN"></span>
- <span id="index-undefined-symbol-in-linker-script"></span>
- <p>Force <var>symbol</var> to be entered in the output file as an undefined
- symbol. Doing this may, for example, trigger linking of additional
- modules from standard libraries. You may list several <var>symbol</var>s for
- each <code>EXTERN</code>, and you may use <code>EXTERN</code> multiple times. This
- command has the same effect as the ‘<samp>-u</samp>’ command-line option.
- </p>
- </dd>
- <dt><code>FORCE_COMMON_ALLOCATION</code></dt>
- <dd><span id="index-FORCE_005fCOMMON_005fALLOCATION"></span>
- <span id="index-common-allocation-in-linker-script"></span>
- <p>This command has the same effect as the ‘<samp>-d</samp>’ command-line option:
- to make <code>ld</code> assign space to common symbols even if a relocatable
- output file is specified (‘<samp>-r</samp>’).
- </p>
- </dd>
- <dt><code>INHIBIT_COMMON_ALLOCATION</code></dt>
- <dd><span id="index-INHIBIT_005fCOMMON_005fALLOCATION"></span>
- <span id="index-common-allocation-in-linker-script-1"></span>
- <p>This command has the same effect as the ‘<samp>--no-define-common</samp>’
- command-line option: to make <code>ld</code> omit the assignment of addresses
- to common symbols even for a non-relocatable output file.
- </p>
- </dd>
- <dt><code>FORCE_GROUP_ALLOCATION</code></dt>
- <dd><span id="index-FORCE_005fGROUP_005fALLOCATION"></span>
- <span id="index-group-allocation-in-linker-script-1"></span>
- <span id="index-section-groups-1"></span>
- <span id="index-COMDAT-1"></span>
- <p>This command has the same effect as the
- ‘<samp>--force-group-allocation</samp>’ command-line option: to make
- <code>ld</code> place section group members like normal input sections,
- and to delete the section groups even if a relocatable output file is
- specified (‘<samp>-r</samp>’).
- </p>
- </dd>
- <dt><code>INSERT [ AFTER | BEFORE ] <var>output_section</var></code></dt>
- <dd><span id="index-INSERT"></span>
- <span id="index-insert-user-script-into-default-script"></span>
- <p>This command is typically used in a script specified by ‘<samp>-T</samp>’ to
- augment the default <code>SECTIONS</code> with, for example, overlays. It
- inserts all prior linker script statements after (or before)
- <var>output_section</var>, and also causes ‘<samp>-T</samp>’ to not override the
- default linker script. The exact insertion point is as for orphan
- sections. See <a href="#Location-Counter">Location Counter</a>. The insertion happens after the
- linker has mapped input sections to output sections. Prior to the
- insertion, since ‘<samp>-T</samp>’ scripts are parsed before the default
- linker script, statements in the ‘<samp>-T</samp>’ script occur before the
- default linker script statements in the internal linker representation
- of the script. In particular, input section assignments will be made
- to ‘<samp>-T</samp>’ output sections before those in the default script. Here
- is an example of how a ‘<samp>-T</samp>’ script using <code>INSERT</code> might look:
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- OVERLAY :
- {
- .ov1 { ov1*(.text) }
- .ov2 { ov2*(.text) }
- }
- }
- INSERT AFTER .text;
- </pre></div>
- <p>Note that when ‘<samp>-T</samp>’ is used twice, once to override the default
- script and once to augment that script using <code>INSERT</code> the order
- of parsing and section assignments apply as for the default script.
- The script with <code>INSERT</code> should be specified <em>first</em> on the
- command line.
- </p>
- </dd>
- <dt><code>NOCROSSREFS(<var>section</var> <var>section</var> …)</code></dt>
- <dd><span id="index-NOCROSSREFS_0028sections_0029"></span>
- <span id="index-cross-references"></span>
- <p>This command may be used to tell <code>ld</code> to issue an error about any
- references among certain output sections.
- </p>
- <p>In certain types of programs, particularly on embedded systems when
- using overlays, when one section is loaded into memory, another section
- will not be. Any direct references between the two sections would be
- errors. For example, it would be an error if code in one section called
- a function defined in the other section.
- </p>
- <p>The <code>NOCROSSREFS</code> command takes a list of output section names. If
- <code>ld</code> detects any cross references between the sections, it reports
- an error and returns a non-zero exit status. Note that the
- <code>NOCROSSREFS</code> command uses output section names, not input section
- names.
- </p>
- </dd>
- <dt><code>NOCROSSREFS_TO(<var>tosection</var> <var>fromsection</var> …)</code></dt>
- <dd><span id="index-NOCROSSREFS_005fTO_0028tosection-fromsections_0029"></span>
- <span id="index-cross-references-1"></span>
- <p>This command may be used to tell <code>ld</code> to issue an error about any
- references to one section from a list of other sections.
- </p>
- <p>The <code>NOCROSSREFS</code> command is useful when ensuring that two or more
- output sections are entirely independent but there are situations where
- a one-way dependency is needed. For example, in a multi-core application
- there may be shared code that can be called from each core but for safety
- must never call back.
- </p>
- <p>The <code>NOCROSSREFS_TO</code> command takes a list of output section names.
- The first section can not be referenced from any of the other sections.
- If <code>ld</code> detects any references to the first section from any of
- the other sections, it reports an error and returns a non-zero exit
- status. Note that the <code>NOCROSSREFS_TO</code> command uses output section
- names, not input section names.
- </p>
- </dd>
- <dt><code>OUTPUT_ARCH(<var>bfdarch</var>)</code></dt>
- <dd><span id="index-OUTPUT_005fARCH_0028bfdarch_0029"></span>
- <span id="index-machine-architecture"></span>
- <span id="index-architecture"></span>
- <p>Specify a particular output machine architecture. The argument is one
- of the names used by the BFD library (see <a href="#BFD">BFD</a>). You can see the
- architecture of an object file by using the <code>objdump</code> program with
- the ‘<samp>-f</samp>’ option.
- </p>
- </dd>
- <dt><code>LD_FEATURE(<var>string</var>)</code></dt>
- <dd><span id="index-LD_005fFEATURE_0028string_0029"></span>
- <p>This command may be used to modify <code>ld</code> behavior. If
- <var>string</var> is <code>"SANE_EXPR"</code> then absolute symbols and numbers
- in a script are simply treated as numbers everywhere.
- See <a href="#Expression-Section">Expression Section</a>.
- </p></dd>
- </dl>
- <hr>
- <span id="Assignments"></span><div class="header">
- <p>
- Next: <a href="#SECTIONS" accesskey="n" rel="next">SECTIONS</a>, Previous: <a href="#Simple-Commands" accesskey="p" rel="prev">Simple Commands</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Assigning-Values-to-Symbols"></span><h3 class="section">3.5 Assigning Values to Symbols</h3>
- <span id="index-assignment-in-scripts"></span>
- <span id="index-symbol-definition_002c-scripts"></span>
- <span id="index-variables_002c-defining"></span>
- <p>You may assign a value to a symbol in a linker script. This will define
- the symbol and place it into the symbol table with a global scope.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Simple-Assignments" accesskey="1">Simple Assignments</a></td><td> </td><td align="left" valign="top">Simple Assignments
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#HIDDEN" accesskey="2">HIDDEN</a></td><td> </td><td align="left" valign="top">HIDDEN
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#PROVIDE" accesskey="3">PROVIDE</a></td><td> </td><td align="left" valign="top">PROVIDE
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#PROVIDE_005fHIDDEN" accesskey="4">PROVIDE_HIDDEN</a></td><td> </td><td align="left" valign="top">PROVIDE_HIDDEN
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Source-Code-Reference" accesskey="5">Source Code Reference</a></td><td> </td><td align="left" valign="top">How to use a linker script defined symbol in source code
- </td></tr>
- </table>
- <hr>
- <span id="Simple-Assignments"></span><div class="header">
- <p>
- Next: <a href="#HIDDEN" accesskey="n" rel="next">HIDDEN</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Simple-Assignments-1"></span><h4 class="subsection">3.5.1 Simple Assignments</h4>
- <p>You may assign to a symbol using any of the C assignment operators:
- </p>
- <dl compact="compact">
- <dt><code><var>symbol</var> = <var>expression</var> ;</code></dt>
- <dt><code><var>symbol</var> += <var>expression</var> ;</code></dt>
- <dt><code><var>symbol</var> -= <var>expression</var> ;</code></dt>
- <dt><code><var>symbol</var> *= <var>expression</var> ;</code></dt>
- <dt><code><var>symbol</var> /= <var>expression</var> ;</code></dt>
- <dt><code><var>symbol</var> <<= <var>expression</var> ;</code></dt>
- <dt><code><var>symbol</var> >>= <var>expression</var> ;</code></dt>
- <dt><code><var>symbol</var> &= <var>expression</var> ;</code></dt>
- <dt><code><var>symbol</var> |= <var>expression</var> ;</code></dt>
- </dl>
- <p>The first case will define <var>symbol</var> to the value of
- <var>expression</var>. In the other cases, <var>symbol</var> must already be
- defined, and the value will be adjusted accordingly.
- </p>
- <p>The special symbol name ‘<samp>.</samp>’ indicates the location counter. You
- may only use this within a <code>SECTIONS</code> command. See <a href="#Location-Counter">Location Counter</a>.
- </p>
- <p>The semicolon after <var>expression</var> is required.
- </p>
- <p>Expressions are defined below; see <a href="#Expressions">Expressions</a>.
- </p>
- <p>You may write symbol assignments as commands in their own right, or as
- statements within a <code>SECTIONS</code> command, or as part of an output
- section description in a <code>SECTIONS</code> command.
- </p>
- <p>The section of the symbol will be set from the section of the
- expression; for more information, see <a href="#Expression-Section">Expression Section</a>.
- </p>
- <p>Here is an example showing the three different places that symbol
- assignments may be used:
- </p>
- <div class="example">
- <pre class="example">floating_point = 0;
- SECTIONS
- {
- .text :
- {
- *(.text)
- _etext = .;
- }
- _bdata = (. + 3) & ~ 3;
- .data : { *(.data) }
- }
- </pre></div>
- <p>In this example, the symbol ‘<samp>floating_point</samp>’ will be defined as
- zero. The symbol ‘<samp>_etext</samp>’ will be defined as the address following
- the last ‘<samp>.text</samp>’ input section. The symbol ‘<samp>_bdata</samp>’ will be
- defined as the address following the ‘<samp>.text</samp>’ output section aligned
- upward to a 4 byte boundary.
- </p>
- <hr>
- <span id="HIDDEN"></span><div class="header">
- <p>
- Next: <a href="#PROVIDE" accesskey="n" rel="next">PROVIDE</a>, Previous: <a href="#Simple-Assignments" accesskey="p" rel="prev">Simple Assignments</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="HIDDEN-1"></span><h4 class="subsection">3.5.2 HIDDEN</h4>
- <span id="index-HIDDEN"></span>
- <p>For ELF targeted ports, define a symbol that will be hidden and won’t be
- exported. The syntax is <code>HIDDEN(<var>symbol</var> = <var>expression</var>)</code>.
- </p>
- <p>Here is the example from <a href="#Simple-Assignments">Simple Assignments</a>, rewritten to use
- <code>HIDDEN</code>:
- </p>
- <div class="example">
- <pre class="example">HIDDEN(floating_point = 0);
- SECTIONS
- {
- .text :
- {
- *(.text)
- HIDDEN(_etext = .);
- }
- HIDDEN(_bdata = (. + 3) & ~ 3);
- .data : { *(.data) }
- }
- </pre></div>
- <p>In this case none of the three symbols will be visible outside this module.
- </p>
- <hr>
- <span id="PROVIDE"></span><div class="header">
- <p>
- Next: <a href="#PROVIDE_005fHIDDEN" accesskey="n" rel="next">PROVIDE_HIDDEN</a>, Previous: <a href="#HIDDEN" accesskey="p" rel="prev">HIDDEN</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="PROVIDE-1"></span><h4 class="subsection">3.5.3 PROVIDE</h4>
- <span id="index-PROVIDE"></span>
- <p>In some cases, it is desirable for a linker script to define a symbol
- only if it is referenced and is not defined by any object included in
- the link. For example, traditional linkers defined the symbol
- ‘<samp>etext</samp>’. However, ANSI C requires that the user be able to use
- ‘<samp>etext</samp>’ as a function name without encountering an error. The
- <code>PROVIDE</code> keyword may be used to define a symbol, such as
- ‘<samp>etext</samp>’, only if it is referenced but not defined. The syntax is
- <code>PROVIDE(<var>symbol</var> = <var>expression</var>)</code>.
- </p>
- <p>Here is an example of using <code>PROVIDE</code> to define ‘<samp>etext</samp>’:
- </p><div class="example">
- <pre class="example">SECTIONS
- {
- .text :
- {
- *(.text)
- _etext = .;
- PROVIDE(etext = .);
- }
- }
- </pre></div>
- <p>In this example, if the program defines ‘<samp>_etext</samp>’ (with a leading
- underscore), the linker will give a multiple definition diagnostic. If,
- on the other hand, the program defines ‘<samp>etext</samp>’ (with no leading
- underscore), the linker will silently use the definition in the program.
- If the program references ‘<samp>etext</samp>’ but does not define it, the
- linker will use the definition in the linker script.
- </p>
- <p>Note - the <code>PROVIDE</code> directive considers a common symbol to be
- defined, even though such a symbol could be combined with the symbol
- that the <code>PROVIDE</code> would create. This is particularly important
- when considering constructor and destructor list symbols such as
- ‘<samp>__CTOR_LIST__</samp>’ as these are often defined as common symbols.
- </p>
- <hr>
- <span id="PROVIDE_005fHIDDEN"></span><div class="header">
- <p>
- Next: <a href="#Source-Code-Reference" accesskey="n" rel="next">Source Code Reference</a>, Previous: <a href="#PROVIDE" accesskey="p" rel="prev">PROVIDE</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="PROVIDE_005fHIDDEN-1"></span><h4 class="subsection">3.5.4 PROVIDE_HIDDEN</h4>
- <span id="index-PROVIDE_005fHIDDEN"></span>
- <p>Similar to <code>PROVIDE</code>. For ELF targeted ports, the symbol will be
- hidden and won’t be exported.
- </p>
- <hr>
- <span id="Source-Code-Reference"></span><div class="header">
- <p>
- Previous: <a href="#PROVIDE_005fHIDDEN" accesskey="p" rel="prev">PROVIDE_HIDDEN</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Source-Code-Reference-1"></span><h4 class="subsection">3.5.5 Source Code Reference</h4>
- <p>Accessing a linker script defined variable from source code is not
- intuitive. In particular a linker script symbol is not equivalent to
- a variable declaration in a high level language, it is instead a
- symbol that does not have a value.
- </p>
- <p>Before going further, it is important to note that compilers often
- transform names in the source code into different names when they are
- stored in the symbol table. For example, Fortran compilers commonly
- prepend or append an underscore, and C++ performs extensive ‘<samp>name
- mangling</samp>’. Therefore there might be a discrepancy between the name
- of a variable as it is used in source code and the name of the same
- variable as it is defined in a linker script. For example in C a
- linker script variable might be referred to as:
- </p>
- <div class="example">
- <pre class="example"> extern int foo;
- </pre></div>
- <p>But in the linker script it might be defined as:
- </p>
- <div class="example">
- <pre class="example"> _foo = 1000;
- </pre></div>
- <p>In the remaining examples however it is assumed that no name
- transformation has taken place.
- </p>
- <p>When a symbol is declared in a high level language such as C, two
- things happen. The first is that the compiler reserves enough space
- in the program’s memory to hold the <em>value</em> of the symbol. The
- second is that the compiler creates an entry in the program’s symbol
- table which holds the symbol’s <em>address</em>. ie the symbol table
- contains the address of the block of memory holding the symbol’s
- value. So for example the following C declaration, at file scope:
- </p>
- <div class="example">
- <pre class="example"> int foo = 1000;
- </pre></div>
- <p>creates an entry called ‘<samp>foo</samp>’ in the symbol table. This entry
- holds the address of an ‘<samp>int</samp>’ sized block of memory where the
- number 1000 is initially stored.
- </p>
- <p>When a program references a symbol the compiler generates code that
- first accesses the symbol table to find the address of the symbol’s
- memory block and then code to read the value from that memory block.
- So:
- </p>
- <div class="example">
- <pre class="example"> foo = 1;
- </pre></div>
- <p>looks up the symbol ‘<samp>foo</samp>’ in the symbol table, gets the address
- associated with this symbol and then writes the value 1 into that
- address. Whereas:
- </p>
- <div class="example">
- <pre class="example"> int * a = & foo;
- </pre></div>
- <p>looks up the symbol ‘<samp>foo</samp>’ in the symbol table, gets its address
- and then copies this address into the block of memory associated with
- the variable ‘<samp>a</samp>’.
- </p>
- <p>Linker scripts symbol declarations, by contrast, create an entry in
- the symbol table but do not assign any memory to them. Thus they are
- an address without a value. So for example the linker script definition:
- </p>
- <div class="example">
- <pre class="example"> foo = 1000;
- </pre></div>
- <p>creates an entry in the symbol table called ‘<samp>foo</samp>’ which holds
- the address of memory location 1000, but nothing special is stored at
- address 1000. This means that you cannot access the <em>value</em> of a
- linker script defined symbol - it has no value - all you can do is
- access the <em>address</em> of a linker script defined symbol.
- </p>
- <p>Hence when you are using a linker script defined symbol in source code
- you should always take the address of the symbol, and never attempt to
- use its value. For example suppose you want to copy the contents of a
- section of memory called .ROM into a section called .FLASH and the
- linker script contains these declarations:
- </p>
- <div class="example">
- <pre class="example"> start_of_ROM = .ROM;
- end_of_ROM = .ROM + sizeof (.ROM);
- start_of_FLASH = .FLASH;
- </pre></div>
- <p>Then the C source code to perform the copy would be:
- </p>
- <div class="example">
- <pre class="example"> extern char start_of_ROM, end_of_ROM, start_of_FLASH;
- memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
- </pre></div>
- <p>Note the use of the ‘<samp>&</samp>’ operators. These are correct.
- Alternatively the symbols can be treated as the names of vectors or
- arrays and then the code will again work as expected:
- </p>
- <div class="example">
- <pre class="example"> extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
- memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);
- </pre></div>
- <p>Note how using this method does not require the use of ‘<samp>&</samp>’
- operators.
- </p>
- <hr>
- <span id="SECTIONS"></span><div class="header">
- <p>
- Next: <a href="#MEMORY" accesskey="n" rel="next">MEMORY</a>, Previous: <a href="#Assignments" accesskey="p" rel="prev">Assignments</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="SECTIONS-Command"></span><h3 class="section">3.6 SECTIONS Command</h3>
- <span id="index-SECTIONS"></span>
- <p>The <code>SECTIONS</code> command tells the linker how to map input sections
- into output sections, and how to place the output sections in memory.
- </p>
- <p>The format of the <code>SECTIONS</code> command is:
- </p><div class="example">
- <pre class="example">SECTIONS
- {
- <var>sections-command</var>
- <var>sections-command</var>
- …
- }
- </pre></div>
- <p>Each <var>sections-command</var> may of be one of the following:
- </p>
- <ul>
- <li> an <code>ENTRY</code> command (see <a href="#Entry-Point">Entry command</a>)
- </li><li> a symbol assignment (see <a href="#Assignments">Assignments</a>)
- </li><li> an output section description
- </li><li> an overlay description
- </li></ul>
- <p>The <code>ENTRY</code> command and symbol assignments are permitted inside the
- <code>SECTIONS</code> command for convenience in using the location counter in
- those commands. This can also make the linker script easier to
- understand because you can use those commands at meaningful points in
- the layout of the output file.
- </p>
- <p>Output section descriptions and overlay descriptions are described
- below.
- </p>
- <p>If you do not use a <code>SECTIONS</code> command in your linker script, the
- linker will place each input section into an identically named output
- section in the order that the sections are first encountered in the
- input files. If all input sections are present in the first file, for
- example, the order of sections in the output file will match the order
- in the first input file. The first section will be at address zero.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Output-Section-Description" accesskey="1">Output Section Description</a></td><td> </td><td align="left" valign="top">Output section description
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Name" accesskey="2">Output Section Name</a></td><td> </td><td align="left" valign="top">Output section name
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Address" accesskey="3">Output Section Address</a></td><td> </td><td align="left" valign="top">Output section address
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Input-Section" accesskey="4">Input Section</a></td><td> </td><td align="left" valign="top">Input section description
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Data" accesskey="5">Output Section Data</a></td><td> </td><td align="left" valign="top">Output section data
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Keywords" accesskey="6">Output Section Keywords</a></td><td> </td><td align="left" valign="top">Output section keywords
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Discarding" accesskey="7">Output Section Discarding</a></td><td> </td><td align="left" valign="top">Output section discarding
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Attributes" accesskey="8">Output Section Attributes</a></td><td> </td><td align="left" valign="top">Output section attributes
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Overlay-Description" accesskey="9">Overlay Description</a></td><td> </td><td align="left" valign="top">Overlay description
- </td></tr>
- </table>
- <hr>
- <span id="Output-Section-Description"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Name" accesskey="n" rel="next">Output Section Name</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Description-1"></span><h4 class="subsection">3.6.1 Output Section Description</h4>
- <p>The full description of an output section looks like this:
- </p><div class="example">
- <pre class="example"><var>section</var> [<var>address</var>] [(<var>type</var>)] :
- [AT(<var>lma</var>)]
- [ALIGN(<var>section_align</var>) | ALIGN_WITH_INPUT]
- [SUBALIGN(<var>subsection_align</var>)]
- [<var>constraint</var>]
- {
- <var>output-section-command</var>
- <var>output-section-command</var>
- …
- } [><var>region</var>] [AT><var>lma_region</var>] [:<var>phdr</var> :<var>phdr</var> …] [=<var>fillexp</var>] [,]
- </pre></div>
- <p>Most output sections do not use most of the optional section attributes.
- </p>
- <p>The whitespace around <var>section</var> is required, so that the section
- name is unambiguous. The colon and the curly braces are also required.
- The comma at the end may be required if a <var>fillexp</var> is used and
- the next <var>sections-command</var> looks like a continuation of the expression.
- The line breaks and other white space are optional.
- </p>
- <p>Each <var>output-section-command</var> may be one of the following:
- </p>
- <ul>
- <li> a symbol assignment (see <a href="#Assignments">Assignments</a>)
- </li><li> an input section description (see <a href="#Input-Section">Input Section</a>)
- </li><li> data values to include directly (see <a href="#Output-Section-Data">Output Section Data</a>)
- </li><li> a special output section keyword (see <a href="#Output-Section-Keywords">Output Section Keywords</a>)
- </li></ul>
- <hr>
- <span id="Output-Section-Name"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Address" accesskey="n" rel="next">Output Section Address</a>, Previous: <a href="#Output-Section-Description" accesskey="p" rel="prev">Output Section Description</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Name-1"></span><h4 class="subsection">3.6.2 Output Section Name</h4>
- <span id="index-name_002c-section"></span>
- <span id="index-section-name"></span>
- <p>The name of the output section is <var>section</var>. <var>section</var> must
- meet the constraints of your output format. In formats which only
- support a limited number of sections, such as <code>a.out</code>, the name
- must be one of the names supported by the format (<code>a.out</code>, for
- example, allows only ‘<samp>.text</samp>’, ‘<samp>.data</samp>’ or ‘<samp>.bss</samp>’). If the
- output format supports any number of sections, but with numbers and not
- names (as is the case for Oasys), the name should be supplied as a
- quoted numeric string. A section name may consist of any sequence of
- characters, but a name which contains any unusual characters such as
- commas must be quoted.
- </p>
- <p>The output section name ‘<samp>/DISCARD/</samp>’ is special; <a href="#Output-Section-Discarding">Output Section Discarding</a>.
- </p>
- <hr>
- <span id="Output-Section-Address"></span><div class="header">
- <p>
- Next: <a href="#Input-Section" accesskey="n" rel="next">Input Section</a>, Previous: <a href="#Output-Section-Name" accesskey="p" rel="prev">Output Section Name</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Address-1"></span><h4 class="subsection">3.6.3 Output Section Address</h4>
- <span id="index-address_002c-section"></span>
- <span id="index-section-address"></span>
- <p>The <var>address</var> is an expression for the VMA (the virtual memory
- address) of the output section. This address is optional, but if it
- is provided then the output address will be set exactly as specified.
- </p>
- <p>If the output address is not specified then one will be chosen for the
- section, based on the heuristic below. This address will be adjusted
- to fit the alignment requirement of the output section. The
- alignment requirement is the strictest alignment of any input section
- contained within the output section.
- </p>
- <p>The output section address heuristic is as follows:
- </p>
- <ul>
- <li> If an output memory <var>region</var> is set for the section then it
- is added to this region and its address will be the next free address
- in that region.
- </li><li> If the MEMORY command has been used to create a list of memory
- regions then the first region which has attributes compatible with the
- section is selected to contain it. The section’s output address will
- be the next free address in that region; <a href="#MEMORY">MEMORY</a>.
- </li><li> If no memory regions were specified, or none match the section then
- the output address will be based on the current value of the location
- counter.
- </li></ul>
- <p>For example:
- </p>
- <div class="example">
- <pre class="example">.text . : { *(.text) }
- </pre></div>
- <p>and
- </p>
- <div class="example">
- <pre class="example">.text : { *(.text) }
- </pre></div>
- <p>are subtly different. The first will set the address of the
- ‘<samp>.text</samp>’ output section to the current value of the location
- counter. The second will set it to the current value of the location
- counter aligned to the strictest alignment of any of the ‘<samp>.text</samp>’
- input sections.
- </p>
- <p>The <var>address</var> may be an arbitrary expression; <a href="#Expressions">Expressions</a>.
- For example, if you want to align the section on a 0x10 byte boundary,
- so that the lowest four bits of the section address are zero, you could
- do something like this:
- </p><div class="example">
- <pre class="example">.text ALIGN(0x10) : { *(.text) }
- </pre></div>
- <p>This works because <code>ALIGN</code> returns the current location counter
- aligned upward to the specified value.
- </p>
- <p>Specifying <var>address</var> for a section will change the value of the
- location counter, provided that the section is non-empty. (Empty
- sections are ignored).
- </p>
- <hr>
- <span id="Input-Section"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Data" accesskey="n" rel="next">Output Section Data</a>, Previous: <a href="#Output-Section-Address" accesskey="p" rel="prev">Output Section Address</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Input-Section-Description"></span><h4 class="subsection">3.6.4 Input Section Description</h4>
- <span id="index-input-sections"></span>
- <span id="index-mapping-input-sections-to-output-sections"></span>
- <p>The most common output section command is an input section description.
- </p>
- <p>The input section description is the most basic linker script operation.
- You use output sections to tell the linker how to lay out your program
- in memory. You use input section descriptions to tell the linker how to
- map the input files into your memory layout.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Input-Section-Basics" accesskey="1">Input Section Basics</a></td><td> </td><td align="left" valign="top">Input section basics
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Input-Section-Wildcards" accesskey="2">Input Section Wildcards</a></td><td> </td><td align="left" valign="top">Input section wildcard patterns
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Input-Section-Common" accesskey="3">Input Section Common</a></td><td> </td><td align="left" valign="top">Input section for common symbols
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Input-Section-Keep" accesskey="4">Input Section Keep</a></td><td> </td><td align="left" valign="top">Input section and garbage collection
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Input-Section-Example" accesskey="5">Input Section Example</a></td><td> </td><td align="left" valign="top">Input section example
- </td></tr>
- </table>
- <hr>
- <span id="Input-Section-Basics"></span><div class="header">
- <p>
- Next: <a href="#Input-Section-Wildcards" accesskey="n" rel="next">Input Section Wildcards</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Input-Section-Basics-1"></span><h4 class="subsubsection">3.6.4.1 Input Section Basics</h4>
- <span id="index-input-section-basics"></span>
- <p>An input section description consists of a file name optionally followed
- by a list of section names in parentheses.
- </p>
- <p>The file name and the section name may be wildcard patterns, which we
- describe further below (see <a href="#Input-Section-Wildcards">Input Section Wildcards</a>).
- </p>
- <p>The most common input section description is to include all input
- sections with a particular name in the output section. For example, to
- include all input ‘<samp>.text</samp>’ sections, you would write:
- </p><div class="example">
- <pre class="example">*(.text)
- </pre></div>
- <p>Here the ‘<samp>*</samp>’ is a wildcard which matches any file name. To exclude a list
- <span id="index-EXCLUDE_005fFILE"></span>
- of files from matching the file name wildcard, EXCLUDE_FILE may be used to
- match all files except the ones specified in the EXCLUDE_FILE list. For
- example:
- </p><div class="example">
- <pre class="example">EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors)
- </pre></div>
- <p>will cause all .ctors sections from all files except <samp>crtend.o</samp>
- and <samp>otherfile.o</samp> to be included. The EXCLUDE_FILE can also be
- placed inside the section list, for example:
- </p><div class="example">
- <pre class="example">*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
- </pre></div>
- <p>The result of this is identically to the previous example. Supporting
- two syntaxes for EXCLUDE_FILE is useful if the section list contains
- more than one section, as described below.
- </p>
- <p>There are two ways to include more than one section:
- </p><div class="example">
- <pre class="example">*(.text .rdata)
- *(.text) *(.rdata)
- </pre></div>
- <p>The difference between these is the order in which the ‘<samp>.text</samp>’ and
- ‘<samp>.rdata</samp>’ input sections will appear in the output section. In the
- first example, they will be intermingled, appearing in the same order as
- they are found in the linker input. In the second example, all
- ‘<samp>.text</samp>’ input sections will appear first, followed by all
- ‘<samp>.rdata</samp>’ input sections.
- </p>
- <p>When using EXCLUDE_FILE with more than one section, if the exclusion
- is within the section list then the exclusion only applies to the
- immediately following section, for example:
- </p><div class="example">
- <pre class="example">*(EXCLUDE_FILE (*somefile.o) .text .rdata)
- </pre></div>
- <p>will cause all ‘<samp>.text</samp>’ sections from all files except
- <samp>somefile.o</samp> to be included, while all ‘<samp>.rdata</samp>’ sections
- from all files, including <samp>somefile.o</samp>, will be included. To
- exclude the ‘<samp>.rdata</samp>’ sections from <samp>somefile.o</samp> the example
- could be modified to:
- </p><div class="example">
- <pre class="example">*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
- </pre></div>
- <p>Alternatively, placing the EXCLUDE_FILE outside of the section list,
- before the input file selection, will cause the exclusion to apply for
- all sections. Thus the previous example can be rewritten as:
- </p><div class="example">
- <pre class="example">EXCLUDE_FILE (*somefile.o) *(.text .rdata)
- </pre></div>
- <p>You can specify a file name to include sections from a particular file.
- You would do this if one or more of your files contain special data that
- needs to be at a particular location in memory. For example:
- </p><div class="example">
- <pre class="example">data.o(.data)
- </pre></div>
- <p>To refine the sections that are included based on the section flags
- of an input section, INPUT_SECTION_FLAGS may be used.
- </p>
- <p>Here is a simple example for using Section header flags for ELF sections:
- </p>
- <div class="example">
- <pre class="example">SECTIONS {
- .text : { INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) }
- .text2 : { INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) }
- }
- </pre></div>
- <p>In this example, the output section ‘<samp>.text</samp>’ will be comprised of any
- input section matching the name *(.text) whose section header flags
- <code>SHF_MERGE</code> and <code>SHF_STRINGS</code> are set. The output section
- ‘<samp>.text2</samp>’ will be comprised of any input section matching the name *(.text)
- whose section header flag <code>SHF_WRITE</code> is clear.
- </p>
- <p>You can also specify files within archives by writing a pattern
- matching the archive, a colon, then the pattern matching the file,
- with no whitespace around the colon.
- </p>
- <dl compact="compact">
- <dt>‘<samp>archive:file</samp>’</dt>
- <dd><p>matches file within archive
- </p></dd>
- <dt>‘<samp>archive:</samp>’</dt>
- <dd><p>matches the whole archive
- </p></dd>
- <dt>‘<samp>:file</samp>’</dt>
- <dd><p>matches file but not one in an archive
- </p></dd>
- </dl>
- <p>Either one or both of ‘<samp>archive</samp>’ and ‘<samp>file</samp>’ can contain shell
- wildcards. On DOS based file systems, the linker will assume that a
- single letter followed by a colon is a drive specifier, so
- ‘<samp>c:myfile.o</samp>’ is a simple file specification, not ‘<samp>myfile.o</samp>’
- within an archive called ‘<samp>c</samp>’. ‘<samp>archive:file</samp>’ filespecs may
- also be used within an <code>EXCLUDE_FILE</code> list, but may not appear in
- other linker script contexts. For instance, you cannot extract a file
- from an archive by using ‘<samp>archive:file</samp>’ in an <code>INPUT</code>
- command.
- </p>
- <p>If you use a file name without a list of sections, then all sections in
- the input file will be included in the output section. This is not
- commonly done, but it may by useful on occasion. For example:
- </p><div class="example">
- <pre class="example">data.o
- </pre></div>
- <p>When you use a file name which is not an ‘<samp>archive:file</samp>’ specifier
- and does not contain any wild card
- characters, the linker will first see if you also specified the file
- name on the linker command line or in an <code>INPUT</code> command. If you
- did not, the linker will attempt to open the file as an input file, as
- though it appeared on the command line. Note that this differs from an
- <code>INPUT</code> command, because the linker will not search for the file in
- the archive search path.
- </p>
- <hr>
- <span id="Input-Section-Wildcards"></span><div class="header">
- <p>
- Next: <a href="#Input-Section-Common" accesskey="n" rel="next">Input Section Common</a>, Previous: <a href="#Input-Section-Basics" accesskey="p" rel="prev">Input Section Basics</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Input-Section-Wildcard-Patterns"></span><h4 class="subsubsection">3.6.4.2 Input Section Wildcard Patterns</h4>
- <span id="index-input-section-wildcards"></span>
- <span id="index-wildcard-file-name-patterns"></span>
- <span id="index-file-name-wildcard-patterns"></span>
- <span id="index-section-name-wildcard-patterns"></span>
- <p>In an input section description, either the file name or the section
- name or both may be wildcard patterns.
- </p>
- <p>The file name of ‘<samp>*</samp>’ seen in many examples is a simple wildcard
- pattern for the file name.
- </p>
- <p>The wildcard patterns are like those used by the Unix shell.
- </p>
- <dl compact="compact">
- <dt>‘<samp>*</samp>’</dt>
- <dd><p>matches any number of characters
- </p></dd>
- <dt>‘<samp>?</samp>’</dt>
- <dd><p>matches any single character
- </p></dd>
- <dt>‘<samp>[<var>chars</var>]</samp>’</dt>
- <dd><p>matches a single instance of any of the <var>chars</var>; the ‘<samp>-</samp>’
- character may be used to specify a range of characters, as in
- ‘<samp>[a-z]</samp>’ to match any lower case letter
- </p></dd>
- <dt>‘<samp>\</samp>’</dt>
- <dd><p>quotes the following character
- </p></dd>
- </dl>
- <p>File name wildcard patterns only match files which are explicitly
- specified on the command line or in an <code>INPUT</code> command. The linker
- does not search directories to expand wildcards.
- </p>
- <p>If a file name matches more than one wildcard pattern, or if a file name
- appears explicitly and is also matched by a wildcard pattern, the linker
- will use the first match in the linker script. For example, this
- sequence of input section descriptions is probably in error, because the
- <samp>data.o</samp> rule will not be used:
- </p><div class="example">
- <pre class="example">.data : { *(.data) }
- .data1 : { data.o(.data) }
- </pre></div>
- <span id="index-SORT_005fBY_005fNAME"></span>
- <p>Normally, the linker will place files and sections matched by wildcards
- in the order in which they are seen during the link. You can change
- this by using the <code>SORT_BY_NAME</code> keyword, which appears before a wildcard
- pattern in parentheses (e.g., <code>SORT_BY_NAME(.text*)</code>). When the
- <code>SORT_BY_NAME</code> keyword is used, the linker will sort the files or sections
- into ascending order by name before placing them in the output file.
- </p>
- <span id="index-SORT_005fBY_005fALIGNMENT"></span>
- <p><code>SORT_BY_ALIGNMENT</code> is similar to <code>SORT_BY_NAME</code>.
- <code>SORT_BY_ALIGNMENT</code> will sort sections into descending order of
- alignment before placing them in the output file. Placing larger
- alignments before smaller alignments can reduce the amount of padding
- needed.
- </p>
- <span id="index-SORT_005fBY_005fINIT_005fPRIORITY"></span>
- <p><code>SORT_BY_INIT_PRIORITY</code> is also similar to <code>SORT_BY_NAME</code>.
- <code>SORT_BY_INIT_PRIORITY</code> will sort sections into ascending
- numerical order of the GCC init_priority attribute encoded in the
- section name before placing them in the output file. In
- <code>.init_array.NNNNN</code> and <code>.fini_array.NNNNN</code>, <code>NNNNN</code> is
- the init_priority. In <code>.ctors.NNNNN</code> and <code>.dtors.NNNNN</code>,
- <code>NNNNN</code> is 65535 minus the init_priority.
- </p>
- <span id="index-SORT"></span>
- <p><code>SORT</code> is an alias for <code>SORT_BY_NAME</code>.
- </p>
- <span id="index-REVERSE"></span>
- <p><code>REVERSE</code> indicates that the sorting should be reversed. If used
- on its own then <code>REVERSE</code> implies <code>SORT_BY_NAME</code>, otherwise
- it reverses the enclosed <code>SORT..</code> command. Note - reverse
- sorting of alignment is not currently supported.
- </p>
- <p>Note - the sorting commands only accept a single wildcard pattern. So
- for example the following will not work:
- </p><div class="example">
- <pre class="example"> *(REVERSE(.text* .init*))
- </pre></div>
- <p>To resolve this problem list the patterns individually, like this:
- </p><div class="example">
- <pre class="example"> *(REVERSE(.text*))
- *(REVERSE(.init*))
- </pre></div>
- <p>Note - you can put the <code>EXCLUDE_FILE</code> command inside a sorting
- command, but not the other way around. So for example:
- </p><div class="example">
- <pre class="example"> *(SORT_BY_NAME(EXCLUDE_FILE(foo) .text*))
- </pre></div>
- <p>will work, but:
- </p><div class="example">
- <pre class="example"> *(EXCLUDE_FILE(foo) SORT_BY_NAME(.text*))
- </pre></div>
- <p>will not.
- </p>
- <p>When there are nested section sorting commands in linker script, there
- can be at most 1 level of nesting for section sorting commands.
- </p>
- <ol>
- <li> <code>SORT_BY_NAME</code> (<code>SORT_BY_ALIGNMENT</code> (wildcard section pattern)).
- It will sort the input sections by name first, then by alignment if two
- sections have the same name.
- </li><li> <code>SORT_BY_ALIGNMENT</code> (<code>SORT_BY_NAME</code> (wildcard section pattern)).
- It will sort the input sections by alignment first, then by name if two
- sections have the same alignment.
- </li><li> <code>SORT_BY_NAME</code> (<code>SORT_BY_NAME</code> (wildcard section pattern)) is
- treated the same as <code>SORT_BY_NAME</code> (wildcard section pattern).
- </li><li> <code>SORT_BY_ALIGNMENT</code> (<code>SORT_BY_ALIGNMENT</code> (wildcard section pattern))
- is treated the same as <code>SORT_BY_ALIGNMENT</code> (wildcard section pattern).
- </li><li> <code>SORT_BY_NAME</code> (<code>REVERSE</code> (wildcard section pattern))
- reverse sorts by name.
- </li><li> <code>REVERSE</code> (<code>SORT_BY_NAME</code> (wildcard section pattern))
- reverse sorts by name.
- </li><li> <code>SORT_BY_INIT_PRIORITY</code> (<code>REVERSE</code> (wildcard section pattern))
- reverse sorts by init priority.
- </li><li> All other nested section sorting commands are invalid.
- </li></ol>
- <p>When both command-line section sorting option and linker script
- section sorting command are used, section sorting command always
- takes precedence over the command-line option.
- </p>
- <p>If the section sorting command in linker script isn’t nested, the
- command-line option will make the section sorting command to be
- treated as nested sorting command.
- </p>
- <ol>
- <li> <code>SORT_BY_NAME</code> (wildcard section pattern ) with
- <samp>--sort-sections alignment</samp> is equivalent to
- <code>SORT_BY_NAME</code> (<code>SORT_BY_ALIGNMENT</code> (wildcard section pattern)).
- </li><li> <code>SORT_BY_ALIGNMENT</code> (wildcard section pattern) with
- <samp>--sort-section name</samp> is equivalent to
- <code>SORT_BY_ALIGNMENT</code> (<code>SORT_BY_NAME</code> (wildcard section pattern)).
- </li></ol>
- <p>If the section sorting command in linker script is nested, the
- command-line option will be ignored.
- </p>
- <span id="index-SORT_005fNONE"></span>
- <p><code>SORT_NONE</code> disables section sorting by ignoring the command-line
- section sorting option.
- </p>
- <p>If you ever get confused about where input sections are going, use the
- ‘<samp>-M</samp>’ linker option to generate a map file. The map file shows
- precisely how input sections are mapped to output sections.
- </p>
- <p>This example shows how wildcard patterns might be used to partition
- files. This linker script directs the linker to place all ‘<samp>.text</samp>’
- sections in ‘<samp>.text</samp>’ and all ‘<samp>.bss</samp>’ sections in ‘<samp>.bss</samp>’.
- The linker will place the ‘<samp>.data</samp>’ section from all files beginning
- with an upper case character in ‘<samp>.DATA</samp>’; for all other files, the
- linker will place the ‘<samp>.data</samp>’ section in ‘<samp>.data</samp>’.
- </p><div class="example">
- <pre class="example">SECTIONS {
- .text : { *(.text) }
- .DATA : { [A-Z]*(.data) }
- .data : { *(.data) }
- .bss : { *(.bss) }
- }
- </pre></div>
- <hr>
- <span id="Input-Section-Common"></span><div class="header">
- <p>
- Next: <a href="#Input-Section-Keep" accesskey="n" rel="next">Input Section Keep</a>, Previous: <a href="#Input-Section-Wildcards" accesskey="p" rel="prev">Input Section Wildcards</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Input-Section-for-Common-Symbols"></span><h4 class="subsubsection">3.6.4.3 Input Section for Common Symbols</h4>
- <span id="index-common-symbol-placement"></span>
- <span id="index-uninitialized-data-placement"></span>
- <p>A special notation is needed for common symbols, because in many object
- file formats common symbols do not have a particular input section. The
- linker treats common symbols as though they are in an input section
- named ‘<samp>COMMON</samp>’.
- </p>
- <p>You may use file names with the ‘<samp>COMMON</samp>’ section just as with any
- other input sections. You can use this to place common symbols from a
- particular input file in one section while common symbols from other
- input files are placed in another section.
- </p>
- <p>In most cases, common symbols in input files will be placed in the
- ‘<samp>.bss</samp>’ section in the output file. For example:
- </p><div class="example">
- <pre class="example">.bss { *(.bss) *(COMMON) }
- </pre></div>
- <span id="index-scommon-section"></span>
- <span id="index-small-common-symbols"></span>
- <p>Some object file formats have more than one type of common symbol. For
- example, the MIPS ELF object file format distinguishes standard common
- symbols and small common symbols. In this case, the linker will use a
- different special section name for other types of common symbols. In
- the case of MIPS ELF, the linker uses ‘<samp>COMMON</samp>’ for standard common
- symbols and ‘<samp>.scommon</samp>’ for small common symbols. This permits you
- to map the different types of common symbols into memory at different
- locations.
- </p>
- <span id="index-_005bCOMMON_005d"></span>
- <p>You will sometimes see ‘<samp>[COMMON]</samp>’ in old linker scripts. This
- notation is now considered obsolete. It is equivalent to
- ‘<samp>*(COMMON)</samp>’.
- </p>
- <hr>
- <span id="Input-Section-Keep"></span><div class="header">
- <p>
- Next: <a href="#Input-Section-Example" accesskey="n" rel="next">Input Section Example</a>, Previous: <a href="#Input-Section-Common" accesskey="p" rel="prev">Input Section Common</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Input-Section-and-Garbage-Collection"></span><h4 class="subsubsection">3.6.4.4 Input Section and Garbage Collection</h4>
- <span id="index-KEEP"></span>
- <span id="index-garbage-collection-3"></span>
- <p>When link-time garbage collection is in use (‘<samp>--gc-sections</samp>’),
- it is often useful to mark sections that should not be eliminated.
- This is accomplished by surrounding an input section’s wildcard entry
- with <code>KEEP()</code>, as in <code>KEEP(*(.init))</code> or
- <code>KEEP(SORT_BY_NAME(*)(.ctors))</code>.
- </p>
- <hr>
- <span id="Input-Section-Example"></span><div class="header">
- <p>
- Previous: <a href="#Input-Section-Keep" accesskey="p" rel="prev">Input Section Keep</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Input-Section-Example-1"></span><h4 class="subsubsection">3.6.4.5 Input Section Example</h4>
- <p>The following example is a complete linker script. It tells the linker
- to read all of the sections from file <samp>all.o</samp> and place them at the
- start of output section ‘<samp>outputa</samp>’ which starts at location
- ‘<samp>0x10000</samp>’. All of section ‘<samp>.input1</samp>’ from file <samp>foo.o</samp>
- follows immediately, in the same output section. All of section
- ‘<samp>.input2</samp>’ from <samp>foo.o</samp> goes into output section
- ‘<samp>outputb</samp>’, followed by section ‘<samp>.input1</samp>’ from <samp>foo1.o</samp>.
- All of the remaining ‘<samp>.input1</samp>’ and ‘<samp>.input2</samp>’ sections from any
- files are written to output section ‘<samp>outputc</samp>’.
- </p>
- <div class="example">
- <pre class="example">SECTIONS {
- outputa 0x10000 :
- {
- all.o
- foo.o (.input1)
- }
- </pre><pre class="example"> outputb :
- {
- foo.o (.input2)
- foo1.o (.input1)
- }
- </pre><pre class="example"> outputc :
- {
- *(.input1)
- *(.input2)
- }
- }
- </pre></div>
- <p>If an output section’s name is the same as the input section’s name
- and is representable as a C identifier, then the linker will
- automatically see <a href="#PROVIDE">PROVIDE</a> two symbols: __start_SECNAME and
- __stop_SECNAME, where SECNAME is the name of the section. These
- indicate the start address and end address of the output section
- respectively. Note: most section names are not representable as
- C identifiers because they contain a ‘<samp>.</samp>’ character.
- </p>
- <hr>
- <span id="Output-Section-Data"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Keywords" accesskey="n" rel="next">Output Section Keywords</a>, Previous: <a href="#Input-Section" accesskey="p" rel="prev">Input Section</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Data-1"></span><h4 class="subsection">3.6.5 Output Section Data</h4>
- <span id="index-data"></span>
- <span id="index-section-data"></span>
- <span id="index-output-section-data"></span>
- <span id="index-ASCIZ-_0060_0060string_0027_0027"></span>
- <span id="index-BYTE_0028expression_0029"></span>
- <span id="index-SHORT_0028expression_0029"></span>
- <span id="index-LONG_0028expression_0029"></span>
- <span id="index-QUAD_0028expression_0029"></span>
- <span id="index-SQUAD_0028expression_0029"></span>
- <p>You can include explicit bytes of data in an output section by using
- <code>BYTE</code>, <code>SHORT</code>, <code>LONG</code>, <code>QUAD</code>, or <code>SQUAD</code> as
- an output section command. Each keyword is followed by an expression in
- parentheses providing the value to store (see <a href="#Expressions">Expressions</a>). The
- value of the expression is stored at the current value of the location
- counter.
- </p>
- <p>The <code>BYTE</code>, <code>SHORT</code>, <code>LONG</code>, and <code>QUAD</code> commands
- store one, two, four, and eight bytes (respectively). After storing the
- bytes, the location counter is incremented by the number of bytes
- stored.
- </p>
- <p>For example, this will store the byte 1 followed by the four byte value
- of the symbol ‘<samp>addr</samp>’:
- </p><div class="example">
- <pre class="example">BYTE(1)
- LONG(addr)
- </pre></div>
- <p>When using a 64 bit host or target, <code>QUAD</code> and <code>SQUAD</code> are the
- same; they both store an 8 byte, or 64 bit, value. When both host and
- target are 32 bits, an expression is computed as 32 bits. In this case
- <code>QUAD</code> stores a 32 bit value zero extended to 64 bits, and
- <code>SQUAD</code> stores a 32 bit value sign extended to 64 bits.
- </p>
- <p>If the object file format of the output file has an explicit endianness,
- which is the normal case, the value will be stored in that endianness.
- When the object file format does not have an explicit endianness, as is
- true of, for example, S-records, the value will be stored in the
- endianness of the first input object file.
- </p>
- <p>You can include a zero-terminated string in an output section by using
- <code>ASCIZ</code>. The keyword is followed by a string which is stored at
- the current value of the location counter adding a zero byte at the
- end. If the string includes spaces it must be enclosed in double
- quotes. The string may contain ’\n’, ’\r’, ’\t’ and octal numbers.
- Hex numbers are not supported.
- </p>
- <p>For example, this string of 16 characters will create a 17 byte area
- </p><div class="example">
- <pre class="example"> ASCIZ "This is 16 bytes"
- </pre></div>
- <p>Note—these commands only work inside a section description and not
- between them, so the following will produce an error from the linker:
- </p><div class="example">
- <pre class="example">SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } </pre></div>
- <p>whereas this will work:
- </p><div class="example">
- <pre class="example">SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } </pre></div>
- <span id="index-FILL_0028expression_0029"></span>
- <span id="index-holes_002c-filling"></span>
- <span id="index-unspecified-memory"></span>
- <p>You may use the <code>FILL</code> command to set the fill pattern for the
- current section. It is followed by an expression in parentheses. Any
- otherwise unspecified regions of memory within the section (for example,
- gaps left due to the required alignment of input sections) are filled
- with the value of the expression, repeated as
- necessary. A <code>FILL</code> statement covers memory locations after the
- point at which it occurs in the section definition; by including more
- than one <code>FILL</code> statement, you can have different fill patterns in
- different parts of an output section.
- </p>
- <p>This example shows how to fill unspecified regions of memory with the
- value ‘<samp>0x90</samp>’:
- </p><div class="example">
- <pre class="example">FILL(0x90909090)
- </pre></div>
- <p>The <code>FILL</code> command is similar to the ‘<samp>=<var>fillexp</var></samp>’ output
- section attribute, but it only affects the
- part of the section following the <code>FILL</code> command, rather than the
- entire section. If both are used, the <code>FILL</code> command takes
- precedence. See <a href="#Output-Section-Fill">Output Section Fill</a>, for details on the fill
- expression.
- </p>
- <p>Note - normally the value of <code>expression</code> is zero extended to 4
- bytes when used to fill gaps. Thus ‘<samp>FILL(144)</samp>’ will fill a
- region with repeats of the pattern ‘<samp>0 0 0 144</samp>’. The value is
- treated as a big-endian number, so for example
- ‘<samp>FILL(22 * 256 + 23)</samp>’ will fill the region with repeats of the
- pattern ‘<samp>0 0 22 23</samp>’. If the expression results in a value with
- more than 4 significant bytes only the least 4 bytes of the value will
- be used.
- </p>
- <p>The above rules do not apply when the <code>expression</code> is a simple
- hexadecimal number. In this case zero extension is not performed and
- all bytes are significant. So ‘<samp>FILL(0x90)</samp>’ will fill a region with
- repeats of ‘<samp>0x90</samp>’ with no zero bytes, and ‘<samp>FILL(0x9192)</samp>’
- will fill the region with repeats of ‘<samp>0x91 0x92</samp>’. Zero bytes
- in a hexadecimal expression are significant even at the start, so
- ‘<samp>FILL(0x0090)</samp>’ will fill a region with repeats of ‘<samp>0x00 0x90</samp>’.
- </p>
- <p>Hexadecimal numbers can be longer than 4 bytes, and all of the bytes
- are significant, so ‘<samp>FILL(0x123456789a)</samp>’ will fill a region with
- repeats of the 5 byte sequence ‘<samp>0x12 0x34 0x56 0x78 0x9a</samp>’.
- Excess bytes in a hexadecimal value beyond the size of a region will
- be silently ignored.
- </p>
- <p>The above only applies to hexadecimal numbers specified as
- ‘<samp>0x[0-9][a-f][A-F]</samp>’. Hexadecimal numbers specified with a
- ‘<samp>$</samp>’ prefix, or a ‘<samp>h</samp>’, ‘<samp>H</samp>’, ‘<samp>x</samp>’ or ‘<samp>X</samp>’ suffix
- will follow the normal fill value rules. This also applies to
- expressions that involve hexadecimal numbers, and hexadecimal numbers
- that have a magnitude suffix.
- </p>
- <span id="index-LINKER_005fVERSION-1"></span>
- <span id="index-LINKER_005fVERSION"></span>
- <p>The <code>LINKER_VERSION</code> command inserts a string containing the
- version of the linker at the current point. Note - by default this
- directive is disabled and will do nothing. It only becomes active if
- the <samp>--enable-linker-version</samp> command line option is used.
- </p>
- <p>Built-in linker scripts for ELF based targets already include this
- directive in their ‘<samp>.comment</samp>’ section.
- </p>
- <hr>
- <span id="Output-Section-Keywords"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Discarding" accesskey="n" rel="next">Output Section Discarding</a>, Previous: <a href="#Output-Section-Data" accesskey="p" rel="prev">Output Section Data</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Keywords-1"></span><h4 class="subsection">3.6.6 Output Section Keywords</h4>
- <p>There are a couple of keywords which can appear as output section
- commands.
- </p>
- <dl compact="compact">
- <dd><span id="index-CREATE_005fOBJECT_005fSYMBOLS"></span>
- <span id="index-input-filename-symbols"></span>
- <span id="index-filename-symbols"></span>
- </dd>
- <dt><code>CREATE_OBJECT_SYMBOLS</code></dt>
- <dd><p>The command tells the linker to create a symbol for each input file.
- The name of each symbol will be the name of the corresponding input
- file. The section of each symbol will be the output section in which
- the <code>CREATE_OBJECT_SYMBOLS</code> command appears.
- </p>
- <p>This is conventional for the a.out object file format. It is not
- normally used for any other object file format.
- </p>
- <span id="index-CONSTRUCTORS"></span>
- <span id="index-C_002b_002b-constructors_002c-arranging-in-link"></span>
- <span id="index-constructors_002c-arranging-in-link"></span>
- </dd>
- <dt><code>CONSTRUCTORS</code></dt>
- <dd><p>When linking using the a.out object file format, the linker uses an
- unusual set construct to support C++ global constructors and
- destructors. When linking object file formats which do not support
- arbitrary sections, such as ECOFF and XCOFF, the linker will
- automatically recognize C++ global constructors and destructors by name.
- For these object file formats, the <code>CONSTRUCTORS</code> command tells the
- linker to place constructor information in the output section where the
- <code>CONSTRUCTORS</code> command appears. The <code>CONSTRUCTORS</code> command is
- ignored for other object file formats.
- </p>
- <p>The symbol <code><span class="nolinebreak">__CTOR_LIST__</span></code><!-- /@w --> marks the start of the global
- constructors, and the symbol <code><span class="nolinebreak">__CTOR_END__</span></code><!-- /@w --> marks the end.
- Similarly, <code><span class="nolinebreak">__DTOR_LIST__</span></code><!-- /@w --> and <code><span class="nolinebreak">__DTOR_END__</span></code><!-- /@w --> mark
- the start and end of the global destructors. The
- first word in the list is the number of entries, followed by the address
- of each constructor or destructor, followed by a zero word. The
- compiler must arrange to actually run the code. For these object file
- formats <small>GNU</small> C++ normally calls constructors from a subroutine
- <code>__main</code>; a call to <code>__main</code> is automatically inserted into
- the startup code for <code>main</code>. <small>GNU</small> C++ normally runs
- destructors either by using <code>atexit</code>, or directly from the function
- <code>exit</code>.
- </p>
- <p>For object file formats such as <code>COFF</code> or <code>ELF</code> which support
- arbitrary section names, <small>GNU</small> C++ will normally arrange to put the
- addresses of global constructors and destructors into the <code>.ctors</code>
- and <code>.dtors</code> sections. Placing the following sequence into your
- linker script will build the sort of table which the <small>GNU</small> C++
- runtime code expects to see.
- </p>
- <div class="example">
- <pre class="example"> __CTOR_LIST__ = .;
- LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
- *(.ctors)
- LONG(0)
- __CTOR_END__ = .;
- __DTOR_LIST__ = .;
- LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
- *(.dtors)
- LONG(0)
- __DTOR_END__ = .;
- </pre></div>
- <p>If you are using the <small>GNU</small> C++ support for initialization priority,
- which provides some control over the order in which global constructors
- are run, you must sort the constructors at link time to ensure that they
- are executed in the correct order. When using the <code>CONSTRUCTORS</code>
- command, use ‘<samp>SORT_BY_NAME(CONSTRUCTORS)</samp>’ instead. When using the
- <code>.ctors</code> and <code>.dtors</code> sections, use ‘<samp>*(SORT_BY_NAME(.ctors))</samp>’ and
- ‘<samp>*(SORT_BY_NAME(.dtors))</samp>’ instead of just ‘<samp>*(.ctors)</samp>’ and
- ‘<samp>*(.dtors)</samp>’.
- </p>
- <p>Normally the compiler and linker will handle these issues automatically,
- and you will not need to concern yourself with them. However, you may
- need to consider this if you are using C++ and writing your own linker
- scripts.
- </p>
- </dd>
- </dl>
- <hr>
- <span id="Output-Section-Discarding"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Attributes" accesskey="n" rel="next">Output Section Attributes</a>, Previous: <a href="#Output-Section-Keywords" accesskey="p" rel="prev">Output Section Keywords</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Discarding-1"></span><h4 class="subsection">3.6.7 Output Section Discarding</h4>
- <span id="index-discarding-sections"></span>
- <span id="index-sections_002c-discarding"></span>
- <span id="index-removing-sections"></span>
- <p>The linker will not normally create output sections with no contents.
- This is for convenience when referring to input sections that may or
- may not be present in any of the input files. For example:
- </p><div class="example">
- <pre class="example">.foo : { *(.foo) }
- </pre></div>
- <p>will only create a ‘<samp>.foo</samp>’ section in the output file if there is a
- ‘<samp>.foo</samp>’ section in at least one input file, and if the input
- sections are not all empty. Other link script directives that allocate
- space in an output section will also create the output section. So
- too will assignments to dot even if the assignment does not create
- space, except for ‘<samp>. = 0</samp>’, ‘<samp>. = . + 0</samp>’, ‘<samp>. = sym</samp>’,
- ‘<samp>. = . + sym</samp>’ and ‘<samp>. = ALIGN (. != 0, expr, 1)</samp>’ when
- ‘<samp>sym</samp>’ is an absolute symbol of value 0 defined in the script.
- This allows you to force output of an empty section with ‘<samp>. = .</samp>’.
- </p>
- <p>The linker will ignore address assignments (see <a href="#Output-Section-Address">Output Section Address</a>)
- on discarded output sections, except when the linker script defines
- symbols in the output section. In that case the linker will obey
- the address assignments, possibly advancing dot even though the
- section is discarded.
- </p>
- <span id="index-_002fDISCARD_002f"></span>
- <p>The special output section name ‘<samp>/DISCARD/</samp>’ may be used to discard
- input sections. Any input sections which are assigned to an output
- section named ‘<samp>/DISCARD/</samp>’ are not included in the output file.
- </p>
- <p>This can be used to discard input sections marked with the ELF flag
- <code>SHF_GNU_RETAIN</code>, which would otherwise have been saved from linker
- garbage collection.
- </p>
- <p>Note, sections that match the ‘<samp>/DISCARD/</samp>’ output section will be
- discarded even if they are in an ELF section group which has other
- members which are not being discarded. This is deliberate.
- Discarding takes precedence over grouping.
- </p>
- <hr>
- <span id="Output-Section-Attributes"></span><div class="header">
- <p>
- Next: <a href="#Overlay-Description" accesskey="n" rel="next">Overlay Description</a>, Previous: <a href="#Output-Section-Discarding" accesskey="p" rel="prev">Output Section Discarding</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Attributes-1"></span><h4 class="subsection">3.6.8 Output Section Attributes</h4>
- <span id="index-output-section-attributes"></span>
- <p>We showed above that the full description of an output section looked
- like this:
- </p>
- <div class="example">
- <pre class="example"><var>section</var> [<var>address</var>] [(<var>type</var>)] :
- [AT(<var>lma</var>)]
- [ALIGN(<var>section_align</var>) | ALIGN_WITH_INPUT]
- [SUBALIGN(<var>subsection_align</var>)]
- [<var>constraint</var>]
- {
- <var>output-section-command</var>
- <var>output-section-command</var>
- …
- } [><var>region</var>] [AT><var>lma_region</var>] [:<var>phdr</var> :<var>phdr</var> …] [=<var>fillexp</var>]
- </pre></div>
- <p>We’ve already described <var>section</var>, <var>address</var>, and
- <var>output-section-command</var>. In this section we will describe the
- remaining section attributes.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Output-Section-Type" accesskey="1">Output Section Type</a></td><td> </td><td align="left" valign="top">Output section type
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-LMA" accesskey="2">Output Section LMA</a></td><td> </td><td align="left" valign="top">Output section LMA
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Forced-Output-Alignment" accesskey="3">Forced Output Alignment</a></td><td> </td><td align="left" valign="top">Forced Output Alignment
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Forced-Input-Alignment" accesskey="4">Forced Input Alignment</a></td><td> </td><td align="left" valign="top">Forced Input Alignment
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Constraint" accesskey="5">Output Section Constraint</a></td><td> </td><td align="left" valign="top">Output section constraint
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Region" accesskey="6">Output Section Region</a></td><td> </td><td align="left" valign="top">Output section region
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Phdr" accesskey="7">Output Section Phdr</a></td><td> </td><td align="left" valign="top">Output section phdr
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Output-Section-Fill" accesskey="8">Output Section Fill</a></td><td> </td><td align="left" valign="top">Output section fill
- </td></tr>
- </table>
- <hr>
- <span id="Output-Section-Type"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-LMA" accesskey="n" rel="next">Output Section LMA</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Type-1"></span><h4 class="subsubsection">3.6.8.1 Output Section Type</h4>
- <p>Each output section may have a type. The type is a keyword in
- parentheses. The following types are defined:
- </p>
- <dl compact="compact">
- <dt><code>NOLOAD</code></dt>
- <dd><p>The section should be marked as not loadable, so that it will not be
- loaded into memory when the program is run.
- </p>
- </dd>
- <dt><code>READONLY</code></dt>
- <dd><p>The section should be marked as read-only.
- </p>
- </dd>
- <dt><code>DSECT</code></dt>
- <dt><code>COPY</code></dt>
- <dt><code>INFO</code></dt>
- <dt><code>OVERLAY</code></dt>
- <dd><p>These type names are supported for backward compatibility, and are
- rarely used. They all have the same effect: the section should be
- marked as not allocatable, so that no memory is allocated for the
- section when the program is run.
- </p>
- </dd>
- <dt><code>TYPE = <var>type</var></code></dt>
- <dd><p>Set the section type to the integer <var>type</var>. When generating an ELF
- output file, type names <code>SHT_PROGBITS</code>, <code>SHT_STRTAB</code>,
- <code>SHT_NOTE</code>, <code>SHT_NOBITS</code>, <code>SHT_INIT_ARRAY</code>,
- <code>SHT_FINI_ARRAY</code>, and <code>SHT_PREINIT_ARRAY</code> are also allowed
- for <var>type</var>. It is the user’s responsibility to ensure that any
- special requirements of the section type are met.
- </p>
- <p>Note - the TYPE only is used if some or all of the contents of the
- section do not have an implicit type of their own. So for example:
- </p><div class="example">
- <pre class="example"> .foo . TYPE = SHT_PROGBITS { *(.bar) }
- </pre></div>
- <p>will set the type of section ‘<samp>.foo</samp>’ to the type of the section
- ‘<samp>.bar</samp>’ in the input files, which may not be the SHT_PROGBITS
- type. Whereas:
- </p><div class="example">
- <pre class="example"> .foo . TYPE = SHT_PROGBITS { BYTE(1) }
- </pre></div>
- <p>will set the type of ‘<samp>.foo</samp>’ to SHT_PROGBBITS. If it is necessary
- to override the type of incoming sections and force the output section
- type then an extra piece of untyped data will be needed:
- </p><div class="example">
- <pre class="example"> .foo . TYPE = SHT_PROGBITS { BYTE(1); *(.bar) }
- </pre></div>
- </dd>
- <dt><code>READONLY ( TYPE = <var>type</var> )</code></dt>
- <dd><p>This form of the syntax combines the <var>READONLY</var> type with the
- type specified by <var>type</var>.
- </p>
- </dd>
- </dl>
- <span id="index-NOLOAD"></span>
- <span id="index-prevent-unnecessary-loading"></span>
- <span id="index-loading_002c-preventing"></span>
- <p>The linker normally sets the attributes of an output section based on
- the input sections which map into it. You can override this by using
- the section type. For example, in the script sample below, the
- ‘<samp>ROM</samp>’ section is addressed at memory location ‘<samp>0</samp>’ and does not
- need to be loaded when the program is run.
- </p><div class="example">
- <pre class="example">SECTIONS {
- ROM 0 (NOLOAD) : { … }
- …
- }
- </pre></div>
- <hr>
- <span id="Output-Section-LMA"></span><div class="header">
- <p>
- Next: <a href="#Forced-Output-Alignment" accesskey="n" rel="next">Forced Output Alignment</a>, Previous: <a href="#Output-Section-Type" accesskey="p" rel="prev">Output Section Type</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-LMA-1"></span><h4 class="subsubsection">3.6.8.2 Output Section LMA</h4>
- <span id="index-AT_003elma_005fregion"></span>
- <span id="index-AT_0028lma_0029"></span>
- <span id="index-load-address"></span>
- <span id="index-section-load-address"></span>
- <p>Every section has a virtual address (VMA) and a load address (LMA); see
- <a href="#Basic-Script-Concepts">Basic Script Concepts</a>. The virtual address is specified by the
- see <a href="#Output-Section-Address">Output Section Address</a> described earlier. The load address is
- specified by the <code>AT</code> or <code>AT></code> keywords. Specifying a load
- address is optional.
- </p>
- <p>The <code>AT</code> keyword takes an expression as an argument. This
- specifies the exact load address of the section. The <code>AT></code> keyword
- takes the name of a memory region as an argument. See <a href="#MEMORY">MEMORY</a>. The
- load address of the section is set to the next free address in the
- region, aligned to the section’s alignment requirements.
- </p>
- <p>If neither <code>AT</code> nor <code>AT></code> is specified for an allocatable
- section, the linker will use the following heuristic to determine the
- load address:
- </p>
- <ul>
- <li> If the section has a specific VMA address, then this is used as
- the LMA address as well.
- </li><li> If the section is not allocatable then its LMA is set to its VMA.
- </li><li> Otherwise if a memory region can be found that is compatible
- with the current section, and this region contains at least one
- section, then the LMA is set so the difference between the
- VMA and LMA is the same as the difference between the VMA and LMA of
- the last section in the located region.
- </li><li> If no memory regions have been declared then a default region
- that covers the entire address space is used in the previous step.
- </li><li> If no suitable region could be found, or there was no previous
- section then the LMA is set equal to the VMA.
- </li></ul>
- <span id="index-ROM-initialized-data"></span>
- <span id="index-initialized-data-in-ROM"></span>
- <p>This feature is designed to make it easy to build a ROM image. For
- example, the following linker script creates three output sections: one
- called ‘<samp>.text</samp>’, which starts at <code>0x1000</code>, one called
- ‘<samp>.mdata</samp>’, which is loaded at the end of the ‘<samp>.text</samp>’ section
- even though its VMA is <code>0x2000</code>, and one called ‘<samp>.bss</samp>’ to hold
- uninitialized data at address <code>0x3000</code>. The symbol <code>_data</code> is
- defined with the value <code>0x2000</code>, which shows that the location
- counter holds the VMA value, not the LMA value.
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- .text 0x1000 : { *(.text) _etext = . ; }
- .mdata 0x2000 :
- AT ( ADDR (.text) + SIZEOF (.text) )
- { _data = . ; *(.data); _edata = . ; }
- .bss 0x3000 :
- { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;}
- }
- </pre></div>
- <p>The run-time initialization code for use with a program generated with
- this linker script would include something like the following, to copy
- the initialized data from the ROM image to its runtime address. Notice
- how this code takes advantage of the symbols defined by the linker
- script.
- </p>
- <div class="example">
- <pre class="example">extern char _etext, _data, _edata, _bstart, _bend;
- char *src = &_etext;
- char *dst = &_data;
- /* ROM has data at end of text; copy it. */
- while (dst < &_edata)
- *dst++ = *src++;
- /* Zero bss. */
- for (dst = &_bstart; dst< &_bend; dst++)
- *dst = 0;
- </pre></div>
- <hr>
- <span id="Forced-Output-Alignment"></span><div class="header">
- <p>
- Next: <a href="#Forced-Input-Alignment" accesskey="n" rel="next">Forced Input Alignment</a>, Previous: <a href="#Output-Section-LMA" accesskey="p" rel="prev">Output Section LMA</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Forced-Output-Alignment-1"></span><h4 class="subsubsection">3.6.8.3 Forced Output Alignment</h4>
- <span id="index-ALIGN_0028section_005falign_0029"></span>
- <span id="index-forcing-output-section-alignment"></span>
- <span id="index-output-section-alignment"></span>
- <p>You can increase an output section’s alignment by using ALIGN. As an
- alternative you can enforce that the difference between the VMA and LMA remains
- intact throughout this output section with the ALIGN_WITH_INPUT attribute.
- </p>
- <hr>
- <span id="Forced-Input-Alignment"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Constraint" accesskey="n" rel="next">Output Section Constraint</a>, Previous: <a href="#Forced-Output-Alignment" accesskey="p" rel="prev">Forced Output Alignment</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Forced-Input-Alignment-1"></span><h4 class="subsubsection">3.6.8.4 Forced Input Alignment</h4>
- <span id="index-SUBALIGN_0028subsection_005falign_0029"></span>
- <span id="index-forcing-input-section-alignment"></span>
- <span id="index-input-section-alignment"></span>
- <p>You can force input section alignment within an output section by using
- SUBALIGN. The value specified overrides any alignment given by input
- sections, whether larger or smaller.
- </p>
- <hr>
- <span id="Output-Section-Constraint"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Region" accesskey="n" rel="next">Output Section Region</a>, Previous: <a href="#Forced-Input-Alignment" accesskey="p" rel="prev">Forced Input Alignment</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Constraint-1"></span><h4 class="subsubsection">3.6.8.5 Output Section Constraint</h4>
- <span id="index-ONLY_005fIF_005fRO"></span>
- <span id="index-ONLY_005fIF_005fRW"></span>
- <span id="index-constraints-on-output-sections"></span>
- <p>You can specify that an output section should only be created if all
- of its input sections are read-only or all of its input sections are
- read-write by using the keyword <code>ONLY_IF_RO</code> and
- <code>ONLY_IF_RW</code> respectively.
- </p>
- <hr>
- <span id="Output-Section-Region"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Phdr" accesskey="n" rel="next">Output Section Phdr</a>, Previous: <a href="#Output-Section-Constraint" accesskey="p" rel="prev">Output Section Constraint</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Region-1"></span><h4 class="subsubsection">3.6.8.6 Output Section Region</h4>
- <span id="index-_003eregion"></span>
- <span id="index-section_002c-assigning-to-memory-region"></span>
- <span id="index-memory-regions-and-sections"></span>
- <p>You can assign a section to a previously defined region of memory by
- using ‘<samp>><var>region</var></samp>’. See <a href="#MEMORY">MEMORY</a>.
- </p>
- <p>Here is a simple example:
- </p><div class="example">
- <pre class="example">MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
- SECTIONS { ROM : { *(.text) } >rom }
- </pre></div>
- <hr>
- <span id="Output-Section-Phdr"></span><div class="header">
- <p>
- Next: <a href="#Output-Section-Fill" accesskey="n" rel="next">Output Section Fill</a>, Previous: <a href="#Output-Section-Region" accesskey="p" rel="prev">Output Section Region</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Phdr-1"></span><h4 class="subsubsection">3.6.8.7 Output Section Phdr</h4>
- <span id="index-_003aphdr"></span>
- <span id="index-section_002c-assigning-to-program-header"></span>
- <span id="index-program-headers-and-sections"></span>
- <p>You can assign a section to a previously defined program segment by
- using ‘<samp>:<var>phdr</var></samp>’. See <a href="#PHDRS">PHDRS</a>. If a section is assigned to
- one or more segments, then all subsequent allocated sections will be
- assigned to those segments as well, unless they use an explicitly
- <code>:<var>phdr</var></code> modifier. You can use <code>:NONE</code> to tell the
- linker to not put the section in any segment at all.
- </p>
- <p>Here is a simple example:
- </p><div class="example">
- <pre class="example">PHDRS { text PT_LOAD ; }
- SECTIONS { .text : { *(.text) } :text }
- </pre></div>
- <hr>
- <span id="Output-Section-Fill"></span><div class="header">
- <p>
- Previous: <a href="#Output-Section-Phdr" accesskey="p" rel="prev">Output Section Phdr</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Output-Section-Fill-1"></span><h4 class="subsubsection">3.6.8.8 Output Section Fill</h4>
- <span id="index-_003dfillexp"></span>
- <span id="index-section-fill-pattern"></span>
- <span id="index-fill-pattern_002c-entire-section"></span>
- <p>You can set the fill pattern for an entire section by using
- ‘<samp>=<var>fillexp</var></samp>’. <var>fillexp</var> is an expression
- (see <a href="#Expressions">Expressions</a>). Any otherwise unspecified regions of memory
- within the output section (for example, gaps left due to the required
- alignment of input sections) will be filled with the value, repeated as
- necessary. If the fill expression is a simple hex number, ie. a string
- of hex digit starting with ‘<samp>0x</samp>’ and without a trailing ‘<samp>k</samp>’ or ‘<samp>M</samp>’, then
- an arbitrarily long sequence of hex digits can be used to specify the
- fill pattern; Leading zeros become part of the pattern too. For all
- other cases, including extra parentheses or a unary <code>+</code>, the fill
- pattern is the four least significant bytes of the value of the
- expression. If the value is less than four bytes in size then it will
- be zero extended to four bytes. In all cases, the number is big-endian.
- </p>
- <div class="example">
- <pre class="example">Fill Value Fill Pattern
- 0x90 90 90 90 90
- 0x0090 00 90 00 90
- 144 00 00 00 90
- </pre></div>
- <p>You can also change the fill value with a <code>FILL</code> command in the
- output section commands; (see <a href="#Output-Section-Data">Output Section Data</a>).
- </p>
- <p>Here is a simple example:
- </p><div class="example">
- <pre class="example">SECTIONS { .text : { *(.text) } =0x90909090 }
- </pre></div>
- <hr>
- <span id="Overlay-Description"></span><div class="header">
- <p>
- Previous: <a href="#Output-Section-Attributes" accesskey="p" rel="prev">Output Section Attributes</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Overlay-Description-1"></span><h4 class="subsection">3.6.9 Overlay Description</h4>
- <span id="index-OVERLAY"></span>
- <span id="index-overlays"></span>
- <p>An overlay description provides an easy way to describe sections which
- are to be loaded as part of a single memory image but are to be run at
- the same memory address. At run time, some sort of overlay manager will
- copy the overlaid sections in and out of the runtime memory address as
- required, perhaps by simply manipulating addressing bits. This approach
- can be useful, for example, when a certain region of memory is faster
- than another.
- </p>
- <p>Overlays are described using the <code>OVERLAY</code> command. The
- <code>OVERLAY</code> command is used within a <code>SECTIONS</code> command, like an
- output section description. The full syntax of the <code>OVERLAY</code>
- command is as follows:
- </p><div class="example">
- <pre class="example">OVERLAY [<var>start</var>] : [NOCROSSREFS] [AT ( <var>ldaddr</var> )]
- {
- <var>secname1</var>
- {
- <var>output-section-command</var>
- <var>output-section-command</var>
- …
- } [:<var>phdr</var>…] [=<var>fill</var>]
- <var>secname2</var>
- {
- <var>output-section-command</var>
- <var>output-section-command</var>
- …
- } [:<var>phdr</var>…] [=<var>fill</var>]
- …
- } [><var>region</var>] [:<var>phdr</var>…] [=<var>fill</var>] [,]
- </pre></div>
- <p>Everything is optional except <code>OVERLAY</code> (a keyword), and each
- section must have a name (<var>secname1</var> and <var>secname2</var> above). The
- section definitions within the <code>OVERLAY</code> construct are identical to
- those within the general <code>SECTIONS</code> construct (see <a href="#SECTIONS">SECTIONS</a>),
- except that no addresses and no memory regions may be defined for
- sections within an <code>OVERLAY</code>.
- </p>
- <p>The comma at the end may be required if a <var>fill</var> is used and
- the next <var>sections-command</var> looks like a continuation of the expression.
- </p>
- <p>The sections are all defined with the same starting address. The load
- addresses of the sections are arranged such that they are consecutive in
- memory starting at the load address used for the <code>OVERLAY</code> as a
- whole (as with normal section definitions, the load address is optional,
- and defaults to the start address; the start address is also optional,
- and defaults to the current value of the location counter).
- </p>
- <p>If the <code>NOCROSSREFS</code> keyword is used, and there are any
- references among the sections, the linker will report an error. Since
- the sections all run at the same address, it normally does not make
- sense for one section to refer directly to another.
- See <a href="#Miscellaneous-Commands">NOCROSSREFS</a>.
- </p>
- <p>For each section within the <code>OVERLAY</code>, the linker automatically
- provides two symbols. The symbol <code>__load_start_<var>secname</var></code> is
- defined as the starting load address of the section. The symbol
- <code>__load_stop_<var>secname</var></code> is defined as the final load address of
- the section. Any characters within <var>secname</var> which are not legal
- within C identifiers are removed. C (or assembler) code may use these
- symbols to move the overlaid sections around as necessary.
- </p>
- <p>At the end of the overlay, the value of the location counter is set to
- the start address of the overlay plus the size of the largest section.
- </p>
- <p>Here is an example. Remember that this would appear inside a
- <code>SECTIONS</code> construct.
- </p><div class="example">
- <pre class="example"> OVERLAY 0x1000 : AT (0x4000)
- {
- .text0 { o1/*.o(.text) }
- .text1 { o2/*.o(.text) }
- }
- </pre></div>
- <p>This will define both ‘<samp>.text0</samp>’ and ‘<samp>.text1</samp>’ to start at
- address 0x1000. ‘<samp>.text0</samp>’ will be loaded at address 0x4000, and
- ‘<samp>.text1</samp>’ will be loaded immediately after ‘<samp>.text0</samp>’. The
- following symbols will be defined if referenced: <code>__load_start_text0</code>,
- <code>__load_stop_text0</code>, <code>__load_start_text1</code>,
- <code>__load_stop_text1</code>.
- </p>
- <p>C code to copy overlay <code>.text1</code> into the overlay area might look
- like the following.
- </p>
- <div class="example">
- <pre class="example"> extern char __load_start_text1, __load_stop_text1;
- memcpy ((char *) 0x1000, &__load_start_text1,
- &__load_stop_text1 - &__load_start_text1);
- </pre></div>
- <p>Note that the <code>OVERLAY</code> command is just syntactic sugar, since
- everything it does can be done using the more basic commands. The above
- example could have been written identically as follows.
- </p>
- <div class="example">
- <pre class="example"> .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
- PROVIDE (__load_start_text0 = LOADADDR (.text0));
- PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
- .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
- PROVIDE (__load_start_text1 = LOADADDR (.text1));
- PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
- . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
- </pre></div>
- <hr>
- <span id="MEMORY"></span><div class="header">
- <p>
- Next: <a href="#PHDRS" accesskey="n" rel="next">PHDRS</a>, Previous: <a href="#SECTIONS" accesskey="p" rel="prev">SECTIONS</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="MEMORY-Command"></span><h3 class="section">3.7 MEMORY Command</h3>
- <span id="index-MEMORY"></span>
- <span id="index-memory-regions"></span>
- <span id="index-regions-of-memory"></span>
- <span id="index-allocating-memory"></span>
- <span id="index-discontinuous-memory"></span>
- <p>The linker’s default configuration permits allocation of all available
- memory. You can override this by using the <code>MEMORY</code> command.
- </p>
- <p>The <code>MEMORY</code> command describes the location and size of blocks of
- memory in the target. You can use it to describe which memory regions
- may be used by the linker, and which memory regions it must avoid. You
- can then assign sections to particular memory regions. The linker will
- set section addresses based on the memory regions, and will warn about
- regions that become too full. The linker will not shuffle sections
- around to fit into the available regions.
- </p>
- <p>A linker script may contain many uses of the <code>MEMORY</code> command,
- however, all memory blocks defined are treated as if they were
- specified inside a single <code>MEMORY</code> command. The syntax for
- <code>MEMORY</code> is:
- </p><div class="example">
- <pre class="example">MEMORY
- {
- <var>name</var> [(<var>attr</var>)] : ORIGIN = <var>origin</var>, LENGTH = <var>len</var>
- …
- }
- </pre></div>
- <p>The <var>name</var> is a name used in the linker script to refer to the
- region. The region name has no meaning outside of the linker script.
- Region names are stored in a separate name space, and will not conflict
- with symbol names, file names, or section names. Each memory region
- must have a distinct name within the <code>MEMORY</code> command. However you can
- add later alias names to existing memory regions with the <a href="#REGION_005fALIAS">REGION_ALIAS</a>
- command.
- </p>
- <span id="index-memory-region-attributes"></span>
- <p>The <var>attr</var> string is an optional list of attributes that specify
- whether to use a particular memory region for an input section which is
- not explicitly mapped in the linker script. As described in
- <a href="#SECTIONS">SECTIONS</a>, if you do not specify an output section for some input
- section, the linker will create an output section with the same name as
- the input section. If you define region attributes, the linker will use
- them to select the memory region for the output section that it creates.
- </p>
- <p>The <var>attr</var> string must consist only of the following characters:
- </p><dl compact="compact">
- <dt>‘<samp>R</samp>’</dt>
- <dd><p>Read-only section
- </p></dd>
- <dt>‘<samp>W</samp>’</dt>
- <dd><p>Read/write section
- </p></dd>
- <dt>‘<samp>X</samp>’</dt>
- <dd><p>Executable section
- </p></dd>
- <dt>‘<samp>A</samp>’</dt>
- <dd><p>Allocatable section
- </p></dd>
- <dt>‘<samp>I</samp>’</dt>
- <dd><p>Initialized section
- </p></dd>
- <dt>‘<samp>L</samp>’</dt>
- <dd><p>Same as ‘<samp>I</samp>’
- </p></dd>
- <dt>‘<samp>!</samp>’</dt>
- <dd><p>Invert the sense of any of the attributes that follow
- </p></dd>
- </dl>
- <p>If an unmapped section matches any of the listed attributes other than
- ‘<samp>!</samp>’, it will be placed in the memory region. The ‘<samp>!</samp>’
- attribute reverses the test for the characters that follow, so that an
- unmapped section will be placed in the memory region only if it does
- not match any of the attributes listed afterwards. Thus an attribute
- string of ‘<samp>RW!X</samp>’ will match any unmapped section that has either
- or both of the ‘<samp>R</samp>’ and ‘<samp>W</samp>’ attributes, but only as long as
- the section does not also have the ‘<samp>X</samp>’ attribute.
- </p>
- <span id="index-ORIGIN-_003d"></span>
- <span id="index-o-_003d"></span>
- <span id="index-org-_003d"></span>
- <p>The <var>origin</var> is an numerical expression for the start address of
- the memory region. The expression must evaluate to a constant and it
- cannot involve any symbols. The keyword <code>ORIGIN</code> may be
- abbreviated to <code>org</code> or <code>o</code> (but not, for example,
- <code>ORG</code>).
- </p>
- <span id="index-LENGTH-_003d"></span>
- <span id="index-len-_003d"></span>
- <span id="index-l-_003d"></span>
- <p>The <var>len</var> is an expression for the size in bytes of the memory
- region. As with the <var>origin</var> expression, the expression must
- be numerical only and must evaluate to a constant. The keyword
- <code>LENGTH</code> may be abbreviated to <code>len</code> or <code>l</code>.
- </p>
- <p>In the following example, we specify that there are two memory regions
- available for allocation: one starting at ‘<samp>0</samp>’ for 256 kilobytes,
- and the other starting at ‘<samp>0x40000000</samp>’ for four megabytes. The
- linker will place into the ‘<samp>rom</samp>’ memory region every section which
- is not explicitly mapped into a memory region, and is either read-only
- or executable. The linker will place other sections which are not
- explicitly mapped into a memory region into the ‘<samp>ram</samp>’ memory
- region.
- </p>
- <div class="example">
- <pre class="example">MEMORY
- {
- rom (rx) : ORIGIN = 0, LENGTH = 256K
- ram (!rx) : org = 0x40000000, l = 4M
- }
- </pre></div>
- <p>Once you define a memory region, you can direct the linker to place
- specific output sections into that memory region by using the
- ‘<samp>><var>region</var></samp>’ output section attribute. For example, if you have
- a memory region named ‘<samp>mem</samp>’, you would use ‘<samp>>mem</samp>’ in the
- output section definition. See <a href="#Output-Section-Region">Output Section Region</a>. If no address
- was specified for the output section, the linker will set the address to
- the next available address within the memory region. If the combined
- output sections directed to a memory region are too large for the
- region, the linker will issue an error message.
- </p>
- <p>It is possible to access the origin and length of a memory in an
- expression via the <code>ORIGIN(<var>memory</var>)</code> and
- <code>LENGTH(<var>memory</var>)</code> functions:
- </p>
- <div class="example">
- <pre class="example"> _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
- </pre></div>
- <hr>
- <span id="PHDRS"></span><div class="header">
- <p>
- Next: <a href="#VERSION" accesskey="n" rel="next">VERSION</a>, Previous: <a href="#MEMORY" accesskey="p" rel="prev">MEMORY</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="PHDRS-Command"></span><h3 class="section">3.8 PHDRS Command</h3>
- <span id="index-PHDRS"></span>
- <span id="index-program-headers"></span>
- <span id="index-ELF-program-headers"></span>
- <span id="index-program-segments"></span>
- <span id="index-segments_002c-ELF"></span>
- <p>The ELF object file format uses <em>program headers</em>, also knows as
- <em>segments</em>. The program headers describe how the program should be
- loaded into memory. You can print them out by using the <code>objdump</code>
- program with the ‘<samp>-p</samp>’ option.
- </p>
- <p>When you run an ELF program on a native ELF system, the system loader
- reads the program headers in order to figure out how to load the
- program. This will only work if the program headers are set correctly.
- This manual does not describe the details of how the system loader
- interprets program headers; for more information, see the ELF ABI.
- </p>
- <p>The linker will create reasonable program headers by default. However,
- in some cases, you may need to specify the program headers more
- precisely. You may use the <code>PHDRS</code> command for this purpose. When
- the linker sees the <code>PHDRS</code> command in the linker script, it will
- not create any program headers other than the ones specified.
- </p>
- <p>The linker only pays attention to the <code>PHDRS</code> command when
- generating an ELF output file. In other cases, the linker will simply
- ignore <code>PHDRS</code>.
- </p>
- <p>This is the syntax of the <code>PHDRS</code> command. The words <code>PHDRS</code>,
- <code>FILEHDR</code>, <code>AT</code>, and <code>FLAGS</code> are keywords.
- </p>
- <div class="example">
- <pre class="example">PHDRS
- {
- <var>name</var> <var>type</var> [ FILEHDR ] [ PHDRS ] [ AT ( <var>address</var> ) ]
- [ FLAGS ( <var>flags</var> ) ] ;
- }
- </pre></div>
- <p>The <var>name</var> is used only for reference in the <code>SECTIONS</code> command
- of the linker script. It is not put into the output file. Program
- header names are stored in a separate name space, and will not conflict
- with symbol names, file names, or section names. Each program header
- must have a distinct name. The headers are processed in order and it
- is usual for them to map to sections in ascending load address order.
- </p>
- <p>Certain program header types describe segments of memory which the
- system loader will load from the file. In the linker script, you
- specify the contents of these segments by placing allocatable output
- sections in the segments. You use the ‘<samp>:<var>phdr</var></samp>’ output section
- attribute to place a section in a particular segment. See <a href="#Output-Section-Phdr">Output Section Phdr</a>.
- </p>
- <p>It is normal to put certain sections in more than one segment. This
- merely implies that one segment of memory contains another. You may
- repeat ‘<samp>:<var>phdr</var></samp>’, using it once for each segment which should
- contain the section.
- </p>
- <p>If you place a section in one or more segments using ‘<samp>:<var>phdr</var></samp>’,
- then the linker will place all subsequent allocatable sections which do
- not specify ‘<samp>:<var>phdr</var></samp>’ in the same segments. This is for
- convenience, since generally a whole set of contiguous sections will be
- placed in a single segment. You can use <code>:NONE</code> to override the
- default segment and tell the linker to not put the section in any
- segment at all.
- </p>
- <span id="index-FILEHDR"></span>
- <span id="index-PHDRS-1"></span>
- <p>You may use the <code>FILEHDR</code> and <code>PHDRS</code> keywords after
- the program header type to further describe the contents of the segment.
- The <code>FILEHDR</code> keyword means that the segment should include the ELF
- file header. The <code>PHDRS</code> keyword means that the segment should
- include the ELF program headers themselves. If applied to a loadable
- segment (<code>PT_LOAD</code>), all prior loadable segments must have one of
- these keywords.
- </p>
- <p>The <var>type</var> may be one of the following. The numbers indicate the
- value of the keyword.
- </p>
- <dl compact="compact">
- <dt><code>PT_NULL</code> (0)</dt>
- <dd><p>Indicates an unused program header.
- </p>
- </dd>
- <dt><code>PT_LOAD</code> (1)</dt>
- <dd><p>Indicates that this program header describes a segment to be loaded from
- the file.
- </p>
- </dd>
- <dt><code>PT_DYNAMIC</code> (2)</dt>
- <dd><p>Indicates a segment where dynamic linking information can be found.
- </p>
- </dd>
- <dt><code>PT_INTERP</code> (3)</dt>
- <dd><p>Indicates a segment where the name of the program interpreter may be
- found.
- </p>
- </dd>
- <dt><code>PT_NOTE</code> (4)</dt>
- <dd><p>Indicates a segment holding note information.
- </p>
- </dd>
- <dt><code>PT_SHLIB</code> (5)</dt>
- <dd><p>A reserved program header type, defined but not specified by the ELF
- ABI.
- </p>
- </dd>
- <dt><code>PT_PHDR</code> (6)</dt>
- <dd><p>Indicates a segment where the program headers may be found.
- </p>
- </dd>
- <dt><code>PT_TLS</code> (7)</dt>
- <dd><p>Indicates a segment containing thread local storage.
- </p>
- </dd>
- <dt><var>expression</var></dt>
- <dd><p>An expression giving the numeric type of the program header. This may
- be used for types not defined above.
- </p></dd>
- </dl>
- <p>You can specify that a segment should be loaded at a particular address
- in memory by using an <code>AT</code> expression. This is identical to the
- <code>AT</code> command used as an output section attribute (see <a href="#Output-Section-LMA">Output Section LMA</a>). The <code>AT</code> command for a program header overrides the
- output section attribute.
- </p>
- <p>The linker will normally set the segment flags based on the sections
- which comprise the segment. You may use the <code>FLAGS</code> keyword to
- explicitly specify the segment flags. The value of <var>flags</var> must be
- an integer. It is used to set the <code>p_flags</code> field of the program
- header.
- </p>
- <p>Here is an example of <code>PHDRS</code>. This shows a typical set of program
- headers used on a native ELF system.
- </p>
- <div class="example">
- <pre class="example">PHDRS
- {
- headers PT_PHDR PHDRS ;
- interp PT_INTERP ;
- text PT_LOAD FILEHDR PHDRS ;
- data PT_LOAD ;
- dynamic PT_DYNAMIC ;
- }
- SECTIONS
- {
- . = SIZEOF_HEADERS;
- .interp : { *(.interp) } :text :interp
- .text : { *(.text) } :text
- .rodata : { *(.rodata) } /* defaults to :text */
- …
- . = . + 0x1000; /* move to a new page in memory */
- .data : { *(.data) } :data
- .dynamic : { *(.dynamic) } :data :dynamic
- …
- }
- </pre></div>
- <hr>
- <span id="VERSION"></span><div class="header">
- <p>
- Next: <a href="#Expressions" accesskey="n" rel="next">Expressions</a>, Previous: <a href="#PHDRS" accesskey="p" rel="prev">PHDRS</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="VERSION-Command"></span><h3 class="section">3.9 VERSION Command</h3>
- <span id="index-VERSION-_007bscript-text_007d"></span>
- <span id="index-symbol-versions"></span>
- <span id="index-version-script"></span>
- <span id="index-versions-of-symbols"></span>
- <p>The linker supports symbol versions when using ELF. Symbol versions are
- only useful when using shared libraries. The dynamic linker can use
- symbol versions to select a specific version of a function when it runs
- a program that may have been linked against an earlier version of the
- shared library.
- </p>
- <p>You can include a version script directly in the main linker script, or
- you can supply the version script as an implicit linker script. You can
- also use the ‘<samp>--version-script</samp>’ linker option.
- </p>
- <p>The syntax of the <code>VERSION</code> command is simply
- </p><div class="example">
- <pre class="example">VERSION { version-script-commands }
- </pre></div>
- <p>The format of the version script commands is identical to that used by
- Sun’s linker in Solaris 2.5. The version script defines a tree of
- version nodes. You specify the node names and interdependencies in the
- version script. You can specify which symbols are bound to which
- version nodes, and you can reduce a specified set of symbols to local
- scope so that they are not globally visible outside of the shared
- library.
- </p>
- <p>The easiest way to demonstrate the version script language is with a few
- examples.
- </p>
- <div class="example">
- <pre class="example">VERS_1.1 {
- global:
- foo1;
- local:
- old*;
- original*;
- new*;
- };
- VERS_1.2 {
- foo2;
- } VERS_1.1;
- VERS_2.0 {
- bar1; bar2;
- extern "C++" {
- ns::*;
- "f(int, double)";
- };
- } VERS_1.2;
- </pre></div>
- <p>This example version script defines three version nodes. The first
- version node defined is ‘<samp>VERS_1.1</samp>’; it has no other dependencies.
- The script binds the symbol ‘<samp>foo1</samp>’ to ‘<samp>VERS_1.1</samp>’. It reduces
- a number of symbols to local scope so that they are not visible outside
- of the shared library; this is done using wildcard patterns, so that any
- symbol whose name begins with ‘<samp>old</samp>’, ‘<samp>original</samp>’, or ‘<samp>new</samp>’
- is matched. The wildcard patterns available are the same as those used
- in the shell when matching filenames (also known as “globbing”).
- However, if you specify the symbol name inside double quotes, then the
- name is treated as literal, rather than as a glob pattern.
- </p>
- <p>Next, the version script defines node ‘<samp>VERS_1.2</samp>’. This node
- depends upon ‘<samp>VERS_1.1</samp>’. The script binds the symbol ‘<samp>foo2</samp>’
- to the version node ‘<samp>VERS_1.2</samp>’.
- </p>
- <p>Finally, the version script defines node ‘<samp>VERS_2.0</samp>’. This node
- depends upon ‘<samp>VERS_1.2</samp>’. The scripts binds the symbols ‘<samp>bar1</samp>’
- and ‘<samp>bar2</samp>’ are bound to the version node ‘<samp>VERS_2.0</samp>’.
- </p>
- <p>When the linker finds a symbol defined in a library which is not
- specifically bound to a version node, it will effectively bind it to an
- unspecified base version of the library. You can bind all otherwise
- unspecified symbols to a given version node by using ‘<samp>global: *;</samp>’
- somewhere in the version script. Note that it’s slightly crazy to use
- wildcards in a global spec except on the last version node. Global
- wildcards elsewhere run the risk of accidentally adding symbols to the
- set exported for an old version. That’s wrong since older versions
- ought to have a fixed set of symbols.
- </p>
- <p>The names of the version nodes have no specific meaning other than what
- they might suggest to the person reading them. The ‘<samp>2.0</samp>’ version
- could just as well have appeared in between ‘<samp>1.1</samp>’ and ‘<samp>1.2</samp>’.
- However, this would be a confusing way to write a version script.
- </p>
- <p>Node name can be omitted, provided it is the only version node
- in the version script. Such version script doesn’t assign any versions to
- symbols, only selects which symbols will be globally visible out and which
- won’t.
- </p>
- <div class="example">
- <pre class="example">{ global: foo; bar; local: *; };
- </pre></div>
- <p>When you link an application against a shared library that has versioned
- symbols, the application itself knows which version of each symbol it
- requires, and it also knows which version nodes it needs from each
- shared library it is linked against. Thus at runtime, the dynamic
- loader can make a quick check to make sure that the libraries you have
- linked against do in fact supply all of the version nodes that the
- application will need to resolve all of the dynamic symbols. In this
- way it is possible for the dynamic linker to know with certainty that
- all external symbols that it needs will be resolvable without having to
- search for each symbol reference.
- </p>
- <p>The symbol versioning is in effect a much more sophisticated way of
- doing minor version checking that SunOS does. The fundamental problem
- that is being addressed here is that typically references to external
- functions are bound on an as-needed basis, and are not all bound when
- the application starts up. If a shared library is out of date, a
- required interface may be missing; when the application tries to use
- that interface, it may suddenly and unexpectedly fail. With symbol
- versioning, the user will get a warning when they start their program if
- the libraries being used with the application are too old.
- </p>
- <p>There are several GNU extensions to Sun’s versioning approach. The
- first of these is the ability to bind a symbol to a version node in the
- source file where the symbol is defined instead of in the versioning
- script. This was done mainly to reduce the burden on the library
- maintainer. You can do this by putting something like:
- </p><div class="example">
- <pre class="example">__asm__(".symver original_foo,foo@VERS_1.1");
- </pre></div>
- <p>in the C source file. This renames the function ‘<samp>original_foo</samp>’ to
- be an alias for ‘<samp>foo</samp>’ bound to the version node ‘<samp>VERS_1.1</samp>’.
- The ‘<samp>local:</samp>’ directive can be used to prevent the symbol
- ‘<samp>original_foo</samp>’ from being exported. A ‘<samp>.symver</samp>’ directive
- takes precedence over a version script.
- </p>
- <p>The second GNU extension is to allow multiple versions of the same
- function to appear in a given shared library. In this way you can make
- an incompatible change to an interface without increasing the major
- version number of the shared library, while still allowing applications
- linked against the old interface to continue to function.
- </p>
- <p>To do this, you must use multiple ‘<samp>.symver</samp>’ directives in the
- source file. Here is an example:
- </p>
- <div class="example">
- <pre class="example">__asm__(".symver original_foo,foo@");
- __asm__(".symver old_foo,foo@VERS_1.1");
- __asm__(".symver old_foo1,foo@VERS_1.2");
- __asm__(".symver new_foo,foo@@VERS_2.0");
- </pre></div>
- <p>In this example, ‘<samp>foo@</samp>’ represents the symbol ‘<samp>foo</samp>’ bound to the
- unspecified base version of the symbol. The source file that contains this
- example would define 4 C functions: ‘<samp>original_foo</samp>’, ‘<samp>old_foo</samp>’,
- ‘<samp>old_foo1</samp>’, and ‘<samp>new_foo</samp>’.
- </p>
- <p>When you have multiple definitions of a given symbol, there needs to be
- some way to specify a default version to which external references to
- this symbol will be bound. You can do this with the
- ‘<samp>foo@@VERS_2.0</samp>’ type of ‘<samp>.symver</samp>’ directive. You can only
- declare one version of a symbol as the default in this manner; otherwise
- you would effectively have multiple definitions of the same symbol.
- </p>
- <p>If you wish to bind a reference to a specific version of the symbol
- within the shared library, you can use the aliases of convenience
- (i.e., ‘<samp>old_foo</samp>’), or you can use the ‘<samp>.symver</samp>’ directive to
- specifically bind to an external version of the function in question.
- </p>
- <p>You can also specify the language in the version script:
- </p>
- <div class="example">
- <pre class="example">VERSION extern "lang" { version-script-commands }
- </pre></div>
- <p>The supported ‘<samp>lang</samp>’s are ‘<samp>C</samp>’, ‘<samp>C++</samp>’, and ‘<samp>Java</samp>’.
- The linker will iterate over the list of symbols at the link time and
- demangle them according to ‘<samp>lang</samp>’ before matching them to the
- patterns specified in ‘<samp>version-script-commands</samp>’. The default
- ‘<samp>lang</samp>’ is ‘<samp>C</samp>’.
- </p>
- <p>Demangled names may contains spaces and other special characters. As
- described above, you can use a glob pattern to match demangled names,
- or you can use a double-quoted string to match the string exactly. In
- the latter case, be aware that minor differences (such as differing
- whitespace) between the version script and the demangler output will
- cause a mismatch. As the exact string generated by the demangler
- might change in the future, even if the mangled name does not, you
- should check that all of your version directives are behaving as you
- expect when you upgrade.
- </p>
- <hr>
- <span id="Expressions"></span><div class="header">
- <p>
- Next: <a href="#Implicit-Linker-Scripts" accesskey="n" rel="next">Implicit Linker Scripts</a>, Previous: <a href="#VERSION" accesskey="p" rel="prev">VERSION</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Expressions-in-Linker-Scripts"></span><h3 class="section">3.10 Expressions in Linker Scripts</h3>
- <span id="index-expressions"></span>
- <span id="index-arithmetic"></span>
- <p>The syntax for expressions in the linker script language is identical to
- that of C expressions, except that whitespace is required in some
- places to resolve syntactic ambiguities. All expressions are
- evaluated as integers. All expressions are evaluated in the same
- size, which is 32 bits if both the host and target are 32 bits, and is
- otherwise 64 bits.
- </p>
- <p>You can use and set symbol values in expressions.
- </p>
- <p>The linker defines several special purpose builtin functions for use in
- expressions.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Constants" accesskey="1">Constants</a></td><td> </td><td align="left" valign="top">Constants
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Symbolic-Constants" accesskey="2">Symbolic Constants</a></td><td> </td><td align="left" valign="top">Symbolic constants
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Symbols" accesskey="3">Symbols</a></td><td> </td><td align="left" valign="top">Symbol Names
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Orphan-Sections" accesskey="4">Orphan Sections</a></td><td> </td><td align="left" valign="top">Orphan Sections
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Location-Counter" accesskey="5">Location Counter</a></td><td> </td><td align="left" valign="top">The Location Counter
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Operators" accesskey="6">Operators</a></td><td> </td><td align="left" valign="top">Operators
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Evaluation" accesskey="7">Evaluation</a></td><td> </td><td align="left" valign="top">Evaluation
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Expression-Section" accesskey="8">Expression Section</a></td><td> </td><td align="left" valign="top">The Section of an Expression
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Builtin-Functions" accesskey="9">Builtin Functions</a></td><td> </td><td align="left" valign="top">Builtin Functions
- </td></tr>
- </table>
- <hr>
- <span id="Constants"></span><div class="header">
- <p>
- Next: <a href="#Symbolic-Constants" accesskey="n" rel="next">Symbolic Constants</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Constants-1"></span><h4 class="subsection">3.10.1 Constants</h4>
- <span id="index-integer-notation"></span>
- <span id="index-constants-in-linker-scripts"></span>
- <p>All constants are integers.
- </p>
- <p>As in C, the linker considers an integer beginning with ‘<samp>0</samp>’ to be
- octal, and an integer beginning with ‘<samp>0x</samp>’ or ‘<samp>0X</samp>’ to be
- hexadecimal. Alternatively the linker accepts suffixes of ‘<samp>h</samp>’ or
- ‘<samp>H</samp>’ for hexadecimal, ‘<samp>o</samp>’ or ‘<samp>O</samp>’ for octal, ‘<samp>b</samp>’ or
- ‘<samp>B</samp>’ for binary and ‘<samp>d</samp>’ or ‘<samp>D</samp>’ for decimal. Any integer
- value without a prefix or a suffix is considered to be decimal.
- </p>
- <span id="index-scaled-integers"></span>
- <span id="index-K-and-M-integer-suffixes"></span>
- <span id="index-M-and-K-integer-suffixes"></span>
- <span id="index-suffixes-for-integers"></span>
- <span id="index-integer-suffixes"></span>
- <p>In addition, you can use the suffixes <code>K</code> and <code>M</code> to scale a
- constant by
- <code>1024</code> or <code>1024*1024</code>
- respectively. For example, the following
- all refer to the same quantity:
- </p>
- <div class="example">
- <pre class="example">_fourk_1 = 4K;
- _fourk_2 = 4096;
- _fourk_3 = 0x1000;
- _fourk_4 = 10000o;
- </pre></div>
- <p>Note - the <code>K</code> and <code>M</code> suffixes cannot be used in
- conjunction with the base suffixes mentioned above.
- </p>
- <hr>
- <span id="Symbolic-Constants"></span><div class="header">
- <p>
- Next: <a href="#Symbols" accesskey="n" rel="next">Symbols</a>, Previous: <a href="#Constants" accesskey="p" rel="prev">Constants</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Symbolic-Constants-1"></span><h4 class="subsection">3.10.2 Symbolic Constants</h4>
- <span id="index-symbolic-constants"></span>
- <span id="index-CONSTANT"></span>
- <p>It is possible to refer to target-specific constants via the use of
- the <code>CONSTANT(<var>name</var>)</code> operator, where <var>name</var> is one of:
- </p>
- <dl compact="compact">
- <dt><code>MAXPAGESIZE</code></dt>
- <dd><span id="index-MAXPAGESIZE"></span>
- <p>The target’s maximum page size.
- </p>
- </dd>
- <dt><code>COMMONPAGESIZE</code></dt>
- <dd><span id="index-COMMONPAGESIZE"></span>
- <p>The target’s default page size.
- </p></dd>
- </dl>
- <p>So for example:
- </p>
- <div class="example">
- <pre class="example"> .text ALIGN (CONSTANT (MAXPAGESIZE)) : { *(.text) }
- </pre></div>
- <p>will create a text section aligned to the largest page boundary
- supported by the target.
- </p>
- <hr>
- <span id="Symbols"></span><div class="header">
- <p>
- Next: <a href="#Orphan-Sections" accesskey="n" rel="next">Orphan Sections</a>, Previous: <a href="#Symbolic-Constants" accesskey="p" rel="prev">Symbolic Constants</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Symbol-Names"></span><h4 class="subsection">3.10.3 Symbol Names</h4>
- <span id="index-symbol-names"></span>
- <span id="index-names"></span>
- <span id="index-quoted-symbol-names"></span>
- <span id="index-_0022"></span>
- <p>Unless quoted, symbol names start with a letter, underscore, or period
- and may include letters, digits, underscores, periods, and hyphens.
- Unquoted symbol names must not conflict with any keywords. You can
- specify a symbol which contains odd characters or has the same name as a
- keyword by surrounding the symbol name in double quotes:
- </p><div class="example">
- <pre class="example">"SECTION" = 9;
- "with a space" = "also with a space" + 10;
- </pre></div>
- <p>Since symbols can contain many non-alphabetic characters, it is safest
- to delimit symbols with spaces. For example, ‘<samp>A-B</samp>’ is one symbol,
- whereas ‘<samp>A - B</samp>’ is an expression involving subtraction.
- </p>
- <hr>
- <span id="Orphan-Sections"></span><div class="header">
- <p>
- Next: <a href="#Location-Counter" accesskey="n" rel="next">Location Counter</a>, Previous: <a href="#Symbols" accesskey="p" rel="prev">Symbols</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Orphan-Sections-1"></span><h4 class="subsection">3.10.4 Orphan Sections</h4>
- <span id="index-orphan"></span>
- <p>Orphan sections are sections present in the input files which
- are not explicitly placed into the output file by the linker
- script. The linker will still copy these sections into the
- output file by either finding, or creating a suitable output section
- in which to place the orphaned input section.
- </p>
- <p>If the name of an orphaned input section exactly matches the name of
- an existing output section, then the orphaned input section will be
- placed at the end of that output section.
- </p>
- <p>If there is no output section with a matching name then new output
- sections will be created. Each new output section will have the same
- name as the orphan section placed within it. If there are multiple
- orphan sections with the same name, these will all be combined into
- one new output section.
- </p>
- <p>If new output sections are created to hold orphaned input sections,
- then the linker must decide where to place these new output sections
- in relation to existing output sections. On most modern targets, the
- linker attempts to place orphan sections after sections of the same
- attribute, such as code vs data, loadable vs non-loadable, etc. If no
- sections with matching attributes are found, or your target lacks this
- support, the orphan section is placed at the end of the file.
- </p>
- <p>The command-line options ‘<samp>--orphan-handling</samp>’ and ‘<samp>--unique</samp>’
- (see <a href="#Options">Command-line Options</a>) can be used to control which
- output sections an orphan is placed in.
- </p>
- <hr>
- <span id="Location-Counter"></span><div class="header">
- <p>
- Next: <a href="#Operators" accesskey="n" rel="next">Operators</a>, Previous: <a href="#Orphan-Sections" accesskey="p" rel="prev">Orphan Sections</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="The-Location-Counter"></span><h4 class="subsection">3.10.5 The Location Counter</h4>
- <span id="index-_002e"></span>
- <span id="index-dot"></span>
- <span id="index-location-counter"></span>
- <span id="index-current-output-location"></span>
- <p>The special linker variable <em>dot</em> ‘<samp>.</samp>’ always contains the
- current output location counter. Since the <code>.</code> always refers to a
- location in an output section, it may only appear in an expression
- within a <code>SECTIONS</code> command. The <code>.</code> symbol may appear
- anywhere that an ordinary symbol is allowed in an expression.
- </p>
- <span id="index-holes"></span>
- <p>Assigning a value to <code>.</code> will cause the location counter to be
- moved. This may be used to create holes in the output section. The
- location counter may not be moved backwards inside an output section,
- and may not be moved backwards outside of an output section if so
- doing creates areas with overlapping LMAs.
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- output :
- {
- file1(.text)
- . = . + 1000;
- file2(.text)
- . += 1000;
- file3(.text)
- } = 0x12345678;
- }
- </pre></div>
- <p>In the previous example, the ‘<samp>.text</samp>’ section from <samp>file1</samp> is
- located at the beginning of the output section ‘<samp>output</samp>’. It is
- followed by a 1000 byte gap. Then the ‘<samp>.text</samp>’ section from
- <samp>file2</samp> appears, also with a 1000 byte gap following before the
- ‘<samp>.text</samp>’ section from <samp>file3</samp>. The notation ‘<samp>= 0x12345678</samp>’
- specifies what data to write in the gaps (see <a href="#Output-Section-Fill">Output Section Fill</a>).
- </p>
- <span id="index-dot-inside-sections"></span>
- <p>Note: <code>.</code> actually refers to the byte offset from the start of the
- current containing object. Normally this is the <code>SECTIONS</code>
- statement, whose start address is 0, hence <code>.</code> can be used as an
- absolute address. If <code>.</code> is used inside a section description
- however, it refers to the byte offset from the start of that section,
- not an absolute address. Thus in a script like this:
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- . = 0x100
- .text: {
- *(.text)
- . = 0x200
- }
- . = 0x500
- .data: {
- *(.data)
- . += 0x600
- }
- }
- </pre></div>
- <p>The ‘<samp>.text</samp>’ section will be assigned a starting address of 0x100
- and a size of exactly 0x200 bytes, even if there is not enough data in
- the ‘<samp>.text</samp>’ input sections to fill this area. (If there is too
- much data, an error will be produced because this would be an attempt to
- move <code>.</code> backwards). The ‘<samp>.data</samp>’ section will start at 0x500
- and it will have an extra 0x600 bytes worth of space after the end of
- the values from the ‘<samp>.data</samp>’ input sections and before the end of
- the ‘<samp>.data</samp>’ output section itself.
- </p>
- <span id="index-dot-outside-sections"></span>
- <p>Setting symbols to the value of the location counter outside of an
- output section statement can result in unexpected values if the linker
- needs to place orphan sections. For example, given the following:
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
- start_of_data = . ;
- .data: { *(.data) }
- end_of_data = . ;
- }
- </pre></div>
- <p>If the linker needs to place some input section, e.g. <code>.rodata</code>,
- not mentioned in the script, it might choose to place that section
- between <code>.text</code> and <code>.data</code>. You might think the linker
- should place <code>.rodata</code> on the blank line in the above script, but
- blank lines are of no particular significance to the linker. As well,
- the linker doesn’t associate the above symbol names with their
- sections. Instead, it assumes that all assignments or other
- statements belong to the previous output section, except for the
- special case of an assignment to <code>.</code>. I.e., the linker will
- place the orphan <code>.rodata</code> section as if the script was written
- as follows:
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
- start_of_data = . ;
- .rodata: { *(.rodata) }
- .data: { *(.data) }
- end_of_data = . ;
- }
- </pre></div>
- <p>This may or may not be the script author’s intention for the value of
- <code>start_of_data</code>. One way to influence the orphan section
- placement is to assign the location counter to itself, as the linker
- assumes that an assignment to <code>.</code> is setting the start address of
- a following output section and thus should be grouped with that
- section. So you could write:
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
- . = . ;
- start_of_data = . ;
- .data: { *(.data) }
- end_of_data = . ;
- }
- </pre></div>
- <p>Now, the orphan <code>.rodata</code> section will be placed between
- <code>end_of_text</code> and <code>start_of_data</code>.
- </p>
- <hr>
- <span id="Operators"></span><div class="header">
- <p>
- Next: <a href="#Evaluation" accesskey="n" rel="next">Evaluation</a>, Previous: <a href="#Location-Counter" accesskey="p" rel="prev">Location Counter</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Operators-1"></span><h4 class="subsection">3.10.6 Operators</h4>
- <span id="index-operators-for-arithmetic"></span>
- <span id="index-arithmetic-operators"></span>
- <span id="index-precedence-in-expressions"></span>
- <p>The linker recognizes the standard C set of arithmetic operators, with
- the standard bindings and precedence levels:
- </p><div class="example">
- <pre class="example">precedence associativity Operators Notes
- (highest)
- 1 left ! - ~ (1)
- 2 left * / %
- 3 left + -
- 4 left >> <<
- 5 left > < <= >=
- 6 left == !=
- 7 left &
- 8 left ^
- 9 left |
- 10 left &&
- 11 left ||
- 12 right ? :
- 13 right += -= *= /= <<= >>= &= |= ^= (2)
- (lowest)
- </pre></div>
- <p>Notes:
- (1) Prefix operators
- (2) See <a href="#Assignments">Assignments</a>.
- </p>
- <hr>
- <span id="Evaluation"></span><div class="header">
- <p>
- Next: <a href="#Expression-Section" accesskey="n" rel="next">Expression Section</a>, Previous: <a href="#Operators" accesskey="p" rel="prev">Operators</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Evaluation-1"></span><h4 class="subsection">3.10.7 Evaluation</h4>
- <span id="index-lazy-evaluation"></span>
- <span id="index-expression-evaluation-order"></span>
- <p>The linker evaluates expressions lazily. It only computes the value of
- an expression when absolutely necessary.
- </p>
- <p>The linker needs some information, such as the value of the start
- address of the first section, and the origins and lengths of memory
- regions, in order to do any linking at all. These values are computed
- as soon as possible when the linker reads in the linker script.
- </p>
- <p>However, other values (such as symbol values) are not known or needed
- until after storage allocation. Such values are evaluated later, when
- other information (such as the sizes of output sections) is available
- for use in the symbol assignment expression.
- </p>
- <p>The sizes of sections cannot be known until after allocation, so
- assignments dependent upon these are not performed until after
- allocation.
- </p>
- <p>Some expressions, such as those depending upon the location counter
- ‘<samp>.</samp>’, must be evaluated during section allocation.
- </p>
- <p>If the result of an expression is required, but the value is not
- available, then an error results. For example, a script like the
- following
- </p><div class="example">
- <pre class="example">SECTIONS
- {
- .text 9+this_isnt_constant :
- { *(.text) }
- }
- </pre></div>
- <p>will cause the error message ‘<samp>non constant expression for initial
- address</samp>’.
- </p>
- <hr>
- <span id="Expression-Section"></span><div class="header">
- <p>
- Next: <a href="#Builtin-Functions" accesskey="n" rel="next">Builtin Functions</a>, Previous: <a href="#Evaluation" accesskey="p" rel="prev">Evaluation</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="The-Section-of-an-Expression"></span><h4 class="subsection">3.10.8 The Section of an Expression</h4>
- <span id="index-expression-sections"></span>
- <span id="index-absolute-expressions"></span>
- <span id="index-relative-expressions"></span>
- <span id="index-absolute-and-relocatable-symbols"></span>
- <span id="index-relocatable-and-absolute-symbols"></span>
- <span id="index-symbols_002c-relocatable-and-absolute"></span>
- <p>Addresses and symbols may be section relative, or absolute. A section
- relative symbol is relocatable. If you request relocatable output
- using the ‘<samp>-r</samp>’ option, a further link operation may change the
- value of a section relative symbol. On the other hand, an absolute
- symbol will retain the same value throughout any further link
- operations.
- </p>
- <p>Some terms in linker expressions are addresses. This is true of
- section relative symbols and for builtin functions that return an
- address, such as <code>ADDR</code>, <code>LOADADDR</code>, <code>ORIGIN</code> and
- <code>SEGMENT_START</code>. Other terms are simply numbers, or are builtin
- functions that return a non-address value, such as <code>LENGTH</code>.
- One complication is that unless you set <code>LD_FEATURE ("SANE_EXPR")</code>
- (see <a href="#Miscellaneous-Commands">Miscellaneous Commands</a>), numbers and absolute symbols are treated
- differently depending on their location, for compatibility with older
- versions of <code>ld</code>. Expressions appearing outside an output
- section definition treat all numbers as absolute addresses.
- Expressions appearing inside an output section definition treat
- absolute symbols as numbers. If <code>LD_FEATURE ("SANE_EXPR")</code> is
- given, then absolute symbols and numbers are simply treated as numbers
- everywhere.
- </p>
- <p>In the following simple example,
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- . = 0x100;
- __executable_start = 0x100;
- .data :
- {
- . = 0x10;
- __data_start = 0x10;
- *(.data)
- }
- …
- }
- </pre></div>
- <p>both <code>.</code> and <code>__executable_start</code> are set to the absolute
- address 0x100 in the first two assignments, then both <code>.</code> and
- <code>__data_start</code> are set to 0x10 relative to the <code>.data</code>
- section in the second two assignments.
- </p>
- <p>For expressions involving numbers, relative addresses and absolute
- addresses, ld follows these rules to evaluate terms:
- </p>
- <ul>
- <li> Unary operations on an absolute address or number, and binary
- operations on two absolute addresses or two numbers, or between one
- absolute address and a number, apply the operator to the value(s).
- </li><li> Unary operations on a relative address, and binary operations on two
- relative addresses in the same section or between one relative address
- and a number, apply the operator to the offset part of the address(es).
- </li><li> Other binary operations, that is, between two relative addresses not
- in the same section, or between a relative address and an absolute
- address, first convert any non-absolute term to an absolute address
- before applying the operator.
- </li></ul>
- <p>The result section of each sub-expression is as follows:
- </p>
- <ul>
- <li> An operation involving only numbers results in a number.
- </li><li> The result of comparisons, ‘<samp>&&</samp>’ and ‘<samp>||</samp>’ is also a number.
- </li><li> The result of other binary arithmetic and logical operations on two
- relative addresses in the same section or two absolute addresses
- (after above conversions) is also a number when
- <code>LD_FEATURE ("SANE_EXPR")</code> or inside an output section definition
- but an absolute address otherwise.
- </li><li> The result of other operations on relative addresses or one
- relative address and a number, is a relative address in the same
- section as the relative operand(s).
- </li><li> The result of other operations on absolute addresses (after above
- conversions) is an absolute address.
- </li></ul>
- <p>You can use the builtin function <code>ABSOLUTE</code> to force an expression
- to be absolute when it would otherwise be relative. For example, to
- create an absolute symbol set to the address of the end of the output
- section ‘<samp>.data</samp>’:
- </p><div class="example">
- <pre class="example">SECTIONS
- {
- .data : { *(.data) _edata = ABSOLUTE(.); }
- }
- </pre></div>
- <p>If ‘<samp>ABSOLUTE</samp>’ were not used, ‘<samp>_edata</samp>’ would be relative to the
- ‘<samp>.data</samp>’ section.
- </p>
- <p>Using <code>LOADADDR</code> also forces an expression absolute, since this
- particular builtin function returns an absolute address.
- </p>
- <hr>
- <span id="Builtin-Functions"></span><div class="header">
- <p>
- Previous: <a href="#Expression-Section" accesskey="p" rel="prev">Expression Section</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Builtin-Functions-1"></span><h4 class="subsection">3.10.9 Builtin Functions</h4>
- <span id="index-functions-in-expressions"></span>
- <p>The linker script language includes a number of builtin functions for
- use in linker script expressions.
- </p>
- <dl compact="compact">
- <dt><code>ABSOLUTE(<var>exp</var>)</code></dt>
- <dd><span id="index-ABSOLUTE_0028exp_0029"></span>
- <span id="index-expression_002c-absolute"></span>
- <p>Return the absolute (non-relocatable, as opposed to non-negative) value
- of the expression <var>exp</var>. Primarily useful to assign an absolute
- value to a symbol within a section definition, where symbol values are
- normally section relative. See <a href="#Expression-Section">Expression Section</a>.
- </p>
- </dd>
- <dt><code>ADDR(<var>section</var>)</code></dt>
- <dd><span id="index-ADDR_0028section_0029"></span>
- <span id="index-section-address-in-expression"></span>
- <p>Return the address (VMA) of the named <var>section</var>. Your
- script must previously have defined the location of that section. In
- the following example, <code>start_of_output_1</code>, <code>symbol_1</code> and
- <code>symbol_2</code> are assigned equivalent values, except that
- <code>symbol_1</code> will be relative to the <code>.output1</code> section while
- the other two will be absolute:
- </p><div class="example">
- <pre class="example">SECTIONS { …
- .output1 :
- {
- start_of_output_1 = ABSOLUTE(.);
- …
- }
- .output :
- {
- symbol_1 = ADDR(.output1);
- symbol_2 = start_of_output_1;
- }
- … }
- </pre></div>
- </dd>
- <dt><code>ALIGN(<var>align</var>)</code></dt>
- <dt><code>ALIGN(<var>exp</var>,<var>align</var>)</code></dt>
- <dd><span id="index-ALIGN_0028align_0029"></span>
- <span id="index-ALIGN_0028exp_002calign_0029"></span>
- <span id="index-round-up-location-counter"></span>
- <span id="index-align-location-counter"></span>
- <span id="index-round-up-expression"></span>
- <span id="index-align-expression"></span>
- <p>Return the location counter (<code>.</code>) or arbitrary expression aligned
- to the next <var>align</var> boundary. The single operand <code>ALIGN</code>
- doesn’t change the value of the location counter—it just does
- arithmetic on it. The two operand <code>ALIGN</code> allows an arbitrary
- expression to be aligned upwards (<code>ALIGN(<var>align</var>)</code> is
- equivalent to <code>ALIGN(ABSOLUTE(.), <var>align</var>)</code>).
- </p>
- <p>Here is an example which aligns the output <code>.data</code> section to the
- next <code>0x2000</code> byte boundary after the preceding section and sets a
- variable within the section to the next <code>0x8000</code> boundary after the
- input sections:
- </p><div class="example">
- <pre class="example">SECTIONS { …
- .data ALIGN(0x2000): {
- *(.data)
- variable = ALIGN(0x8000);
- }
- … }
- </pre></div>
- <p>The first use of <code>ALIGN</code> in this example specifies the location of
- a section because it is used as the optional <var>address</var> attribute of
- a section definition (see <a href="#Output-Section-Address">Output Section Address</a>). The second use
- of <code>ALIGN</code> is used to defines the value of a symbol.
- </p>
- <p>The builtin function <code>NEXT</code> is closely related to <code>ALIGN</code>.
- </p>
- </dd>
- <dt><code>ALIGNOF(<var>section</var>)</code></dt>
- <dd><span id="index-ALIGNOF_0028section_0029"></span>
- <span id="index-section-alignment"></span>
- <p>Return the alignment in bytes of the named <var>section</var>, if that section has
- been allocated, or zero if the section has not been allocated. If the
- section does not exist in the linker script the linker will report an
- error. If <var>section</var> is <code>NEXT_SECTION</code> then <code>ALIGNOF</code> will
- return the alignment of the next allocated section specified in the
- linker script, or zero if there is no such section. In the following
- example, the alignment of the <code>.output</code> section is stored as the
- first value in that section.
- </p><div class="example">
- <pre class="example">SECTIONS{ …
- .output {
- LONG (ALIGNOF (.output))
- …
- }
- … }
- </pre></div>
- </dd>
- <dt><code>BLOCK(<var>exp</var>)</code></dt>
- <dd><span id="index-BLOCK_0028exp_0029"></span>
- <p>This is a synonym for <code>ALIGN</code>, for compatibility with older linker
- scripts. It is most often seen when setting the address of an output
- section.
- </p>
- </dd>
- <dt><code>DATA_SEGMENT_ALIGN(<var>maxpagesize</var>, <var>commonpagesize</var>)</code></dt>
- <dd><span id="index-DATA_005fSEGMENT_005fALIGN_0028maxpagesize_002c-commonpagesize_0029"></span>
- <p>This is equivalent to either
- </p><div class="example">
- <pre class="example">(ALIGN(<var>maxpagesize</var>) + (. & (<var>maxpagesize</var> - 1)))
- </pre></div>
- <p>or
- </p><div class="example">
- <pre class="example">(ALIGN(<var>maxpagesize</var>)
- + ((. + <var>commonpagesize</var> - 1) & (<var>maxpagesize</var> - <var>commonpagesize</var>)))
- </pre></div>
- <p>depending on whether the latter uses fewer <var>commonpagesize</var> sized pages
- for the data segment (area between the result of this expression and
- <code>DATA_SEGMENT_END</code>) than the former or not.
- If the latter form is used, it means <var>commonpagesize</var> bytes of runtime
- memory will be saved at the expense of up to <var>commonpagesize</var> wasted
- bytes in the on-disk file.
- </p>
- <p>This expression can only be used directly in <code>SECTIONS</code> commands, not in
- any output section descriptions and only once in the linker script.
- <var>commonpagesize</var> should be less or equal to <var>maxpagesize</var> and should
- be the system page size the object wants to be optimized for while still
- running on system page sizes up to <var>maxpagesize</var>. Note however
- that ‘<samp>-z relro</samp>’ protection will not be effective if the system
- page size is larger than <var>commonpagesize</var>.
- </p>
- <p>Example:
- </p><div class="example">
- <pre class="example"> . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
- </pre></div>
- </dd>
- <dt><code>DATA_SEGMENT_END(<var>exp</var>)</code></dt>
- <dd><span id="index-DATA_005fSEGMENT_005fEND_0028exp_0029"></span>
- <p>This defines the end of data segment for <code>DATA_SEGMENT_ALIGN</code>
- evaluation purposes.
- </p>
- <div class="example">
- <pre class="example"> . = DATA_SEGMENT_END(.);
- </pre></div>
- </dd>
- <dt><code>DATA_SEGMENT_RELRO_END(<var>offset</var>, <var>exp</var>)</code></dt>
- <dd><span id="index-DATA_005fSEGMENT_005fRELRO_005fEND_0028offset_002c-exp_0029"></span>
- <p>This defines the end of the <code>PT_GNU_RELRO</code> segment when
- ‘<samp>-z relro</samp>’ option is used.
- When ‘<samp>-z relro</samp>’ option is not present, <code>DATA_SEGMENT_RELRO_END</code>
- does nothing, otherwise <code>DATA_SEGMENT_ALIGN</code> is padded so that
- <var>exp</var> + <var>offset</var> is aligned to the <var>commonpagesize</var>
- argument given to <code>DATA_SEGMENT_ALIGN</code>. If present in the linker
- script, it must be placed between <code>DATA_SEGMENT_ALIGN</code> and
- <code>DATA_SEGMENT_END</code>. Evaluates to the second argument plus any
- padding needed at the end of the <code>PT_GNU_RELRO</code> segment due to
- section alignment.
- </p>
- <div class="example">
- <pre class="example"> . = DATA_SEGMENT_RELRO_END(24, .);
- </pre></div>
- </dd>
- <dt><code>DEFINED(<var>symbol</var>)</code></dt>
- <dd><span id="index-DEFINED_0028symbol_0029"></span>
- <span id="index-symbol-defaults"></span>
- <p>Return 1 if <var>symbol</var> is in the linker global symbol table and is
- defined before the statement using DEFINED in the script, otherwise
- return 0. You can use this function to provide
- default values for symbols. For example, the following script fragment
- shows how to set a global symbol ‘<samp>begin</samp>’ to the first location in
- the ‘<samp>.text</samp>’ section—but if a symbol called ‘<samp>begin</samp>’ already
- existed, its value is preserved:
- </p>
- <div class="example">
- <pre class="example">SECTIONS { …
- .text : {
- begin = DEFINED(begin) ? begin : . ;
- …
- }
- …
- }
- </pre></div>
- </dd>
- <dt><code>LENGTH(<var>memory</var>)</code></dt>
- <dd><span id="index-LENGTH_0028memory_0029"></span>
- <p>Return the length of the memory region named <var>memory</var>.
- </p>
- </dd>
- <dt><code>LOADADDR(<var>section</var>)</code></dt>
- <dd><span id="index-LOADADDR_0028section_0029"></span>
- <span id="index-section-load-address-in-expression"></span>
- <p>Return the absolute LMA of the named <var>section</var>. (see <a href="#Output-Section-LMA">Output Section LMA</a>).
- </p>
- </dd>
- <dt><code>LOG2CEIL(<var>exp</var>)</code></dt>
- <dd><span id="index-LOG2CEIL_0028exp_0029"></span>
- <p>Return the binary logarithm of <var>exp</var> rounded towards infinity.
- <code>LOG2CEIL(0)</code> returns 0.
- </p>
- <span id="index-MAX"></span>
- </dd>
- <dt><code>MAX(<var>exp1</var>, <var>exp2</var>)</code></dt>
- <dd><p>Returns the maximum of <var>exp1</var> and <var>exp2</var>.
- </p>
- <span id="index-MIN"></span>
- </dd>
- <dt><code>MIN(<var>exp1</var>, <var>exp2</var>)</code></dt>
- <dd><p>Returns the minimum of <var>exp1</var> and <var>exp2</var>.
- </p>
- </dd>
- <dt><code>NEXT(<var>exp</var>)</code></dt>
- <dd><span id="index-NEXT_0028exp_0029"></span>
- <span id="index-unallocated-address_002c-next"></span>
- <p>Return the next unallocated address that is a multiple of <var>exp</var>.
- This function is closely related to <code>ALIGN(<var>exp</var>)</code>; unless you
- use the <code>MEMORY</code> command to define discontinuous memory for the
- output file, the two functions are equivalent.
- </p>
- </dd>
- <dt><code>ORIGIN(<var>memory</var>)</code></dt>
- <dd><span id="index-ORIGIN_0028memory_0029"></span>
- <p>Return the origin of the memory region named <var>memory</var>.
- </p>
- </dd>
- <dt><code>SEGMENT_START(<var>segment</var>, <var>default</var>)</code></dt>
- <dd><span id="index-SEGMENT_005fSTART_0028segment_002c-default_0029"></span>
- <p>Return the base address of the named <var>segment</var>. If an explicit
- value has already been given for this segment (with a command-line
- ‘<samp>-T</samp>’ option) then that value will be returned otherwise the value
- will be <var>default</var>. At present, the ‘<samp>-T</samp>’ command-line option
- can only be used to set the base address for the “text”, “data”, and
- “bss” sections, but you can use <code>SEGMENT_START</code> with any segment
- name.
- </p>
- </dd>
- <dt><code>SIZEOF(<var>section</var>)</code></dt>
- <dd><span id="index-SIZEOF_0028section_0029"></span>
- <span id="index-section-size"></span>
- <p>Return the size in bytes of the named <var>section</var>, if that section has
- been allocated, or zero if the section has not been allocated. If the
- section does not exist in the linker script the linker will report an
- error. If <var>section</var> is <code>NEXT_SECTION</code> then <code>SIZEOF</code> will
- return the alignment of the next allocated section specified in the
- linker script, or zero if there is no such section. In the following
- example, <code>symbol_1</code> and <code>symbol_2</code> are assigned identical
- values:
- </p><div class="example">
- <pre class="example">SECTIONS{ …
- .output {
- .start = . ;
- …
- .end = . ;
- }
- symbol_1 = .end - .start ;
- symbol_2 = SIZEOF(.output);
- … }
- </pre></div>
- </dd>
- <dt><code>SIZEOF_HEADERS</code></dt>
- <dd><span id="index-SIZEOF_005fHEADERS"></span>
- <span id="index-header-size"></span>
- <p>Return the size in bytes of the output file’s headers. This is
- information which appears at the start of the output file. You can use
- this number when setting the start address of the first section, if you
- choose, to facilitate paging.
- </p>
- <span id="index-not-enough-room-for-program-headers"></span>
- <span id="index-program-headers_002c-not-enough-room"></span>
- <p>When producing an ELF output file, if the linker script uses the
- <code>SIZEOF_HEADERS</code> builtin function, the linker must compute the
- number of program headers before it has determined all the section
- addresses and sizes. If the linker later discovers that it needs
- additional program headers, it will report an error ‘<samp>not enough
- room for program headers</samp>’. To avoid this error, you must avoid using
- the <code>SIZEOF_HEADERS</code> function, or you must rework your linker
- script to avoid forcing the linker to use additional program headers, or
- you must define the program headers yourself using the <code>PHDRS</code>
- command (see <a href="#PHDRS">PHDRS</a>).
- </p></dd>
- </dl>
- <hr>
- <span id="Implicit-Linker-Scripts"></span><div class="header">
- <p>
- Previous: <a href="#Expressions" accesskey="p" rel="prev">Expressions</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Implicit-Linker-Scripts-1"></span><h3 class="section">3.11 Implicit Linker Scripts</h3>
- <span id="index-implicit-linker-scripts"></span>
- <p>If you specify a linker input file which the linker can not recognize as
- an object file or an archive file, it will try to read the file as a
- linker script. If the file can not be parsed as a linker script, the
- linker will report an error.
- </p>
- <p>An implicit linker script will not replace the default linker script.
- </p>
- <p>Typically an implicit linker script would contain only symbol
- assignments, or the <code>INPUT</code>, <code>GROUP</code>, or <code>VERSION</code>
- commands.
- </p>
- <p>Any input files read because of an implicit linker script will be read
- at the position in the command line where the implicit linker script was
- read. This can affect archive searching.
- </p>
- <hr>
- <span id="Plugins"></span><div class="header">
- <p>
- Next: <a href="#Special-Sections" accesskey="n" rel="next">Special Sections</a>, Previous: <a href="#Scripts" accesskey="p" rel="prev">Scripts</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Linker-Plugins"></span><h2 class="chapter">4 Linker Plugins</h2>
- <span id="index-plugins"></span>
- <span id="index-linker-plugins"></span>
- <p>The linker can use dynamically loaded plugins to modify its behavior.
- For example, the link-time optimization feature that some compilers
- support is implemented with a linker plugin.
- </p>
- <p>Currently there is only one plugin shipped by default, but more may
- be added here later.
- </p>
- <p>Plugins are enabled via the use of the <samp>-plugin <var>name</var></samp>
- command line option. See <a href="#Options">Options</a>.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#libdep-Plugin" accesskey="1">libdep Plugin</a></td><td> </td><td align="left" valign="top">Static Library Dependencies Plugin
- </td></tr>
- </table>
- <hr>
- <span id="libdep-Plugin"></span><div class="header">
- <p>
- Up: <a href="#Plugins" accesskey="u" rel="up">Plugins</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Static-Library-Dependencies-Plugin"></span><h3 class="section">4.1 Static Library Dependencies Plugin</h3>
- <span id="index-static-library-dependencies"></span>
- <p>Originally, static libraries were contained in an archive file consisting
- just of a collection of relocatable object files. Later they evolved to
- optionally include a symbol table, to assist in finding the needed objects
- within a library. There their evolution ended, and dynamic libraries
- rose to ascendance.
- </p>
- <p>One useful feature of dynamic libraries was that, more than just collecting
- multiple objects into a single file, they also included a list of their
- dependencies, such that one could specify just the name of a single dynamic
- library at link time, and all of its dependencies would be implicitly
- referenced as well. But static libraries lacked this feature, so if a
- link invocation was switched from using dynamic libraries to static
- libraries, the link command would usually fail unless it was rewritten to
- explicitly list the dependencies of the static library.
- </p>
- <p>The GNU <code>ar</code> utility now supports a <samp>--record-libdeps</samp> option
- to embed dependency lists into static libraries as well, and the <samp>libdep</samp>
- plugin may be used to read this dependency information at link time. The
- dependency information is stored as a single string, carrying <samp>-l</samp>
- and <samp>-L</samp> arguments as they would normally appear in a linker
- command line. As such, the information can be written with any text
- utility and stored into any archive, even if GNU <code>ar</code> is not
- being used to create the archive. The information is stored in an
- archive member named ‘<samp>__.LIBDEP</samp>’.
- </p>
- <p>For example, given a library <samp>libssl.a</samp> that depends on another
- library <samp>libcrypto.a</samp> which may be found in <samp>/usr/local/lib</samp>,
- the ‘<samp>__.LIBDEP</samp>’ member of <samp>libssl.a</samp> would contain
- </p>
- <div class="example">
- <pre class="example">-L/usr/local/lib -lcrypto
- </pre></div>
- <hr>
- <span id="Special-Sections"></span><div class="header">
- <p>
- Next: <a href="#Machine-Dependent" accesskey="n" rel="next">Machine Dependent</a>, Previous: <a href="#Plugins" accesskey="p" rel="prev">Plugins</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Special-Sections-1"></span><h2 class="chapter">5 Special Sections</h2>
- <p>When linking ELF format object files <code>ld</code> treats some sections
- in a special, non standard manner. This part of the manual describes
- these sections.
- </p>
- <dl compact="compact">
- <dt><code>.gnu.warning</code></dt>
- <dd><p>The contents of any section with this name are assumed to be an ascii
- format warning message. The contents will be displayed to the user if
- the sections appears in any input file, but the section will not be
- copied into the output image. If the <samp>--fatal-warnings</samp> option
- is enabled then the warnings - if any are encountered - will also stop
- the link from completing.
- </p>
- <p>Note - the ‘<samp>.gnu.warning</samp>’ section is not subject to linker
- garbage collection or orphan handling.
- </p>
- </dd>
- <dt><code>.gnu.warning.<var>SYM</var></code></dt>
- <dd><p>The contents of any section whoes name starts with the prefix
- ‘<samp>.gnu.warning.</samp>’ and then finishes with the name of a symbol is
- treated in a similar fashion to the ‘<samp>.gnu.warning</samp>’ section, but
- only if the named symbol is referenced. So for example the contents
- of a section called ‘<samp>.gnu.warning.foo</samp>’ will be displayed as
- warning message if, and only if, the symbol ‘<samp>foo</samp>’ is referenced
- by one or more of the input files. This includes object files pulled
- in from static libraries, shared objects needed to complete the link
- and so on.
- </p>
- <p>Note - because these warning messages are generated before the linker
- performs garbage collection (if enabled) it is possible for a warning
- to be displayed for a symbol that is later removed and then never
- appears in the final output.
- </p>
- </dd>
- <dt><code>.note.gnu.property</code></dt>
- <dd><p>When the linker combines sections of this name it will merge them
- together according to various rules encoded into the notes
- themselves. Therefore the contents of the output .note.gnu.property
- section may not correspond to a simple concatenation of the input
- sections. If the <samp>-Map</samp> option has been used to request a
- linker map then details of any property merging will be included in
- the map.
- </p>
- </dd>
- </dl>
- <hr>
- <span id="Machine-Dependent"></span><div class="header">
- <p>
- Next: <a href="#BFD" accesskey="n" rel="next">BFD</a>, Previous: <a href="#Special-Sections" accesskey="p" rel="prev">Special Sections</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Machine-Dependent-Features"></span><h2 class="chapter">6 Machine Dependent Features</h2>
- <span id="index-machine-dependencies"></span>
- <p><code>ld</code> has additional features on some platforms; the following
- sections describe them. Machines where <code>ld</code> has no additional
- functionality are not listed.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#H8_002f300" accesskey="1">H8/300</a></td><td> </td><td align="left" valign="top"><code>ld</code> and the H8/300
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#M68HC11_002f68HC12" accesskey="2">M68HC11/68HC12</a></td><td> </td><td align="left" valign="top"><code>ld</code> and the Motorola 68HC11 and 68HC12 families
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#ARM" accesskey="3">ARM</a></td><td> </td><td align="left" valign="top"><code>ld</code> and the ARM family
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#HPPA-ELF32" accesskey="4">HPPA ELF32</a></td><td> </td><td align="left" valign="top"><code>ld</code> and HPPA 32-bit ELF
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#M68K" accesskey="5">M68K</a></td><td> </td><td align="left" valign="top"><code>ld</code> and the Motorola 68K family
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#MIPS" accesskey="6">MIPS</a></td><td> </td><td align="left" valign="top"><code>ld</code> and the MIPS family
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#MMIX" accesskey="7">MMIX</a></td><td> </td><td align="left" valign="top"><code>ld</code> and MMIX
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#MSP430" accesskey="8">MSP430</a></td><td> </td><td align="left" valign="top"><code>ld</code> and MSP430
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#NDS32" accesskey="9">NDS32</a></td><td> </td><td align="left" valign="top"><code>ld</code> and NDS32
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Nios-II">Nios II</a></td><td> </td><td align="left" valign="top"><code>ld</code> and the Altera Nios II
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#PowerPC-ELF32">PowerPC ELF32</a></td><td> </td><td align="left" valign="top"><code>ld</code> and PowerPC 32-bit ELF Support
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td><td> </td><td align="left" valign="top"><code>ld</code> and PowerPC64 64-bit ELF Support
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#S_002f390-ELF">S/390 ELF</a></td><td> </td><td align="left" valign="top"><code>ld</code> and S/390 ELF Support
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#SPU-ELF">SPU ELF</a></td><td> </td><td align="left" valign="top"><code>ld</code> and SPU ELF Support
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#TI-COFF">TI COFF</a></td><td> </td><td align="left" valign="top"><code>ld</code> and TI COFF
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#WIN32">WIN32</a></td><td> </td><td align="left" valign="top"><code>ld</code> and WIN32 (cygwin/mingw)
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Xtensa">Xtensa</a></td><td> </td><td align="left" valign="top"><code>ld</code> and Xtensa Processors
- </td></tr>
- </table>
- <hr>
- <span id="H8_002f300"></span><div class="header">
- <p>
- Next: <a href="#M68HC11_002f68HC12" accesskey="n" rel="next">M68HC11/68HC12</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-the-H8_002f300"></span><h3 class="section">6.1 <code>ld</code> and the H8/300</h3>
- <span id="index-H8_002f300-support"></span>
- <p>For the H8/300, <code>ld</code> can perform these global optimizations when
- you specify the ‘<samp>--relax</samp>’ command-line option.
- </p>
- <dl compact="compact">
- <dd><span id="index-relaxing-on-H8_002f300"></span>
- </dd>
- <dt><em>relaxing address modes</em></dt>
- <dd><p><code>ld</code> finds all <code>jsr</code> and <code>jmp</code> instructions whose
- targets are within eight bits, and turns them into eight-bit
- program-counter relative <code>bsr</code> and <code>bra</code> instructions,
- respectively.
- </p>
- <span id="index-synthesizing-on-H8_002f300"></span>
- </dd>
- <dt><em>synthesizing instructions</em></dt>
- <dd><p><code>ld</code> finds all <code>mov.b</code> instructions which use the
- sixteen-bit absolute address form, but refer to the top
- page of memory, and changes them to use the eight-bit address form.
- (That is: the linker turns ‘<samp>mov.b <code>@</code><var>aa</var>:16</samp>’ into
- ‘<samp>mov.b <code>@</code><var>aa</var>:8</samp>’ whenever the address <var>aa</var> is in the
- top page of memory).
- </p>
- <p><code>ld</code> finds all <code>mov</code> instructions which use the register
- indirect with 32-bit displacement addressing mode, but use a small
- displacement inside 16-bit displacement range, and changes them to use
- the 16-bit displacement form. (That is: the linker turns ‘<samp>mov.b
- <code>@</code><var>d</var>:32,ERx</samp>’ into ‘<samp>mov.b <code>@</code><var>d</var>:16,ERx</samp>’
- whenever the displacement <var>d</var> is in the 16 bit signed integer
- range. Only implemented in ELF-format ld).
- </p>
- </dd>
- <dt><em>bit manipulation instructions</em></dt>
- <dd><p><code>ld</code> finds all bit manipulation instructions like <code>band, bclr,
- biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor</code>
- which use 32 bit and 16 bit absolute address form, but refer to the top
- page of memory, and changes them to use the 8 bit address form.
- (That is: the linker turns ‘<samp>bset #xx:3,<code>@</code><var>aa</var>:32</samp>’ into
- ‘<samp>bset #xx:3,<code>@</code><var>aa</var>:8</samp>’ whenever the address <var>aa</var> is in
- the top page of memory).
- </p>
- </dd>
- <dt><em>system control instructions</em></dt>
- <dd><p><code>ld</code> finds all <code>ldc.w, stc.w</code> instructions which use the
- 32 bit absolute address form, but refer to the top page of memory, and
- changes them to use 16 bit address form.
- (That is: the linker turns ‘<samp>ldc.w <code>@</code><var>aa</var>:32,ccr</samp>’ into
- ‘<samp>ldc.w <code>@</code><var>aa</var>:16,ccr</samp>’ whenever the address <var>aa</var> is in
- the top page of memory).
- </p></dd>
- </dl>
- <hr>
- <span id="M68HC11_002f68HC12"></span><div class="header">
- <p>
- Next: <a href="#ARM" accesskey="n" rel="next">ARM</a>, Previous: <a href="#H8_002f300" accesskey="p" rel="prev">H8/300</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-the-Motorola-68HC11-and-68HC12-families"></span><h3 class="section">6.2 <code>ld</code> and the Motorola 68HC11 and 68HC12 families</h3>
- <span id="index-M68HC11-and-68HC12-support"></span>
- <span id="Linker-Relaxation"></span><h4 class="subsection">6.2.1 Linker Relaxation</h4>
- <p>For the Motorola 68HC11, <code>ld</code> can perform these global
- optimizations when you specify the ‘<samp>--relax</samp>’ command-line option.
- </p>
- <dl compact="compact">
- <dd><span id="index-relaxing-on-M68HC11"></span>
- </dd>
- <dt><em>relaxing address modes</em></dt>
- <dd><p><code>ld</code> finds all <code>jsr</code> and <code>jmp</code> instructions whose
- targets are within eight bits, and turns them into eight-bit
- program-counter relative <code>bsr</code> and <code>bra</code> instructions,
- respectively.
- </p>
- <p><code>ld</code> also looks at all 16-bit extended addressing modes and
- transforms them in a direct addressing mode when the address is in
- page 0 (between 0 and 0x0ff).
- </p>
- </dd>
- <dt><em>relaxing gcc instruction group</em></dt>
- <dd><p>When <code>gcc</code> is called with <samp>-mrelax</samp>, it can emit group
- of instructions that the linker can optimize to use a 68HC11 direct
- addressing mode. These instructions consists of <code>bclr</code> or
- <code>bset</code> instructions.
- </p>
- </dd>
- </dl>
- <span id="Trampoline-Generation"></span><h4 class="subsection">6.2.2 Trampoline Generation</h4>
- <span id="index-trampoline-generation-on-M68HC11"></span>
- <span id="index-trampoline-generation-on-M68HC12"></span>
- <p>For 68HC11 and 68HC12, <code>ld</code> can generate trampoline code to
- call a far function using a normal <code>jsr</code> instruction. The linker
- will also change the relocation to some far function to use the
- trampoline address instead of the function address. This is typically the
- case when a pointer to a function is taken. The pointer will in fact
- point to the function trampoline.
- </p>
- <hr>
- <span id="ARM"></span><div class="header">
- <p>
- Next: <a href="#HPPA-ELF32" accesskey="n" rel="next">HPPA ELF32</a>, Previous: <a href="#M68HC11_002f68HC12" accesskey="p" rel="prev">M68HC11/68HC12</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-the-ARM-family"></span><h3 class="section">6.3 <code>ld</code> and the ARM family</h3>
- <span id="index-ARM-interworking-support"></span>
- <span id="index-_002d_002dsupport_002dold_002dcode"></span>
- <p>For the ARM, <code>ld</code> will generate code stubs to allow functions calls
- between ARM and Thumb code. These stubs only work with code that has
- been compiled and assembled with the ‘<samp>-mthumb-interwork</samp>’ command
- line option. If it is necessary to link with old ARM object files or
- libraries, which have not been compiled with the -mthumb-interwork
- option then the ‘<samp>--support-old-code</samp>’ command-line switch should be
- given to the linker. This will make it generate larger stub functions
- which will work with non-interworking aware ARM code. Note, however,
- the linker does not support generating stubs for function calls to
- non-interworking aware Thumb code.
- </p>
- <span id="index-thumb-entry-point"></span>
- <span id="index-entry-point_002c-thumb"></span>
- <span id="index-_002d_002dthumb_002dentry_003dentry"></span>
- <p>The ‘<samp>--thumb-entry</samp>’ switch is a duplicate of the generic
- ‘<samp>--entry</samp>’ switch, in that it sets the program’s starting address.
- But it also sets the bottom bit of the address, so that it can be
- branched to using a BX instruction, and the program will start
- executing in Thumb mode straight away.
- </p>
- <span id="index-PE-import-table-prefixing"></span>
- <span id="index-_002d_002duse_002dnul_002dprefixed_002dimport_002dtables"></span>
- <p>The ‘<samp>--use-nul-prefixed-import-tables</samp>’ switch is specifying, that
- the import tables idata4 and idata5 have to be generated with a zero
- element prefix for import libraries. This is the old style to generate
- import tables. By default this option is turned off.
- </p>
- <span id="index-BE8"></span>
- <span id="index-_002d_002dbe8"></span>
- <p>The ‘<samp>--be8</samp>’ switch instructs <code>ld</code> to generate BE8 format
- executables. This option is only valid when linking big-endian
- objects - ie ones which have been assembled with the <samp>-EB</samp>
- option. The resulting image will contain big-endian data and
- little-endian code.
- </p>
- <span id="index-TARGET1"></span>
- <span id="index-_002d_002dtarget1_002drel"></span>
- <span id="index-_002d_002dtarget1_002dabs"></span>
- <p>The ‘<samp>R_ARM_TARGET1</samp>’ relocation is typically used for entries in the
- ‘<samp>.init_array</samp>’ section. It is interpreted as either ‘<samp>R_ARM_REL32</samp>’
- or ‘<samp>R_ARM_ABS32</samp>’, depending on the target. The ‘<samp>--target1-rel</samp>’
- and ‘<samp>--target1-abs</samp>’ switches override the default.
- </p>
- <span id="index-TARGET2"></span>
- <span id="index-_002d_002dtarget2_003dtype"></span>
- <p>The ‘<samp>--target2=type</samp>’ switch overrides the default definition of the
- ‘<samp>R_ARM_TARGET2</samp>’ relocation. Valid values for ‘<samp>type</samp>’, their
- meanings, and target defaults are as follows:
- </p><dl compact="compact">
- <dt>‘<samp>rel</samp>’</dt>
- <dd><p>‘<samp>R_ARM_REL32</samp>’ (arm*-*-elf, arm*-*-eabi)
- </p></dd>
- <dt>‘<samp>abs</samp>’</dt>
- <dd><p>‘<samp>R_ARM_ABS32</samp>’
- </p></dd>
- <dt>‘<samp>got-rel</samp>’</dt>
- <dd><p>‘<samp>R_ARM_GOT_PREL</samp>’ (arm*-*-linux, arm*-*-*bsd)
- </p></dd>
- </dl>
- <span id="index-FIX_005fV4BX"></span>
- <span id="index-_002d_002dfix_002dv4bx"></span>
- <p>The ‘<samp>R_ARM_V4BX</samp>’ relocation (defined by the ARM AAELF
- specification) enables objects compiled for the ARMv4 architecture to be
- interworking-safe when linked with other objects compiled for ARMv4t, but
- also allows pure ARMv4 binaries to be built from the same ARMv4 objects.
- </p>
- <p>In the latter case, the switch <samp>--fix-v4bx</samp> must be passed to the
- linker, which causes v4t <code>BX rM</code> instructions to be rewritten as
- <code>MOV PC,rM</code>, since v4 processors do not have a <code>BX</code> instruction.
- </p>
- <p>In the former case, the switch should not be used, and ‘<samp>R_ARM_V4BX</samp>’
- relocations are ignored.
- </p>
- <span id="index-FIX_005fV4BX_005fINTERWORKING"></span>
- <span id="index-_002d_002dfix_002dv4bx_002dinterworking"></span>
- <p>Replace <code>BX rM</code> instructions identified by ‘<samp>R_ARM_V4BX</samp>’
- relocations with a branch to the following veneer:
- </p>
- <div class="example">
- <pre class="example">TST rM, #1
- MOVEQ PC, rM
- BX Rn
- </pre></div>
- <p>This allows generation of libraries/applications that work on ARMv4 cores
- and are still interworking safe. Note that the above veneer clobbers the
- condition flags, so may cause incorrect program behavior in rare cases.
- </p>
- <span id="index-USE_005fBLX"></span>
- <span id="index-_002d_002duse_002dblx"></span>
- <p>The ‘<samp>--use-blx</samp>’ switch enables the linker to use ARM/Thumb
- BLX instructions (available on ARMv5t and above) in various
- situations. Currently it is used to perform calls via the PLT from Thumb
- code using BLX rather than using BX and a mode-switching stub before
- each PLT entry. This should lead to such calls executing slightly faster.
- </p>
- <span id="index-VFP11_005fDENORM_005fFIX"></span>
- <span id="index-_002d_002dvfp11_002ddenorm_002dfix"></span>
- <p>The ‘<samp>--vfp11-denorm-fix</samp>’ switch enables a link-time workaround for a
- bug in certain VFP11 coprocessor hardware, which sometimes allows
- instructions with denorm operands (which must be handled by support code)
- to have those operands overwritten by subsequent instructions before
- the support code can read the intended values.
- </p>
- <p>The bug may be avoided in scalar mode if you allow at least one
- intervening instruction between a VFP11 instruction which uses a register
- and another instruction which writes to the same register, or at least two
- intervening instructions if vector mode is in use. The bug only affects
- full-compliance floating-point mode: you do not need this workaround if
- you are using "runfast" mode. Please contact ARM for further details.
- </p>
- <p>If you know you are using buggy VFP11 hardware, you can
- enable this workaround by specifying the linker option
- ‘<samp>--vfp-denorm-fix=scalar</samp>’ if you are using the VFP11 scalar
- mode only, or ‘<samp>--vfp-denorm-fix=vector</samp>’ if you are using
- vector mode (the latter also works for scalar code). The default is
- ‘<samp>--vfp-denorm-fix=none</samp>’.
- </p>
- <p>If the workaround is enabled, instructions are scanned for
- potentially-troublesome sequences, and a veneer is created for each
- such sequence which may trigger the erratum. The veneer consists of the
- first instruction of the sequence and a branch back to the subsequent
- instruction. The original instruction is then replaced with a branch to
- the veneer. The extra cycles required to call and return from the veneer
- are sufficient to avoid the erratum in both the scalar and vector cases.
- </p>
- <span id="index-ARM1176-erratum-workaround"></span>
- <span id="index-_002d_002dfix_002darm1176"></span>
- <span id="index-_002d_002dno_002dfix_002darm1176"></span>
- <p>The ‘<samp>--fix-arm1176</samp>’ switch enables a link-time workaround for an erratum
- in certain ARM1176 processors. The workaround is enabled by default if you
- are targeting ARM v6 (excluding ARM v6T2) or earlier. It can be disabled
- unconditionally by specifying ‘<samp>--no-fix-arm1176</samp>’.
- </p>
- <p>Further information is available in the “ARM1176JZ-S and ARM1176JZF-S
- Programmer Advice Notice” available on the ARM documentation website at:
- http://infocenter.arm.com/.
- </p>
- <span id="index-STM32L4xx-erratum-workaround"></span>
- <span id="index-_002d_002dfix_002dstm32l4xx_002d629360"></span>
- <p>The ‘<samp>--fix-stm32l4xx-629360</samp>’ switch enables a link-time
- workaround for a bug in the bus matrix / memory controller for some of
- the STM32 Cortex-M4 based products (STM32L4xx). When accessing
- off-chip memory via the affected bus for bus reads of 9 words or more,
- the bus can generate corrupt data and/or abort. These are only
- core-initiated accesses (not DMA), and might affect any access:
- integer loads such as LDM, POP and floating-point loads such as VLDM,
- VPOP. Stores are not affected.
- </p>
- <p>The bug can be avoided by splitting memory accesses into the
- necessary chunks to keep bus reads below 8 words.
- </p>
- <p>The workaround is not enabled by default, this is equivalent to use
- ‘<samp>--fix-stm32l4xx-629360=none</samp>’. If you know you are using buggy
- STM32L4xx hardware, you can enable the workaround by specifying the
- linker option ‘<samp>--fix-stm32l4xx-629360</samp>’, or the equivalent
- ‘<samp>--fix-stm32l4xx-629360=default</samp>’.
- </p>
- <p>If the workaround is enabled, instructions are scanned for
- potentially-troublesome sequences, and a veneer is created for each
- such sequence which may trigger the erratum. The veneer consists in a
- replacement sequence emulating the behaviour of the original one and a
- branch back to the subsequent instruction. The original instruction is
- then replaced with a branch to the veneer.
- </p>
- <p>The workaround does not always preserve the memory access order for
- the LDMDB instruction, when the instruction loads the PC.
- </p>
- <p>The workaround is not able to handle problematic instructions when
- they are in the middle of an IT block, since a branch is not allowed
- there. In that case, the linker reports a warning and no replacement
- occurs.
- </p>
- <p>The workaround is not able to replace problematic instructions with a
- PC-relative branch instruction if the ‘<samp>.text</samp>’ section is too
- large. In that case, when the branch that replaces the original code
- cannot be encoded, the linker reports a warning and no replacement
- occurs.
- </p>
- <span id="index-NO_005fENUM_005fSIZE_005fWARNING"></span>
- <span id="index-_002d_002dno_002denum_002dsize_002dwarning"></span>
- <p>The <samp>--no-enum-size-warning</samp> switch prevents the linker from
- warning when linking object files that specify incompatible EABI
- enumeration size attributes. For example, with this switch enabled,
- linking of an object file using 32-bit enumeration values with another
- using enumeration values fitted into the smallest possible space will
- not be diagnosed.
- </p>
- <span id="index-NO_005fWCHAR_005fSIZE_005fWARNING"></span>
- <span id="index-_002d_002dno_002dwchar_002dsize_002dwarning"></span>
- <p>The <samp>--no-wchar-size-warning</samp> switch prevents the linker from
- warning when linking object files that specify incompatible EABI
- <code>wchar_t</code> size attributes. For example, with this switch enabled,
- linking of an object file using 32-bit <code>wchar_t</code> values with another
- using 16-bit <code>wchar_t</code> values will not be diagnosed.
- </p>
- <span id="index-PIC_005fVENEER"></span>
- <span id="index-_002d_002dpic_002dveneer"></span>
- <p>The ‘<samp>--pic-veneer</samp>’ switch makes the linker use PIC sequences for
- ARM/Thumb interworking veneers, even if the rest of the binary
- is not PIC. This avoids problems on uClinux targets where
- ‘<samp>--emit-relocs</samp>’ is used to generate relocatable binaries.
- </p>
- <span id="index-STUB_005fGROUP_005fSIZE"></span>
- <span id="index-_002d_002dstub_002dgroup_002dsize_003dN"></span>
- <p>The linker will automatically generate and insert small sequences of
- code into a linked ARM ELF executable whenever an attempt is made to
- perform a function call to a symbol that is too far away. The
- placement of these sequences of instructions - called stubs - is
- controlled by the command-line option <samp>--stub-group-size=N</samp>.
- The placement is important because a poor choice can create a need for
- duplicate stubs, increasing the code size. The linker will try to
- group stubs together in order to reduce interruptions to the flow of
- code, but it needs guidance as to how big these groups should be and
- where they should be placed.
- </p>
- <p>The value of ‘<samp>N</samp>’, the parameter to the
- <samp>--stub-group-size=</samp> option controls where the stub groups are
- placed. If it is negative then all stubs are placed after the first
- branch that needs them. If it is positive then the stubs can be
- placed either before or after the branches that need them. If the
- value of ‘<samp>N</samp>’ is 1 (either +1 or -1) then the linker will choose
- exactly where to place groups of stubs, using its built in heuristics.
- A value of ‘<samp>N</samp>’ greater than 1 (or smaller than -1) tells the
- linker that a single group of stubs can service at most ‘<samp>N</samp>’ bytes
- from the input sections.
- </p>
- <p>The default, if <samp>--stub-group-size=</samp> is not specified, is
- ‘<samp>N = +1</samp>’.
- </p>
- <p>Farcalls stubs insertion is fully supported for the ARM-EABI target
- only, because it relies on object files properties not present
- otherwise.
- </p>
- <span id="index-Cortex_002dA8-erratum-workaround"></span>
- <span id="index-_002d_002dfix_002dcortex_002da8"></span>
- <span id="index-_002d_002dno_002dfix_002dcortex_002da8"></span>
- <p>The ‘<samp>--fix-cortex-a8</samp>’ switch enables a link-time workaround for an erratum in certain Cortex-A8 processors. The workaround is enabled by default if you are targeting the ARM v7-A architecture profile. It can be enabled otherwise by specifying ‘<samp>--fix-cortex-a8</samp>’, or disabled unconditionally by specifying ‘<samp>--no-fix-cortex-a8</samp>’.
- </p>
- <p>The erratum only affects Thumb-2 code. Please contact ARM for further details.
- </p>
- <span id="index-Cortex_002dA53-erratum-835769-workaround"></span>
- <span id="index-_002d_002dfix_002dcortex_002da53_002d835769"></span>
- <span id="index-_002d_002dno_002dfix_002dcortex_002da53_002d835769"></span>
- <p>The ‘<samp>--fix-cortex-a53-835769</samp>’ switch enables a link-time workaround for erratum 835769 present on certain early revisions of Cortex-A53 processors. The workaround is disabled by default. It can be enabled by specifying ‘<samp>--fix-cortex-a53-835769</samp>’, or disabled unconditionally by specifying ‘<samp>--no-fix-cortex-a53-835769</samp>’.
- </p>
- <p>Please contact ARM for further details.
- </p>
- <span id="index-_002d_002dmerge_002dexidx_002dentries"></span>
- <span id="index-_002d_002dno_002dmerge_002dexidx_002dentries-1"></span>
- <span id="index-Merging-exidx-entries"></span>
- <p>The ‘<samp>--no-merge-exidx-entries</samp>’ switch disables the merging of adjacent exidx entries in debuginfo.
- </p>
- <span id="index-_002d_002dlong_002dplt"></span>
- <span id="index-32_002dbit-PLT-entries"></span>
- <p>The ‘<samp>--long-plt</samp>’ option enables the use of 16 byte PLT entries
- which support up to 4Gb of code. The default is to use 12 byte PLT
- entries which only support 512Mb of code.
- </p>
- <span id="index-_002d_002dno_002dapply_002ddynamic_002drelocs"></span>
- <span id="index-AArch64-rela-addend"></span>
- <p>The ‘<samp>--no-apply-dynamic-relocs</samp>’ option makes AArch64 linker do not apply
- link-time values for dynamic relocations.
- </p>
- <span id="index-Placement-of-SG-veneers"></span>
- <p>All SG veneers are placed in the special output section <code>.gnu.sgstubs</code>.
- Its start address must be set, either with the command-line option
- ‘<samp>--section-start</samp>’ or in a linker script, to indicate where to place these
- veneers in memory.
- </p>
- <span id="index-_002d_002dcmse_002dimplib"></span>
- <span id="index-Secure-gateway-import-library"></span>
- <p>The ‘<samp>--cmse-implib</samp>’ option requests that the import libraries
- specified by the ‘<samp>--out-implib</samp>’ and ‘<samp>--in-implib</samp>’ options are
- secure gateway import libraries, suitable for linking a non-secure
- executable against secure code as per ARMv8-M Security Extensions.
- </p>
- <span id="index-_002d_002din_002dimplib_003dfile"></span>
- <span id="index-Input-import-library"></span>
- <p>The ‘<samp>--in-implib=file</samp>’ specifies an input import library whose symbols
- must keep the same address in the executable being produced. A warning is
- given if no ‘<samp>--out-implib</samp>’ is given but new symbols have been introduced
- in the executable that should be listed in its import library. Otherwise, if
- ‘<samp>--out-implib</samp>’ is specified, the symbols are added to the output import
- library. A warning is also given if some symbols present in the input import
- library have disappeared from the executable. This option is only effective
- for Secure Gateway import libraries, ie. when ‘<samp>--cmse-implib</samp>’ is
- specified.
- </p>
- <hr>
- <span id="HPPA-ELF32"></span><div class="header">
- <p>
- Next: <a href="#M68K" accesskey="n" rel="next">M68K</a>, Previous: <a href="#ARM" accesskey="p" rel="prev">ARM</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-HPPA-32_002dbit-ELF-Support"></span><h3 class="section">6.4 <code>ld</code> and HPPA 32-bit ELF Support</h3>
- <span id="index-HPPA-multiple-sub_002dspace-stubs"></span>
- <span id="index-_002d_002dmulti_002dsubspace"></span>
- <p>When generating a shared library, <code>ld</code> will by default generate
- import stubs suitable for use with a single sub-space application.
- The ‘<samp>--multi-subspace</samp>’ switch causes <code>ld</code> to generate export
- stubs, and different (larger) import stubs suitable for use with
- multiple sub-spaces.
- </p>
- <span id="index-HPPA-stub-grouping"></span>
- <span id="index-_002d_002dstub_002dgroup_002dsize_003dN-1"></span>
- <p>Long branch stubs and import/export stubs are placed by <code>ld</code> in
- stub sections located between groups of input sections.
- ‘<samp>--stub-group-size</samp>’ specifies the maximum size of a group of input
- sections handled by one stub section. Since branch offsets are signed,
- a stub section may serve two groups of input sections, one group before
- the stub section, and one group after it. However, when using
- conditional branches that require stubs, it may be better (for branch
- prediction) that stub sections only serve one group of input sections.
- A negative value for ‘<samp>N</samp>’ chooses this scheme, ensuring that
- branches to stubs always use a negative offset. Two special values of
- ‘<samp>N</samp>’ are recognized, ‘<samp>1</samp>’ and ‘<samp>-1</samp>’. These both instruct
- <code>ld</code> to automatically size input section groups for the branch types
- detected, with the same behaviour regarding stub placement as other
- positive or negative values of ‘<samp>N</samp>’ respectively.
- </p>
- <p>Note that ‘<samp>--stub-group-size</samp>’ does not split input sections. A
- single input section larger than the group size specified will of course
- create a larger group (of one section). If input sections are too
- large, it may not be possible for a branch to reach its stub.
- </p>
- <hr>
- <span id="M68K"></span><div class="header">
- <p>
- Next: <a href="#MIPS" accesskey="n" rel="next">MIPS</a>, Previous: <a href="#HPPA-ELF32" accesskey="p" rel="prev">HPPA ELF32</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-the-Motorola-68K-family"></span><h3 class="section">6.5 <code>ld</code> and the Motorola 68K family</h3>
- <span id="index-Motorola-68K-GOT-generation"></span>
- <span id="index-_002d_002dgot_003dtype"></span>
- <p>The ‘<samp>--got=<var>type</var></samp>’ option lets you choose the GOT generation scheme.
- The choices are ‘<samp>single</samp>’, ‘<samp>negative</samp>’, ‘<samp>multigot</samp>’ and
- ‘<samp>target</samp>’. When ‘<samp>target</samp>’ is selected the linker chooses
- the default GOT generation scheme for the current target.
- ‘<samp>single</samp>’ tells the linker to generate a single GOT with
- entries only at non-negative offsets.
- ‘<samp>negative</samp>’ instructs the linker to generate a single GOT with
- entries at both negative and positive offsets. Not all environments
- support such GOTs.
- ‘<samp>multigot</samp>’ allows the linker to generate several GOTs in the
- output file. All GOT references from a single input object
- file access the same GOT, but references from different input object
- files might access different GOTs. Not all environments support such GOTs.
- </p>
- <hr>
- <span id="MIPS"></span><div class="header">
- <p>
- Next: <a href="#MMIX" accesskey="n" rel="next">MMIX</a>, Previous: <a href="#M68K" accesskey="p" rel="prev">M68K</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-the-MIPS-family"></span><h3 class="section">6.6 <code>ld</code> and the MIPS family</h3>
- <span id="index-MIPS-microMIPS-instruction-choice-selection"></span>
- <span id="index-_002d_002dinsn32-1"></span>
- <span id="index-_002d_002dno_002dinsn32-1"></span>
- <p>The ‘<samp>--insn32</samp>’ and ‘<samp>--no-insn32</samp>’ options control the choice of
- microMIPS instructions used in code generated by the linker, such as that
- in the PLT or lazy binding stubs, or in relaxation. If ‘<samp>--insn32</samp>’ is
- used, then the linker only uses 32-bit instruction encodings. By default
- or if ‘<samp>--no-insn32</samp>’ is used, all instruction encodings are used,
- including 16-bit ones where possible.
- </p>
- <span id="index-MIPS-branch-relocation-check-control"></span>
- <span id="index-_002d_002dignore_002dbranch_002disa-1"></span>
- <span id="index-_002d_002dno_002dignore_002dbranch_002disa-1"></span>
- <p>The ‘<samp>--ignore-branch-isa</samp>’ and ‘<samp>--no-ignore-branch-isa</samp>’ options
- control branch relocation checks for invalid ISA mode transitions. If
- ‘<samp>--ignore-branch-isa</samp>’ is used, then the linker accepts any branch
- relocations and any ISA mode transition required is lost in relocation
- calculation, except for some cases of <code>BAL</code> instructions which meet
- relaxation conditions and are converted to equivalent <code>JALX</code>
- instructions as the associated relocation is calculated. By default
- or if ‘<samp>--no-ignore-branch-isa</samp>’ is used a check is made causing
- the loss of an ISA mode transition to produce an error.
- </p>
- <hr>
- <span id="MMIX"></span><div class="header">
- <p>
- Next: <a href="#MSP430" accesskey="n" rel="next">MSP430</a>, Previous: <a href="#MIPS" accesskey="p" rel="prev">MIPS</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-MMIX"></span><h3 class="section">6.7 <code>ld</code> and MMIX</h3>
- <p>For MMIX, there is a choice of generating <code>ELF</code> object files or
- <code>mmo</code> object files when linking. The simulator <code>mmix</code>
- understands the <code>mmo</code> format. The binutils <code>objcopy</code> utility
- can translate between the two formats.
- </p>
- <p>There is one special section, the ‘<samp>.MMIX.reg_contents</samp>’ section.
- Contents in this section is assumed to correspond to that of global
- registers, and symbols referring to it are translated to special symbols,
- equal to registers. In a final link, the start address of the
- ‘<samp>.MMIX.reg_contents</samp>’ section corresponds to the first allocated
- global register multiplied by 8. Register <code>$255</code> is not included in
- this section; it is always set to the program entry, which is at the
- symbol <code>Main</code> for <code>mmo</code> files.
- </p>
- <p>Global symbols with the prefix <code>__.MMIX.start.</code>, for example
- <code>__.MMIX.start..text</code> and <code>__.MMIX.start..data</code> are special.
- The default linker script uses these to set the default start address
- of a section.
- </p>
- <p>Initial and trailing multiples of zero-valued 32-bit words in a section,
- are left out from an mmo file.
- </p>
- <hr>
- <span id="MSP430"></span><div class="header">
- <p>
- Next: <a href="#NDS32" accesskey="n" rel="next">NDS32</a>, Previous: <a href="#MMIX" accesskey="p" rel="prev">MMIX</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-MSP430"></span><h3 class="section">6.8 <code>ld</code> and MSP430</h3>
- <p>For the MSP430 it is possible to select the MPU architecture. The flag ‘<samp>-m [mpu type]</samp>’
- will select an appropriate linker script for selected MPU type. (To get a list of known MPUs
- just pass ‘<samp>-m help</samp>’ option to the linker).
- </p>
- <span id="index-MSP430-extra-sections"></span>
- <p>The linker will recognize some extra sections which are MSP430 specific:
- </p>
- <dl compact="compact">
- <dt><code>‘<samp>.vectors</samp>’</code></dt>
- <dd><p>Defines a portion of ROM where interrupt vectors located.
- </p>
- </dd>
- <dt><code>‘<samp>.bootloader</samp>’</code></dt>
- <dd><p>Defines the bootloader portion of the ROM (if applicable). Any code
- in this section will be uploaded to the MPU.
- </p>
- </dd>
- <dt><code>‘<samp>.infomem</samp>’</code></dt>
- <dd><p>Defines an information memory section (if applicable). Any code in
- this section will be uploaded to the MPU.
- </p>
- </dd>
- <dt><code>‘<samp>.infomemnobits</samp>’</code></dt>
- <dd><p>This is the same as the ‘<samp>.infomem</samp>’ section except that any code
- in this section will not be uploaded to the MPU.
- </p>
- </dd>
- <dt><code>‘<samp>.noinit</samp>’</code></dt>
- <dd><p>Denotes a portion of RAM located above ‘<samp>.bss</samp>’ section.
- </p>
- <p>The last two sections are used by gcc.
- </p></dd>
- </dl>
- <dl compact="compact">
- <dd><span id="index-MSP430-Options"></span>
- <span id="index-_002d_002dcode_002dregion"></span>
- </dd>
- <dt><samp>--code-region=[either,lower,upper,none]</samp></dt>
- <dd><p>This will transform .text* sections to [either,lower,upper].text* sections. The
- argument passed to GCC for -mcode-region is propagated to the linker
- using this option.
- </p>
- <span id="index-_002d_002ddata_002dregion"></span>
- </dd>
- <dt><samp>--data-region=[either,lower,upper,none]</samp></dt>
- <dd><p>This will transform .data*, .bss* and .rodata* sections to
- [either,lower,upper].[data,bss,rodata]* sections. The argument passed to GCC
- for -mdata-region is propagated to the linker using this option.
- </p>
- <span id="index-_002d_002ddisable_002dsec_002dtransformation"></span>
- </dd>
- <dt><samp>--disable-sec-transformation</samp></dt>
- <dd><p>Prevent the transformation of sections as specified by the <code>--code-region</code>
- and <code>--data-region</code> options.
- This is useful if you are compiling and linking using a single call to the GCC
- wrapper, and want to compile the source files using -m[code,data]-region but
- not transform the sections for prebuilt libraries and objects.
- </p></dd>
- </dl>
- <hr>
- <span id="NDS32"></span><div class="header">
- <p>
- Next: <a href="#Nios-II" accesskey="n" rel="next">Nios II</a>, Previous: <a href="#MSP430" accesskey="p" rel="prev">MSP430</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-NDS32"></span><h3 class="section">6.9 <code>ld</code> and NDS32</h3>
- <span id="index-relaxing-on-NDS32"></span>
- <p>For NDS32, there are some options to select relaxation behavior. The linker
- relaxes objects according to these options.
- </p>
- <dl compact="compact">
- <dt><code>‘<samp>--m[no-]fp-as-gp</samp>’</code></dt>
- <dd><p>Disable/enable fp-as-gp relaxation.
- </p>
- </dd>
- <dt><code>‘<samp>--mexport-symbols=FILE</samp>’</code></dt>
- <dd><p>Exporting symbols and their address into FILE as linker script.
- </p>
- </dd>
- <dt><code>‘<samp>--m[no-]ex9</samp>’</code></dt>
- <dd><p>Disable/enable link-time EX9 relaxation.
- </p>
- </dd>
- <dt><code>‘<samp>--mexport-ex9=FILE</samp>’</code></dt>
- <dd><p>Export the EX9 table after linking.
- </p>
- </dd>
- <dt><code>‘<samp>--mimport-ex9=FILE</samp>’</code></dt>
- <dd><p>Import the Ex9 table for EX9 relaxation.
- </p>
- </dd>
- <dt><code>‘<samp>--mupdate-ex9</samp>’</code></dt>
- <dd><p>Update the existing EX9 table.
- </p>
- </dd>
- <dt><code>‘<samp>--mex9-limit=NUM</samp>’</code></dt>
- <dd><p>Maximum number of entries in the ex9 table.
- </p>
- </dd>
- <dt><code>‘<samp>--mex9-loop-aware</samp>’</code></dt>
- <dd><p>Avoid generating the EX9 instruction inside the loop.
- </p>
- </dd>
- <dt><code>‘<samp>--m[no-]ifc</samp>’</code></dt>
- <dd><p>Disable/enable the link-time IFC optimization.
- </p>
- </dd>
- <dt><code>‘<samp>--mifc-loop-aware</samp>’</code></dt>
- <dd><p>Avoid generating the IFC instruction inside the loop.
- </p></dd>
- </dl>
- <hr>
- <span id="Nios-II"></span><div class="header">
- <p>
- Next: <a href="#PowerPC-ELF32" accesskey="n" rel="next">PowerPC ELF32</a>, Previous: <a href="#NDS32" accesskey="p" rel="prev">NDS32</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-the-Altera-Nios-II"></span><h3 class="section">6.10 <code>ld</code> and the Altera Nios II</h3>
- <span id="index-Nios-II-call-relaxation"></span>
- <span id="index-_002d_002drelax-on-Nios-II"></span>
- <p>Call and immediate jump instructions on Nios II processors are limited to
- transferring control to addresses in the same 256MB memory segment,
- which may result in <code>ld</code> giving
- ‘<samp>relocation truncated to fit</samp>’ errors with very large programs.
- The command-line option <samp>--relax</samp> enables the generation of
- trampolines that can access the entire 32-bit address space for calls
- outside the normal <code>call</code> and <code>jmpi</code> address range. These
- trampolines are inserted at section boundaries, so may not themselves
- be reachable if an input section and its associated call trampolines are
- larger than 256MB.
- </p>
- <p>The <samp>--relax</samp> option is enabled by default unless <samp>-r</samp>
- is also specified. You can disable trampoline generation by using the
- <samp>--no-relax</samp> linker option. You can also disable this optimization
- locally by using the ‘<samp>set .noat</samp>’ directive in assembly-language
- source files, as the linker-inserted trampolines use the <code>at</code>
- register as a temporary.
- </p>
- <p>Note that the linker <samp>--relax</samp> option is independent of assembler
- relaxation options, and that using the GNU assembler’s <samp>-relax-all</samp>
- option interferes with the linker’s more selective call instruction relaxation.
- </p>
- <hr>
- <span id="PowerPC-ELF32"></span><div class="header">
- <p>
- Next: <a href="#PowerPC64-ELF64" accesskey="n" rel="next">PowerPC64 ELF64</a>, Previous: <a href="#Nios-II" accesskey="p" rel="prev">Nios II</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-PowerPC-32_002dbit-ELF-Support"></span><h3 class="section">6.11 <code>ld</code> and PowerPC 32-bit ELF Support</h3>
- <span id="index-PowerPC-long-branches"></span>
- <span id="index-_002d_002drelax-on-PowerPC"></span>
- <p>Branches on PowerPC processors are limited to a signed 26-bit
- displacement, which may result in <code>ld</code> giving
- ‘<samp>relocation truncated to fit</samp>’ errors with very large programs.
- ‘<samp>--relax</samp>’ enables the generation of trampolines that can access
- the entire 32-bit address space. These trampolines are inserted at
- section boundaries, so may not themselves be reachable if an input
- section exceeds 33M in size. You may combine ‘<samp>-r</samp>’ and
- ‘<samp>--relax</samp>’ to add trampolines in a partial link. In that case
- both branches to undefined symbols and inter-section branches are also
- considered potentially out of range, and trampolines inserted.
- </p>
- <span id="index-PowerPC-ELF32-options"></span>
- <dl compact="compact">
- <dd><span id="index-PowerPC-PLT"></span>
- <span id="index-_002d_002dbss_002dplt"></span>
- </dd>
- <dt><samp>--bss-plt</samp></dt>
- <dd><p>Current PowerPC GCC accepts a ‘<samp>-msecure-plt</samp>’ option that
- generates code capable of using a newer PLT and GOT layout that has
- the security advantage of no executable section ever needing to be
- writable and no writable section ever being executable. PowerPC
- <code>ld</code> will generate this layout, including stubs to access the
- PLT, if all input files (including startup and static libraries) were
- compiled with ‘<samp>-msecure-plt</samp>’. ‘<samp>--bss-plt</samp>’ forces the old
- BSS PLT (and GOT layout) which can give slightly better performance.
- </p>
- <span id="index-_002d_002dsecure_002dplt"></span>
- </dd>
- <dt><samp>--secure-plt</samp></dt>
- <dd><p><code>ld</code> will use the new PLT and GOT layout if it is linking new
- ‘<samp>-fpic</samp>’ or ‘<samp>-fPIC</samp>’ code, but does not do so automatically
- when linking non-PIC code. This option requests the new PLT and GOT
- layout. A warning will be given if some object file requires the old
- style BSS PLT.
- </p>
- <span id="index-PowerPC-GOT"></span>
- <span id="index-_002d_002dsdata_002dgot"></span>
- </dd>
- <dt><samp>--sdata-got</samp></dt>
- <dd><p>The new secure PLT and GOT are placed differently relative to other
- sections compared to older BSS PLT and GOT placement. The location of
- <code>.plt</code> must change because the new secure PLT is an initialized
- section while the old PLT is uninitialized. The reason for the
- <code>.got</code> change is more subtle: The new placement allows
- <code>.got</code> to be read-only in applications linked with
- ‘<samp>-z relro -z now</samp>’. However, this placement means that
- <code>.sdata</code> cannot always be used in shared libraries, because the
- PowerPC ABI accesses <code>.sdata</code> in shared libraries from the GOT
- pointer. ‘<samp>--sdata-got</samp>’ forces the old GOT placement. PowerPC
- GCC doesn’t use <code>.sdata</code> in shared libraries, so this option is
- really only useful for other compilers that may do so.
- </p>
- <span id="index-PowerPC-stub-symbols"></span>
- <span id="index-_002d_002demit_002dstub_002dsyms"></span>
- </dd>
- <dt><samp>--emit-stub-syms</samp></dt>
- <dd><p>This option causes <code>ld</code> to label linker stubs with a local
- symbol that encodes the stub type and destination.
- </p>
- <span id="index-PowerPC-TLS-optimization"></span>
- <span id="index-_002d_002dno_002dtls_002doptimize"></span>
- </dd>
- <dt><samp>--no-tls-optimize</samp></dt>
- <dd><p>PowerPC <code>ld</code> normally performs some optimization of code
- sequences used to access Thread-Local Storage. Use this option to
- disable the optimization.
- </p></dd>
- </dl>
- <hr>
- <span id="PowerPC64-ELF64"></span><div class="header">
- <p>
- Next: <a href="#S_002f390-ELF" accesskey="n" rel="next">S/390 ELF</a>, Previous: <a href="#PowerPC-ELF32" accesskey="p" rel="prev">PowerPC ELF32</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-PowerPC64-64_002dbit-ELF-Support"></span><h3 class="section">6.12 <code>ld</code> and PowerPC64 64-bit ELF Support</h3>
- <span id="index-PowerPC64-ELF64-options"></span>
- <dl compact="compact">
- <dd><span id="index-PowerPC64-stub-grouping"></span>
- <span id="index-_002d_002dstub_002dgroup_002dsize"></span>
- </dd>
- <dt><samp>--stub-group-size</samp></dt>
- <dd><p>Long branch stubs, PLT call stubs and TOC adjusting stubs are placed
- by <code>ld</code> in stub sections located between groups of input sections.
- ‘<samp>--stub-group-size</samp>’ specifies the maximum size of a group of input
- sections handled by one stub section. Since branch offsets are signed,
- a stub section may serve two groups of input sections, one group before
- the stub section, and one group after it. However, when using
- conditional branches that require stubs, it may be better (for branch
- prediction) that stub sections only serve one group of input sections.
- A negative value for ‘<samp>N</samp>’ chooses this scheme, ensuring that
- branches to stubs always use a negative offset. Two special values of
- ‘<samp>N</samp>’ are recognized, ‘<samp>1</samp>’ and ‘<samp>-1</samp>’. These both instruct
- <code>ld</code> to automatically size input section groups for the branch types
- detected, with the same behaviour regarding stub placement as other
- positive or negative values of ‘<samp>N</samp>’ respectively.
- </p>
- <p>Note that ‘<samp>--stub-group-size</samp>’ does not split input sections. A
- single input section larger than the group size specified will of course
- create a larger group (of one section). If input sections are too
- large, it may not be possible for a branch to reach its stub.
- </p>
- <span id="index-PowerPC64-stub-symbols"></span>
- <span id="index-_002d_002demit_002dstub_002dsyms-1"></span>
- </dd>
- <dt><samp>--emit-stub-syms</samp></dt>
- <dd><p>This option causes <code>ld</code> to label linker stubs with a local
- symbol that encodes the stub type and destination.
- </p>
- <span id="index-PowerPC64-dot-symbols"></span>
- <span id="index-_002d_002ddotsyms"></span>
- <span id="index-_002d_002dno_002ddotsyms"></span>
- </dd>
- <dt><samp>--dotsyms</samp></dt>
- <dt><samp>--no-dotsyms</samp></dt>
- <dd><p>These two options control how <code>ld</code> interprets version patterns
- in a version script. Older PowerPC64 compilers emitted both a
- function descriptor symbol with the same name as the function, and a
- code entry symbol with the name prefixed by a dot (‘<samp>.</samp>’). To
- properly version a function ‘<samp>foo</samp>’, the version script thus needs
- to control both ‘<samp>foo</samp>’ and ‘<samp>.foo</samp>’. The option
- ‘<samp>--dotsyms</samp>’, on by default, automatically adds the required
- dot-prefixed patterns. Use ‘<samp>--no-dotsyms</samp>’ to disable this
- feature.
- </p>
- <span id="index-PowerPC64-register-save_002frestore-functions"></span>
- <span id="index-_002d_002dsave_002drestore_002dfuncs"></span>
- <span id="index-_002d_002dno_002dsave_002drestore_002dfuncs"></span>
- </dd>
- <dt><samp>--save-restore-funcs</samp></dt>
- <dt><samp>--no-save-restore-funcs</samp></dt>
- <dd><p>These two options control whether PowerPC64 <code>ld</code> automatically
- provides out-of-line register save and restore functions used by
- ‘<samp>-Os</samp>’ code. The default is to provide any such referenced
- function for a normal final link, and to not do so for a relocatable
- link.
- </p>
- <span id="index-PowerPC64-TLS-optimization"></span>
- <span id="index-_002d_002dno_002dtls_002doptimize-1"></span>
- </dd>
- <dt><samp>--no-tls-optimize</samp></dt>
- <dd><p>PowerPC64 <code>ld</code> normally performs some optimization of code
- sequences used to access Thread-Local Storage. Use this option to
- disable the optimization.
- </p>
- <span id="index-PowerPC64-_005f_005ftls_005fget_005faddr-optimization"></span>
- <span id="index-_002d_002dtls_002dget_002daddr_002doptimize"></span>
- <span id="index-_002d_002dno_002dtls_002dget_002daddr_002doptimize"></span>
- <span id="index-_002d_002dtls_002dget_002daddr_002dregsave"></span>
- <span id="index-_002d_002dno_002dtls_002dget_002daddr_002dregsave"></span>
- </dd>
- <dt><samp>--tls-get-addr-optimize</samp></dt>
- <dt><samp>--no-tls-get-addr-optimize</samp></dt>
- <dd><p>These options control how PowerPC64 <code>ld</code> uses a special
- stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support
- an optimization that allows the second and subsequent calls to
- <code>__tls_get_addr</code> for a given symbol to be resolved by the special
- stub without calling in to glibc. By default the linker enables
- generation of the stub when glibc advertises the availability of
- __tls_get_addr_opt.
- Using <samp>--tls-get-addr-optimize</samp> with an older glibc won’t do
- much besides slow down your applications, but may be useful if linking
- an application against an older glibc with the expectation that it
- will normally be used on systems having a newer glibc.
- <samp>--tls-get-addr-regsave</samp> forces generation of a stub that saves
- and restores volatile registers around the call into glibc. Normally,
- this is done when the linker detects a call to __tls_get_addr_desc.
- Such calls then go via the register saving stub to __tls_get_addr_opt.
- <samp>--no-tls-get-addr-regsave</samp> disables generation of the
- register saves.
- </p>
- <span id="index-PowerPC64-OPD-optimization"></span>
- <span id="index-_002d_002dno_002dopd_002doptimize"></span>
- </dd>
- <dt><samp>--no-opd-optimize</samp></dt>
- <dd><p>PowerPC64 <code>ld</code> normally removes <code>.opd</code> section entries
- corresponding to deleted link-once functions, or functions removed by
- the action of ‘<samp>--gc-sections</samp>’ or linker script <code>/DISCARD/</code>.
- Use this option to disable <code>.opd</code> optimization.
- </p>
- <span id="index-PowerPC64-OPD-spacing"></span>
- <span id="index-_002d_002dnon_002doverlapping_002dopd"></span>
- </dd>
- <dt><samp>--non-overlapping-opd</samp></dt>
- <dd><p>Some PowerPC64 compilers have an option to generate compressed
- <code>.opd</code> entries spaced 16 bytes apart, overlapping the third word,
- the static chain pointer (unused in C) with the first word of the next
- entry. This option expands such entries to the full 24 bytes.
- </p>
- <span id="index-PowerPC64-TOC-optimization"></span>
- <span id="index-_002d_002dno_002dtoc_002doptimize"></span>
- </dd>
- <dt><samp>--no-toc-optimize</samp></dt>
- <dd><p>PowerPC64 <code>ld</code> normally removes unused <code>.toc</code> section
- entries. Such entries are detected by examining relocations that
- reference the TOC in code sections. A reloc in a deleted code section
- marks a TOC word as unneeded, while a reloc in a kept code section
- marks a TOC word as needed. Since the TOC may reference itself, TOC
- relocs are also examined. TOC words marked as both needed and
- unneeded will of course be kept. TOC words without any referencing
- reloc are assumed to be part of a multi-word entry, and are kept or
- discarded as per the nearest marked preceding word. This works
- reliably for compiler generated code, but may be incorrect if assembly
- code is used to insert TOC entries. Use this option to disable the
- optimization.
- </p>
- <span id="index-PowerPC64-inline-PLT-call-optimization"></span>
- <span id="index-_002d_002dno_002dinline_002doptimize"></span>
- </dd>
- <dt><samp>--no-inline-optimize</samp></dt>
- <dd><p>PowerPC64 <code>ld</code> normally replaces inline PLT call sequences
- marked with <code>R_PPC64_PLTSEQ</code>, <code>R_PPC64_PLTCALL</code>,
- <code>R_PPC64_PLT16_HA</code> and <code>R_PPC64_PLT16_LO_DS</code> relocations by
- a number of <code>nop</code>s and a direct call when the function is defined
- locally and can’t be overridden by some other definition. This option
- disables that optimization.
- </p>
- <span id="index-PowerPC64-multi_002dTOC"></span>
- <span id="index-_002d_002dno_002dmulti_002dtoc"></span>
- </dd>
- <dt><samp>--no-multi-toc</samp></dt>
- <dd><p>If given any toc option besides <code>-mcmodel=medium</code> or
- <code>-mcmodel=large</code>, PowerPC64 GCC generates code for a TOC model
- where TOC
- entries are accessed with a 16-bit offset from r2. This limits the
- total TOC size to 64K. PowerPC64 <code>ld</code> extends this limit by
- grouping code sections such that each group uses less than 64K for its
- TOC entries, then inserts r2 adjusting stubs between inter-group
- calls. <code>ld</code> does not split apart input sections, so cannot
- help if a single input file has a <code>.toc</code> section that exceeds
- 64K, most likely from linking multiple files with <code>ld -r</code>.
- Use this option to turn off this feature.
- </p>
- <span id="index-PowerPC64-TOC-sorting"></span>
- <span id="index-_002d_002dno_002dtoc_002dsort"></span>
- </dd>
- <dt><samp>--no-toc-sort</samp></dt>
- <dd><p>By default, <code>ld</code> sorts TOC sections so that those whose file
- happens to have a section called <code>.init</code> or <code>.fini</code> are
- placed first, followed by TOC sections referenced by code generated
- with PowerPC64 gcc’s <code>-mcmodel=small</code>, and lastly TOC sections
- referenced only by code generated with PowerPC64 gcc’s
- <code>-mcmodel=medium</code> or <code>-mcmodel=large</code> options. Doing this
- results in better TOC grouping for multi-TOC. Use this option to turn
- off this feature.
- </p>
- <span id="index-PowerPC64-PLT-stub-alignment"></span>
- <span id="index-_002d_002dplt_002dalign"></span>
- <span id="index-_002d_002dno_002dplt_002dalign"></span>
- </dd>
- <dt><samp>--plt-align</samp></dt>
- <dt><samp>--no-plt-align</samp></dt>
- <dd><p>Use these options to control whether individual PLT call stubs are
- aligned to a 32-byte boundary, or to the specified power of two
- boundary when using <code>--plt-align=</code>. A negative value may be
- specified to pad PLT call stubs so that they do not cross the
- specified power of two boundary (or the minimum number of boundaries
- if a PLT stub is so large that it must cross a boundary). By default
- PLT call stubs are aligned to 32-byte boundaries.
- </p>
- <span id="index-PowerPC64-PLT-call-stub-static-chain"></span>
- <span id="index-_002d_002dplt_002dstatic_002dchain"></span>
- <span id="index-_002d_002dno_002dplt_002dstatic_002dchain"></span>
- </dd>
- <dt><samp>--plt-static-chain</samp></dt>
- <dt><samp>--no-plt-static-chain</samp></dt>
- <dd><p>Use these options to control whether PLT call stubs load the static
- chain pointer (r11). <code>ld</code> defaults to not loading the static
- chain since there is never any need to do so on a PLT call.
- </p>
- <span id="index-PowerPC64-PLT-call-stub-thread-safety"></span>
- <span id="index-_002d_002dplt_002dthread_002dsafe"></span>
- <span id="index-_002d_002dno_002dplt_002dthread_002dsafe"></span>
- </dd>
- <dt><samp>--plt-thread-safe</samp></dt>
- <dt><samp>--no-plt-thread-safe</samp></dt>
- <dd><p>With power7’s weakly ordered memory model, it is possible when using
- lazy binding for ld.so to update a plt entry in one thread and have
- another thread see the individual plt entry words update in the wrong
- order, despite ld.so carefully writing in the correct order and using
- memory write barriers. To avoid this we need some sort of read
- barrier in the call stub, or use LD_BIND_NOW=1. By default, <code>ld</code>
- looks for calls to commonly used functions that create threads, and if
- seen, adds the necessary barriers. Use these options to change the
- default behaviour.
- </p>
- <span id="index-PowerPC64-ELFv2-PLT-localentry-optimization"></span>
- <span id="index-_002d_002dplt_002dlocalentry"></span>
- <span id="index-_002d_002dno_002dplt_002dlocalentry"></span>
- </dd>
- <dt><samp>--plt-localentry</samp></dt>
- <dt><samp>--no-localentry</samp></dt>
- <dd><p>ELFv2 functions with localentry:0 are those with a single entry point,
- ie. global entry == local entry, and that have no requirement on r2
- (the TOC/GOT pointer) or r12, and guarantee r2 is unchanged on return.
- Such an external function can be called via the PLT without saving r2
- or restoring it on return, avoiding a common load-hit-store for small
- functions. The optimization is attractive, with up to 40% reduction
- in execution time for a small function, but can result in symbol
- interposition failures. Also, minor changes in a shared library,
- including system libraries, can cause a function that was localentry:0
- to become localentry:8. This will result in a dynamic loader
- complaint and failure to run. The option is experimental, use with
- care. <samp>--no-plt-localentry</samp> is the default.
- </p>
- <span id="index-PowerPC64-Power10-stubs"></span>
- <span id="index-_002d_002dpower10_002dstubs"></span>
- <span id="index-_002d_002dno_002dpower10_002dstubs"></span>
- </dd>
- <dt><samp>--power10-stubs</samp></dt>
- <dt><samp>--no-power10-stubs</samp></dt>
- <dd><p>When PowerPC64 <code>ld</code> links input object files containing
- relocations used on power10 prefixed instructions it normally creates
- linkage stubs (PLT call and long branch) using power10 instructions
- for <code>@notoc</code> PLT calls where <code>r2</code> is not known. The
- power10 notoc stubs are smaller and faster, so are preferred for
- power10. <samp>--power10-stubs</samp> and <samp>--no-power10-stubs</samp>
- allow you to override the linker’s selection of stub instructions.
- <samp>--power10-stubs=auto</samp> allows the user to select the default
- auto mode.
- </p></dd>
- </dl>
- <hr>
- <span id="S_002f390-ELF"></span><div class="header">
- <p>
- Next: <a href="#SPU-ELF" accesskey="n" rel="next">SPU ELF</a>, Previous: <a href="#PowerPC64-ELF64" accesskey="p" rel="prev">PowerPC64 ELF64</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-S_002f390-ELF-Support"></span><h3 class="section">6.13 <code>ld</code> and S/390 ELF Support</h3>
- <span id="index-S_002f390-ELF-options"></span>
- <dl compact="compact">
- <dd>
- <span id="index-S_002f390"></span>
- <span id="index-_002d_002ds390_002dpgste"></span>
- </dd>
- <dt><samp>--s390-pgste</samp></dt>
- <dd><p>This option marks the result file with a <code>PT_S390_PGSTE</code>
- segment. The Linux kernel is supposed to allocate 4k page tables for
- binaries marked that way.
- </p></dd>
- </dl>
- <hr>
- <span id="SPU-ELF"></span><div class="header">
- <p>
- Next: <a href="#TI-COFF" accesskey="n" rel="next">TI COFF</a>, Previous: <a href="#S_002f390-ELF" accesskey="p" rel="prev">S/390 ELF</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-SPU-ELF-Support"></span><h3 class="section">6.14 <code>ld</code> and SPU ELF Support</h3>
- <span id="index-SPU-ELF-options"></span>
- <dl compact="compact">
- <dd>
- <span id="index-SPU-plugins"></span>
- <span id="index-_002d_002dplugin"></span>
- </dd>
- <dt><samp>--plugin</samp></dt>
- <dd><p>This option marks an executable as a PIC plugin module.
- </p>
- <span id="index-SPU-overlays"></span>
- <span id="index-_002d_002dno_002doverlays"></span>
- </dd>
- <dt><samp>--no-overlays</samp></dt>
- <dd><p>Normally, <code>ld</code> recognizes calls to functions within overlay
- regions, and redirects such calls to an overlay manager via a stub.
- <code>ld</code> also provides a built-in overlay manager. This option
- turns off all this special overlay handling.
- </p>
- <span id="index-SPU-overlay-stub-symbols"></span>
- <span id="index-_002d_002demit_002dstub_002dsyms-2"></span>
- </dd>
- <dt><samp>--emit-stub-syms</samp></dt>
- <dd><p>This option causes <code>ld</code> to label overlay stubs with a local
- symbol that encodes the stub type and destination.
- </p>
- <span id="index-SPU-extra-overlay-stubs"></span>
- <span id="index-_002d_002dextra_002doverlay_002dstubs"></span>
- </dd>
- <dt><samp>--extra-overlay-stubs</samp></dt>
- <dd><p>This option causes <code>ld</code> to add overlay call stubs on all
- function calls out of overlay regions. Normally stubs are not added
- on calls to non-overlay regions.
- </p>
- <span id="index-SPU-local-store-size"></span>
- <span id="index-_002d_002dlocal_002dstore_003dlo_003ahi"></span>
- </dd>
- <dt><samp>--local-store=lo:hi</samp></dt>
- <dd><p><code>ld</code> usually checks that a final executable for SPU fits in
- the address range 0 to 256k. This option may be used to change the
- range. Disable the check entirely with <samp>--local-store=0:0</samp>.
- </p>
- <span id="index-SPU"></span>
- <span id="index-_002d_002dstack_002danalysis"></span>
- </dd>
- <dt><samp>--stack-analysis</samp></dt>
- <dd><p>SPU local store space is limited. Over-allocation of stack space
- unnecessarily limits space available for code and data, while
- under-allocation results in runtime failures. If given this option,
- <code>ld</code> will provide an estimate of maximum stack usage.
- <code>ld</code> does this by examining symbols in code sections to
- determine the extents of functions, and looking at function prologues
- for stack adjusting instructions. A call-graph is created by looking
- for relocations on branch instructions. The graph is then searched
- for the maximum stack usage path. Note that this analysis does not
- find calls made via function pointers, and does not handle recursion
- and other cycles in the call graph. Stack usage may be
- under-estimated if your code makes such calls. Also, stack usage for
- dynamic allocation, e.g. alloca, will not be detected. If a link map
- is requested, detailed information about each function’s stack usage
- and calls will be given.
- </p>
- <span id="index-SPU-1"></span>
- <span id="index-_002d_002demit_002dstack_002dsyms"></span>
- </dd>
- <dt><samp>--emit-stack-syms</samp></dt>
- <dd><p>This option, if given along with <samp>--stack-analysis</samp> will result
- in <code>ld</code> emitting stack sizing symbols for each function.
- These take the form <code>__stack_<function_name></code> for global
- functions, and <code>__stack_<number>_<function_name></code> for static
- functions. <code><number></code> is the section id in hex. The value of
- such symbols is the stack requirement for the corresponding function.
- The symbol size will be zero, type <code>STT_NOTYPE</code>, binding
- <code>STB_LOCAL</code>, and section <code>SHN_ABS</code>.
- </p></dd>
- </dl>
- <hr>
- <span id="TI-COFF"></span><div class="header">
- <p>
- Next: <a href="#WIN32" accesskey="n" rel="next">WIN32</a>, Previous: <a href="#SPU-ELF" accesskey="p" rel="prev">SPU ELF</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld_0027s-Support-for-Various-TI-COFF-Versions"></span><h3 class="section">6.15 <code>ld</code>’s Support for Various TI COFF Versions</h3>
- <span id="index-TI-COFF-versions"></span>
- <span id="index-_002d_002dformat_003dversion"></span>
- <p>The ‘<samp>--format</samp>’ switch allows selection of one of the various
- TI COFF versions. The latest of this writing is 2; versions 0 and 1 are
- also supported. The TI COFF versions also vary in header byte-order
- format; <code>ld</code> will read any version or byte order, but the output
- header format depends on the default specified by the specific target.
- </p>
- <hr>
- <span id="WIN32"></span><div class="header">
- <p>
- Next: <a href="#Xtensa" accesskey="n" rel="next">Xtensa</a>, Previous: <a href="#TI-COFF" accesskey="p" rel="prev">TI COFF</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-WIN32-_0028cygwin_002fmingw_0029"></span><h3 class="section">6.16 <code>ld</code> and WIN32 (cygwin/mingw)</h3>
- <p>This section describes some of the win32 specific <code>ld</code> issues.
- See <a href="#Options">Command-line Options</a> for detailed description of the
- command-line options mentioned here.
- </p>
- <dl compact="compact">
- <dd><span id="index-import-libraries"></span>
- </dd>
- <dt><em>import libraries</em></dt>
- <dd><p>The standard Windows linker creates and uses so-called import
- libraries, which contains information for linking to dll’s. They are
- regular static archives and are handled as any other static
- archive. The cygwin and mingw ports of <code>ld</code> have specific
- support for creating such libraries provided with the
- ‘<samp>--out-implib</samp>’ command-line option.
- </p>
- </dd>
- <dt><em>Resource only DLLs</em></dt>
- <dd><p>It is possible to create a DLL that only contains resources, ie just a
- ‘<samp>.rsrc</samp>’ section, but in order to do so a custom linker script
- must be used. This is because the built-in default linker scripts
- will always create ‘<samp>.text</samp>’ and ‘<samp>.idata</samp>’ sections, even if
- there is no input to go into them.
- </p>
- <p>The script should look like this, although the <code>OUTPUT_FORMAT</code>
- should be changed to match the desired format.
- </p>
- <div class="example">
- <pre class="example">OUTPUT_FORMAT(pei-i386)
- SECTIONS
- {
- . = SIZEOF_HEADERS;
- . = ALIGN(__section_alignment__);
- .rsrc __image_base__ + __section_alignment__ : ALIGN(4)
- {
- KEEP (*(.rsrc))
- KEEP (*(.rsrc$*))
- }
- /DISCARD/ : { *(*) }
- }
- </pre></div>
- <p>With this script saved to a file called, eg <samp>rsrc.ld</samp>, a command
- line like this can be used to create the resource only DLL
- <samp>rsrc.dll</samp> from an input file called <samp>rsrc.o</samp>:
- </p>
- <div class="example">
- <pre class="example">ld -dll --subsystem windows -e 0 -s rsrc.o -o rsrc.dll -T rsrc.ld
- </pre></div>
- </dd>
- <dt><em>exporting DLL symbols</em></dt>
- <dd><span id="index-exporting-DLL-symbols"></span>
- <p>The cygwin/mingw <code>ld</code> has several ways to export symbols for dll’s.
- </p>
- <dl compact="compact">
- <dt><em>using auto-export functionality</em></dt>
- <dd><span id="index-using-auto_002dexport-functionality"></span>
- <p>By default <code>ld</code> exports symbols with the auto-export functionality,
- which is controlled by the following command-line options:
- </p>
- <ul>
- <li> –export-all-symbols [This is the default]
- </li><li> –exclude-symbols
- </li><li> –exclude-libs
- </li><li> –exclude-modules-for-implib
- </li><li> –version-script
- </li></ul>
- <p>When auto-export is in operation, <code>ld</code> will export all the non-local
- (global and common) symbols it finds in a DLL, with the exception of a few
- symbols known to belong to the system’s runtime and libraries. As it will
- often not be desirable to export all of a DLL’s symbols, which may include
- private functions that are not part of any public interface, the command-line
- options listed above may be used to filter symbols out from the list for
- exporting. The ‘<samp>--output-def</samp>’ option can be used in order to see the
- final list of exported symbols with all exclusions taken into effect.
- </p>
- <p>If ‘<samp>--export-all-symbols</samp>’ is not given explicitly on the
- command line, then the default auto-export behavior will be <em>disabled</em>
- if either of the following are true:
- </p>
- <ul>
- <li> A DEF file is used.
- </li><li> Any symbol in any object file was marked with the __declspec(dllexport) attribute.
- </li></ul>
- </dd>
- <dt><em>using a DEF file</em></dt>
- <dd><span id="index-using-a-DEF-file"></span>
- <p>Another way of exporting symbols is using a DEF file. A DEF file is
- an ASCII file containing definitions of symbols which should be
- exported when a dll is created. Usually it is named ‘<samp><dll
- name>.def</samp>’ and is added as any other object file to the linker’s
- command line. The file’s name must end in ‘<samp>.def</samp>’ or ‘<samp>.DEF</samp>’.
- </p>
- <div class="example">
- <pre class="example">gcc -o <output> <objectfiles> <dll name>.def
- </pre></div>
- <p>Using a DEF file turns off the normal auto-export behavior, unless the
- ‘<samp>--export-all-symbols</samp>’ option is also used.
- </p>
- <p>Here is an example of a DEF file for a shared library called ‘<samp>xyz.dll</samp>’:
- </p>
- <div class="example">
- <pre class="example">LIBRARY "xyz.dll" BASE=0x20000000
- EXPORTS
- foo
- bar
- _bar = bar
- another_foo = abc.dll.afoo
- var1 DATA
- doo = foo == foo2
- eoo DATA == var1
- </pre></div>
- <p>This example defines a DLL with a non-default base address and seven
- symbols in the export table. The third exported symbol <code>_bar</code> is an
- alias for the second. The fourth symbol, <code>another_foo</code> is resolved
- by "forwarding" to another module and treating it as an alias for
- <code>afoo</code> exported from the DLL ‘<samp>abc.dll</samp>’. The final symbol
- <code>var1</code> is declared to be a data object. The ‘<samp>doo</samp>’ symbol in
- export library is an alias of ‘<samp>foo</samp>’, which gets the string name
- in export table ‘<samp>foo2</samp>’. The ‘<samp>eoo</samp>’ symbol is an data export
- symbol, which gets in export table the name ‘<samp>var1</samp>’.
- </p>
- <p>The optional <code>LIBRARY <name></code> command indicates the <em>internal</em>
- name of the output DLL. If ‘<samp><name></samp>’ does not include a suffix,
- the default library suffix, ‘<samp>.DLL</samp>’ is appended.
- </p>
- <p>When the .DEF file is used to build an application, rather than a
- library, the <code>NAME <name></code> command should be used instead of
- <code>LIBRARY</code>. If ‘<samp><name></samp>’ does not include a suffix, the default
- executable suffix, ‘<samp>.EXE</samp>’ is appended.
- </p>
- <p>With either <code>LIBRARY <name></code> or <code>NAME <name></code> the optional
- specification <code>BASE = <number></code> may be used to specify a
- non-default base address for the image.
- </p>
- <p>If neither <code>LIBRARY <name></code> nor <code>NAME <name></code> is specified,
- or they specify an empty string, the internal name is the same as the
- filename specified on the command line.
- </p>
- <p>The complete specification of an export symbol is:
- </p>
- <div class="example">
- <pre class="example">EXPORTS
- ( ( ( <name1> [ = <name2> ] )
- | ( <name1> = <module-name> . <external-name>))
- [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
- </pre></div>
- <p>Declares ‘<samp><name1></samp>’ as an exported symbol from the DLL, or declares
- ‘<samp><name1></samp>’ as an exported alias for ‘<samp><name2></samp>’; or declares
- ‘<samp><name1></samp>’ as a "forward" alias for the symbol
- ‘<samp><external-name></samp>’ in the DLL ‘<samp><module-name></samp>’.
- Optionally, the symbol may be exported by the specified ordinal
- ‘<samp><integer></samp>’ alias. The optional ‘<samp><name3></samp>’ is the to be used
- string in import/export table for the symbol.
- </p>
- <p>The optional keywords that follow the declaration indicate:
- </p>
- <p><code>NONAME</code>: Do not put the symbol name in the DLL’s export table. It
- will still be exported by its ordinal alias (either the value specified
- by the .def specification or, otherwise, the value assigned by the
- linker). The symbol name, however, does remain visible in the import
- library (if any), unless <code>PRIVATE</code> is also specified.
- </p>
- <p><code>DATA</code>: The symbol is a variable or object, rather than a function.
- The import lib will export only an indirect reference to <code>foo</code> as
- the symbol <code>_imp__foo</code> (ie, <code>foo</code> must be resolved as
- <code>*_imp__foo</code>).
- </p>
- <p><code>CONSTANT</code>: Like <code>DATA</code>, but put the undecorated <code>foo</code> as
- well as <code>_imp__foo</code> into the import library. Both refer to the
- read-only import address table’s pointer to the variable, not to the
- variable itself. This can be dangerous. If the user code fails to add
- the <code>dllimport</code> attribute and also fails to explicitly add the
- extra indirection that the use of the attribute enforces, the
- application will behave unexpectedly.
- </p>
- <p><code>PRIVATE</code>: Put the symbol in the DLL’s export table, but do not put
- it into the static import library used to resolve imports at link time. The
- symbol can still be imported using the <code>LoadLibrary/GetProcAddress</code>
- API at runtime or by using the GNU ld extension of linking directly to
- the DLL without an import library.
- </p>
- <p>See ld/deffilep.y in the binutils sources for the full specification of
- other DEF file statements
- </p>
- <span id="index-creating-a-DEF-file"></span>
- <p>While linking a shared dll, <code>ld</code> is able to create a DEF file
- with the ‘<samp>--output-def <file></samp>’ command-line option.
- </p>
- </dd>
- <dt><em>Using decorations</em></dt>
- <dd><span id="index-Using-decorations"></span>
- <p>Another way of marking symbols for export is to modify the source code
- itself, so that when building the DLL each symbol to be exported is
- declared as:
- </p>
- <div class="example">
- <pre class="example">__declspec(dllexport) int a_variable
- __declspec(dllexport) void a_function(int with_args)
- </pre></div>
- <p>All such symbols will be exported from the DLL. If, however,
- any of the object files in the DLL contain symbols decorated in
- this way, then the normal auto-export behavior is disabled, unless
- the ‘<samp>--export-all-symbols</samp>’ option is also used.
- </p>
- <p>Note that object files that wish to access these symbols must <em>not</em>
- decorate them with dllexport. Instead, they should use dllimport,
- instead:
- </p>
- <div class="example">
- <pre class="example">__declspec(dllimport) int a_variable
- __declspec(dllimport) void a_function(int with_args)
- </pre></div>
- <p>This complicates the structure of library header files, because
- when included by the library itself the header must declare the
- variables and functions as dllexport, but when included by client
- code the header must declare them as dllimport. There are a number
- of idioms that are typically used to do this; often client code can
- omit the __declspec() declaration completely. See
- ‘<samp>--enable-auto-import</samp>’ and ‘<samp>automatic data imports</samp>’ for more
- information.
- </p></dd>
- </dl>
- <span id="index-automatic-data-imports"></span>
- </dd>
- <dt><em>automatic data imports</em></dt>
- <dd><p>The standard Windows dll format supports data imports from dlls only
- by adding special decorations (dllimport/dllexport), which let the
- compiler produce specific assembler instructions to deal with this
- issue. This increases the effort necessary to port existing Un*x
- code to these platforms, especially for large
- c++ libraries and applications. The auto-import feature, which was
- initially provided by Paul Sokolovsky, allows one to omit the
- decorations to achieve a behavior that conforms to that on POSIX/Un*x
- platforms. This feature is enabled with the ‘<samp>--enable-auto-import</samp>’
- command-line option, although it is enabled by default on cygwin/mingw.
- The ‘<samp>--enable-auto-import</samp>’ option itself now serves mainly to
- suppress any warnings that are ordinarily emitted when linked objects
- trigger the feature’s use.
- </p>
- <p>auto-import of variables does not always work flawlessly without
- additional assistance. Sometimes, you will see this message
- </p>
- <p>"variable ’<var>’ can’t be auto-imported. Please read the
- documentation for ld’s <code>--enable-auto-import</code> for details."
- </p>
- <p>The ‘<samp>--enable-auto-import</samp>’ documentation explains why this error
- occurs, and several methods that can be used to overcome this difficulty.
- One of these methods is the <em>runtime pseudo-relocs</em> feature, described
- below.
- </p>
- <span id="index-runtime-pseudo_002drelocation"></span>
- <p>For complex variables imported from DLLs (such as structs or classes),
- object files typically contain a base address for the variable and an
- offset (<em>addend</em>) within the variable–to specify a particular
- field or public member, for instance. Unfortunately, the runtime loader used
- in win32 environments is incapable of fixing these references at runtime
- without the additional information supplied by dllimport/dllexport decorations.
- The standard auto-import feature described above is unable to resolve these
- references.
- </p>
- <p>The ‘<samp>--enable-runtime-pseudo-relocs</samp>’ switch allows these references to
- be resolved without error, while leaving the task of adjusting the references
- themselves (with their non-zero addends) to specialized code provided by the
- runtime environment. Recent versions of the cygwin and mingw environments and
- compilers provide this runtime support; older versions do not. However, the
- support is only necessary on the developer’s platform; the compiled result will
- run without error on an older system.
- </p>
- <p>‘<samp>--enable-runtime-pseudo-relocs</samp>’ is not the default; it must be explicitly
- enabled as needed.
- </p>
- <span id="index-direct-linking-to-a-dll"></span>
- </dd>
- <dt><em>direct linking to a dll</em></dt>
- <dd><p>The cygwin/mingw ports of <code>ld</code> support the direct linking,
- including data symbols, to a dll without the usage of any import
- libraries. This is much faster and uses much less memory than does the
- traditional import library method, especially when linking large
- libraries or applications. When <code>ld</code> creates an import lib, each
- function or variable exported from the dll is stored in its own bfd, even
- though a single bfd could contain many exports. The overhead involved in
- storing, loading, and processing so many bfd’s is quite large, and explains the
- tremendous time, memory, and storage needed to link against particularly
- large or complex libraries when using import libs.
- </p>
- <p>Linking directly to a dll uses no extra command-line switches other than
- ‘<samp>-L</samp>’ and ‘<samp>-l</samp>’, because <code>ld</code> already searches for a number
- of names to match each library. All that is needed from the developer’s
- perspective is an understanding of this search, in order to force ld to
- select the dll instead of an import library.
- </p>
- <p>For instance, when ld is called with the argument ‘<samp>-lxxx</samp>’ it will attempt
- to find, in the first directory of its search path,
- </p>
- <div class="example">
- <pre class="example">libxxx.dll.a
- xxx.dll.a
- libxxx.a
- xxx.lib
- libxxx.lib
- cygxxx.dll (*)
- libxxx.dll
- xxx.dll
- </pre></div>
- <p>before moving on to the next directory in the search path.
- </p>
- <p>(*) Actually, this is not ‘<samp>cygxxx.dll</samp>’ but in fact is ‘<samp><prefix>xxx.dll</samp>’,
- where ‘<samp><prefix></samp>’ is set by the <code>ld</code> option
- ‘<samp>--dll-search-prefix=<prefix></samp>’. In the case of cygwin, the standard gcc spec
- file includes ‘<samp>--dll-search-prefix=cyg</samp>’, so in effect we actually search for
- ‘<samp>cygxxx.dll</samp>’.
- </p>
- <p>Other win32-based unix environments, such as mingw or pw32, may use other
- ‘<samp><prefix></samp>’es, although at present only cygwin makes use of this feature. It
- was originally intended to help avoid name conflicts among dll’s built for the
- various win32/un*x environments, so that (for example) two versions of a zlib dll
- could coexist on the same machine.
- </p>
- <p>The generic cygwin/mingw path layout uses a ‘<samp>bin</samp>’ directory for
- applications and dll’s and a ‘<samp>lib</samp>’ directory for the import
- libraries (using cygwin nomenclature):
- </p>
- <div class="example">
- <pre class="example">bin/
- cygxxx.dll
- lib/
- libxxx.dll.a (in case of dll's)
- libxxx.a (in case of static archive)
- </pre></div>
- <p>Linking directly to a dll without using the import library can be
- done two ways:
- </p>
- <p>1. Use the dll directly by adding the ‘<samp>bin</samp>’ path to the link line
- </p><div class="example">
- <pre class="example">gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
- </pre></div>
- <p>However, as the dll’s often have version numbers appended to their names
- (‘<samp>cygncurses-5.dll</samp>’) this will often fail, unless one specifies
- ‘<samp>-L../bin -lncurses-5</samp>’ to include the version. Import libs are generally
- not versioned, and do not have this difficulty.
- </p>
- <p>2. Create a symbolic link from the dll to a file in the ‘<samp>lib</samp>’
- directory according to the above mentioned search pattern. This
- should be used to avoid unwanted changes in the tools needed for
- making the app/dll.
- </p>
- <div class="example">
- <pre class="example">ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
- </pre></div>
- <p>Then you can link without any make environment changes.
- </p>
- <div class="example">
- <pre class="example">gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
- </pre></div>
- <p>This technique also avoids the version number problems, because the following is
- perfectly legal
- </p>
- <div class="example">
- <pre class="example">bin/
- cygxxx-5.dll
- lib/
- libxxx.dll.a -> ../bin/cygxxx-5.dll
- </pre></div>
- <p>Linking directly to a dll without using an import lib will work
- even when auto-import features are exercised, and even when
- ‘<samp>--enable-runtime-pseudo-relocs</samp>’ is used.
- </p>
- <p>Given the improvements in speed and memory usage, one might justifiably
- wonder why import libraries are used at all. There are three reasons:
- </p>
- <p>1. Until recently, the link-directly-to-dll functionality did <em>not</em>
- work with auto-imported data.
- </p>
- <p>2. Sometimes it is necessary to include pure static objects within the
- import library (which otherwise contains only bfd’s for indirection
- symbols that point to the exports of a dll). Again, the import lib
- for the cygwin kernel makes use of this ability, and it is not
- possible to do this without an import lib.
- </p>
- <p>3. Symbol aliases can only be resolved using an import lib. This is
- critical when linking against OS-supplied dll’s (eg, the win32 API)
- in which symbols are usually exported as undecorated aliases of their
- stdcall-decorated assembly names.
- </p>
- <p>So, import libs are not going away. But the ability to replace
- true import libs with a simple symbolic link to (or a copy of)
- a dll, in many cases, is a useful addition to the suite of tools
- binutils makes available to the win32 developer. Given the
- massive improvements in memory requirements during linking, storage
- requirements, and linking speed, we expect that many developers
- will soon begin to use this feature whenever possible.
- </p>
- </dd>
- <dt><em>symbol aliasing</em></dt>
- <dd><dl compact="compact">
- <dt><em>adding additional names</em></dt>
- <dd><p>Sometimes, it is useful to export symbols with additional names.
- A symbol ‘<samp>foo</samp>’ will be exported as ‘<samp>foo</samp>’, but it can also be
- exported as ‘<samp>_foo</samp>’ by using special directives in the DEF file
- when creating the dll. This will affect also the optional created
- import library. Consider the following DEF file:
- </p>
- <div class="example">
- <pre class="example">LIBRARY "xyz.dll" BASE=0x61000000
- EXPORTS
- foo
- _foo = foo
- </pre></div>
- <p>The line ‘<samp>_foo = foo</samp>’ maps the symbol ‘<samp>foo</samp>’ to ‘<samp>_foo</samp>’.
- </p>
- <p>Another method for creating a symbol alias is to create it in the
- source code using the "weak" attribute:
- </p>
- <div class="example">
- <pre class="example">void foo () { /* Do something. */; }
- void _foo () __attribute__ ((weak, alias ("foo")));
- </pre></div>
- <p>See the gcc manual for more information about attributes and weak
- symbols.
- </p>
- </dd>
- <dt><em>renaming symbols</em></dt>
- <dd><p>Sometimes it is useful to rename exports. For instance, the cygwin
- kernel does this regularly. A symbol ‘<samp>_foo</samp>’ can be exported as
- ‘<samp>foo</samp>’ but not as ‘<samp>_foo</samp>’ by using special directives in the
- DEF file. (This will also affect the import library, if it is
- created). In the following example:
- </p>
- <div class="example">
- <pre class="example">LIBRARY "xyz.dll" BASE=0x61000000
- EXPORTS
- _foo = foo
- </pre></div>
- <p>The line ‘<samp>_foo = foo</samp>’ maps the exported symbol ‘<samp>foo</samp>’ to
- ‘<samp>_foo</samp>’.
- </p></dd>
- </dl>
- <p>Note: using a DEF file disables the default auto-export behavior,
- unless the ‘<samp>--export-all-symbols</samp>’ command-line option is used.
- If, however, you are trying to rename symbols, then you should list
- <em>all</em> desired exports in the DEF file, including the symbols
- that are not being renamed, and do <em>not</em> use the
- ‘<samp>--export-all-symbols</samp>’ option. If you list only the
- renamed symbols in the DEF file, and use ‘<samp>--export-all-symbols</samp>’
- to handle the other symbols, then the both the new names <em>and</em>
- the original names for the renamed symbols will be exported.
- In effect, you’d be aliasing those symbols, not renaming them,
- which is probably not what you wanted.
- </p>
- <span id="index-weak-externals"></span>
- </dd>
- <dt><em>weak externals</em></dt>
- <dd><p>The Windows object format, PE, specifies a form of weak symbols called
- weak externals. When a weak symbol is linked and the symbol is not
- defined, the weak symbol becomes an alias for some other symbol. There
- are three variants of weak externals:
- </p><ul>
- <li> Definition is searched for in objects and libraries, historically
- called lazy externals.
- </li><li> Definition is searched for only in other objects, not in libraries.
- This form is not presently implemented.
- </li><li> No search; the symbol is an alias. This form is not presently
- implemented.
- </li></ul>
- <p>As a GNU extension, weak symbols that do not specify an alternate symbol
- are supported. If the symbol is undefined when linking, the symbol
- uses a default value.
- </p>
- <span id="index-aligned-common-symbols"></span>
- </dd>
- <dt><em>aligned common symbols</em></dt>
- <dd><p>As a GNU extension to the PE file format, it is possible to specify the
- desired alignment for a common symbol. This information is conveyed from
- the assembler or compiler to the linker by means of GNU-specific commands
- carried in the object file’s ‘<samp>.drectve</samp>’ section, which are recognized
- by <code>ld</code> and respected when laying out the common symbols. Native
- tools will be able to process object files employing this GNU extension,
- but will fail to respect the alignment instructions, and may issue noisy
- warnings about unknown linker directives.
- </p>
- </dd>
- </dl>
- <hr>
- <span id="Xtensa"></span><div class="header">
- <p>
- Previous: <a href="#WIN32" accesskey="p" rel="prev">WIN32</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="ld-and-Xtensa-Processors"></span><h3 class="section">6.17 <code>ld</code> and Xtensa Processors</h3>
- <span id="index-Xtensa-processors"></span>
- <p>The default <code>ld</code> behavior for Xtensa processors is to interpret
- <code>SECTIONS</code> commands so that lists of explicitly named sections in a
- specification with a wildcard file will be interleaved when necessary to
- keep literal pools within the range of PC-relative load offsets. For
- example, with the command:
- </p>
- <div class="example">
- <pre class="example">SECTIONS
- {
- .text : {
- *(.literal .text)
- }
- }
- </pre></div>
- <p><code>ld</code> may interleave some of the <code>.literal</code>
- and <code>.text</code> sections from different object files to ensure that the
- literal pools are within the range of PC-relative load offsets. A valid
- interleaving might place the <code>.literal</code> sections from an initial
- group of files followed by the <code>.text</code> sections of that group of
- files. Then, the <code>.literal</code> sections from the rest of the files
- and the <code>.text</code> sections from the rest of the files would follow.
- </p>
- <span id="index-_002d_002drelax-on-Xtensa"></span>
- <span id="index-relaxing-on-Xtensa"></span>
- <p>Relaxation is enabled by default for the Xtensa version of <code>ld</code> and
- provides two important link-time optimizations. The first optimization
- is to combine identical literal values to reduce code size. A redundant
- literal will be removed and all the <code>L32R</code> instructions that use it
- will be changed to reference an identical literal, as long as the
- location of the replacement literal is within the offset range of all
- the <code>L32R</code> instructions. The second optimization is to remove
- unnecessary overhead from assembler-generated “longcall” sequences of
- <code>L32R</code>/<code>CALLX<var>n</var></code> when the target functions are within
- range of direct <code>CALL<var>n</var></code> instructions.
- </p>
- <p>For each of these cases where an indirect call sequence can be optimized
- to a direct call, the linker will change the <code>CALLX<var>n</var></code>
- instruction to a <code>CALL<var>n</var></code> instruction, remove the <code>L32R</code>
- instruction, and remove the literal referenced by the <code>L32R</code>
- instruction if it is not used for anything else. Removing the
- <code>L32R</code> instruction always reduces code size but can potentially
- hurt performance by changing the alignment of subsequent branch targets.
- By default, the linker will always preserve alignments, either by
- switching some instructions between 24-bit encodings and the equivalent
- density instructions or by inserting a no-op in place of the <code>L32R</code>
- instruction that was removed. If code size is more important than
- performance, the <samp>--size-opt</samp> option can be used to prevent the
- linker from widening density instructions or inserting no-ops, except in
- a few cases where no-ops are required for correctness.
- </p>
- <p>The following Xtensa-specific command-line options can be used to
- control the linker:
- </p>
- <span id="index-Xtensa-options"></span>
- <dl compact="compact">
- <dt><samp>--size-opt</samp></dt>
- <dd><p>When optimizing indirect calls to direct calls, optimize for code size
- more than performance. With this option, the linker will not insert
- no-ops or widen density instructions to preserve branch target
- alignment. There may still be some cases where no-ops are required to
- preserve the correctness of the code.
- </p>
- </dd>
- <dt><samp>--abi-windowed</samp></dt>
- <dt><samp>--abi-call0</samp></dt>
- <dd><p>Choose ABI for the output object and for the generated PLT code.
- PLT code inserted by the linker must match ABI of the output object
- because windowed and call0 ABI use incompatible function call
- conventions.
- Default ABI is chosen by the ABI tag in the <code>.xtensa.info</code> section
- of the first input object.
- A warning is issued if ABI tags of input objects do not match each other
- or the chosen output object ABI.
- </p></dd>
- </dl>
- <hr>
- <span id="BFD"></span><div class="header">
- <p>
- Next: <a href="#Reporting-Bugs" accesskey="n" rel="next">Reporting Bugs</a>, Previous: <a href="#Machine-Dependent" accesskey="p" rel="prev">Machine Dependent</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="BFD-1"></span><h2 class="chapter">7 BFD</h2>
- <span id="index-back-end"></span>
- <span id="index-object-file-management"></span>
- <span id="index-object-formats-available"></span>
- <span id="index-objdump-_002di"></span>
- <p>The linker accesses object and archive files using the BFD libraries.
- These libraries allow the linker to use the same routines to operate on
- object files whatever the object file format. A different object file
- format can be supported simply by creating a new BFD back end and adding
- it to the library. To conserve runtime memory, however, the linker and
- associated tools are usually configured to support only a subset of the
- object file formats available. You can use <code>objdump -i</code>
- (see <a href="https://sourceware.org/binutils/docs/binutils/objdump.html#objdump">objdump</a> in <cite>The GNU Binary Utilities</cite>) to
- list all the formats available for your configuration.
- </p>
- <span id="index-BFD-requirements"></span>
- <span id="index-requirements-for-BFD"></span>
- <p>As with most implementations, BFD is a compromise between
- several conflicting requirements. The major factor influencing
- BFD design was efficiency: any time used converting between
- formats is time which would not have been spent had BFD not
- been involved. This is partly offset by abstraction payback; since
- BFD simplifies applications and back ends, more time and care
- may be spent optimizing algorithms for a greater speed.
- </p>
- <p>One minor artifact of the BFD solution which you should bear in
- mind is the potential for information loss. There are two places where
- useful information can be lost using the BFD mechanism: during
- conversion and during output. See <a href="#BFD-information-loss">BFD information loss</a>.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#BFD-outline" accesskey="1">BFD outline</a></td><td> </td><td align="left" valign="top">How it works: an outline of BFD
- </td></tr>
- </table>
- <hr>
- <span id="BFD-outline"></span><div class="header">
- <p>
- Up: <a href="#BFD" accesskey="u" rel="up">BFD</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="How-It-Works_003a-An-Outline-of-BFD"></span><h3 class="section">7.1 How It Works: An Outline of BFD</h3>
- <span id="index-opening-object-files"></span>
- <p>When an object file is opened, BFD subroutines automatically determine
- the format of the input object file. They then build a descriptor in
- memory with pointers to routines that will be used to access elements of
- the object file’s data structures.
- </p>
- <p>As different information from the object files is required,
- BFD reads from different sections of the file and processes them.
- For example, a very common operation for the linker is processing symbol
- tables. Each BFD back end provides a routine for converting
- between the object file’s representation of symbols and an internal
- canonical format. When the linker asks for the symbol table of an object
- file, it calls through a memory pointer to the routine from the
- relevant BFD back end which reads and converts the table into a canonical
- form. The linker then operates upon the canonical form. When the link is
- finished and the linker writes the output file’s symbol table,
- another BFD back end routine is called to take the newly
- created symbol table and convert it into the chosen output format.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#BFD-information-loss" accesskey="1">BFD information loss</a></td><td> </td><td align="left" valign="top">Information Loss
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Canonical-format" accesskey="2">Canonical format</a></td><td> </td><td align="left" valign="top">The BFD canonical object-file format
- </td></tr>
- </table>
- <hr>
- <span id="BFD-information-loss"></span><div class="header">
- <p>
- Next: <a href="#Canonical-format" accesskey="n" rel="next">Canonical format</a>, Up: <a href="#BFD-outline" accesskey="u" rel="up">BFD outline</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Information-Loss"></span><h4 class="subsection">7.1.1 Information Loss</h4>
- <p><em>Information can be lost during output.</em> The output formats
- supported by BFD do not provide identical facilities, and
- information which can be described in one form has nowhere to go in
- another format. One example of this is alignment information in
- <code>b.out</code>. There is nowhere in an <code>a.out</code> format file to store
- alignment information on the contained data, so when a file is linked
- from <code>b.out</code> and an <code>a.out</code> image is produced, alignment
- information will not propagate to the output file. (The linker will
- still use the alignment information internally, so the link is performed
- correctly).
- </p>
- <p>Another example is COFF section names. COFF files may contain an
- unlimited number of sections, each one with a textual section name. If
- the target of the link is a format which does not have many sections (e.g.,
- <code>a.out</code>) or has sections without names (e.g., the Oasys format), the
- link cannot be done simply. You can circumvent this problem by
- describing the desired input-to-output section mapping with the linker command
- language.
- </p>
- <p><em>Information can be lost during canonicalization.</em> The BFD
- internal canonical form of the external formats is not exhaustive; there
- are structures in input formats for which there is no direct
- representation internally. This means that the BFD back ends
- cannot maintain all possible data richness through the transformation
- between external to internal and back to external formats.
- </p>
- <p>This limitation is only a problem when an application reads one
- format and writes another. Each BFD back end is responsible for
- maintaining as much data as possible, and the internal BFD
- canonical form has structures which are opaque to the BFD core,
- and exported only to the back ends. When a file is read in one format,
- the canonical form is generated for BFD and the application. At the
- same time, the back end saves away any information which may otherwise
- be lost. If the data is then written back in the same format, the back
- end routine will be able to use the canonical form provided by the
- BFD core as well as the information it prepared earlier. Since
- there is a great deal of commonality between back ends,
- there is no information lost when
- linking or copying big endian COFF to little endian COFF, or <code>a.out</code> to
- <code>b.out</code>. When a mixture of formats is linked, the information is
- only lost from the files whose format differs from the destination.
- </p>
- <hr>
- <span id="Canonical-format"></span><div class="header">
- <p>
- Previous: <a href="#BFD-information-loss" accesskey="p" rel="prev">BFD information loss</a>, Up: <a href="#BFD-outline" accesskey="u" rel="up">BFD outline</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="The-BFD-canonical-object_002dfile-format"></span><h4 class="subsection">7.1.2 The BFD canonical object-file format</h4>
- <p>The greatest potential for loss of information occurs when there is the least
- overlap between the information provided by the source format, that
- stored by the canonical format, and that needed by the
- destination format. A brief description of the canonical form may help
- you understand which kinds of data you can count on preserving across
- conversions.
- <span id="index-BFD-canonical-format"></span>
- <span id="index-internal-object_002dfile-format"></span>
- </p>
- <dl compact="compact">
- <dt><em>files</em></dt>
- <dd><p>Information stored on a per-file basis includes target machine
- architecture, particular implementation format type, a demand pageable
- bit, and a write protected bit. Information like Unix magic numbers is
- not stored here—only the magic numbers’ meaning, so a <code>ZMAGIC</code>
- file would have both the demand pageable bit and the write protected
- text bit set. The byte order of the target is stored on a per-file
- basis, so that big- and little-endian object files may be used with one
- another.
- </p>
- </dd>
- <dt><em>sections</em></dt>
- <dd><p>Each section in the input file contains the name of the section, the
- section’s original address in the object file, size and alignment
- information, various flags, and pointers into other BFD data
- structures.
- </p>
- </dd>
- <dt><em>symbols</em></dt>
- <dd><p>Each symbol contains a pointer to the information for the object file
- which originally defined it, its name, its value, and various flag
- bits. When a BFD back end reads in a symbol table, it relocates all
- symbols to make them relative to the base of the section where they were
- defined. Doing this ensures that each symbol points to its containing
- section. Each symbol also has a varying amount of hidden private data
- for the BFD back end. Since the symbol points to the original file, the
- private data format for that symbol is accessible. <code>ld</code> can
- operate on a collection of symbols of wildly different formats without
- problems.
- </p>
- <p>Normal global and simple local symbols are maintained on output, so an
- output file (no matter its format) will retain symbols pointing to
- functions and to global, static, and common variables. Some symbol
- information is not worth retaining; in <code>a.out</code>, type information is
- stored in the symbol table as long symbol names. This information would
- be useless to most COFF debuggers; the linker has command-line switches
- to allow users to throw it away.
- </p>
- <p>There is one word of type information within the symbol, so if the
- format supports symbol type information within symbols (for example, COFF,
- Oasys) and the type is simple enough to fit within one word
- (nearly everything but aggregates), the information will be preserved.
- </p>
- </dd>
- <dt><em>relocation level</em></dt>
- <dd><p>Each canonical BFD relocation record contains a pointer to the symbol to
- relocate to, the offset of the data to relocate, the section the data
- is in, and a pointer to a relocation type descriptor. Relocation is
- performed by passing messages through the relocation type
- descriptor and the symbol pointer. Therefore, relocations can be performed
- on output data using a relocation method that is only available in one of the
- input formats. For instance, Oasys provides a byte relocation format.
- A relocation record requesting this relocation type would point
- indirectly to a routine to perform this, so the relocation may be
- performed on a byte being written to a 68k COFF file, even though 68k COFF
- has no such relocation type.
- </p>
- </dd>
- <dt><em>line numbers</em></dt>
- <dd><p>Object formats can contain, for debugging purposes, some form of mapping
- between symbols, source line numbers, and addresses in the output file.
- These addresses have to be relocated along with the symbol information.
- Each symbol with an associated list of line number records points to the
- first record of the list. The head of a line number list consists of a
- pointer to the symbol, which allows finding out the address of the
- function whose line number is being described. The rest of the list is
- made up of pairs: offsets into the section and line numbers. Any format
- which can simply derive this information can pass it successfully
- between formats.
- </p></dd>
- </dl>
- <hr>
- <span id="Reporting-Bugs"></span><div class="header">
- <p>
- Next: <a href="#MRI" accesskey="n" rel="next">MRI</a>, Previous: <a href="#BFD" accesskey="p" rel="prev">BFD</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Reporting-Bugs-1"></span><h2 class="chapter">8 Reporting Bugs</h2>
- <span id="index-bugs-in-ld"></span>
- <span id="index-reporting-bugs-in-ld"></span>
- <p>Your bug reports play an essential role in making <code>ld</code> reliable.
- </p>
- <p>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 <code>ld</code>
- work better. Bug reports are your contribution to the maintenance of
- <code>ld</code>.
- </p>
- <p>In order for a bug report to serve its purpose, you must include the
- information that enables us to fix the bug.
- </p>
- <table class="menu" border="0" cellspacing="0">
- <tr><td align="left" valign="top">• <a href="#Bug-Criteria" accesskey="1">Bug Criteria</a></td><td> </td><td align="left" valign="top">Have you found a bug?
- </td></tr>
- <tr><td align="left" valign="top">• <a href="#Bug-Reporting" accesskey="2">Bug Reporting</a></td><td> </td><td align="left" valign="top">How to report bugs
- </td></tr>
- </table>
- <hr>
- <span id="Bug-Criteria"></span><div class="header">
- <p>
- Next: <a href="#Bug-Reporting" accesskey="n" rel="next">Bug Reporting</a>, Up: <a href="#Reporting-Bugs" accesskey="u" rel="up">Reporting Bugs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="Have-You-Found-a-Bug_003f"></span><h3 class="section">8.1 Have You Found a Bug?</h3>
- <span id="index-bug-criteria"></span>
- <p>If you are not sure whether you have found a bug, here are some guidelines:
- </p>
- <ul>
- <li> <span id="index-fatal-signal"></span>
- <span id="index-linker-crash"></span>
- <span id="index-crash-of-linker"></span>
- If the linker gets a fatal signal, for any input whatever, that is a
- <code>ld</code> bug. Reliable linkers never crash.
- </li><li> <span id="index-error-on-valid-input"></span>
- If <code>ld</code> produces an error message for valid input, that is a bug.
- </li><li> <span id="index-invalid-input"></span>
- If <code>ld</code> does not produce an error message for invalid input, that
- may be a bug. In the general case, the linker can not verify that
- object files are correct.
- </li><li> If you are an experienced user of linkers, your suggestions for
- improvement of <code>ld</code> are welcome in any case.
- </li></ul>
- <hr>
- <span id="Bug-Reporting"></span><div class="header">
- <p>
- Previous: <a href="#Bug-Criteria" accesskey="p" rel="prev">Bug Criteria</a>, Up: <a href="#Reporting-Bugs" accesskey="u" rel="up">Reporting Bugs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="How-to-Report-Bugs"></span><h3 class="section">8.2 How to Report Bugs</h3>
- <span id="index-bug-reports"></span>
- <span id="index-ld-bugs_002c-reporting"></span>
- <p>A number of companies and individuals offer support for <small>GNU</small>
- products. If you obtained <code>ld</code> from a support organization, we
- recommend you contact that organization first.
- </p>
- <p>You can find contact information for many support companies and
- individuals in the file <samp>etc/SERVICE</samp> in the <small>GNU</small> Emacs
- distribution.
- </p>
- <p>Otherwise, send bug reports for <code>ld</code> to
- <a href="https://bugs.linaro.org/">https://bugs.linaro.org/</a>.
- </p>
- <p>The fundamental principle of reporting bugs usefully is this:
- <strong>report all the facts</strong>. If you are not sure whether to state a
- fact or leave it out, state it!
- </p>
- <p>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 a symbol 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 linker
- 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.
- </p>
- <p>Keep in mind that the purpose of a bug report is to enable us to fix
- the bug if it is new to us. Therefore, always write your bug reports
- on the assumption that the bug has not been reported previously.
- </p>
- <p>Sometimes people give a few sketchy facts and ask, “Does this ring a
- bell?” This cannot help us fix a bug, so it is basically useless. We
- respond by asking for enough details to enable us to investigate.
- You might as well expedite matters by sending them to begin with.
- </p>
- <p>To enable us to fix the bug, you should include all these things:
- </p>
- <ul>
- <li> The version of <code>ld</code>. <code>ld</code> announces it if you start it with
- the ‘<samp>--version</samp>’ argument.
- <p>Without this, we will not know whether there is any point in looking for
- the bug in the current version of <code>ld</code>.
- </p>
- </li><li> Any patches you may have applied to the <code>ld</code> source, including any
- patches made to the <code>BFD</code> library.
- </li><li> The type of machine you are using, and the operating system name and
- version number.
- </li><li> What compiler (and its version) was used to compile <code>ld</code>—e.g.
- “<code>gcc-2.7</code>”.
- </li><li> The command arguments you gave the linker to link your example and
- observe the bug. To guarantee you will not omit something important,
- list them all. A copy of the Makefile (or the output from make) is
- sufficient.
- <p>If we were to try to guess the arguments, we would probably guess wrong
- and then we might not encounter the bug.
- </p>
- </li><li> A complete input file, or set of input files, that will reproduce the
- bug. It is generally most helpful to send the actual object files
- provided that they are reasonably small. Say no more than 10K. For
- bigger files you can either make them available by FTP or HTTP or else
- state that you are willing to send the object file(s) to whomever
- requests them. (Note - your email will be going to a mailing list, so
- we do not want to clog it up with large attachments). But small
- attachments are best.
- <p>If the source files were assembled using <code>gas</code> or compiled using
- <code>gcc</code>, then it may be OK to send the source files rather than the
- object files. In this case, be sure to say exactly what version of
- <code>gas</code> or <code>gcc</code> was used to produce the object files. Also say
- how <code>gas</code> or <code>gcc</code> were configured.
- </p>
- </li><li> A description of what behavior you observe that you believe is
- incorrect. For example, “It gets a fatal signal.”
- <p>Of course, if the bug is that <code>ld</code> 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.
- </p>
- <p>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 <code>ld</code> is out of sync, 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.
- </p>
- </li><li> If you wish to suggest changes to the <code>ld</code> source, send us context
- diffs, as generated by <code>diff</code> with the ‘<samp>-u</samp>’, ‘<samp>-c</samp>’, or
- ‘<samp>-p</samp>’ option. Always send diffs from the old file to the new file.
- If you even discuss something in the <code>ld</code> source, refer to it by
- context, not by line number.
- <p>The line numbers in our development sources will not match those in your
- sources. Your line numbers would convey no useful information to us.
- </p></li></ul>
- <p>Here are some things that are not necessary:
- </p>
- <ul>
- <li> A description of the envelope of the bug.
- <p>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.
- </p>
- <p>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.
- </p>
- <p>Of course, if you can find a simpler example to report <em>instead</em>
- 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.
- </p>
- <p>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.
- </p>
- </li><li> A patch for the bug.
- <p>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.
- </p>
- <p>Sometimes with a program as complicated as <code>ld</code> 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.
- </p>
- <p>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.
- </p>
- </li><li> A guess about what the bug is or what it depends on.
- <p>Such guesses are usually wrong. Even we cannot guess right about such
- things without first using the debugger to find the facts.
- </p></li></ul>
- <hr>
- <span id="MRI"></span><div class="header">
- <p>
- Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="#Reporting-Bugs" accesskey="p" rel="prev">Reporting Bugs</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="MRI-Compatible-Script-Files"></span><h2 class="appendix">Appendix A MRI Compatible Script Files</h2>
- <span id="index-MRI-compatibility"></span>
- <p>To aid users making the transition to <small>GNU</small> <code>ld</code> from the MRI
- linker, <code>ld</code> can use MRI compatible linker scripts as an
- alternative to the more general-purpose linker scripting language
- described in <a href="#Scripts">Scripts</a>. MRI compatible linker scripts have a much
- simpler command set than the scripting language otherwise used with
- <code>ld</code>. <small>GNU</small> <code>ld</code> supports the most commonly used MRI
- linker commands; these commands are described here.
- </p>
- <p>In general, MRI scripts aren’t of much use with the <code>a.out</code> object
- file format, since it only has three sections and MRI scripts lack some
- features to make use of them.
- </p>
- <p>You can specify a file containing an MRI-compatible script using the
- ‘<samp>-c</samp>’ command-line option.
- </p>
- <p>Each command in an MRI-compatible script occupies its own line; each
- command line starts with the keyword that identifies the command (though
- blank lines are also allowed for punctuation). If a line of an
- MRI-compatible script begins with an unrecognized keyword, <code>ld</code>
- issues a warning message, but continues processing the script.
- </p>
- <p>Lines beginning with ‘<samp>*</samp>’ are comments.
- </p>
- <p>You can write these commands using all upper-case letters, or all
- lower case; for example, ‘<samp>chip</samp>’ is the same as ‘<samp>CHIP</samp>’.
- The following list shows only the upper-case form of each command.
- </p>
- <dl compact="compact">
- <dd><span id="index-ABSOLUTE-_0028MRI_0029"></span>
- </dd>
- <dt><code>ABSOLUTE <var>secname</var></code></dt>
- <dt><code>ABSOLUTE <var>secname</var>, <var>secname</var>, … <var>secname</var></code></dt>
- <dd><p>Normally, <code>ld</code> includes in the output file all sections from all
- the input files. However, in an MRI-compatible script, you can use the
- <code>ABSOLUTE</code> command to restrict the sections that will be present in
- your output program. If the <code>ABSOLUTE</code> command is used at all in a
- script, then only the sections named explicitly in <code>ABSOLUTE</code>
- commands will appear in the linker output. You can still use other
- input sections (whatever you select on the command line, or using
- <code>LOAD</code>) to resolve addresses in the output file.
- </p>
- <span id="index-ALIAS-_0028MRI_0029"></span>
- </dd>
- <dt><code>ALIAS <var>out-secname</var>, <var>in-secname</var></code></dt>
- <dd><p>Use this command to place the data from input section <var>in-secname</var>
- in a section called <var>out-secname</var> in the linker output file.
- </p>
- <p><var>in-secname</var> may be an integer.
- </p>
- <span id="index-ALIGN-_0028MRI_0029"></span>
- </dd>
- <dt><code>ALIGN <var>secname</var> = <var>expression</var></code></dt>
- <dd><p>Align the section called <var>secname</var> to <var>expression</var>. The
- <var>expression</var> should be a power of two.
- </p>
- <span id="index-BASE-_0028MRI_0029"></span>
- </dd>
- <dt><code>BASE <var>expression</var></code></dt>
- <dd><p>Use the value of <var>expression</var> as the lowest address (other than
- absolute addresses) in the output file.
- </p>
- <span id="index-CHIP-_0028MRI_0029"></span>
- </dd>
- <dt><code>CHIP <var>expression</var></code></dt>
- <dt><code>CHIP <var>expression</var>, <var>expression</var></code></dt>
- <dd><p>This command does nothing; it is accepted only for compatibility.
- </p>
- <span id="index-END-_0028MRI_0029"></span>
- </dd>
- <dt><code>END</code></dt>
- <dd><p>This command does nothing whatever; it’s only accepted for compatibility.
- </p>
- <span id="index-FORMAT-_0028MRI_0029"></span>
- </dd>
- <dt><code>FORMAT <var>output-format</var></code></dt>
- <dd><p>Similar to the <code>OUTPUT_FORMAT</code> command in the more general linker
- language, but restricted to S-records, if <var>output-format</var> is ‘<samp>S</samp>’
- </p>
- <span id="index-LIST-_0028MRI_0029"></span>
- </dd>
- <dt><code>LIST <var>anything</var>…</code></dt>
- <dd><p>Print (to the standard output file) a link map, as produced by the
- <code>ld</code> command-line option ‘<samp>-M</samp>’.
- </p>
- <p>The keyword <code>LIST</code> may be followed by anything on the
- same line, with no change in its effect.
- </p>
- <span id="index-LOAD-_0028MRI_0029"></span>
- </dd>
- <dt><code>LOAD <var>filename</var></code></dt>
- <dt><code>LOAD <var>filename</var>, <var>filename</var>, … <var>filename</var></code></dt>
- <dd><p>Include one or more object file <var>filename</var> in the link; this has the
- same effect as specifying <var>filename</var> directly on the <code>ld</code>
- command line.
- </p>
- <span id="index-NAME-_0028MRI_0029"></span>
- </dd>
- <dt><code>NAME <var>output-name</var></code></dt>
- <dd><p><var>output-name</var> is the name for the program produced by <code>ld</code>; the
- MRI-compatible command <code>NAME</code> is equivalent to the command-line
- option ‘<samp>-o</samp>’ or the general script language command <code>OUTPUT</code>.
- </p>
- <span id="index-ORDER-_0028MRI_0029"></span>
- </dd>
- <dt><code>ORDER <var>secname</var>, <var>secname</var>, … <var>secname</var></code></dt>
- <dt><code>ORDER <var>secname</var> <var>secname</var> <var>secname</var></code></dt>
- <dd><p>Normally, <code>ld</code> orders the sections in its output file in the
- order in which they first appear in the input files. In an MRI-compatible
- script, you can override this ordering with the <code>ORDER</code> command. The
- sections you list with <code>ORDER</code> will appear first in your output
- file, in the order specified.
- </p>
- <span id="index-PUBLIC-_0028MRI_0029"></span>
- </dd>
- <dt><code>PUBLIC <var>name</var>=<var>expression</var></code></dt>
- <dt><code>PUBLIC <var>name</var>,<var>expression</var></code></dt>
- <dt><code>PUBLIC <var>name</var> <var>expression</var></code></dt>
- <dd><p>Supply a value (<var>expression</var>) for external symbol
- <var>name</var> used in the linker input files.
- </p>
- <span id="index-SECT-_0028MRI_0029"></span>
- </dd>
- <dt><code>SECT <var>secname</var>, <var>expression</var></code></dt>
- <dt><code>SECT <var>secname</var>=<var>expression</var></code></dt>
- <dt><code>SECT <var>secname</var> <var>expression</var></code></dt>
- <dd><p>You can use any of these three forms of the <code>SECT</code> command to
- specify the start address (<var>expression</var>) for section <var>secname</var>.
- If you have more than one <code>SECT</code> statement for the same
- <var>secname</var>, only the <em>first</em> sets the start address.
- </p></dd>
- </dl>
- <hr>
- <span id="GNU-Free-Documentation-License"></span><div class="header">
- <p>
- Next: <a href="#LD-Index" accesskey="n" rel="next">LD Index</a>, Previous: <a href="#MRI" accesskey="p" rel="prev">MRI</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="GNU-Free-Documentation-License-1"></span><h2 class="appendix">Appendix B GNU Free Documentation License</h2>
- <div align="center">Version 1.3, 3 November 2008
- </div>
- <div class="display">
- <pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
- <a href="http://fsf.org/">http://fsf.org/</a>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
- </pre></div>
- <ol start="0">
- <li> PREAMBLE
- <p>The purpose of this License is to make a manual, textbook, or other
- functional and useful document <em>free</em> in the sense of freedom: to
- assure everyone the effective freedom to copy and redistribute it,
- with or without modifying it, either commercially or noncommercially.
- Secondarily, this License preserves for the author and publisher a way
- to get credit for their work, while not being considered responsible
- for modifications made by others.
- </p>
- <p>This License is a kind of “copyleft”, which means that derivative
- works of the document must themselves be free in the same sense. It
- complements the GNU General Public License, which is a copyleft
- license designed for free software.
- </p>
- <p>We have designed this License in order to use it for manuals for free
- software, because free software needs free documentation: a free
- program should come with manuals providing the same freedoms that the
- software does. But this License is not limited to software manuals;
- it can be used for any textual work, regardless of subject matter or
- whether it is published as a printed book. We recommend this License
- principally for works whose purpose is instruction or reference.
- </p>
- </li><li> APPLICABILITY AND DEFINITIONS
- <p>This License applies to any manual or other work, in any medium, that
- contains a notice placed by the copyright holder saying it can be
- distributed under the terms of this License. Such a notice grants a
- world-wide, royalty-free license, unlimited in duration, to use that
- work under the conditions stated herein. The “Document”, below,
- refers to any such manual or work. Any member of the public is a
- licensee, and is addressed as “you”. You accept the license if you
- copy, modify or distribute the work in a way requiring permission
- under copyright law.
- </p>
- <p>A “Modified Version” of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
- </p>
- <p>A “Secondary Section” is a named appendix or a front-matter section
- of the Document that deals exclusively with the relationship of the
- publishers or authors of the Document to the Document’s overall
- subject (or to related matters) and contains nothing that could fall
- directly within that overall subject. (Thus, if the Document is in
- part a textbook of mathematics, a Secondary Section may not explain
- any mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of legal,
- commercial, philosophical, ethical or political position regarding
- them.
- </p>
- <p>The “Invariant Sections” are certain Secondary Sections whose titles
- are designated, as being those of Invariant Sections, in the notice
- that says that the Document is released under this License. If a
- section does not fit the above definition of Secondary then it is not
- allowed to be designated as Invariant. The Document may contain zero
- Invariant Sections. If the Document does not identify any Invariant
- Sections then there are none.
- </p>
- <p>The “Cover Texts” are certain short passages of text that are listed,
- as Front-Cover Texts or Back-Cover Texts, in the notice that says that
- the Document is released under this License. A Front-Cover Text may
- be at most 5 words, and a Back-Cover Text may be at most 25 words.
- </p>
- <p>A “Transparent” copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, that is suitable for revising the document
- straightforwardly with generic text editors or (for images composed of
- pixels) generic paint programs or (for drawings) some widely available
- drawing editor, and that is suitable for input to text formatters or
- for automatic translation to a variety of formats suitable for input
- to text formatters. A copy made in an otherwise Transparent file
- format whose markup, or absence of markup, has been arranged to thwart
- or discourage subsequent modification by readers is not Transparent.
- An image format is not Transparent if used for any substantial amount
- of text. A copy that is not “Transparent” is called “Opaque”.
- </p>
- <p>Examples of suitable formats for Transparent copies include plain
- <small>ASCII</small> without markup, Texinfo input format, LaTeX input
- format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available
- <acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>,
- PostScript or <acronym>PDF</acronym> designed for human modification. Examples
- of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and
- <acronym>JPG</acronym>. Opaque formats include proprietary formats that can be
- read and edited only by proprietary word processors, <acronym>SGML</acronym> or
- <acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are
- not generally available, and the machine-generated <acronym>HTML</acronym>,
- PostScript or <acronym>PDF</acronym> produced by some word processors for
- output purposes only.
- </p>
- <p>The “Title Page” means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the material
- this License requires to appear in the title page. For works in
- formats which do not have any title page as such, “Title Page” means
- the text near the most prominent appearance of the work’s title,
- preceding the beginning of the body of the text.
- </p>
- <p>The “publisher” means any person or entity that distributes copies
- of the Document to the public.
- </p>
- <p>A section “Entitled XYZ” means a named subunit of the Document whose
- title either is precisely XYZ or contains XYZ in parentheses following
- text that translates XYZ in another language. (Here XYZ stands for a
- specific section name mentioned below, such as “Acknowledgements”,
- “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title”
- of such a section when you modify the Document means that it remains a
- section “Entitled XYZ” according to this definition.
- </p>
- <p>The Document may include Warranty Disclaimers next to the notice which
- states that this License applies to the Document. These Warranty
- Disclaimers are considered to be included by reference in this
- License, but only as regards disclaiming warranties: any other
- implication that these Warranty Disclaimers may have is void and has
- no effect on the meaning of this License.
- </p>
- </li><li> VERBATIM COPYING
- <p>You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License applies
- to the Document are reproduced in all copies, and that you add no other
- conditions whatsoever to those of this License. You may not use
- technical measures to obstruct or control the reading or further
- copying of the copies you make or distribute. However, you may accept
- compensation in exchange for copies. If you distribute a large enough
- number of copies you must also follow the conditions in section 3.
- </p>
- <p>You may also lend copies, under the same conditions stated above, and
- you may publicly display copies.
- </p>
- </li><li> COPYING IN QUANTITY
- <p>If you publish printed copies (or copies in media that commonly have
- printed covers) of the Document, numbering more than 100, and the
- Document’s license notice requires Cover Texts, you must enclose the
- copies in covers that carry, clearly and legibly, all these Cover
- Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
- the back cover. Both covers must also clearly and legibly identify
- you as the publisher of these copies. The front cover must present
- the full title with all words of the title equally prominent and
- visible. You may add other material on the covers in addition.
- Copying with changes limited to the covers, as long as they preserve
- the title of the Document and satisfy these conditions, can be treated
- as verbatim copying in other respects.
- </p>
- <p>If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto adjacent
- pages.
- </p>
- <p>If you publish or distribute Opaque copies of the Document numbering
- more than 100, you must either include a machine-readable Transparent
- copy along with each Opaque copy, or state in or with each Opaque copy
- a computer-network location from which the general network-using
- public has access to download using public-standard network protocols
- a complete Transparent copy of the Document, free of added material.
- If you use the latter option, you must take reasonably prudent steps,
- when you begin distribution of Opaque copies in quantity, to ensure
- that this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you distribute an
- Opaque copy (directly or through your agents or retailers) of that
- edition to the public.
- </p>
- <p>It is requested, but not required, that you contact the authors of the
- Document well before redistributing any large number of copies, to give
- them a chance to provide you with an updated version of the Document.
- </p>
- </li><li> MODIFICATIONS
- <p>You may copy and distribute a Modified Version of the Document under
- the conditions of sections 2 and 3 above, provided that you release
- the Modified Version under precisely this License, with the Modified
- Version filling the role of the Document, thus licensing distribution
- and modification of the Modified Version to whoever possesses a copy
- of it. In addition, you must do these things in the Modified Version:
- </p>
- <ol type="A" start="1">
- <li> Use in the Title Page (and on the covers, if any) a title distinct
- from that of the Document, and from those of previous versions
- (which should, if there were any, be listed in the History section
- of the Document). You may use the same title as a previous version
- if the original publisher of that version gives permission.
- </li><li> List on the Title Page, as authors, one or more persons or entities
- responsible for authorship of the modifications in the Modified
- Version, together with at least five of the principal authors of the
- Document (all of its principal authors, if it has fewer than five),
- unless they release you from this requirement.
- </li><li> State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- </li><li> Preserve all the copyright notices of the Document.
- </li><li> Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- </li><li> Include, immediately after the copyright notices, a license notice
- giving the public permission to use the Modified Version under the
- terms of this License, in the form shown in the Addendum below.
- </li><li> Preserve in that license notice the full lists of Invariant Sections
- and required Cover Texts given in the Document’s license notice.
- </li><li> Include an unaltered copy of this License.
- </li><li> Preserve the section Entitled “History”, Preserve its Title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page. If
- there is no section Entitled “History” in the Document, create one
- stating the title, year, authors, and publisher of the Document as
- given on its Title Page, then add an item describing the Modified
- Version as stated in the previous sentence.
- </li><li> Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and likewise
- the network locations given in the Document for previous versions
- it was based on. These may be placed in the “History” section.
- You may omit a network location for a work that was published at
- least four years before the Document itself, or if the original
- publisher of the version it refers to gives permission.
- </li><li> For any section Entitled “Acknowledgements” or “Dedications”, Preserve
- the Title of the section, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements and/or
- dedications given therein.
- </li><li> Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
- </li><li> Delete any section Entitled “Endorsements”. Such a section
- may not be included in the Modified Version.
- </li><li> Do not retitle any existing section to be Entitled “Endorsements” or
- to conflict in title with any Invariant Section.
- </li><li> Preserve any Warranty Disclaimers.
- </li></ol>
- <p>If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no material
- copied from the Document, you may at your option designate some or all
- of these sections as invariant. To do this, add their titles to the
- list of Invariant Sections in the Modified Version’s license notice.
- These titles must be distinct from any other section titles.
- </p>
- <p>You may add a section Entitled “Endorsements”, provided it contains
- nothing but endorsements of your Modified Version by various
- parties—for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition of a
- standard.
- </p>
- <p>You may add a passage of up to five words as a Front-Cover Text, and a
- passage of up to 25 words as a Back-Cover Text, to the end of the list
- of Cover Texts in the Modified Version. Only one passage of
- Front-Cover Text and one of Back-Cover Text may be added by (or
- through arrangements made by) any one entity. If the Document already
- includes a cover text for the same cover, previously added by you or
- by arrangement made by the same entity you are acting on behalf of,
- you may not add another; but you may replace the old one, on explicit
- permission from the previous publisher that added the old one.
- </p>
- <p>The author(s) and publisher(s) of the Document do not by this License
- give permission to use their names for publicity for or to assert or
- imply endorsement of any Modified Version.
- </p>
- </li><li> COMBINING DOCUMENTS
- <p>You may combine the Document with other documents released under this
- License, under the terms defined in section 4 above for modified
- versions, provided that you include in the combination all of the
- Invariant Sections of all of the original documents, unmodified, and
- list them all as Invariant Sections of your combined work in its
- license notice, and that you preserve all their Warranty Disclaimers.
- </p>
- <p>The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name but
- different contents, make the title of each such section unique by
- adding at the end of it, in parentheses, the name of the original
- author or publisher of that section if known, or else a unique number.
- Make the same adjustment to the section titles in the list of
- Invariant Sections in the license notice of the combined work.
- </p>
- <p>In the combination, you must combine any sections Entitled “History”
- in the various original documents, forming one section Entitled
- “History”; likewise combine any sections Entitled “Acknowledgements”,
- and any sections Entitled “Dedications”. You must delete all
- sections Entitled “Endorsements.”
- </p>
- </li><li> COLLECTIONS OF DOCUMENTS
- <p>You may make a collection consisting of the Document and other documents
- released under this License, and replace the individual copies of this
- License in the various documents with a single copy that is included in
- the collection, provided that you follow the rules of this License for
- verbatim copying of each of the documents in all other respects.
- </p>
- <p>You may extract a single document from such a collection, and distribute
- it individually under this License, provided you insert a copy of this
- License into the extracted document, and follow this License in all
- other respects regarding verbatim copying of that document.
- </p>
- </li><li> AGGREGATION WITH INDEPENDENT WORKS
- <p>A compilation of the Document or its derivatives with other separate
- and independent documents or works, in or on a volume of a storage or
- distribution medium, is called an “aggregate” if the copyright
- resulting from the compilation is not used to limit the legal rights
- of the compilation’s users beyond what the individual works permit.
- When the Document is included in an aggregate, this License does not
- apply to the other works in the aggregate which are not themselves
- derivative works of the Document.
- </p>
- <p>If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one half of
- the entire aggregate, the Document’s Cover Texts may be placed on
- covers that bracket the Document within the aggregate, or the
- electronic equivalent of covers if the Document is in electronic form.
- Otherwise they must appear on printed covers that bracket the whole
- aggregate.
- </p>
- </li><li> TRANSLATION
- <p>Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section 4.
- Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License, and all the license notices in the
- Document, and any Warranty Disclaimers, provided that you also include
- the original English version of this License and the original versions
- of those notices and disclaimers. In case of a disagreement between
- the translation and the original version of this License or a notice
- or disclaimer, the original version will prevail.
- </p>
- <p>If a section in the Document is Entitled “Acknowledgements”,
- “Dedications”, or “History”, the requirement (section 4) to Preserve
- its Title (section 1) will typically require changing the actual
- title.
- </p>
- </li><li> TERMINATION
- <p>You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided under this License. Any attempt
- otherwise to copy, modify, sublicense, or distribute it is void, and
- will automatically terminate your rights under this License.
- </p>
- <p>However, if you cease all violation of this License, then your license
- from a particular copyright holder is reinstated (a) provisionally,
- unless and until the copyright holder explicitly and finally
- terminates your license, and (b) permanently, if the copyright holder
- fails to notify you of the violation by some reasonable means prior to
- 60 days after the cessation.
- </p>
- <p>Moreover, your license from a particular copyright holder is
- reinstated permanently if the copyright holder notifies you of the
- violation by some reasonable means, this is the first time you have
- received notice of violation of this License (for any work) from that
- copyright holder, and you cure the violation prior to 30 days after
- your receipt of the notice.
- </p>
- <p>Termination of your rights under this section does not terminate the
- licenses of parties who have received copies or rights from you under
- this License. If your rights have been terminated and not permanently
- reinstated, receipt of a copy of some or all of the same material does
- not give you any rights to use it.
- </p>
- </li><li> FUTURE REVISIONS OF THIS LICENSE
- <p>The Free Software Foundation may publish new, revised versions
- of the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- <a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
- </p>
- <p>Each version of the License is given a distinguishing version number.
- If the Document specifies that a particular numbered version of this
- License “or any later version” applies to it, you have the option of
- following the terms and conditions either of that specified version or
- of any later version that has been published (not as a draft) by the
- Free Software Foundation. If the Document does not specify a version
- number of this License, you may choose any version ever published (not
- as a draft) by the Free Software Foundation. If the Document
- specifies that a proxy can decide which future versions of this
- License can be used, that proxy’s public statement of acceptance of a
- version permanently authorizes you to choose that version for the
- Document.
- </p>
- </li><li> RELICENSING
- <p>“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
- World Wide Web server that publishes copyrightable works and also
- provides prominent facilities for anybody to edit those works. A
- public wiki that anybody can edit is an example of such a server. A
- “Massive Multiauthor Collaboration” (or “MMC”) contained in the
- site means any set of copyrightable works thus published on the MMC
- site.
- </p>
- <p>“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
- license published by Creative Commons Corporation, a not-for-profit
- corporation with a principal place of business in San Francisco,
- California, as well as future copyleft versions of that license
- published by that same organization.
- </p>
- <p>“Incorporate” means to publish or republish a Document, in whole or
- in part, as part of another Document.
- </p>
- <p>An MMC is “eligible for relicensing” if it is licensed under this
- License, and if all works that were first published under this License
- somewhere other than this MMC, and subsequently incorporated in whole
- or in part into the MMC, (1) had no cover texts or invariant sections,
- and (2) were thus incorporated prior to November 1, 2008.
- </p>
- <p>The operator of an MMC Site may republish an MMC contained in the site
- under CC-BY-SA on the same site at any time before August 1, 2009,
- provided the MMC is eligible for relicensing.
- </p>
- </li></ol>
- <span id="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></span><h3 class="heading">ADDENDUM: How to use this License for your documents</h3>
- <p>To use this License in a document you have written, include a copy of
- the License in the document and put the following copyright and
- license notices just after the title page:
- </p>
- <div class="example">
- <pre class="example"> Copyright (C) <var>year</var> <var>your name</var>.
- 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 no Invariant Sections, no Front-Cover Texts, and no Back-Cover
- Texts. A copy of the license is included in the section entitled ``GNU
- Free Documentation License''.
- </pre></div>
- <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
- replace the “with…Texts.” line with this:
- </p>
- <div class="example">
- <pre class="example"> with the Invariant Sections being <var>list their titles</var>, with
- the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
- being <var>list</var>.
- </pre></div>
- <p>If you have Invariant Sections without Cover Texts, or some other
- combination of the three, merge those two alternatives to suit the
- situation.
- </p>
- <p>If your document contains nontrivial examples of program code, we
- recommend releasing these examples in parallel under your choice of
- free software license, such as the GNU General Public License,
- to permit their use in free software.
- </p>
- <hr>
- <span id="LD-Index"></span><div class="header">
- <p>
- Previous: <a href="#GNU-Free-Documentation-License" accesskey="p" rel="prev">GNU Free Documentation License</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <span id="LD-Index-1"></span><h2 class="unnumbered">LD Index</h2>
- <table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#LD-Index_cp_symbol-1"><b>"</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-2"><b>-</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-3"><b>.</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-4"><b>/</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-5"><b>3</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-6"><b>:</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-7"><b>=</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-8"><b>></b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-9"><b>[</b></a>
-
- <br>
- <a class="summary-letter" href="#LD-Index_cp_letter-A"><b>A</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-B"><b>B</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-C"><b>C</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-D"><b>D</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-E"><b>E</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-F"><b>F</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-G"><b>G</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-H"><b>H</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-I"><b>I</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-K"><b>K</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-L"><b>L</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-M"><b>M</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-N"><b>N</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-O"><b>O</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-P"><b>P</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-Q"><b>Q</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-R"><b>R</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-S"><b>S</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-T"><b>T</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-U"><b>U</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-V"><b>V</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-W"><b>W</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-X"><b>X</b></a>
-
- </td></tr></table>
- <table class="index-cp" border="0">
- <tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-1">"</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_0022"><code>"</code></a>:</td><td> </td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-2">-</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_0028"><code>-(</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002daccept_002dunknown_002dinput_002darch"><code>--accept-unknown-input-arch</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dadd_002dneeded"><code>--add-needed</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dadd_002dstdcall_002dalias"><code>--add-stdcall-alias</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dallow_002dmultiple_002ddefinition"><code>--allow-multiple-definition</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dallow_002dshlib_002dundefined"><code>--allow-shlib-undefined</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002das_002dneeded"><code>--as-needed</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002daudit-AUDITLIB"><code>--audit <var>AUDITLIB</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dauxiliary_003dname"><code>--auxiliary=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dbank_002dwindow"><code>--bank-window</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dbase_002dfile"><code>--base-file</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dbe8"><code>--be8</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dbranch_002dstub-on-C_002dSKY"><code>--branch-stub on C-SKY</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dbss_002dplt"><code>--bss-plt</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dbuild_002did"><code>--build-id</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dbuild_002did_003dstyle"><code>--build-id=<var>style</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcheck_002dsections"><code>--check-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcmse_002dimplib"><code>--cmse-implib</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcode_002dregion"><code>--code-region</code></a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcompact_002dbranches"><code>--compact-branches</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dnone"><code>--compress-debug-sections=none</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dzlib"><code>--compress-debug-sections=zlib</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgabi"><code>--compress-debug-sections=zlib-gabi</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgnu"><code>--compress-debug-sections=zlib-gnu</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dzstd"><code>--compress-debug-sections=zstd</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcopy_002ddt_002dneeded_002dentries"><code>--copy-dt-needed-entries</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dcref"><code>--cref</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dctf_002dshare_002dtypes"><code>--ctf-share-types</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dctf_002dvariables"><code>--ctf-variables</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddata_002dregion"><code>--data-region</code></a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddefault_002dimported_002dsymver"><code>--default-imported-symver</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddefault_002dscript_003dscript"><code>--default-script=<var>script</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddefault_002dsymver"><code>--default-symver</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddefsym_003dsymbol_003dexp"><code>--defsym=<var>symbol</var>=<var>exp</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddemangle_005b_003dstyle_005d"><code>--demangle[=<var>style</var>]</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddepaudit-AUDITLIB"><code>--depaudit <var>AUDITLIB</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddependency_002dfile_003ddepfile"><code>--dependency-file=<var>depfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dauto_002dimage_002dbase"><code>--disable-auto-image-base</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dauto_002dimport"><code>--disable-auto-import</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dlarge_002daddress_002daware"><code>--disable-large-address-aware</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dlinker_002dversion"><code>--disable-linker-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dlong_002dsection_002dnames"><code>--disable-long-section-names</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dmultiple_002dabs_002ddefs"><code>--disable-multiple-abs-defs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dnew_002ddtags"><code>--disable-new-dtags</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002druntime_002dpseudo_002dreloc"><code>--disable-runtime-pseudo-reloc</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dsec_002dtransformation"><code>--disable-sec-transformation</code></a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dstdcall_002dfixup"><code>--disable-stdcall-fixup</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddiscard_002dall"><code>--discard-all</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddiscard_002dlocals"><code>--discard-locals</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddll"><code>--dll</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddll_002dsearch_002dprefix"><code>--dll-search-prefix</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddotsyms"><code>--dotsyms</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddsbt_002dindex"><code>--dsbt-index</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddsbt_002dsize"><code>--dsbt-size</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlinker_003dfile"><code>--dynamic-linker=<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlist_002dcpp_002dnew"><code>--dynamic-list-cpp-new</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlist_002dcpp_002dtypeinfo"><code>--dynamic-list-cpp-typeinfo</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlist_002ddata"><code>--dynamic-list-data</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlist_003ddynamic_002dlist_002dfile"><code>--dynamic-list=<var>dynamic-list-file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ddynamicbase"><code>--dynamicbase</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002deh_002dframe_002dhdr"><code>--eh-frame-hdr</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dembedded_002drelocs"><code>--embedded-relocs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002demit_002drelocs"><code>--emit-relocs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002demit_002dstack_002dsyms"><code>--emit-stack-syms</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002demit_002dstub_002dsyms"><code>--emit-stub-syms</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002demit_002dstub_002dsyms-1"><code>--emit-stub-syms</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002demit_002dstub_002dsyms-2"><code>--emit-stub-syms</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dauto_002dimage_002dbase"><code>--enable-auto-image-base</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dauto_002dimport"><code>--enable-auto-import</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dextra_002dpe_002ddebug"><code>--enable-extra-pe-debug</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dlinker_002dversion"><code>--enable-linker-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dlong_002dsection_002dnames"><code>--enable-long-section-names</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dnew_002ddtags"><code>--enable-new-dtags</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dnon_002dcontiguous_002dregions"><code>--enable-non-contiguous-regions</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dnon_002dcontiguous_002dregions_002dwarnings"><code>--enable-non-contiguous-regions-warnings</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dreloc_002dsection"><code>--enable-reloc-section</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002druntime_002dpseudo_002dreloc"><code>--enable-runtime-pseudo-reloc</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dstdcall_002dfixup"><code>--enable-stdcall-fixup</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dentry_003dentry"><code>--entry=<var>entry</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002derror_002dexecstack"><code>--error-execstack</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002derror_002dhandling_002dscript_003dscriptname"><code>--error-handling-script=<var>scriptname</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002derror_002drwx_002dsegments"><code>--error-rwx-segments</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002derror_002dunresolved_002dsymbols"><code>--error-unresolved-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dexclude_002dall_002dsymbols"><code>--exclude-all-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dexclude_002dlibs"><code>--exclude-libs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dexclude_002dmodules_002dfor_002dimplib"><code>--exclude-modules-for-implib</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dexclude_002dsymbols"><code>--exclude-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dexport_002dall_002dsymbols"><code>--export-all-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dexport_002ddynamic"><code>--export-dynamic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dexport_002ddynamic_002dsymbol_002dlist_003dfile"><code>--export-dynamic-symbol-list=<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dexport_002ddynamic_002dsymbol_003dglob"><code>--export-dynamic-symbol=<var>glob</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dextra_002doverlay_002dstubs"><code>--extra-overlay-stubs</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfatal_002dwarnings"><code>--fatal-warnings</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfile_002dalignment"><code>--file-alignment</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfilter_003dname"><code>--filter=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002darm1176"><code>--fix-arm1176</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dcortex_002da53_002d835769"><code>--fix-cortex-a53-835769</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dcortex_002da8"><code>--fix-cortex-a8</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dstm32l4xx_002d629360"><code>--fix-stm32l4xx-629360</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dv4bx"><code>--fix-v4bx</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dv4bx_002dinterworking"><code>--fix-v4bx-interworking</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dforce_002ddynamic"><code>--force-dynamic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dforce_002dexe_002dsuffix"><code>--force-exe-suffix</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dforce_002dgroup_002dallocation"><code>--force-group-allocation</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dforceinteg"><code>--forceinteg</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dformat_003dformat"><code>--format=<var>format</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dformat_003dversion"><code>--format=<var>version</var></code></a>:</td><td> </td><td valign="top"><a href="#TI-COFF">TI COFF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dgc_002dkeep_002dexported"><code>--gc-keep-exported</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dgc_002dsections"><code>--gc-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dgot"><code>--got</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dgot_003dtype"><code>--got=<var>type</var></code></a>:</td><td> </td><td valign="top"><a href="#M68K">M68K</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dgpsize_003dvalue"><code>--gpsize=<var>value</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dhash_002dsize_003dnumber"><code>--hash-size=<var>number</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dhash_002dstyle_003dstyle"><code>--hash-style=<var>style</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dheap"><code>--heap</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dhelp"><code>--help</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dhigh_002dentropy_002dva"><code>--high-entropy-va</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dignore_002dbranch_002disa"><code>--ignore-branch-isa</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dignore_002dbranch_002disa-1"><code>--ignore-branch-isa</code></a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dimage_002dbase"><code>--image-base</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dimagic"><code>--imagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002din_002dimplib_003dfile"><code>--in-implib=<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dinsert_002dtimestamp"><code>--insert-timestamp</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dinsn32"><code>--insn32</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dinsn32-1"><code>--insn32</code></a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002djust_002dsymbols_003dfile"><code>--just-symbols=<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dkill_002dat"><code>--kill-at</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dlarge_002daddress_002daware"><code>--large-address-aware</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dld_002dgenerated_002dunwind_002dinfo"><code>--ld-generated-unwind-info</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dleading_002dunderscore"><code>--leading-underscore</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dlibrary_002dpath_003ddir"><code>--library-path=<var>dir</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dlibrary_003dnamespec"><code>--library=<var>namespec</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dlocal_002dstore_003dlo_003ahi"><code>--local-store=lo:hi</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dlong_002dplt"><code>--long-plt</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dmajor_002dimage_002dversion"><code>--major-image-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dmajor_002dos_002dversion"><code>--major-os-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dmajor_002dsubsystem_002dversion"><code>--major-subsystem-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dmax_002dcache_002dsize_003dsize"><code>--max-cache-size=<var>size</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dmerge_002dexidx_002dentries"><code>--merge-exidx-entries</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dminor_002dimage_002dversion"><code>--minor-image-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dminor_002dos_002dversion"><code>--minor-os-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dminor_002dsubsystem_002dversion"><code>--minor-subsystem-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dmri_002dscript_003dMRI_002dcmdfile"><code>--mri-script=<var>MRI-cmdfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dmulti_002dsubspace"><code>--multi-subspace</code></a>:</td><td> </td><td valign="top"><a href="#HPPA-ELF32">HPPA ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dnmagic"><code>--nmagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dnmagic-1"><code>--nmagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002daccept_002dunknown_002dinput_002darch"><code>--no-accept-unknown-input-arch</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dadd_002dneeded"><code>--no-add-needed</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dallow_002dshlib_002dundefined"><code>--no-allow-shlib-undefined</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dapply_002ddynamic_002drelocs"><code>--no-apply-dynamic-relocs</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002das_002dneeded"><code>--no-as-needed</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dbind"><code>--no-bind</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dcheck_002dsections"><code>--no-check-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dcompact_002dbranches"><code>--no-compact-branches</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dcopy_002ddt_002dneeded_002dentries"><code>--no-copy-dt-needed-entries</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dctf_002dvariables"><code>--no-ctf-variables</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002ddefine_002dcommon"><code>--no-define-common</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002ddemangle"><code>--no-demangle</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002ddotsyms"><code>--no-dotsyms</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002ddynamic_002dlinker"><code>--no-dynamic-linker</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002deh_002dframe_002dhdr"><code>--no-eh-frame-hdr</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002denum_002dsize_002dwarning"><code>--no-enum-size-warning</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dexport_002ddynamic"><code>--no-export-dynamic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dfatal_002dwarnings"><code>--no-fatal-warnings</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dfix_002darm1176"><code>--no-fix-arm1176</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dfix_002dcortex_002da53_002d835769"><code>--no-fix-cortex-a53-835769</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dfix_002dcortex_002da8"><code>--no-fix-cortex-a8</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dgc_002dsections"><code>--no-gc-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dignore_002dbranch_002disa"><code>--no-ignore-branch-isa</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dignore_002dbranch_002disa-1"><code>--no-ignore-branch-isa</code></a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dinline_002doptimize"><code>--no-inline-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dinsn32"><code>--no-insn32</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dinsn32-1"><code>--no-insn32</code></a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002disolation"><code>--no-isolation</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dkeep_002dmemory"><code>--no-keep-memory</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dleading_002dunderscore"><code>--no-leading-underscore</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dmerge_002dexidx_002dentries"><code>--no-merge-exidx-entries</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dmerge_002dexidx_002dentries-1"><code>--no-merge-exidx-entries</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dmulti_002dtoc"><code>--no-multi-toc</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002domagic"><code>--no-omagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002domagic-1"><code>--no-omagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dopd_002doptimize"><code>--no-opd-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002doverlays"><code>--no-overlays</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dplt_002dalign"><code>--no-plt-align</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dplt_002dlocalentry"><code>--no-plt-localentry</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dplt_002dstatic_002dchain"><code>--no-plt-static-chain</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dplt_002dthread_002dsafe"><code>--no-plt-thread-safe</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dpower10_002dstubs"><code>--no-power10-stubs</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dprint_002dgc_002dsections"><code>--no-print-gc-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dprint_002dmap_002ddiscarded"><code>--no-print-map-discarded</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dprint_002dmap_002dlocals"><code>--no-print-map-locals</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dsave_002drestore_002dfuncs"><code>--no-save-restore-funcs</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dseh"><code>--no-seh</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dstrip_002ddiscarded"><code>--no-strip-discarded</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtls_002dget_002daddr_002doptimize"><code>--no-tls-get-addr-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtls_002dget_002daddr_002dregsave"><code>--no-tls-get-addr-regsave</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtls_002doptimize"><code>--no-tls-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtls_002doptimize-1"><code>--no-tls-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtoc_002doptimize"><code>--no-toc-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtoc_002dsort"><code>--no-toc-sort</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtrampoline"><code>--no-trampoline</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dundefined"><code>--no-undefined</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dundefined_002dversion"><code>--no-undefined-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwarn_002dmismatch"><code>--no-warn-mismatch</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwarn_002dsearch_002dmismatch"><code>--no-warn-search-mismatch</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwarnings"><code>--no-warnings</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwchar_002dsize_002dwarning"><code>--no-wchar-size-warning</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwhole_002darchive"><code>--no-whole-archive</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dnoinhibit_002dexec"><code>--noinhibit-exec</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dnon_002doverlapping_002dopd"><code>--non-overlapping-opd</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dnxcompat"><code>--nxcompat</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002doformat_003doutput_002dformat"><code>--oformat=<var>output-format</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002domagic"><code>--omagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002domagic-1"><code>--omagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dorphan_002dhandling_003dMODE"><code>--orphan-handling=<var>MODE</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dout_002dimplib"><code>--out-implib</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002doutput_002ddef"><code>--output-def</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002doutput_003doutput"><code>--output=<var>output</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dpackage_002dmetadata_003dJSON"><code>--package-metadata=<var>JSON</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dpic_002dexecutable"><code>--pic-executable</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dpic_002dveneer"><code>--pic-veneer</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dplt_002dalign"><code>--plt-align</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dplt_002dlocalentry"><code>--plt-localentry</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dplt_002dstatic_002dchain"><code>--plt-static-chain</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dplt_002dthread_002dsafe"><code>--plt-thread-safe</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dplugin"><code>--plugin</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dpop_002dstate"><code>--pop-state</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dpower10_002dstubs"><code>--power10-stubs</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dgc_002dsections"><code>--print-gc-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dmap"><code>--print-map</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dmap_002ddiscarded"><code>--print-map-discarded</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dmap_002dlocals"><code>--print-map-locals</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dmemory_002dusage"><code>--print-memory-usage</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002doutput_002dformat"><code>--print-output-format</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dpush_002dstate"><code>--push-state</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dreduce_002dmemory_002doverheads"><code>--reduce-memory-overheads</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002drelax"><code>--relax</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002drelax-on-Nios-II"><code>--relax on Nios II</code></a>:</td><td> </td><td valign="top"><a href="#Nios-II">Nios II</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002drelax-on-PowerPC"><code>--relax on PowerPC</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002drelax-on-Xtensa"><samp>--relax</samp> on Xtensa</a>:</td><td> </td><td valign="top"><a href="#Xtensa">Xtensa</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002drelocatable"><code>--relocatable</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dremap_002dinputs_002dfile_003dfile"><code>--remap-inputs-file=<samp>file</samp></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dremap_002dinputs_003dpattern_003dfilename"><code>--remap-inputs=<samp>pattern</samp>=<samp>filename</samp></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002drequire_002ddefined_003dsymbol"><code>--require-defined=<var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dretain_002dsymbols_002dfile_003dfilename"><code>--retain-symbols-file=<var>filename</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002ds390_002dpgste"><code>--s390-pgste</code></a>:</td><td> </td><td valign="top"><a href="#S_002f390-ELF">S/390 ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsave_002drestore_002dfuncs"><code>--save-restore-funcs</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dscript_003dscript"><code>--script=<var>script</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsdata_002dgot"><code>--sdata-got</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsection_002dalignment"><code>--section-alignment</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsection_002dstart_003dsectionname_003dorg"><code>--section-start=<var>sectionname</var>=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsecure_002dplt"><code>--secure-plt</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsort_002dcommon"><code>--sort-common</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsort_002dsection_003dalignment"><code>--sort-section=alignment</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsort_002dsection_003dname"><code>--sort-section=name</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dspare_002ddynamic_002dtags"><code>--spare-dynamic-tags</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsplit_002dby_002dfile"><code>--split-by-file</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsplit_002dby_002dreloc"><code>--split-by-reloc</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstack"><code>--stack</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstack_002danalysis"><code>--stack-analysis</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstats"><code>--stats</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstrip_002dall"><code>--strip-all</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstrip_002ddebug"><code>--strip-debug</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstrip_002ddiscarded"><code>--strip-discarded</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstub_002dgroup_002dsize"><code>--stub-group-size</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstub_002dgroup_002dsize-on-C_002dSKY"><code>--stub-group-size on C-SKY</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstub_002dgroup_002dsize_003dN"><code>--stub-group-size=<var>N</var></code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dstub_002dgroup_002dsize_003dN-1"><code>--stub-group-size=<var>N</var></code></a>:</td><td> </td><td valign="top"><a href="#HPPA-ELF32">HPPA ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsubsystem"><code>--subsystem</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsupport_002dold_002dcode"><code>--support-old-code</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dsysroot_003ddirectory"><code>--sysroot=<var>directory</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtarget_002dhelp"><code>--target-help</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtarget1_002dabs"><code>--target1-abs</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtarget1_002drel"><code>--target1-rel</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtarget2_003dtype"><code>--target2=<var>type</var></code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtask_002dlink"><code>--task-link</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dthumb_002dentry_003dentry"><code>--thumb-entry=<var>entry</var></code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtls_002dget_002daddr_002doptimize"><code>--tls-get-addr-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtls_002dget_002daddr_002dregsave"><code>--tls-get-addr-regsave</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtrace"><code>--trace</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtrace_002dsymbol_003dsymbol"><code>--trace-symbol=<var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtraditional_002dformat"><code>--traditional-format</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dtsaware"><code>--tsaware</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dundefined_003dsymbol"><code>--undefined=<var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dunique_005b_003dSECTION_005d"><code>--unique[=<var>SECTION</var>]</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dunresolved_002dsymbols"><code>--unresolved-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002duse_002dblx"><code>--use-blx</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002duse_002dnul_002dprefixed_002dimport_002dtables"><code>--use-nul-prefixed-import-tables</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dverbose_005b_003dNUMBER_005d"><code>--verbose[=<var>NUMBER</var>]</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dversion"><code>--version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dversion_002dscript_003dversion_002dscriptfile"><code>--version-script=<var>version-scriptfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dvfp11_002ddenorm_002dfix"><code>--vfp11-denorm-fix</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dalternate_002dem"><code>--warn-alternate-em</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dcommon"><code>--warn-common</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dconstructors"><code>--warn-constructors</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dexecstack"><code>--warn-execstack</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dmultiple_002dgp"><code>--warn-multiple-gp</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002donce"><code>--warn-once</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002drwx_002dsegments"><code>--warn-rwx-segments</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dsection_002dalign"><code>--warn-section-align</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dtextrel"><code>--warn-textrel</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dunresolved_002dsymbols"><code>--warn-unresolved-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwdmdriver"><code>--wdmdriver</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwhole_002darchive"><code>--whole-archive</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dwrap_003dsymbol"><code>--wrap=<var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002da-keyword"><code>-a <var>keyword</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dassert-keyword"><code>-assert <var>keyword</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002db-format"><code>-b <var>format</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dBdynamic"><code>-Bdynamic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dBgroup"><code>-Bgroup</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dBno_002dsymbolic"><code>-Bno-symbolic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dBshareable"><code>-Bshareable</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dBstatic"><code>-Bstatic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dBsymbolic"><code>-Bsymbolic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dBsymbolic_002dfunctions"><code>-Bsymbolic-functions</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dc-MRI_002dcmdfile"><code>-c <var>MRI-cmdfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dcall_005fshared"><code>-call_shared</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dd"><code>-d</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002ddc"><code>-dc</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002ddn"><code>-dn</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002ddp"><code>-dp</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002ddT-script"><code>-dT <var>script</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002ddy"><code>-dy</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dE"><code>-E</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002de-entry"><code>-e <var>entry</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dEB"><code>-EB</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dEL"><code>-EL</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002df-name"><code>-f <var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dF-name"><code>-F <var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dfini_003dname"><code>-fini=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dg"><code>-g</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dG-value"><code>-G <var>value</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dh-name"><code>-h <var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002di"><code>-i</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dIfile"><code>-I<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dinit_003dname"><code>-init=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dL-dir"><code>-L <var>dir</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dl-namespec"><code>-l <var>namespec</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dM"><code>-M</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dm-emulation"><code>-m <var>emulation</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dMap_003dmapfile"><code>-Map=<var>mapfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dn"><code>-n</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dN"><code>-N</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dN-1"><code>-N</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dn-1"><code>-n</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dno_002dpie"><code>-no-pie</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002d_002dno_002drelax">–no-relax</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dnon_005fshared"><code>-non_shared</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dnostdlib"><code>-nostdlib</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dO-level"><code>-O <var>level</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002do-output"><code>-o <var>output</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dP-AUDITLIB"><code>-P <var>AUDITLIB</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dpie"><code>-pie</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dplugin-name"><code>-plugin <var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dq"><code>-q</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dqmagic"><code>-qmagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dQy"><code>-Qy</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dr"><code>-r</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dR-file"><code>-R <var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002drpath_002dlink_003ddir"><code>-rpath-link=<var>dir</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002drpath_003ddir"><code>-rpath=<var>dir</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002ds"><code>-s</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dS"><code>-S</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dshared"><code>-shared</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dsoname_003dname"><code>-soname=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dstatic"><code>-static</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dt"><code>-t</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dT-script"><code>-T <var>script</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dTbss_003dorg"><code>-Tbss=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dTdata_003dorg"><code>-Tdata=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dTldata_002dsegment_003dorg"><code>-Tldata-segment=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dTrodata_002dsegment_003dorg"><code>-Trodata-segment=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dTtext_002dsegment_003dorg"><code>-Ttext-segment=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dTtext_003dorg"><code>-Ttext=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002du-symbol"><code>-u <var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dUr"><code>-Ur</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dv"><code>-v</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dV"><code>-V</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dw"><code>-w</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dx"><code>-x</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dX"><code>-X</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dY-path"><code>-Y <var>path</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dy-symbol"><code>-y <var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dz"><code>-z</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dz-defs"><code>-z defs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dz-keyword"><code>-z <var>keyword</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dz-muldefs"><code>-z muldefs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002dz-undefs"><code>-z undefs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-3">.</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002e"><code>.</code></a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-4">/</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_002fDISCARD_002f">/DISCARD/</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Discarding">Output Section Discarding</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-5">3</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-32_002dbit-PLT-entries">32-bit PLT entries</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-6">:</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_003aphdr"><code>:<var>phdr</var></code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Phdr">Output Section Phdr</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-7">=</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_003dfillexp"><code>=<var>fillexp</var></code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Fill">Output Section Fill</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-8">></th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_003eregion"><code>><var>region</var></code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Region">Output Section Region</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_symbol-9">[</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-_005bCOMMON_005d">[COMMON]</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-A">A</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-AArch64-rela-addend">AArch64 rela addend</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ABSOLUTE-_0028MRI_0029"><code>ABSOLUTE</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-absolute-and-relocatable-symbols">absolute and relocatable symbols</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-absolute-expressions">absolute expressions</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ABSOLUTE_0028exp_0029"><code>ABSOLUTE(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ADDR_0028section_0029"><code>ADDR(<var>section</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-address_002c-section">address, section</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Address">Output Section Address</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ALIAS-_0028MRI_0029"><code>ALIAS</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ALIGN-_0028MRI_0029"><code>ALIGN</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-align-expression">align expression</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-align-location-counter">align location counter</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ALIGN_0028align_0029"><code>ALIGN(<var>align</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ALIGN_0028exp_002calign_0029"><code>ALIGN(<var>exp</var>,<var>align</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ALIGN_0028section_005falign_0029"><code>ALIGN(<var>section_align</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Forced-Output-Alignment">Forced Output Alignment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-aligned-common-symbols">aligned common symbols</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ALIGNOF_0028section_0029"><code>ALIGNOF(<var>section</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-allocating-memory">allocating memory</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-architecture">architecture</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-archive-files_002c-from-cmd-line">archive files, from cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-archive-search-path-in-linker-script">archive search path in linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-arithmetic">arithmetic</a>:</td><td> </td><td valign="top"><a href="#Expressions">Expressions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-arithmetic-operators">arithmetic operators</a>:</td><td> </td><td valign="top"><a href="#Operators">Operators</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ARM-interworking-support">ARM interworking support</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ARM1176-erratum-workaround">ARM1176 erratum workaround</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ASCIZ-_0060_0060string_0027_0027"><code>ASCIZ ``<var>string</var>''</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ASSERT"><code>ASSERT</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-assertion-in-linker-script">assertion in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-assignment-in-scripts">assignment in scripts</a>:</td><td> </td><td valign="top"><a href="#Assignments">Assignments</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-AS_005fNEEDED_0028files_0029"><code>AS_NEEDED(<var>files</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-AT_0028lma_0029"><code>AT(<var>lma</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-AT_003elma_005fregion"><code>AT><var>lma_region</var></code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-automatic-data-imports">automatic data imports</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-B">B</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-back-end">back end</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-BASE-_0028MRI_0029"><code>BASE</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-BE8">BE8</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-BFD-canonical-format">BFD canonical format</a>:</td><td> </td><td valign="top"><a href="#Canonical-format">Canonical format</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-BFD-requirements">BFD requirements</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-big_002dendian-objects">big-endian objects</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-binary-input-format">binary input format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-BLOCK_0028exp_0029"><code>BLOCK(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-bug-criteria">bug criteria</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-bug-reports">bug reports</a>:</td><td> </td><td valign="top"><a href="#Bug-Reporting">Bug Reporting</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-bugs-in-ld">bugs in <code>ld</code></a>:</td><td> </td><td valign="top"><a href="#Reporting-Bugs">Reporting Bugs</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-BYTE_0028expression_0029"><code>BYTE(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-C">C</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-C_002b_002b-constructors_002c-arranging-in-link">C++ constructors, arranging in link</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-CHIP-_0028MRI_0029"><code>CHIP</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-COLLECT_005fNO_005fDEMANGLE"><code>COLLECT_NO_DEMANGLE</code></a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-combining-symbols_002c-warnings-on">combining symbols, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-COMDAT">COMDAT</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-COMDAT-1">COMDAT</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-command-files">command files</a>:</td><td> </td><td valign="top"><a href="#Scripts">Scripts</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-command-line">command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-common-allocation">common allocation</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-common-allocation-1">common allocation</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-common-allocation-in-linker-script">common allocation in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-common-allocation-in-linker-script-1">common allocation in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-common-symbol-placement">common symbol placement</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-COMMONPAGESIZE"><code>COMMONPAGESIZE</code></a>:</td><td> </td><td valign="top"><a href="#Symbolic-Constants">Symbolic Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-compatibility_002c-MRI">compatibility, MRI</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-CONSTANT"><code>CONSTANT</code></a>:</td><td> </td><td valign="top"><a href="#Symbolic-Constants">Symbolic Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-constants-in-linker-scripts">constants in linker scripts</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-constraints-on-output-sections">constraints on output sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Constraint">Output Section Constraint</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-constructors">constructors</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-CONSTRUCTORS"><code>CONSTRUCTORS</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-constructors_002c-arranging-in-link">constructors, arranging in link</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Cortex_002dA53-erratum-835769-workaround">Cortex-A53 erratum 835769 workaround</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Cortex_002dA8-erratum-workaround">Cortex-A8 erratum workaround</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-crash-of-linker">crash of linker</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-CREATE_005fOBJECT_005fSYMBOLS"><code>CREATE_OBJECT_SYMBOLS</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-creating-a-DEF-file">creating a DEF file</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-cross-reference-table">cross reference table</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-cross-references">cross references</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-cross-references-1">cross references</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ctf-type-sharing">ctf type sharing</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ctf-variables">ctf variables</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-current-output-location">current output location</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-D">D</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-data">data</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DATA_005fSEGMENT_005fALIGN_0028maxpagesize_002c-commonpagesize_0029"><code>DATA_SEGMENT_ALIGN(<var>maxpagesize</var>, <var>commonpagesize</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DATA_005fSEGMENT_005fEND_0028exp_0029"><code>DATA_SEGMENT_END(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DATA_005fSEGMENT_005fRELRO_005fEND_0028offset_002c-exp_0029"><code>DATA_SEGMENT_RELRO_END(<var>offset</var>, <var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-dbx">dbx</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DEF-files_002c-creating">DEF files, creating</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-default-emulation">default emulation</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-default-input-format">default input format</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-defined-symbol">defined symbol</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DEFINED_0028symbol_0029"><code>DEFINED(<var>symbol</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-deleting-local-symbols">deleting local symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-demangling_002c-default">demangling, default</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-demangling_002c-from-command-line">demangling, from command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-dependency-file">dependency file</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-direct-linking-to-a-dll">direct linking to a dll</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-discarding-sections">discarding sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Discarding">Output Section Discarding</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-discontinuous-memory">discontinuous memory</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DLLs_002c-creating">DLLs, creating</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DLLs_002c-creating-1">DLLs, creating</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DLLs_002c-creating-2">DLLs, creating</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-DLLs_002c-linking-to">DLLs, linking to</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-dot">dot</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-dot-inside-sections">dot inside sections</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-dot-outside-sections">dot outside sections</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-dynamic-linker_002c-from-command-line">dynamic linker, from command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-dynamic-symbol-table">dynamic symbol table</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-E">E</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ELF-program-headers">ELF program headers</a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ELF-symbol-visibility">ELF symbol visibility</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-emulation">emulation</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-emulation_002c-default">emulation, default</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-END-_0028MRI_0029"><code>END</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-endianness">endianness</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-entry-point">entry point</a>:</td><td> </td><td valign="top"><a href="#Entry-Point">Entry Point</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-entry-point_002c-from-command-line">entry point, from command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-entry-point_002c-thumb">entry point, thumb</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ENTRY_0028symbol_0029"><code>ENTRY(<var>symbol</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Entry-Point">Entry Point</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-error-on-valid-input">error on valid input</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-example-of-linker-script">example of linker script</a>:</td><td> </td><td valign="top"><a href="#Simple-Example">Simple Example</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-EXCLUDE_005fFILE">EXCLUDE_FILE</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Basics">Input Section Basics</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-executable-segments_002c-warnings-on">executable segments, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-executable-stack_002c-warnings-on">executable stack, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-export-dynamic-symbol">export dynamic symbol</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-export-dynamic-symbol-list">export dynamic symbol list</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-exporting-DLL-symbols">exporting DLL symbols</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-expression-evaluation-order">expression evaluation order</a>:</td><td> </td><td valign="top"><a href="#Evaluation">Evaluation</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-expression-sections">expression sections</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-expression_002c-absolute">expression, absolute</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-expressions">expressions</a>:</td><td> </td><td valign="top"><a href="#Expressions">Expressions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-EXTERN"><code>EXTERN</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-F">F</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-fatal-signal">fatal signal</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-file-name-wildcard-patterns">file name wildcard patterns</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-FILEHDR"><code>FILEHDR</code></a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-filename-symbols">filename symbols</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-fill-pattern_002c-entire-section">fill pattern, entire section</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Fill">Output Section Fill</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-FILL_0028expression_0029"><code>FILL(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-finalization-function">finalization function</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-first-input-file">first input file</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-first-instruction">first instruction</a>:</td><td> </td><td valign="top"><a href="#Entry-Point">Entry Point</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-FIX_005fV4BX">FIX_V4BX</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-FIX_005fV4BX_005fINTERWORKING">FIX_V4BX_INTERWORKING</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-FORCE_005fCOMMON_005fALLOCATION"><code>FORCE_COMMON_ALLOCATION</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-FORCE_005fGROUP_005fALLOCATION"><code>FORCE_GROUP_ALLOCATION</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-forcing-input-section-alignment">forcing input section alignment</a>:</td><td> </td><td valign="top"><a href="#Forced-Input-Alignment">Forced Input Alignment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-forcing-output-section-alignment">forcing output section alignment</a>:</td><td> </td><td valign="top"><a href="#Forced-Output-Alignment">Forced Output Alignment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-forcing-the-creation-of-dynamic-sections">forcing the creation of dynamic sections</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-FORMAT-_0028MRI_0029"><code>FORMAT</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-functions-in-expressions">functions in expressions</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-G">G</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-garbage-collection">garbage collection</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-garbage-collection-1">garbage collection</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-garbage-collection-2">garbage collection</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-garbage-collection-3">garbage collection</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Keep">Input Section Keep</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-generating-optimized-output">generating optimized output</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-GNU-linker"><small>GNU</small> linker</a>:</td><td> </td><td valign="top"><a href="#Overview">Overview</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-GNUTARGET"><code>GNUTARGET</code></a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-group-allocation-in-linker-script">group allocation in linker script</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-group-allocation-in-linker-script-1">group allocation in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-GROUP_0028files_0029"><code>GROUP(<var>files</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-grouping-input-files">grouping input files</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-groups-of-archives">groups of archives</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-H">H</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-H8_002f300-support">H8/300 support</a>:</td><td> </td><td valign="top"><a href="#H8_002f300">H8/300</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-header-size">header size</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-heap-size">heap size</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-help">help</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-HIDDEN">HIDDEN</a>:</td><td> </td><td valign="top"><a href="#HIDDEN">HIDDEN</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-holes">holes</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-holes_002c-filling">holes, filling</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-HPPA-multiple-sub_002dspace-stubs">HPPA multiple sub-space stubs</a>:</td><td> </td><td valign="top"><a href="#HPPA-ELF32">HPPA ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-HPPA-stub-grouping">HPPA stub grouping</a>:</td><td> </td><td valign="top"><a href="#HPPA-ELF32">HPPA ELF32</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-I">I</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-image-base">image base</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-implicit-linker-scripts">implicit linker scripts</a>:</td><td> </td><td valign="top"><a href="#Implicit-Linker-Scripts">Implicit Linker Scripts</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-import-libraries">import libraries</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-INCLUDE-filename"><code>INCLUDE <var>filename</var></code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-including-a-linker-script">including a linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-including-an-entire-archive">including an entire archive</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-incremental-link">incremental link</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-INHIBIT_005fCOMMON_005fALLOCATION"><code>INHIBIT_COMMON_ALLOCATION</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-initialization-function">initialization function</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-initialized-data-in-ROM">initialized data in ROM</a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-file-format-in-linker-script">input file format in linker script</a>:</td><td> </td><td valign="top"><a href="#Format-Commands">Format Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-filename-symbols">input filename symbols</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-files-in-linker-scripts">input files in linker scripts</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-files_002c-displaying">input files, displaying</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-format">input format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-format-1">input format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Input-import-library">Input import library</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-object-files-in-linker-scripts">input object files in linker scripts</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-section-alignment">input section alignment</a>:</td><td> </td><td valign="top"><a href="#Forced-Input-Alignment">Forced Input Alignment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-section-basics">input section basics</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Basics">Input Section Basics</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-section-wildcards">input section wildcards</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-input-sections">input sections</a>:</td><td> </td><td valign="top"><a href="#Input-Section">Input Section</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-INPUT_0028files_0029"><code>INPUT(<var>files</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-INSERT"><code>INSERT</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-insert-user-script-into-default-script">insert user script into default script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-integer-notation">integer notation</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-integer-suffixes">integer suffixes</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-internal-object_002dfile-format">internal object-file format</a>:</td><td> </td><td valign="top"><a href="#Canonical-format">Canonical format</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-invalid-input">invalid input</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-K">K</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-K-and-M-integer-suffixes">K and M integer suffixes</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-KEEP">KEEP</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Keep">Input Section Keep</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-L">L</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-l-_003d"><code>l =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-lazy-evaluation">lazy evaluation</a>:</td><td> </td><td valign="top"><a href="#Evaluation">Evaluation</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ld-bugs_002c-reporting"><code>ld</code> bugs, reporting</a>:</td><td> </td><td valign="top"><a href="#Bug-Reporting">Bug Reporting</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ldata-segment-origin_002c-cmd-line">ldata segment origin, cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LDEMULATION"><code>LDEMULATION</code></a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LD_005fFEATURE_0028string_0029"><code>LD_FEATURE(<var>string</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-len-_003d"><code>len =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LENGTH-_003d"><code>LENGTH =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LENGTH_0028memory_0029"><code>LENGTH(<var>memory</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-library-search-path-in-linker-script">library search path in linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-link-map">link map</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-link-map-discarded">link map discarded</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-link_002dtime-runtime-library-search-path">link-time runtime library search path</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-crash">linker crash</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-plugins">linker plugins</a>:</td><td> </td><td valign="top"><a href="#Plugins">Plugins</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-script-concepts">linker script concepts</a>:</td><td> </td><td valign="top"><a href="#Basic-Script-Concepts">Basic Script Concepts</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-script-example">linker script example</a>:</td><td> </td><td valign="top"><a href="#Simple-Example">Simple Example</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-script-file-commands">linker script file commands</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-script-format">linker script format</a>:</td><td> </td><td valign="top"><a href="#Script-Format">Script Format</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-script-input-object-files">linker script input object files</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-script-simple-commands">linker script simple commands</a>:</td><td> </td><td valign="top"><a href="#Simple-Commands">Simple Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-linker-scripts">linker scripts</a>:</td><td> </td><td valign="top"><a href="#Scripts">Scripts</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LINKER_005fVERSION">LINKER_VERSION</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LINKER_005fVERSION-1"><code>LINKER_VERSION</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LIST-_0028MRI_0029"><code>LIST</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-little_002dendian-objects">little-endian objects</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LOAD-_0028MRI_0029"><code>LOAD</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-load-address">load address</a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LOADADDR_0028section_0029"><code>LOADADDR(<var>section</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-loading_002c-preventing">loading, preventing</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Type">Output Section Type</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-local-symbols_002c-deleting">local symbols, deleting</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-location-counter">location counter</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LOG2CEIL_0028exp_0029"><code>LOG2CEIL(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-LONG_0028expression_0029"><code>LONG(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-M">M</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-M-and-K-integer-suffixes">M and K integer suffixes</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-M68HC11-and-68HC12-support">M68HC11 and 68HC12 support</a>:</td><td> </td><td valign="top"><a href="#M68HC11_002f68HC12">M68HC11/68HC12</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-machine-architecture">machine architecture</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-machine-dependencies">machine dependencies</a>:</td><td> </td><td valign="top"><a href="#Machine-Dependent">Machine Dependent</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-mapping-input-sections-to-output-sections">mapping input sections to output sections</a>:</td><td> </td><td valign="top"><a href="#Input-Section">Input Section</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MAX"><code>MAX</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MAXPAGESIZE"><code>MAXPAGESIZE</code></a>:</td><td> </td><td valign="top"><a href="#Symbolic-Constants">Symbolic Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MEMORY"><code>MEMORY</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-memory-region-attributes">memory region attributes</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-memory-regions">memory regions</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-memory-regions-and-sections">memory regions and sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Region">Output Section Region</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-memory-usage">memory usage</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-memory-usage-1">memory usage</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Merging-exidx-entries">Merging exidx entries</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MIN"><code>MIN</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MIPS-branch-relocation-check-control">MIPS branch relocation check control</a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MIPS-microMIPS-instruction-choice-selection">MIPS microMIPS instruction choice selection</a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Motorola-68K-GOT-generation">Motorola 68K GOT generation</a>:</td><td> </td><td valign="top"><a href="#M68K">M68K</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MRI-compatibility">MRI compatibility</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MSP430-extra-sections">MSP430 extra sections</a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-MSP430-Options">MSP430 Options</a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-N">N</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-NAME-_0028MRI_0029"><code>NAME</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-name_002c-section">name, section</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Name">Output Section Name</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-names">names</a>:</td><td> </td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-naming-the-output-file">naming the output file</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-NEXT_0028exp_0029"><code>NEXT(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Nios-II-call-relaxation">Nios II call relaxation</a>:</td><td> </td><td valign="top"><a href="#Nios-II">Nios II</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-NMAGIC">NMAGIC</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-NOCROSSREFS_0028sections_0029"><code>NOCROSSREFS(<var>sections</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-NOCROSSREFS_005fTO_0028tosection-fromsections_0029"><code>NOCROSSREFS_TO(<var>tosection</var> <var>fromsections</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-NOLOAD"><code>NOLOAD</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Type">Output Section Type</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-not-enough-room-for-program-headers">not enough room for program headers</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-NO_005fENUM_005fSIZE_005fWARNING">NO_ENUM_SIZE_WARNING</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-NO_005fWCHAR_005fSIZE_005fWARNING">NO_WCHAR_SIZE_WARNING</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-O">O</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-o-_003d"><code>o =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-objdump-_002di"><code>objdump -i</code></a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-object-file-management">object file management</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-object-files">object files</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-object-formats-available">object formats available</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-object-size">object size</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-OMAGIC">OMAGIC</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-OMAGIC-1">OMAGIC</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ONLY_005fIF_005fRO"><code>ONLY_IF_RO</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Constraint">Output Section Constraint</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ONLY_005fIF_005fRW"><code>ONLY_IF_RW</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Constraint">Output Section Constraint</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-opening-object-files">opening object files</a>:</td><td> </td><td valign="top"><a href="#BFD-outline">BFD outline</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-operators-for-arithmetic">operators for arithmetic</a>:</td><td> </td><td valign="top"><a href="#Operators">Operators</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-options">options</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ORDER-_0028MRI_0029"><code>ORDER</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-org-_003d"><code>org =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ORIGIN-_003d"><code>ORIGIN =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ORIGIN_0028memory_0029"><code>ORIGIN(<var>memory</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-orphan">orphan</a>:</td><td> </td><td valign="top"><a href="#Orphan-Sections">Orphan Sections</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-orphan-sections">orphan sections</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-output-file-after-errors">output file after errors</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-output-file-format-in-linker-script">output file format in linker script</a>:</td><td> </td><td valign="top"><a href="#Format-Commands">Format Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-output-file-name-in-linker-script">output file name in linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-output-format">output format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-output-section-alignment">output section alignment</a>:</td><td> </td><td valign="top"><a href="#Forced-Output-Alignment">Forced Output Alignment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-output-section-attributes">output section attributes</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Attributes">Output Section Attributes</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-output-section-data">output section data</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-OUTPUT_0028filename_0029"><code>OUTPUT(<var>filename</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-OUTPUT_005fARCH_0028bfdarch_0029"><code>OUTPUT_ARCH(<var>bfdarch</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-OUTPUT_005fFORMAT_0028bfdname_0029"><code>OUTPUT_FORMAT(<var>bfdname</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Format-Commands">Format Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-OVERLAY"><code>OVERLAY</code></a>:</td><td> </td><td valign="top"><a href="#Overlay-Description">Overlay Description</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-overlays">overlays</a>:</td><td> </td><td valign="top"><a href="#Overlay-Description">Overlay Description</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-P">P</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-partial-link">partial link</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PE-import-table-prefixing">PE import table prefixing</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PHDRS"><code>PHDRS</code></a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PHDRS-1"><code>PHDRS</code></a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PIC_005fVENEER">PIC_VENEER</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Placement-of-SG-veneers">Placement of SG veneers</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-plugins">plugins</a>:</td><td> </td><td valign="top"><a href="#Plugins">Plugins</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-pop-state-governing-input-file-handling">pop state governing input file handling</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-position-dependent-executables">position dependent executables</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-position-independent-executables">position independent executables</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC-ELF32-options">PowerPC ELF32 options</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC-GOT">PowerPC GOT</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC-long-branches">PowerPC long branches</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC-PLT">PowerPC PLT</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC-stub-symbols">PowerPC stub symbols</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC-TLS-optimization">PowerPC TLS optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-dot-symbols">PowerPC64 dot symbols</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-ELF64-options">PowerPC64 ELF64 options</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-ELFv2-PLT-localentry-optimization">PowerPC64 ELFv2 PLT localentry optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-inline-PLT-call-optimization">PowerPC64 inline PLT call optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-multi_002dTOC">PowerPC64 multi-TOC</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-OPD-optimization">PowerPC64 OPD optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-OPD-spacing">PowerPC64 OPD spacing</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-PLT-call-stub-static-chain">PowerPC64 PLT call stub static chain</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-PLT-call-stub-thread-safety">PowerPC64 PLT call stub thread safety</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-PLT-stub-alignment">PowerPC64 PLT stub alignment</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-Power10-stubs">PowerPC64 Power10 stubs</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-register-save_002frestore-functions">PowerPC64 register save/restore functions</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-stub-grouping">PowerPC64 stub grouping</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-stub-symbols">PowerPC64 stub symbols</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-TLS-optimization">PowerPC64 TLS optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-TOC-optimization">PowerPC64 TOC optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-TOC-sorting">PowerPC64 TOC sorting</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PowerPC64-_005f_005ftls_005fget_005faddr-optimization">PowerPC64 __tls_get_addr optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-precedence-in-expressions">precedence in expressions</a>:</td><td> </td><td valign="top"><a href="#Operators">Operators</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-prevent-unnecessary-loading">prevent unnecessary loading</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Type">Output Section Type</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-program-headers">program headers</a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-program-headers-and-sections">program headers and sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Phdr">Output Section Phdr</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-program-headers_002c-not-enough-room">program headers, not enough room</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-program-segments">program segments</a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PROVIDE">PROVIDE</a>:</td><td> </td><td valign="top"><a href="#PROVIDE">PROVIDE</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PROVIDE_005fHIDDEN">PROVIDE_HIDDEN</a>:</td><td> </td><td valign="top"><a href="#PROVIDE_005fHIDDEN">PROVIDE_HIDDEN</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-PUBLIC-_0028MRI_0029"><code>PUBLIC</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-push-state-governing-input-file-handling">push state governing input file handling</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-Q">Q</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-QUAD_0028expression_0029"><code>QUAD(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-quoted-symbol-names">quoted symbol names</a>:</td><td> </td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-R">R</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-read_002donly-text">read-only text</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-read_002fwrite-from-cmd-line">read/write from cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-region-alias">region alias</a>:</td><td> </td><td valign="top"><a href="#REGION_005fALIAS">REGION_ALIAS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-region-names">region names</a>:</td><td> </td><td valign="top"><a href="#REGION_005fALIAS">REGION_ALIAS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-regions-of-memory">regions of memory</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-REGION_005fALIAS_0028alias_002c-region_0029"><code>REGION_ALIAS(<var>alias</var>, <var>region</var>)</code></a>:</td><td> </td><td valign="top"><a href="#REGION_005fALIAS">REGION_ALIAS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-relative-expressions">relative expressions</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-relaxing-addressing-modes">relaxing addressing modes</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-relaxing-on-H8_002f300">relaxing on H8/300</a>:</td><td> </td><td valign="top"><a href="#H8_002f300">H8/300</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-relaxing-on-M68HC11">relaxing on M68HC11</a>:</td><td> </td><td valign="top"><a href="#M68HC11_002f68HC12">M68HC11/68HC12</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-relaxing-on-NDS32"><code>relaxing on NDS32</code></a>:</td><td> </td><td valign="top"><a href="#NDS32">NDS32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-relaxing-on-Xtensa">relaxing on Xtensa</a>:</td><td> </td><td valign="top"><a href="#Xtensa">Xtensa</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-relocatable-and-absolute-symbols">relocatable and absolute symbols</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-relocatable-output">relocatable output</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-remapping-inputs">remapping inputs</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-removing-sections">removing sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Discarding">Output Section Discarding</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-reporting-bugs-in-ld">reporting bugs in <code>ld</code></a>:</td><td> </td><td valign="top"><a href="#Reporting-Bugs">Reporting Bugs</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-requirements-for-BFD">requirements for BFD</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-retain-relocations-in-final-executable">retain relocations in final executable</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-retaining-specified-symbols">retaining specified symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-REVERSE">REVERSE</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-rodata-segment-origin_002c-cmd-line">rodata segment origin, cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-ROM-initialized-data">ROM initialized data</a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-round-up-expression">round up expression</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-round-up-location-counter">round up location counter</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-runtime-library-name">runtime library name</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-runtime-library-search-path">runtime library search path</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-runtime-pseudo_002drelocation">runtime pseudo-relocation</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-S">S</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-S_002f390">S/390</a>:</td><td> </td><td valign="top"><a href="#S_002f390-ELF">S/390 ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-S_002f390-ELF-options">S/390 ELF options</a>:</td><td> </td><td valign="top"><a href="#S_002f390-ELF">S/390 ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-scaled-integers">scaled integers</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-scommon-section">scommon section</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-script-files">script files</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-script-files-1">script files</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-scripts">scripts</a>:</td><td> </td><td valign="top"><a href="#Scripts">Scripts</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-search-directory_002c-from-cmd-line">search directory, from cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-search-path-in-linker-script">search path in linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SEARCH_005fDIR_0028path_0029"><code>SEARCH_DIR(<var>path</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SECT-_0028MRI_0029"><code>SECT</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-address">section address</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Address">Output Section Address</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-address-in-expression">section address in expression</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-alignment">section alignment</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-alignment_002c-warnings-on">section alignment, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-data">section data</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-fill-pattern">section fill pattern</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Fill">Output Section Fill</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-groups">section groups</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-groups-1">section groups</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-load-address">section load address</a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-load-address-in-expression">section load address in expression</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-name">section name</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Name">Output Section Name</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-name-wildcard-patterns">section name wildcard patterns</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section-size">section size</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section_002c-assigning-to-memory-region">section, assigning to memory region</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Region">Output Section Region</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-section_002c-assigning-to-program-header">section, assigning to program header</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Phdr">Output Section Phdr</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SECTIONS"><code>SECTIONS</code></a>:</td><td> </td><td valign="top"><a href="#SECTIONS">SECTIONS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-sections_002c-discarding">sections, discarding</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Discarding">Output Section Discarding</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-sections_002c-orphan">sections, orphan</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Secure-gateway-import-library">Secure gateway import library</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-segment-origins_002c-cmd-line">segment origins, cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-segments_002c-ELF">segments, ELF</a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SEGMENT_005fSTART_0028segment_002c-default_0029"><code>SEGMENT_START(<var>segment</var>, <var>default</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-shared-libraries">shared libraries</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SHORT_0028expression_0029"><code>SHORT(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SIZEOF_0028section_0029"><code>SIZEOF(<var>section</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SIZEOF_005fHEADERS"><code>SIZEOF_HEADERS</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-small-common-symbols">small common symbols</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SORT">SORT</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SORT_005fBY_005fALIGNMENT">SORT_BY_ALIGNMENT</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SORT_005fBY_005fINIT_005fPRIORITY">SORT_BY_INIT_PRIORITY</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SORT_005fBY_005fNAME">SORT_BY_NAME</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SORT_005fNONE">SORT_NONE</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SPU">SPU</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SPU-1">SPU</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SPU-ELF-options">SPU ELF options</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SPU-extra-overlay-stubs">SPU extra overlay stubs</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SPU-local-store-size">SPU local store size</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SPU-overlay-stub-symbols">SPU overlay stub symbols</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SPU-overlays">SPU overlays</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SPU-plugins">SPU plugins</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SQUAD_0028expression_0029"><code>SQUAD(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-stack-size">stack size</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-standard-Unix-system">standard Unix system</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-start-of-execution">start of execution</a>:</td><td> </td><td valign="top"><a href="#Entry-Point">Entry Point</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-start_002dstop_002dgc">start-stop-gc</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-STARTUP_0028filename_0029"><code>STARTUP(<var>filename</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-static-library-dependencies">static library dependencies</a>:</td><td> </td><td valign="top"><a href="#libdep-Plugin">libdep Plugin</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-STM32L4xx-erratum-workaround">STM32L4xx erratum workaround</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-strip-all-symbols">strip all symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-strip-debugger-symbols">strip debugger symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-stripping-all-but-some-symbols">stripping all but some symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-STUB_005fGROUP_005fSIZE">STUB_GROUP_SIZE</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-SUBALIGN_0028subsection_005falign_0029"><code>SUBALIGN(<var>subsection_align</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Forced-Input-Alignment">Forced Input Alignment</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-suffixes-for-integers">suffixes for integers</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbol-defaults">symbol defaults</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbol-definition_002c-scripts">symbol definition, scripts</a>:</td><td> </td><td valign="top"><a href="#Assignments">Assignments</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbol-names">symbol names</a>:</td><td> </td><td valign="top"><a href="#Symbols">Symbols</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbol-tracing">symbol tracing</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbol-versions">symbol versions</a>:</td><td> </td><td valign="top"><a href="#VERSION">VERSION</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbol_002donly-input">symbol-only input</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbolic-constants">symbolic constants</a>:</td><td> </td><td valign="top"><a href="#Symbolic-Constants">Symbolic Constants</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbols_002c-from-command-line">symbols, from command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbols_002c-relocatable-and-absolute">symbols, relocatable and absolute</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbols_002c-require-defined">symbols, require defined</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-symbols_002c-retaining-selectively">symbols, retaining selectively</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-synthesizing-linker">synthesizing linker</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-synthesizing-on-H8_002f300">synthesizing on H8/300</a>:</td><td> </td><td valign="top"><a href="#H8_002f300">H8/300</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-T">T</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-TARGET_0028bfdname_0029"><code>TARGET(<var>bfdname</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Format-Commands">Format Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-TARGET1">TARGET1</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-TARGET2">TARGET2</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-text-segment-origin_002c-cmd-line">text segment origin, cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-thumb-entry-point">thumb entry point</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-TI-COFF-versions">TI COFF versions</a>:</td><td> </td><td valign="top"><a href="#TI-COFF">TI COFF</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-traditional-format">traditional format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-trampoline-generation-on-M68HC11">trampoline generation on M68HC11</a>:</td><td> </td><td valign="top"><a href="#M68HC11_002f68HC12">M68HC11/68HC12</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-trampoline-generation-on-M68HC12">trampoline generation on M68HC12</a>:</td><td> </td><td valign="top"><a href="#M68HC11_002f68HC12">M68HC11/68HC12</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-U">U</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-unallocated-address_002c-next">unallocated address, next</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-undefined-symbol">undefined symbol</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-undefined-symbol-in-linker-script">undefined symbol in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-undefined-symbols_002c-warnings-on">undefined symbols, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-uninitialized-data-placement">uninitialized data placement</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-unspecified-memory">unspecified memory</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-usage">usage</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-USE_005fBLX">USE_BLX</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-using-a-DEF-file">using a DEF file</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-using-auto_002dexport-functionality">using auto-export functionality</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Using-decorations">Using decorations</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-V">V</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-variables_002c-defining">variables, defining</a>:</td><td> </td><td valign="top"><a href="#Assignments">Assignments</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-verbose_005b_003dNUMBER_005d">verbose[=<var>NUMBER</var>]</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-version">version</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-version-script">version script</a>:</td><td> </td><td valign="top"><a href="#VERSION">VERSION</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-version-script_002c-symbol-versions">version script, symbol versions</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-VERSION-_007bscript-text_007d"><code>VERSION {script text}</code></a>:</td><td> </td><td valign="top"><a href="#VERSION">VERSION</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-versions-of-symbols">versions of symbols</a>:</td><td> </td><td valign="top"><a href="#VERSION">VERSION</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-VFP11_005fDENORM_005fFIX">VFP11_DENORM_FIX</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-visibility">visibility</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-W">W</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-warnings_002c-on-combining-symbols">warnings, on combining symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-warnings_002c-on-executable-stack">warnings, on executable stack</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-warnings_002c-on-section-alignment">warnings, on section alignment</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-warnings_002c-on-undefined-symbols">warnings, on undefined symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-warnings_002c-on-writeable-and-exectuable-segments">warnings, on writeable and exectuable segments</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-weak-externals">weak externals</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-what-is-this_003f">what is this?</a>:</td><td> </td><td valign="top"><a href="#Overview">Overview</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-wildcard-file-name-patterns">wildcard file name patterns</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- <tr><th id="LD-Index_cp_letter-X">X</th><td></td><td></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Xtensa-options">Xtensa options</a>:</td><td> </td><td valign="top"><a href="#Xtensa">Xtensa</a></td></tr>
- <tr><td></td><td valign="top"><a href="#index-Xtensa-processors">Xtensa processors</a>:</td><td> </td><td valign="top"><a href="#Xtensa">Xtensa</a></td></tr>
- <tr><td colspan="4"> <hr></td></tr>
- </table>
- <table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#LD-Index_cp_symbol-1"><b>"</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-2"><b>-</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-3"><b>.</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-4"><b>/</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-5"><b>3</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-6"><b>:</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-7"><b>=</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-8"><b>></b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_symbol-9"><b>[</b></a>
-
- <br>
- <a class="summary-letter" href="#LD-Index_cp_letter-A"><b>A</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-B"><b>B</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-C"><b>C</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-D"><b>D</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-E"><b>E</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-F"><b>F</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-G"><b>G</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-H"><b>H</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-I"><b>I</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-K"><b>K</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-L"><b>L</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-M"><b>M</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-N"><b>N</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-O"><b>O</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-P"><b>P</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-Q"><b>Q</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-R"><b>R</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-S"><b>S</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-T"><b>T</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-U"><b>U</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-V"><b>V</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-W"><b>W</b></a>
-
- <a class="summary-letter" href="#LD-Index_cp_letter-X"><b>X</b></a>
-
- </td></tr></table>
- <hr>
- </body>
- </html>
|
