1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916691769186919692069216922692369246925692669276928692969306931693269336934693569366937693869396940694169426943694469456946694769486949695069516952695369546955695669576958695969606961696269636964696569666967696869696970697169726973697469756976697769786979698069816982698369846985698669876988698969906991699269936994699569966997699869997000700170027003700470057006700770087009701070117012701370147015701670177018701970207021702270237024702570267027702870297030703170327033703470357036703770387039704070417042704370447045704670477048704970507051705270537054705570567057705870597060706170627063706470657066706770687069707070717072707370747075707670777078707970807081708270837084708570867087708870897090709170927093709470957096709770987099710071017102710371047105710671077108710971107111711271137114711571167117711871197120712171227123712471257126712771287129713071317132713371347135713671377138713971407141714271437144714571467147714871497150715171527153715471557156715771587159716071617162716371647165716671677168716971707171717271737174717571767177717871797180718171827183718471857186718771887189719071917192719371947195719671977198719972007201720272037204720572067207720872097210721172127213721472157216721772187219722072217222722372247225722672277228722972307231723272337234723572367237723872397240724172427243724472457246724772487249725072517252725372547255725672577258725972607261726272637264726572667267726872697270727172727273727472757276727772787279728072817282728372847285728672877288728972907291729272937294729572967297729872997300730173027303730473057306730773087309731073117312731373147315731673177318731973207321732273237324732573267327732873297330733173327333733473357336733773387339734073417342734373447345734673477348734973507351735273537354735573567357735873597360736173627363736473657366736773687369737073717372737373747375737673777378737973807381738273837384738573867387738873897390739173927393739473957396739773987399740074017402740374047405740674077408740974107411741274137414741574167417741874197420742174227423742474257426742774287429743074317432743374347435743674377438743974407441744274437444744574467447744874497450745174527453745474557456745774587459746074617462746374647465746674677468746974707471747274737474747574767477747874797480748174827483748474857486748774887489749074917492749374947495749674977498749975007501750275037504750575067507750875097510751175127513751475157516751775187519752075217522752375247525752675277528752975307531753275337534753575367537753875397540754175427543754475457546754775487549755075517552755375547555755675577558755975607561756275637564756575667567756875697570757175727573757475757576757775787579758075817582758375847585758675877588758975907591759275937594759575967597759875997600760176027603760476057606760776087609761076117612761376147615761676177618761976207621762276237624762576267627762876297630763176327633763476357636763776387639764076417642764376447645764676477648764976507651765276537654765576567657765876597660766176627663766476657666766776687669767076717672767376747675767676777678767976807681768276837684768576867687768876897690769176927693769476957696769776987699770077017702770377047705770677077708770977107711771277137714771577167717771877197720772177227723772477257726772777287729773077317732773377347735773677377738773977407741774277437744774577467747774877497750775177527753775477557756775777587759776077617762776377647765776677677768776977707771777277737774777577767777777877797780778177827783778477857786778777887789779077917792779377947795779677977798779978007801780278037804780578067807780878097810781178127813781478157816781778187819782078217822782378247825782678277828782978307831783278337834783578367837783878397840784178427843784478457846784778487849785078517852785378547855785678577858785978607861786278637864786578667867786878697870787178727873787478757876787778787879788078817882788378847885788678877888788978907891789278937894789578967897789878997900790179027903790479057906790779087909791079117912791379147915791679177918791979207921792279237924792579267927792879297930793179327933793479357936793779387939794079417942794379447945794679477948794979507951795279537954795579567957795879597960796179627963796479657966796779687969797079717972797379747975797679777978797979807981798279837984798579867987798879897990799179927993799479957996799779987999800080018002800380048005800680078008800980108011801280138014801580168017801880198020802180228023802480258026802780288029803080318032803380348035803680378038803980408041804280438044804580468047804880498050805180528053805480558056805780588059806080618062806380648065806680678068806980708071807280738074807580768077807880798080808180828083808480858086808780888089809080918092809380948095809680978098809981008101810281038104810581068107810881098110811181128113811481158116811781188119812081218122812381248125812681278128812981308131813281338134813581368137813881398140814181428143814481458146814781488149815081518152815381548155815681578158815981608161816281638164816581668167816881698170817181728173817481758176817781788179818081818182818381848185818681878188818981908191819281938194819581968197819881998200820182028203820482058206820782088209821082118212821382148215821682178218821982208221822282238224822582268227822882298230823182328233823482358236823782388239824082418242824382448245824682478248824982508251825282538254825582568257825882598260826182628263826482658266826782688269827082718272827382748275827682778278827982808281828282838284828582868287828882898290829182928293829482958296829782988299830083018302830383048305830683078308830983108311831283138314831583168317831883198320832183228323832483258326832783288329833083318332833383348335833683378338833983408341834283438344834583468347834883498350835183528353835483558356835783588359836083618362836383648365836683678368836983708371837283738374837583768377837883798380838183828383838483858386838783888389839083918392839383948395839683978398839984008401840284038404840584068407840884098410841184128413841484158416841784188419842084218422842384248425842684278428842984308431843284338434843584368437843884398440844184428443844484458446844784488449845084518452845384548455845684578458845984608461846284638464846584668467846884698470847184728473847484758476847784788479848084818482848384848485848684878488848984908491849284938494849584968497849884998500850185028503850485058506850785088509851085118512851385148515851685178518851985208521852285238524852585268527852885298530853185328533853485358536853785388539854085418542854385448545854685478548854985508551855285538554855585568557855885598560856185628563856485658566856785688569857085718572857385748575857685778578857985808581858285838584858585868587858885898590859185928593859485958596859785988599860086018602860386048605860686078608860986108611861286138614861586168617861886198620862186228623862486258626862786288629863086318632863386348635863686378638863986408641864286438644864586468647864886498650865186528653865486558656865786588659866086618662866386648665866686678668866986708671867286738674867586768677867886798680868186828683868486858686868786888689869086918692869386948695869686978698869987008701870287038704870587068707870887098710871187128713871487158716871787188719872087218722872387248725872687278728872987308731873287338734873587368737873887398740874187428743874487458746874787488749875087518752875387548755875687578758875987608761876287638764876587668767876887698770877187728773877487758776877787788779878087818782878387848785878687878788878987908791879287938794879587968797879887998800880188028803880488058806880788088809881088118812881388148815881688178818881988208821882288238824882588268827882888298830883188328833883488358836883788388839884088418842884388448845884688478848884988508851885288538854885588568857885888598860886188628863886488658866886788688869887088718872887388748875887688778878887988808881888288838884888588868887888888898890889188928893889488958896889788988899890089018902890389048905890689078908890989108911891289138914891589168917891889198920892189228923892489258926892789288929893089318932893389348935893689378938893989408941894289438944894589468947894889498950895189528953895489558956895789588959896089618962896389648965896689678968896989708971897289738974897589768977897889798980898189828983898489858986898789888989899089918992899389948995899689978998899990009001900290039004900590069007900890099010901190129013901490159016901790189019902090219022902390249025902690279028902990309031903290339034903590369037903890399040904190429043904490459046904790489049905090519052905390549055905690579058905990609061906290639064906590669067906890699070907190729073907490759076907790789079908090819082908390849085908690879088908990909091909290939094909590969097909890999100910191029103910491059106910791089109911091119112911391149115911691179118911991209121912291239124912591269127912891299130913191329133913491359136913791389139914091419142914391449145914691479148914991509151915291539154915591569157915891599160916191629163916491659166916791689169917091719172917391749175917691779178917991809181918291839184918591869187918891899190919191929193919491959196919791989199920092019202920392049205920692079208920992109211921292139214921592169217921892199220922192229223922492259226922792289229923092319232923392349235923692379238923992409241924292439244924592469247924892499250925192529253925492559256925792589259926092619262926392649265926692679268926992709271927292739274927592769277927892799280928192829283928492859286928792889289929092919292929392949295929692979298929993009301930293039304930593069307930893099310931193129313931493159316931793189319932093219322932393249325932693279328932993309331933293339334933593369337933893399340934193429343934493459346 |
- \input texinfo
- @setfilename ld.info
- @c Copyright (C) 1991-2022 Free Software Foundation, Inc.
- @syncodeindex ky cp
- @c man begin INCLUDE
- @include configdoc.texi
- @c (configdoc.texi is generated by the Makefile)
- @include bfdver.texi
- @c man end
- @c @smallbook
- @macro gcctabopt{body}
- @code{\body\}
- @end macro
- @c man begin NAME
- @ifset man
- @c Configure for the generation of man pages
- @set UsesEnvVars
- @set GENERIC
- @set ARM
- @set C6X
- @set CSKY
- @set H8300
- @set HPPA
- @set M68HC11
- @set M68K
- @set MIPS
- @set MMIX
- @set MSP430
- @set NDS32
- @set NIOSII
- @set PDP11
- @set POWERPC
- @set POWERPC64
- @set Renesas
- @set S/390
- @set SPU
- @set TICOFF
- @set WIN32
- @set XTENSA
- @end ifset
- @c man end
- @ifnottex
- @dircategory Software development
- @direntry
- * Ld: (ld). The GNU linker.
- @end direntry
- @end ifnottex
- @copying
- This file documents the @sc{gnu} linker LD
- @ifset VERSION_PACKAGE
- @value{VERSION_PACKAGE}
- @end ifset
- version @value{VERSION}.
- Copyright @copyright{} 1991-2022 Free Software Foundation, Inc.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3
- or any later version published by the Free Software Foundation;
- with 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''.
- @end copying
- @iftex
- @finalout
- @setchapternewpage odd
- @settitle The GNU linker
- @titlepage
- @title The GNU linker
- @sp 1
- @subtitle @code{ld}
- @ifset VERSION_PACKAGE
- @subtitle @value{VERSION_PACKAGE}
- @end ifset
- @subtitle Version @value{VERSION}
- @author Steve Chamberlain
- @author Ian Lance Taylor
- @page
- @tex
- {\parskip=0pt
- \hfill Red Hat Inc\par
- \hfill nickc\@credhat.com, doc\@redhat.com\par
- \hfill {\it The GNU linker}\par
- \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
- }
- \global\parindent=0pt % Steve likes it this way.
- @end tex
- @vskip 0pt plus 1filll
- @c man begin COPYRIGHT
- Copyright @copyright{} 1991-2022 Free Software Foundation, Inc.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3
- or any later version published by the Free Software Foundation;
- with 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''.
- @c man end
- @end titlepage
- @end iftex
- @contents
- @c FIXME: Talk about importance of *order* of args, cmds to linker!
- @ifnottex
- @node Top
- @top LD
- This file documents the @sc{gnu} linker ld
- @ifset VERSION_PACKAGE
- @value{VERSION_PACKAGE}
- @end ifset
- version @value{VERSION}.
- 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''.
- @menu
- * Overview:: Overview
- * Invocation:: Invocation
- * Scripts:: Linker Scripts
- * Plugins:: Linker Plugins
- @ifset GENERIC
- * Machine Dependent:: Machine Dependent Features
- @end ifset
- @ifclear GENERIC
- @ifset H8300
- * H8/300:: ld and the H8/300
- @end ifset
- @ifset Renesas
- * Renesas:: ld and other Renesas micros
- @end ifset
- @ifset ARM
- * ARM:: ld and the ARM family
- @end ifset
- @ifset M68HC11
- * M68HC11/68HC12:: ld and the Motorola 68HC11 and 68HC12 families
- @end ifset
- @ifset HPPA
- * HPPA ELF32:: ld and HPPA 32-bit ELF
- @end ifset
- @ifset M68K
- * M68K:: ld and Motorola 68K family
- @end ifset
- @ifset MIPS
- * MIPS:: ld and MIPS family
- @end ifset
- @ifset POWERPC
- * PowerPC ELF32:: ld and PowerPC 32-bit ELF Support
- @end ifset
- @ifset POWERPC64
- * PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support
- @end ifset
- @ifset S/390
- * S/390 ELF:: ld and S/390 ELF Support
- @end ifset
- @ifset SPU
- * SPU ELF:: ld and SPU ELF Support
- @end ifset
- @ifset TICOFF
- * TI COFF:: ld and the TI COFF
- @end ifset
- @ifset WIN32
- * Win32:: ld and WIN32 (cygwin/mingw)
- @end ifset
- @ifset XTENSA
- * Xtensa:: ld and Xtensa Processors
- @end ifset
- @end ifclear
- @ifclear SingleFormat
- * BFD:: BFD
- @end ifclear
- @c Following blank line required for remaining bug in makeinfo conds/menus
- * Reporting Bugs:: Reporting Bugs
- * MRI:: MRI Compatible Script Files
- * GNU Free Documentation License:: GNU Free Documentation License
- * LD Index:: LD Index
- @end menu
- @end ifnottex
- @node Overview
- @chapter Overview
- @cindex @sc{gnu} linker
- @cindex what is this?
- @ifset man
- @c man begin SYNOPSIS
- ld [@b{options}] @var{objfile} @dots{}
- @c man end
- @c man begin SEEALSO
- ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
- the Info entries for @file{binutils} and
- @file{ld}.
- @c man end
- @end ifset
- @c man begin DESCRIPTION
- @command{ld} 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 @command{ld}.
- @command{ld} 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.
- @ifset man
- @c For the man only
- This man page does not describe the command language; see the
- @command{ld} entry in @code{info} for full details on the command
- language and on other aspects of the GNU linker.
- @end ifset
- @ifclear SingleFormat
- This version of @command{ld} uses the general purpose BFD libraries
- to operate on object files. This allows @command{ld} to read, combine, and
- write object files in many different formats---for example, COFF or
- @code{a.out}. Different formats may be linked together to produce any
- available kind of object file. @xref{BFD}, for more information.
- @end ifclear
- Aside from its flexibility, the @sc{gnu} linker is more helpful than other
- linkers in providing diagnostic information. Many linkers abandon
- execution immediately upon encountering an error; whenever possible,
- @command{ld} continues executing, allowing you to identify other errors
- (or, in some cases, to get an output file in spite of the error).
- @c man end
- @node Invocation
- @chapter Invocation
- @c man begin DESCRIPTION
- The @sc{gnu} linker @command{ld} 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.
- @c man end
- @ifset UsesEnvVars
- @menu
- * Options:: Command-line Options
- * Environment:: Environment Variables
- @end menu
- @node Options
- @section Command-line Options
- @end ifset
- @cindex command line
- @cindex options
- @c man begin OPTIONS
- The linker supports a plethora of command-line options, but in actual
- practice few of them are used in any particular context.
- @cindex standard Unix system
- For instance, a frequent use of @command{ld} is to link standard Unix
- object files on a standard, supported Unix system. On such a system, to
- link a file @code{hello.o}:
- @smallexample
- ld -o @var{output} /lib/crt0.o hello.o -lc
- @end smallexample
- This tells @command{ld} to produce a file called @var{output} as the
- result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
- the library @code{libc.a}, which will come from the standard search
- directories. (See the discussion of the @samp{-l} option below.)
- Some of the command-line options to @command{ld} may be specified at any
- point in the command line. However, options which refer to files, such
- as @samp{-l} or @samp{-T}, 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.
- @cindex object files
- 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.
- 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{-R},
- and the script command language. If @emph{no} binary input files at all
- are specified, the linker does not produce any output, and issues the
- message @samp{No input files}.
- 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}). 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} or @code{GROUP} 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} option
- to replace the default linker script entirely, but note the effect of
- the @code{INSERT} command. @xref{Scripts}.
- 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.
- For options whose names are multiple letters, either one dash or two can
- precede the option name; for example, @samp{-trace-symbol} and
- @samp{--trace-symbol} 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} option. So for example @samp{-omagic} sets the output file
- name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
- output.
- 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} and @samp{--trace-symbol=foo} are equivalent.
- Unique abbreviations of the names of multiple-letter options are
- accepted.
- Note---if the linker is being invoked indirectly, via a compiler driver
- (e.g. @samp{gcc}) then all the linker command-line options should be
- prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
- compiler driver) like this:
- @smallexample
- gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
- @end smallexample
- 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:
- @smallexample
- gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
- @end smallexample
- Here is a table of the generic command-line switches accepted by the GNU
- linker:
- @table @gcctabopt
- @include at-file.texi
- @kindex -a @var{keyword}
- @item -a @var{keyword}
- This option is supported for HP/UX compatibility. The @var{keyword}
- argument must be one of the strings @samp{archive}, @samp{shared}, or
- @samp{default}. @samp{-aarchive} is functionally equivalent to
- @samp{-Bstatic}, and the other two keywords are functionally equivalent
- to @samp{-Bdynamic}. This option may be used any number of times.
- @kindex --audit @var{AUDITLIB}
- @item --audit @var{AUDITLIB}
- Adds @var{AUDITLIB} to the @code{DT_AUDIT} entry of the dynamic section.
- @var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
- specified in the library. If specified multiple times @code{DT_AUDIT}
- 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} entry in the output file.
- This option is only meaningful on ELF platforms supporting the rtld-audit
- interface.
- @ifclear SingleFormat
- @cindex binary input format
- @kindex -b @var{format}
- @kindex --format=@var{format}
- @cindex input format
- @cindex input format
- @item -b @var{input-format}
- @itemx --format=@var{input-format}
- @command{ld} may be configured to support more than one kind of object
- file. If your @command{ld} is configured this way, you can use the
- @samp{-b} option to specify the binary format for input object files
- that follow this option on the command line. Even when @command{ld} is
- configured to support alternative object formats, you don't usually need
- to specify this, as @command{ld} should be configured to expect as a
- default input format the most usual format on each machine.
- @var{input-format} 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}.)
- @xref{BFD}.
- You may want to use this option if you are linking files with an unusual
- binary format. You can also use @samp{-b} to switch formats explicitly (when
- linking object files of different formats), by including
- @samp{-b @var{input-format}} before each group of object files in a
- particular format.
- The default format is taken from the environment variable
- @code{GNUTARGET}.
- @ifset UsesEnvVars
- @xref{Environment}.
- @end ifset
- You can also define the input format from a script, using the command
- @code{TARGET};
- @ifclear man
- see @ref{Format Commands}.
- @end ifclear
- @end ifclear
- @kindex -c @var{MRI-cmdfile}
- @kindex --mri-script=@var{MRI-cmdfile}
- @cindex compatibility, MRI
- @item -c @var{MRI-commandfile}
- @itemx --mri-script=@var{MRI-commandfile}
- For compatibility with linkers produced by MRI, @command{ld} accepts script
- files written in an alternate, restricted command language, described in
- @ifclear man
- @ref{MRI,,MRI Compatible Script Files}.
- @end ifclear
- @ifset man
- the MRI Compatible Script Files section of GNU ld documentation.
- @end ifset
- Introduce MRI script files with
- the option @samp{-c}; use the @samp{-T} option to run linker
- scripts written in the general-purpose @command{ld} scripting language.
- If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
- specified by any @samp{-L} options.
- @cindex common allocation
- @kindex -d
- @kindex -dc
- @kindex -dp
- @item -d
- @itemx -dc
- @itemx -dp
- 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}). The
- script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
- @xref{Miscellaneous Commands}.
- @kindex --depaudit @var{AUDITLIB}
- @kindex -P @var{AUDITLIB}
- @item --depaudit @var{AUDITLIB}
- @itemx -P @var{AUDITLIB}
- Adds @var{AUDITLIB} to the @code{DT_DEPAUDIT} entry of the dynamic section.
- @var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
- specified in the library. If specified multiple times @code{DT_DEPAUDIT}
- 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.
- @kindex --enable-non-contiguous-regions
- @item --enable-non-contiguous-regions
- 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:
- @smallexample
- 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.*); @} > MEM2
- @}
- 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.
- @end smallexample
- This option is incompatible with INSERT statements because it changes
- the way input sections are mapped to output sections.
- @kindex --enable-non-contiguous-regions-warnings
- @item --enable-non-contiguous-regions-warnings
- This option enables warnings when
- @code{--enable-non-contiguous-regions} 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.
- @cindex entry point, from command line
- @kindex -e @var{entry}
- @kindex --entry=@var{entry}
- @item -e @var{entry}
- @itemx --entry=@var{entry}
- Use @var{entry} as the explicit symbol for beginning execution of your
- program, rather than the default entry point. If there is no symbol
- named @var{entry}, the linker will try to parse @var{entry} 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} for base 16, or a leading
- @samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults
- and other ways of specifying the entry point.
- @kindex --exclude-libs
- @item --exclude-libs @var{lib},@var{lib},...
- 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} 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.
- @kindex --exclude-modules-for-implib
- @item --exclude-modules-for-implib @var{module},@var{module},...
- 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 @command{ld} 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.
- @cindex dynamic symbol table
- @kindex -E
- @kindex --export-dynamic
- @kindex --no-export-dynamic
- @item -E
- @itemx --export-dynamic
- @itemx --no-export-dynamic
- When creating a dynamically linked executable, using the @option{-E}
- option or the @option{--export-dynamic} 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.
- If you do not use either of these options (or use the
- @option{--no-export-dynamic} 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.
- If you use @code{dlopen} 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.
- 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}.
- 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} below.
- @kindex --export-dynamic-symbol=@var{glob}
- @cindex export dynamic symbol
- @item --export-dynamic-symbol=@var{glob}
- When creating a dynamically linked executable, symbols matching
- @var{glob} will be added to the dynamic symbol table. When creating a
- shared library, references to symbols matching @var{glob} 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} or
- @samp{--dynamic-list} are not specified. This option is only meaningful
- on ELF platforms which support shared libraries.
- @kindex --export-dynamic-symbol-list=@var{file}
- @cindex export dynamic symbol list
- @item --export-dynamic-symbol-list=@var{file}
- Specify a @samp{--export-dynamic-symbol} for each pattern in the file.
- The format of the file is the same as the version node without
- scope and node name. See @ref{VERSION} for more information.
- @ifclear SingleFormat
- @cindex big-endian objects
- @cindex endianness
- @kindex -EB
- @item -EB
- Link big-endian objects. This affects the default output format.
- @cindex little-endian objects
- @kindex -EL
- @item -EL
- Link little-endian objects. This affects the default output format.
- @end ifclear
- @kindex -f @var{name}
- @kindex --auxiliary=@var{name}
- @item -f @var{name}
- @itemx --auxiliary=@var{name}
- 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}.
- 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}. If there is one, it will be used instead of the definition
- in the filter object. The shared object @var{name} need not exist.
- Thus the shared object @var{name} may be used to provide an alternative
- implementation of certain functions, perhaps for debugging or for
- machine-specific performance.
- 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.
- @kindex -F @var{name}
- @kindex --filter=@var{name}
- @item -F @var{name}
- @itemx --filter=@var{name}
- 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}.
- 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}. Thus the filter object can be
- used to select a subset of the symbols provided by the object
- @var{name}.
- Some older linkers used the @option{-F} option throughout a compilation
- toolchain for specifying object-file format for both input and output
- object files.
- @ifclear SingleFormat
- The @sc{gnu} linker uses other mechanisms for this purpose: the
- @option{-b}, @option{--format}, @option{--oformat} options, the
- @code{TARGET} command in linker scripts, and the @code{GNUTARGET}
- environment variable.
- @end ifclear
- The @sc{gnu} linker will ignore the @option{-F} option when not
- creating an ELF shared object.
- @cindex finalization function
- @kindex -fini=@var{name}
- @item -fini=@var{name}
- 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} as
- the function to call.
- @kindex -g
- @item -g
- Ignored. Provided for compatibility with other tools.
- @kindex -G @var{value}
- @kindex --gpsize=@var{value}
- @cindex object size
- @item -G @var{value}
- @itemx --gpsize=@var{value}
- Set the maximum size of objects to be optimized using the GP register to
- @var{size}. 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.
- @cindex runtime library name
- @kindex -h @var{name}
- @kindex -soname=@var{name}
- @item -h @var{name}
- @itemx -soname=@var{name}
- 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.
- @kindex -i
- @cindex incremental link
- @item -i
- Perform an incremental link (same as option @samp{-r}).
- @cindex initialization function
- @kindex -init=@var{name}
- @item -init=@var{name}
- 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} as the
- function to call.
- @cindex archive files, from cmd line
- @kindex -l @var{namespec}
- @kindex --library=@var{namespec}
- @item -l @var{namespec}
- @itemx --library=@var{namespec}
- Add the archive or object file specified by @var{namespec} to the
- list of files to link. This option may be used any number of times.
- If @var{namespec} is of the form @file{:@var{filename}}, @command{ld}
- will search the library path for a file called @var{filename}, otherwise it
- will search the library path for a file called @file{lib@var{namespec}.a}.
- On systems which support shared libraries, @command{ld} may also search for
- files other than @file{lib@var{namespec}.a}. Specifically, on ELF
- and SunOS systems, @command{ld} will search a directory for a library
- called @file{lib@var{namespec}.so} before searching for one called
- @file{lib@var{namespec}.a}. (By convention, a @code{.so} extension
- indicates a shared library.) Note that this behavior does not apply
- to @file{:@var{filename}}, which always specifies a file called
- @var{filename}.
- 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.
- See the @option{-(} option for a way to force the linker to search
- archives multiple times.
- You may list the same archive multiple times on the command line.
- @ifset GENERIC
- This type of archive searching is standard for Unix linkers. However,
- if you are using @command{ld} on AIX, note that it is different from the
- behaviour of the AIX linker.
- @end ifset
- @cindex search directory, from cmd line
- @kindex -L @var{dir}
- @kindex --library-path=@var{dir}
- @item -L @var{searchdir}
- @itemx --library-path=@var{searchdir}
- Add path @var{searchdir} to the list of paths that @command{ld} will search
- for archive libraries and @command{ld} 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
- @option{-L} options apply to all @option{-l} options, regardless of the
- order in which the options appear. @option{-L} options do not affect
- how @command{ld} searches for a linker script unless @option{-T}
- option is specified.
- If @var{searchdir} begins with @code{=} or @code{$SYSROOT}, then this
- prefix will be replaced by the @dfn{sysroot prefix}, controlled by the
- @samp{--sysroot} option, or specified when the linker is configured.
- @ifset UsesEnvVars
- The default set of paths searched (without being specified with
- @samp{-L}) depends on which emulation mode @command{ld} is using, and in
- some cases also on how it was configured. @xref{Environment}.
- @end ifset
- The paths can also be specified in a link script with the
- @code{SEARCH_DIR} command. Directories specified this way are searched
- at the point in which the linker script appears in the command line.
- @cindex emulation
- @kindex -m @var{emulation}
- @item -m @var{emulation}
- Emulate the @var{emulation} linker. You can list the available
- emulations with the @samp{--verbose} or @samp{-V} options.
- If the @samp{-m} option is not used, the emulation is taken from the
- @code{LDEMULATION} environment variable, if that is defined.
- Otherwise, the default emulation depends upon how the linker was
- configured.
- @cindex link map
- @kindex -M
- @kindex --print-map
- @item -M
- @itemx --print-map
- Print a link map to the standard output. A link map provides
- information about the link, including the following:
- @itemize @bullet
- @item
- Where object files are mapped into memory.
- @item
- How common symbols are allocated.
- @item
- All archive members included in the link, with a mention of the symbol
- which caused the archive member to be brought in.
- @item
- The values assigned to symbols.
- 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:
- @smallexample
- foo = 1
- foo = foo * 4
- foo = foo + 8
- @end smallexample
- will produce the following output in the link map if the @option{-M}
- option is used:
- @smallexample
- 0x00000001 foo = 0x1
- [0x0000000c] foo = (foo * 0x4)
- [0x0000000c] foo = (foo + 0x8)
- @end smallexample
- See @ref{Expressions} for more information about expressions in linker
- scripts.
- @item
- How GNU properties are merged.
- 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:
- @smallexample
- Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
- @end smallexample
- This indicates that property 0xc0000002 is removed from output when
- merging properties in @file{foo.o}, whose property 0xc0000002 value
- is 0x1, and @file{bar.o}, which doesn't have property 0xc0000002.
- @smallexample
- Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1)
- @end smallexample
- This indicates that property 0xc0010001 value is updated to 0x1 in output
- when merging properties in @file{foo.o}, whose 0xc0010001 property value
- is 0x1, and @file{bar.o}, whose 0xc0010001 property value is 0x1.
- @end itemize
- @cindex link map discarded
- @kindex --print-map-discarded
- @kindex --no-print-map-discarded
- @item --print-map-discarded
- @itemx --no-print-map-discarded
- Print (or do not print) the list of discarded and garbage collected sections
- in the link map. Enabled by default.
- @kindex -n
- @cindex read-only text
- @cindex NMAGIC
- @kindex --nmagic
- @item -n
- @itemx --nmagic
- 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}.
- @kindex -N
- @kindex --omagic
- @cindex read/write from cmd line
- @cindex OMAGIC
- @item -N
- @itemx --omagic
- 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}. Note: Although a writable text section
- is allowed for PE-COFF targets, it does not conform to the format
- specification published by Microsoft.
- @kindex --no-omagic
- @cindex OMAGIC
- @item --no-omagic
- This option negates most of the effects of the @option{-N} 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 @option{-Bdynamic} for this.
- @kindex -o @var{output}
- @kindex --output=@var{output}
- @cindex naming the output file
- @item -o @var{output}
- @itemx --output=@var{output}
- Use @var{output} as the name for the program produced by @command{ld}; if this
- option is not specified, the name @file{a.out} is used by default. The
- script command @code{OUTPUT} can also specify the output file name.
- @kindex --dependency-file=@var{depfile}
- @cindex dependency file
- @item --dependency-file=@var{depfile}
- Write a @dfn{dependency file} to @var{depfile}. This file contains a rule
- suitable for @code{make} 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} (@pxref{Preprocessor Options,, Options
- Controlling the Preprocessor, gcc.info, Using the GNU Compiler
- Collection}). Note that there is no option like the compiler's @samp{-MM},
- 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} 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.
- @kindex -O @var{level}
- @cindex generating optimized output
- @item -O @var{level}
- If @var{level} is a numeric values greater than zero @command{ld} 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.
- @kindex -plugin @var{name}
- @item -plugin @var{name}
- Involve a plugin in the linking process. The @var{name} 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.
- Note that the location of the compiler originated plugins is different
- from the place where the @command{ar}, @command{nm} and
- @command{ranlib} 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 @file{$@{libdir@}/bfd-plugins} directory. All gcc
- based linker plugins are backward compatible, so it is sufficient to
- just copy in the newest one.
- @kindex --push-state
- @cindex push state governing input file handling
- @item --push-state
- The @option{--push-state} 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 @option{--pop-state} option.
- The option which are covered are: @option{-Bdynamic}, @option{-Bstatic},
- @option{-dn}, @option{-dy}, @option{-call_shared}, @option{-non_shared},
- @option{-static}, @option{-N}, @option{-n}, @option{--whole-archive},
- @option{--no-whole-archive}, @option{-r}, @option{-Ur},
- @option{--copy-dt-needed-entries}, @option{--no-copy-dt-needed-entries},
- @option{--as-needed}, @option{--no-as-needed}, and @option{-a}.
- One target for this option are specifications for @file{pkg-config}. When
- used with the @option{--libs} option all possibly needed libraries are
- listed and then possibly linked with all the time. It is better to return
- something as follows:
- @smallexample
- -Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
- @end smallexample
- @kindex --pop-state
- @cindex pop state governing input file handling
- @item --pop-state
- Undoes the effect of --push-state, restores the previous values of the
- flags governing input file handling.
- @kindex -q
- @kindex --emit-relocs
- @cindex retain relocations in final executable
- @item -q
- @itemx --emit-relocs
- 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.
- This option is currently only supported on ELF platforms.
- @kindex --force-dynamic
- @cindex forcing the creation of dynamic sections
- @item --force-dynamic
- Force the output file to have dynamic sections. This option is specific
- to VxWorks targets.
- @cindex partial link
- @cindex relocatable output
- @kindex -r
- @kindex --relocatable
- @item -r
- @itemx --relocatable
- Generate relocatable output---i.e., generate an output file that can in
- turn serve as input to @command{ld}. This is often called @dfn{partial
- linking}. 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}.
- @c ; see @option{-N}.
- If this option is not specified, an absolute file is produced. When
- linking C++ programs, this option @emph{will not} resolve references to
- constructors; to do that, use @samp{-Ur}.
- 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}-based formats do not support partial linking
- with input files in other formats at all.
- This option does the same thing as @samp{-i}.
- @kindex -R @var{file}
- @kindex --just-symbols=@var{file}
- @cindex symbol-only input
- @item -R @var{filename}
- @itemx --just-symbols=@var{filename}
- Read symbol names and their addresses from @var{filename}, 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.
- For compatibility with other ELF linkers, if the @option{-R} option is
- followed by a directory name, rather than a file name, it is treated as
- the @option{-rpath} option.
- @kindex -s
- @kindex --strip-all
- @cindex strip all symbols
- @item -s
- @itemx --strip-all
- Omit all symbol information from the output file.
- @kindex -S
- @kindex --strip-debug
- @cindex strip debugger symbols
- @item -S
- @itemx --strip-debug
- Omit debugger symbol information (but not all symbols) from the output file.
- @kindex --strip-discarded
- @kindex --no-strip-discarded
- @item --strip-discarded
- @itemx --no-strip-discarded
- Omit (or do not omit) global symbols defined in discarded sections.
- Enabled by default.
- @kindex -t
- @kindex --trace
- @cindex input files, displaying
- @item -t
- @itemx --trace
- Print the names of the input files as @command{ld} processes them. If
- @samp{-t} is given twice then members within archives are also printed.
- @samp{-t} 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.
- @kindex -T @var{script}
- @kindex --script=@var{script}
- @cindex script files
- @item -T @var{scriptfile}
- @itemx --script=@var{scriptfile}
- Use @var{scriptfile} as the linker script. This script replaces
- @command{ld}'s default linker script (rather than adding to it), so
- @var{commandfile} must specify everything necessary to describe the
- output file. @xref{Scripts}. If @var{scriptfile} does not exist in
- the current directory, @code{ld} looks for it in the directories
- specified by any preceding @samp{-L} options. Multiple @samp{-T}
- options accumulate.
- @kindex -dT @var{script}
- @kindex --default-script=@var{script}
- @cindex script files
- @item -dT @var{scriptfile}
- @itemx --default-script=@var{scriptfile}
- Use @var{scriptfile} as the default linker script. @xref{Scripts}.
- This option is similar to the @option{--script} 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
- @option{--default-script} 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}).
- @kindex -u @var{symbol}
- @kindex --undefined=@var{symbol}
- @cindex undefined symbol
- @item -u @var{symbol}
- @itemx --undefined=@var{symbol}
- Force @var{symbol} 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} may be repeated with
- different option arguments to enter additional undefined symbols. This
- option is equivalent to the @code{EXTERN} linker script command.
- 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 @option{--require-defined} should be used
- instead.
- @kindex --require-defined=@var{symbol}
- @cindex symbols, require defined
- @cindex defined symbol
- @item --require-defined=@var{symbol}
- Require that @var{symbol} is defined in the output file. This option
- is the same as option @option{--undefined} except that if @var{symbol}
- 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{ASSERT} and @code{DEFINED} together. This option
- can be used multiple times to require additional symbols.
- @kindex -Ur
- @cindex constructors
- @item -Ur
- For anything other than C++ programs, this option is equivalent to
- @samp{-r}: it generates relocatable output---i.e., an output file that can in
- turn serve as input to @command{ld}. When linking C++ programs, @samp{-Ur}
- @emph{does} resolve references to constructors, unlike @samp{-r}.
- It does not work to use @samp{-Ur} on files that were themselves linked
- with @samp{-Ur}; once the constructor table has been built, it cannot
- be added to. Use @samp{-Ur} only for the last partial link, and
- @samp{-r} for the others.
- @kindex --orphan-handling=@var{MODE}
- @cindex orphan sections
- @cindex sections, orphan
- @item --orphan-handling=@var{MODE}
- Control how orphan sections are handled. An orphan section is one not
- specifically mentioned in a linker script. @xref{Orphan Sections}.
- @var{MODE} can have any of the following values:
- @table @code
- @item place
- Orphan sections are placed into a suitable output section following
- the strategy described in @ref{Orphan Sections}. The option
- @samp{--unique} also affects how sections are placed.
- @item discard
- All orphan sections are discarded, by placing them in the
- @samp{/DISCARD/} section (@pxref{Output Section Discarding}).
- @item warn
- The linker will place the orphan section as for @code{place} and also
- issue a warning.
- @item error
- The linker will exit with an error if any orphan section is found.
- @end table
- The default if @samp{--orphan-handling} is not given is @code{place}.
- @kindex --unique[=@var{SECTION}]
- @item --unique[=@var{SECTION}]
- Creates a separate output section for every input section matching
- @var{SECTION}, or if the optional wildcard @var{SECTION} 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.
- @kindex -v
- @kindex -V
- @kindex --version
- @cindex version
- @item -v
- @itemx --version
- @itemx -V
- Display the version number for @command{ld}. The @option{-V} option also
- lists the supported emulations.
- @kindex -x
- @kindex --discard-all
- @cindex deleting local symbols
- @item -x
- @itemx --discard-all
- Delete all local symbols.
- @kindex -X
- @kindex --discard-locals
- @cindex local symbols, deleting
- @item -X
- @itemx --discard-locals
- Delete all temporary local symbols. (These symbols start with
- system-specific local label prefixes, typically @samp{.L} for ELF systems
- or @samp{L} for traditional a.out systems.)
- @kindex -y @var{symbol}
- @kindex --trace-symbol=@var{symbol}
- @cindex symbol tracing
- @item -y @var{symbol}
- @itemx --trace-symbol=@var{symbol}
- Print the name of each linked file in which @var{symbol} appears. This
- option may be given any number of times. On many systems it is necessary
- to prepend an underscore.
- This option is useful when you have an undefined symbol in your link but
- don't know where the reference is coming from.
- @kindex -Y @var{path}
- @item -Y @var{path}
- Add @var{path} to the default library search path. This option exists
- for Solaris compatibility.
- @kindex -z @var{keyword}
- @item -z @var{keyword}
- The recognized keywords are:
- @table @samp
- @item bndplt
- Always generate BND prefix in PLT entries. Supported for Linux/x86_64.
- @item call-nop=prefix-addr
- @itemx call-nop=suffix-nop
- @itemx call-nop=prefix-@var{byte}
- @itemx call-nop=suffix-@var{byte}
- Specify the 1-byte @code{NOP} padding when transforming indirect call
- to a locally defined function, foo, via its GOT slot.
- @option{call-nop=prefix-addr} generates @code{0x67 call foo}.
- @option{call-nop=suffix-nop} generates @code{call foo 0x90}.
- @option{call-nop=prefix-@var{byte}} generates @code{@var{byte} call foo}.
- @option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}.
- Supported for i386 and x86_64.
- @item cet-report=none
- @itemx cet-report=warning
- @itemx cet-report=error
- 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. @option{cet-report=none}, which is the default, will make the
- linker not report missing properties in input files.
- @option{cet-report=warning} will make the linker issue a warning for
- missing properties in input files. @option{cet-report=error} will make
- the linker issue an error for missing properties in input files.
- Note that @option{ibt} will turn off the missing
- GNU_PROPERTY_X86_FEATURE_1_IBT property report and @option{shstk} will
- turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report.
- Supported for Linux/i386 and Linux/x86_64.
- @item combreloc
- @itemx nocombreloc
- Combine multiple dynamic relocation sections and sort to improve
- dynamic symbol lookup caching. Do not do this if @samp{nocombreloc}.
- @item common
- @itemx nocommon
- Generate common symbols with STT_COMMON type during a relocatable
- link. Use STT_OBJECT type if @samp{nocommon}.
- @item common-page-size=@var{value}
- Set the page size most commonly used to @var{value}. Memory image
- layout will be optimized to minimize memory pages if the system is
- using pages of this size.
- @item defs
- 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}.
- @item dynamic-undefined-weak
- @itemx nodynamic-undefined-weak
- 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}. 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.
- @item execstack
- Marks the object as requiring executable stack.
- @item global
- 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.
- @item globalaudit
- 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} bit in the @code{DT_FLAGS_1} dynamic
- tag. Global auditing requires that any auditing library defined via
- the @option{--depaudit} or @option{-P} command-line options be run for
- all dynamic objects loaded by the application.
- @item ibtplt
- Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries.
- Supported for Linux/i386 and Linux/x86_64.
- @item ibt
- Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section
- to indicate compatibility with IBT. This also implies @option{ibtplt}.
- Supported for Linux/i386 and Linux/x86_64.
- @item indirect-extern-access
- @itemx noindirect-extern-access
- 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 @option{noextern-protected-data} and
- @option{nocopyreloc}. Supported for i386 and x86-64.
- @option{noindirect-extern-access} removes
- GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS from .note.gnu.property
- section.
- @item initfirst
- 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.
- @item interpose
- 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.
- @item unique
- @itemx nounique
- 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}). 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} caller
- and does not apply to certain loading mechanisms (such as audit libraries).
- @item lam-u48
- 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.
- @item lam-u57
- 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.
- @item lam-u48-report=none
- @itemx lam-u48-report=warning
- @itemx lam-u48-report=error
- Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48
- property in input .note.gnu.property section.
- @option{lam-u48-report=none}, which is the default, will make the
- linker not report missing properties in input files.
- @option{lam-u48-report=warning} will make the linker issue a warning for
- missing properties in input files. @option{lam-u48-report=error} will
- make the linker issue an error for missing properties in input files.
- Supported for Linux/x86_64.
- @item lam-u57-report=none
- @itemx lam-u57-report=warning
- @itemx lam-u57-report=error
- Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U57
- property in input .note.gnu.property section.
- @option{lam-u57-report=none}, which is the default, will make the
- linker not report missing properties in input files.
- @option{lam-u57-report=warning} will make the linker issue a warning for
- missing properties in input files. @option{lam-u57-report=error} will
- make the linker issue an error for missing properties in input files.
- Supported for Linux/x86_64.
- @item lam-report=none
- @itemx lam-report=warning
- @itemx lam-report=error
- 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. @option{lam-report=none}, which is the default, will make the
- linker not report missing properties in input files.
- @option{lam-report=warning} will make the linker issue a warning for
- missing properties in input files. @option{lam-report=error} will make
- the linker issue an error for missing properties in input files.
- Supported for Linux/x86_64.
- @item lazy
- 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.
- @item loadfltr
- Specify that the object's filters be processed immediately at runtime.
- @item max-page-size=@var{value}
- Set the maximum memory page size supported to @var{value}.
- @item muldefs
- Allow multiple definitions.
- @item nocopyreloc
- Disable linker generated .dynbss variables used in place of variables
- defined in shared libraries. May result in dynamic text relocations.
- @item nodefaultlib
- Specify that the dynamic loader search for dependencies of this object
- should ignore any default library search paths.
- @item nodelete
- Specify that the object shouldn't be unloaded at runtime.
- @item nodlopen
- Specify that the object is not available to @code{dlopen}.
- @item nodump
- Specify that the object can not be dumped by @code{dldump}.
- @item noexecstack
- Marks the object as not requiring executable stack.
- @item noextern-protected-data
- 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.
- @item noreloc-overflow
- 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.
- @item now
- 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.
- @item origin
- Specify that the object requires @samp{$ORIGIN} handling in paths.
- @item pack-relative-relocs
- @itemx nopack-relative-relocs
- Generate compact relative relocation in position-independent executable
- and shared library. It adds @code{DT_RELR}, @code{DT_RELRSZ} and
- @code{DT_RELRENT} entries to the dynamic section. It is ignored when
- building position-dependent executable and relocatable output.
- @option{nopack-relative-relocs} 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.
- @item relro
- @itemx norelro
- Create an ELF @code{PT_GNU_RELRO} 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} smaller
- than the system page size will render this protection ineffective.
- Don't create an ELF @code{PT_GNU_RELRO} segment if @samp{norelro}.
- @item report-relative-reloc
- Report dynamic relative relocations generated by linker. Supported for
- Linux/i386 and Linux/x86_64.
- @item separate-code
- @itemx noseparate-code
- Create separate code @code{PT_LOAD} 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} segment if @samp{noseparate-code} is used.
- @item shstk
- 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.
- @item stack-size=@var{value}
- Specify a stack size for an ELF @code{PT_GNU_STACK} segment.
- Specifying zero will override any default non-zero sized
- @code{PT_GNU_STACK} segment creation.
- @item start-stop-gc
- @itemx nostart-stop-gc
- @cindex start-stop-gc
- When @samp{--gc-sections} is in effect, a reference from a retained
- section to @code{__start_SECNAME} or @code{__stop_SECNAME} causes all
- input sections named @code{SECNAME} to also be retained, if
- @code{SECNAME} is representable as a C identifier and either
- @code{__start_SECNAME} or @code{__stop_SECNAME} is synthesized by the
- linker. @samp{-z start-stop-gc} disables this effect, allowing
- sections to be garbage collected as if the special synthesized symbols
- were not defined. @samp{-z start-stop-gc} has no effect on a
- definition of @code{__start_SECNAME} or @code{__stop_SECNAME} in an
- object file or linker script. Such a definition will prevent the
- linker providing a synthesized @code{__start_SECNAME} or
- @code{__stop_SECNAME} respectively, and therefore the special
- treatment by garbage collection for those references.
- @item start-stop-visibility=@var{value}
- @cindex visibility
- @cindex ELF symbol visibility
- Specify the ELF symbol visibility for synthesized
- @code{__start_SECNAME} and @code{__stop_SECNAME} symbols (@pxref{Input
- Section Example}). @var{value} must be exactly @samp{default},
- @samp{internal}, @samp{hidden}, or @samp{protected}. If no @samp{-z
- start-stop-visibility} option is given, @samp{protected} is used for
- compatibility with historical practice. However, it's highly
- recommended to use @samp{-z start-stop-visibility=hidden} in new
- programs and shared libraries so that these symbols are not exported
- between shared objects, which is not usually what's intended.
- @item text
- @itemx notext
- @itemx textoff
- 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} or @samp{textoff}.
- @item undefs
- 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}.
- @item unique-symbol
- @itemx nounique-symbol
- Avoid duplicated local symbol names in the symbol string table. Append
- ".@code{number}" to duplicated local symbol names if @samp{unique-symbol}
- is used. @option{nounique-symbol} is the default.
- @item x86-64-baseline
- @item x86-64-v2
- @item x86-64-v3
- @itemx x86-64-v4
- Specify the x86-64 ISA level needed in .note.gnu.property section.
- @option{x86-64-baseline} generates @code{GNU_PROPERTY_X86_ISA_1_BASELINE}.
- @option{x86-64-v2} generates @code{GNU_PROPERTY_X86_ISA_1_V2}.
- @option{x86-64-v3} generates @code{GNU_PROPERTY_X86_ISA_1_V3}.
- @option{x86-64-v4} generates @code{GNU_PROPERTY_X86_ISA_1_V4}.
- Supported for Linux/i386 and Linux/x86_64.
- @end table
- Other keywords are ignored for Solaris compatibility.
- @kindex -(
- @cindex groups of archives
- @item -( @var{archives} -)
- @itemx --start-group @var{archives} --end-group
- The @var{archives} should be a list of archive files. They may be
- either explicit file names, or @samp{-l} options.
- 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.
- 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.
- @kindex --accept-unknown-input-arch
- @kindex --no-accept-unknown-input-arch
- @item --accept-unknown-input-arch
- @itemx --no-accept-unknown-input-arch
- 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} option has been added to
- restore the old behaviour.
- @kindex --as-needed
- @kindex --no-as-needed
- @item --as-needed
- @itemx --no-as-needed
- This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
- on the command line after the @option{--as-needed} 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. @option{--as-needed} causes a DT_NEEDED tag to only be
- emitted for a library that @emph{at that point in the link} 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 @emph{after}
- 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. @option{--no-as-needed} restores the default behaviour.
- Note: On Linux based systems the @option{--as-needed} option also has
- an affect on the behaviour of the @option{--rpath} and
- @option{--rpath-link} options. See the description of
- @option{--rpath-link} for more details.
- @kindex --add-needed
- @kindex --no-add-needed
- @item --add-needed
- @itemx --no-add-needed
- These two options have been deprecated because of the similarity of
- their names to the @option{--as-needed} and @option{--no-as-needed}
- options. They have been replaced by @option{--copy-dt-needed-entries}
- and @option{--no-copy-dt-needed-entries}.
- @kindex -assert @var{keyword}
- @item -assert @var{keyword}
- This option is ignored for SunOS compatibility.
- @kindex -Bdynamic
- @kindex -dy
- @kindex -call_shared
- @item -Bdynamic
- @itemx -dy
- @itemx -call_shared
- 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
- @option{-l} options which follow it.
- @kindex -Bgroup
- @item -Bgroup
- Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} 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.
- @option{--unresolved-symbols=report-all} is implied. This option is
- only meaningful on ELF platforms which support shared libraries.
- @kindex -Bstatic
- @kindex -dn
- @kindex -non_shared
- @kindex -static
- @item -Bstatic
- @itemx -dn
- @itemx -non_shared
- @itemx -static
- 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 @option{-l} options which follow it. This
- option also implies @option{--unresolved-symbols=report-all}. This
- option can be used with @option{-shared}. 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.
- @kindex -Bsymbolic
- @item -Bsymbolic
- 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.
- @kindex -Bsymbolic-functions
- @item -Bsymbolic-functions
- 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.
- @kindex -Bno-symbolic
- @item -Bno-symbolic
- This option can cancel previously specified @samp{-Bsymbolic} and
- @samp{-Bsymbolic-functions}.
- @kindex --dynamic-list=@var{dynamic-list-file}
- @item --dynamic-list=@var{dynamic-list-file}
- 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.
- The format of the dynamic list is the same as the version node without
- scope and node name. See @ref{VERSION} for more information.
- @kindex --dynamic-list-data
- @item --dynamic-list-data
- Include all global data symbols to the dynamic list.
- @kindex --dynamic-list-cpp-new
- @item --dynamic-list-cpp-new
- Provide the builtin dynamic list for C++ operator new and delete. It
- is mainly useful for building shared libstdc++.
- @kindex --dynamic-list-cpp-typeinfo
- @item --dynamic-list-cpp-typeinfo
- Provide the builtin dynamic list for C++ runtime type identification.
- @kindex --check-sections
- @kindex --no-check-sections
- @item --check-sections
- @itemx --no-check-sections
- Asks the linker @emph{not} 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 @option{--check-sections}.
- Section overlap is not usually checked for relocatable links. You can
- force checking in that case by using the @option{--check-sections}
- option.
- @kindex --copy-dt-needed-entries
- @kindex --no-copy-dt-needed-entries
- @item --copy-dt-needed-entries
- @itemx --no-copy-dt-needed-entries
- This option affects the treatment of dynamic libraries referred to
- by DT_NEEDED tags @emph{inside} 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 @option{--copy-dt-needed-entries}
- 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 @option{--no-copy-dt-needed-entries}.
- This option also has an effect on the resolution of symbols in dynamic
- libraries. With @option{--copy-dt-needed-entries} 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.
- @cindex cross reference table
- @kindex --cref
- @item --cref
- 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.
- 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.
- @cindex ctf variables
- @kindex --ctf-variables
- @kindex --no-ctf-variables
- @item --ctf-variables
- @item --no-ctf-variables
- 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.
- @option{--ctf-variables} causes the generation of such a section.
- The default behaviour can be restored with @option{--no-ctf-variables}.
- @cindex ctf type sharing
- @kindex --ctf-share-types
- @item --ctf-share-types=@var{method}
- Adjust the method used to share types between translation units in CTF.
- @table @samp
- @item share-unconflicted
- 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.
- @item share-duplicated
- 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.
- @end table
- @cindex common allocation
- @kindex --no-define-common
- @item --no-define-common
- This option inhibits the assignment of addresses to common symbols.
- The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
- @xref{Miscellaneous Commands}.
- The @samp{--no-define-common} 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} 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.
- @cindex group allocation in linker script
- @cindex section groups
- @cindex COMDAT
- @kindex --force-group-allocation
- @item --force-group-allocation
- 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}). The script
- command @code{FORCE_GROUP_ALLOCATION} has the same
- effect. @xref{Miscellaneous Commands}.
- @cindex symbols, from command line
- @kindex --defsym=@var{symbol}=@var{exp}
- @item --defsym=@var{symbol}=@var{expression}
- Create a global symbol in the output file, containing the absolute
- address given by @var{expression}. 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} in this
- context: you may give a hexadecimal constant or the name of an existing
- symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
- constants or symbols. If you need more elaborate expressions, consider
- using the linker command language from a script (@pxref{Assignments}).
- @emph{Note:} there should be no white space between @var{symbol}, the
- equals sign (``@key{=}''), and @var{expression}.
- The linker processes @samp{--defsym} arguments and @samp{-T} arguments
- in order, placing @samp{--defsym} before @samp{-T} will define the
- symbol before the linker script from @samp{-T} is processed, while
- placing @samp{--defsym} after @samp{-T} 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} symbols, which order is correct will depend on what
- you are trying to achieve.
- @cindex demangling, from command line
- @kindex --demangle[=@var{style}]
- @kindex --no-demangle
- @item --demangle[=@var{style}]
- @itemx --no-demangle
- 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}
- is set. These options may be used to override the default.
- @cindex dynamic linker, from command line
- @kindex -I@var{file}
- @kindex --dynamic-linker=@var{file}
- @item -I@var{file}
- @itemx --dynamic-linker=@var{file}
- 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.
- @kindex --no-dynamic-linker
- @item --no-dynamic-linker
- 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.
- @kindex --embedded-relocs
- @item --embedded-relocs
- This option is similar to the @option{--emit-relocs} option except
- that the relocs are stored in a target-specific section. This option
- is only supported by the @samp{BFIN}, @samp{CR16} and @emph{M68K}
- targets.
- @kindex --disable-multiple-abs-defs
- @item --disable-multiple-abs-defs
- Do not allow multiple definitions with symbols included
- in filename invoked by -R or --just-symbols
- @kindex --fatal-warnings
- @kindex --no-fatal-warnings
- @item --fatal-warnings
- @itemx --no-fatal-warnings
- Treat all warnings as errors. The default behaviour can be restored
- with the option @option{--no-fatal-warnings}.
- @kindex --force-exe-suffix
- @item --force-exe-suffix
- Make sure that an output file has a .exe suffix.
- If a successfully built fully linked output file does not have a
- @code{.exe} or @code{.dll} suffix, this option forces the linker to copy
- the output file to one of the same name with a @code{.exe} 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} suffix.
- @kindex --gc-sections
- @kindex --no-gc-sections
- @cindex garbage collection
- @item --gc-sections
- @itemx --no-gc-sections
- 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} 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.
- @samp{--gc-sections} 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{--undefined}, and
- @samp{--gc-keep-exported}.
- This option can be set when doing a partial link (enabled with option
- @samp{-r}). In this case the root of symbols kept must be explicitly
- specified either by one of the options @samp{--entry},
- @samp{--undefined}, or @samp{--gc-keep-exported} or by a @code{ENTRY}
- command in the linker script.
- As a GNU extension, ELF input sections marked with the
- @code{SHF_GNU_RETAIN} flag will not be garbage collected.
- @kindex --print-gc-sections
- @kindex --no-print-gc-sections
- @cindex garbage collection
- @item --print-gc-sections
- @itemx --no-print-gc-sections
- 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}) option. The
- default behaviour (of not listing the sections that are removed) can
- be restored by specifying @samp{--no-print-gc-sections} on the command
- line.
- @kindex --gc-keep-exported
- @cindex garbage collection
- @item --gc-keep-exported
- When @samp{--gc-sections} 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.
- @kindex --print-output-format
- @cindex output format
- @item --print-output-format
- 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} linker script command (@pxref{File Commands}).
- @kindex --print-memory-usage
- @cindex memory usage
- @item --print-memory-usage
- Print used size, total size and used size of memory regions created with
- the @ref{MEMORY} 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:
- @smallexample
- Memory region Used Size Region Size %age Used
- ROM: 256 KB 1 MB 25.00%
- RAM: 32 B 2 GB 0.00%
- @end smallexample
- @cindex help
- @cindex usage
- @kindex --help
- @item --help
- Print a summary of the command-line options on the standard output and exit.
- @kindex --target-help
- @item --target-help
- Print a summary of all target-specific options on the standard output and exit.
- @kindex -Map=@var{mapfile}
- @item -Map=@var{mapfile}
- Print a link map to the file @var{mapfile}. See the description of the
- @option{-M} option, above. If @var{mapfile} is just the character
- @code{-} then the map will be written to stdout.
- Specifying a directory as @var{mapfile} 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}
- file with @code{.map} appended. If however the special character
- @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{%} symbol then @code{.map} will no longer be appended.
- @smallexample
- -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]
- @end smallexample
- It is an error to specify more than one @code{%} character.
- If the map file already exists then it will be overwritten by this
- operation.
- @cindex memory usage
- @kindex --no-keep-memory
- @item --no-keep-memory
- @command{ld} normally optimizes for speed over memory usage by caching the
- symbol tables of input files in memory. This option tells @command{ld} to
- instead optimize for memory usage, by rereading the symbol tables as
- necessary. This may be required if @command{ld} runs out of memory space
- while linking a large executable.
- @kindex --no-undefined
- @kindex -z defs
- @kindex -z undefs
- @item --no-undefined
- @itemx -z defs
- Report unresolved symbol references from regular object files. This
- is done even if the linker is creating a non-symbolic shared library.
- The switch @option{--[no-]allow-shlib-undefined} controls the
- behaviour for reporting unresolved references found in shared
- libraries being linked in.
- The effects of this option can be reverted by using @code{-z undefs}.
- @kindex --allow-multiple-definition
- @kindex -z muldefs
- @item --allow-multiple-definition
- @itemx -z muldefs
- 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.
- @kindex --allow-shlib-undefined
- @kindex --no-allow-shlib-undefined
- @item --allow-shlib-undefined
- @itemx --no-allow-shlib-undefined
- Allows or disallows undefined symbols in shared libraries.
- This switch is similar to @option{--no-undefined} 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.
- 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.
- The reasons for allowing undefined symbol references in shared
- libraries specified at link time are that:
- @itemize @bullet
- @item
- 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.
- @item
- There are some operating systems, eg BeOS and HPPA, where undefined
- symbols in shared libraries are normal.
- 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.
- @end itemize
- @kindex --error-handling-script=@var{scriptname}
- @item --error-handling-script=@var{scriptname}
- If this option is provided then the linker will invoke
- @var{scriptname} 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} 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.
- The availability of this option is controlled by a configure time
- switch, so it may not be present in specific implementations.
- @kindex --no-undefined-version
- @item --no-undefined-version
- 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.
- @kindex --default-symver
- @item --default-symver
- Create and use a default symbol version (the soname) for unversioned
- exported symbols.
- @kindex --default-imported-symver
- @item --default-imported-symver
- Create and use a default symbol version (the soname) for unversioned
- imported symbols.
- @kindex --no-warn-mismatch
- @item --no-warn-mismatch
- Normally @command{ld} 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 @command{ld} 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.
- @kindex --no-warn-search-mismatch
- @item --no-warn-search-mismatch
- Normally @command{ld} will give a warning if it finds an incompatible
- library during a library search. This option silences the warning.
- @kindex --no-whole-archive
- @item --no-whole-archive
- Turn off the effect of the @option{--whole-archive} option for subsequent
- archive files.
- @cindex output file after errors
- @kindex --noinhibit-exec
- @item --noinhibit-exec
- 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.
- @kindex -nostdlib
- @item -nostdlib
- 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.
- @ifclear SingleFormat
- @kindex --oformat=@var{output-format}
- @item --oformat=@var{output-format}
- @command{ld} may be configured to support more than one kind of object
- file. If your @command{ld} is configured this way, you can use the
- @samp{--oformat} option to specify the binary format for the output
- object file. Even when @command{ld} is configured to support alternative
- object formats, you don't usually need to specify this, as @command{ld}
- should be configured to produce as a default output format the most
- usual format on each machine. @var{output-format} 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}.) The script
- command @code{OUTPUT_FORMAT} can also specify the output format, but
- this option overrides it. @xref{BFD}.
- @end ifclear
- @kindex --out-implib
- @item --out-implib @var{file}
- Create an import library in @var{file} corresponding to the executable
- the linker is generating (eg. a DLL or ELF program). This import
- library (which should be called @code{*.dll.a} or @code{*.a} 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} for DLLs). This option is only available for
- the i386 PE and ELF targetted ports of the linker.
- @kindex -pie
- @kindex --pic-executable
- @item -pie
- @itemx --pic-executable
- @cindex position independent executables
- 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.
- @kindex -no-pie
- @item -no-pie
- @cindex position dependent executables
- Create a position dependent executable. This is the default.
- @kindex -qmagic
- @item -qmagic
- This option is ignored for Linux compatibility.
- @kindex -Qy
- @item -Qy
- This option is ignored for SVR4 compatibility.
- @kindex --relax
- @cindex synthesizing linker
- @cindex relaxing addressing modes
- @cindex --no-relax
- @item --relax
- @itemx --no-relax
- An option with machine dependent effects.
- @ifset GENERIC
- This option is only supported on a few targets.
- @end ifset
- @ifset H8300
- @xref{H8/300,,@command{ld} and the H8/300}.
- @end ifset
- @ifset XTENSA
- @xref{Xtensa,, @command{ld} and Xtensa Processors}.
- @end ifset
- @ifset M68HC11
- @xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
- @end ifset
- @ifset NIOSII
- @xref{Nios II,,@command{ld} and the Altera Nios II}.
- @end ifset
- @ifset POWERPC
- @xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
- @end ifset
- On some platforms the @option{--relax} 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.
- On some platforms these link time global optimizations may make symbolic
- debugging of the resulting executable impossible.
- @ifset GENERIC
- This is known to be the case for the Matsushita MN10200 and MN10300
- family of processors.
- @end ifset
- On platforms where the feature is supported, the option
- @option{--no-relax} will disable it.
- On platforms where the feature is not supported, both @option{--relax}
- and @option{--no-relax} are accepted, but ignored.
- @cindex retaining specified symbols
- @cindex stripping all but some symbols
- @cindex symbols, retaining selectively
- @kindex --retain-symbols-file=@var{filename}
- @item --retain-symbols-file=@var{filename}
- Retain @emph{only} the symbols listed in the file @var{filename},
- discarding all others. @var{filename} is simply a flat file, with one
- symbol name per line. This option is especially useful in environments
- @ifset GENERIC
- (such as VxWorks)
- @end ifset
- where a large global symbol table is accumulated gradually, to conserve
- run-time memory.
- @samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
- or symbols needed for relocations.
- You may only specify @samp{--retain-symbols-file} once in the command
- line. It overrides @samp{-s} and @samp{-S}.
- @ifset GENERIC
- @item -rpath=@var{dir}
- @cindex runtime library search path
- @kindex -rpath=@var{dir}
- Add a directory to the runtime library search path. This is used when
- linking an ELF executable with shared objects. All @option{-rpath}
- arguments are concatenated and passed to the runtime linker, which uses
- them to locate shared objects at runtime.
- The @option{-rpath} option is also used when locating shared objects which
- are needed by shared objects explicitly included in the link; see the
- description of the @option{-rpath-link} option. Searching @option{-rpath}
- in this way is only supported by native linkers and cross linkers which
- have been configured with the @option{--with-sysroot} option.
- If @option{-rpath} is not used when linking an ELF executable, the
- contents of the environment variable @code{LD_RUN_PATH} will be used if it
- is defined.
- The @option{-rpath} option may also be used on SunOS. By default, on
- SunOS, the linker will form a runtime search path out of all the
- @option{-L} options it is given. If a @option{-rpath} option is used, the
- runtime search path will be formed exclusively using the @option{-rpath}
- options, ignoring the @option{-L} options. This can be useful when using
- gcc, which adds many @option{-L} options which may be on NFS mounted
- file systems.
- For compatibility with other ELF linkers, if the @option{-R} option is
- followed by a directory name, rather than a file name, it is treated as
- the @option{-rpath} option.
- @end ifset
- @ifset GENERIC
- @cindex link-time runtime library search path
- @kindex -rpath-link=@var{dir}
- @item -rpath-link=@var{dir}
- When using ELF or SunOS, one shared library may require another. This
- happens when an @code{ld -shared} link includes a shared library as one
- of the input files.
- 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 @option{-rpath-link} option
- specifies the first set of directories to search. The
- @option{-rpath-link} option may specify a sequence of directory names
- either by specifying a list of names separated by colons, or by
- appearing multiple times.
- The tokens @var{$ORIGIN} and @var{$LIB} 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}
- and either @samp{lib} - for 32-bit binaries - or @samp{lib64} - for
- 64-bit binaries - in the case of @var{$LIB}.
- The alternative form of these tokens - @var{$@{ORIGIN@}} and
- @var{$@{LIB@}} can also be used. The token @var{$PLATFORM} is not
- supported.
- 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.
- The linker uses the following search paths to locate required shared
- libraries:
- @enumerate
- @item
- Any directories specified by @option{-rpath-link} options.
- @item
- Any directories specified by @option{-rpath} options. The difference
- between @option{-rpath} and @option{-rpath-link} is that directories
- specified by @option{-rpath} options are included in the executable and
- used at runtime, whereas the @option{-rpath-link} option is only effective
- at link time. Searching @option{-rpath} in this way is only supported
- by native linkers and cross linkers which have been configured with
- the @option{--with-sysroot} option.
- @item
- On an ELF system, for native linkers, if the @option{-rpath} and
- @option{-rpath-link} options were not used, search the contents of the
- environment variable @code{LD_RUN_PATH}.
- @item
- On SunOS, if the @option{-rpath} option was not used, search any
- directories specified using @option{-L} options.
- @item
- For a native linker, search the contents of the environment
- variable @code{LD_LIBRARY_PATH}.
- @item
- For a native ELF linker, the directories in @code{DT_RUNPATH} or
- @code{DT_RPATH} of a shared library are searched for shared
- libraries needed by it. The @code{DT_RPATH} entries are ignored if
- @code{DT_RUNPATH} entries exist.
- @item
- For a linker for a Linux system, if the file @file{/etc/ld.so.conf}
- exists, the list of directories found in that file. Note: the path
- to this file is prefixed with the @code{sysroot} value, if that is
- defined, and then any @code{prefix} string if the linker was
- configured with the @command{--prefix=<path>} option.
- @item
- For a native linker on a FreeBSD system, any directories specified by
- the @code{_PATH_ELF_HINTS} macro defined in the @file{elf-hints.h}
- header file.
- @item
- Any directories specified by a @code{SEARCH_DIR} command in a
- linker script given on the command line, including scripts specified
- by @option{-T} (but not @option{-dT}).
- @item
- The default directories, normally @file{/lib} and @file{/usr/lib}.
- @item
- Any directories specified by a plugin LDPT_SET_EXTRA_LIBRARY_PATH.
- @item
- Any directories specified by a @code{SEARCH_DIR} command in a default
- linker script.
- @end enumerate
- Note however on Linux based systems there is an additional caveat: If
- the @option{--as-needed} option is active @emph{and} a shared library
- is located which would normally satisfy the search @emph{and} this
- library does not have DT_NEEDED tag for @file{libc.so}
- @emph{and} there is a shared library later on in the set of search
- directories which also satisfies the search @emph{and}
- this second shared library does have a DT_NEEDED tag for
- @file{libc.so} @emph{then} the second library will be selected instead
- of the first.
- If the required shared library is not found, the linker will issue a
- warning and continue with the link.
- @end ifset
- @kindex -shared
- @kindex -Bshareable
- @item -shared
- @itemx -Bshareable
- @cindex shared libraries
- 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 @option{-e} option is not used and there are
- undefined symbols in the link.
- @kindex --sort-common
- @item --sort-common
- @itemx --sort-common=ascending
- @itemx --sort-common=descending
- This option tells @command{ld} 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.
- @kindex --sort-section=name
- @item --sort-section=name
- This option will apply @code{SORT_BY_NAME} to all wildcard section
- patterns in the linker script.
- @kindex --sort-section=alignment
- @item --sort-section=alignment
- This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
- patterns in the linker script.
- @kindex --spare-dynamic-tags
- @item --spare-dynamic-tags=@var{count}
- 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.
- @kindex --split-by-file
- @item --split-by-file[=@var{size}]
- Similar to @option{--split-by-reloc} but creates a new output section for
- each input file when @var{size} is reached. @var{size} defaults to a
- size of 1 if not given.
- @kindex --split-by-reloc
- @item --split-by-reloc[=@var{count}]
- Tries to creates extra sections in the output file so that no single
- output section in the file contains more than @var{count} 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} relocations one output section will contain that
- many relocations. @var{count} defaults to a value of 32768.
- @kindex --stats
- @item --stats
- Compute and display statistics about the operation of the linker, such
- as execution time and memory usage.
- @kindex --sysroot=@var{directory}
- @item --sysroot=@var{directory}
- Use @var{directory} as the location of the sysroot, overriding the
- configure-time default. This option is only supported by linkers
- that were configured using @option{--with-sysroot}.
- @kindex --task-link
- @item --task-link
- 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.
- @kindex --traditional-format
- @cindex traditional format
- @item --traditional-format
- For some targets, the output of @command{ld} is different in some ways from
- the output of some existing linker. This switch requests @command{ld} to
- use the traditional format instead.
- @cindex dbx
- For example, on SunOS, @command{ld} 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} program can not read the resulting program (@code{gdb} has no
- trouble). The @samp{--traditional-format} switch tells @command{ld} to not
- combine duplicate entries.
- @kindex --section-start=@var{sectionname}=@var{org}
- @item --section-start=@var{sectionname}=@var{org}
- Locate a section in the output file at the absolute
- address given by @var{org}. You may use this option as many
- times as necessary to locate multiple sections in the command
- line.
- @var{org} must be a single hexadecimal integer;
- for compatibility with other linkers, you may omit the leading
- @samp{0x} usually associated with hexadecimal values. @emph{Note:} there
- should be no white space between @var{sectionname}, the equals
- sign (``@key{=}''), and @var{org}.
- @kindex -Tbss=@var{org}
- @kindex -Tdata=@var{org}
- @kindex -Ttext=@var{org}
- @cindex segment origins, cmd line
- @item -Tbss=@var{org}
- @itemx -Tdata=@var{org}
- @itemx -Ttext=@var{org}
- Same as @option{--section-start}, with @code{.bss}, @code{.data} or
- @code{.text} as the @var{sectionname}.
- @kindex -Ttext-segment=@var{org}
- @item -Ttext-segment=@var{org}
- @cindex text segment origin, cmd line
- When creating an ELF executable, it will set the address of the first
- byte of the text segment.
- @kindex -Trodata-segment=@var{org}
- @item -Trodata-segment=@var{org}
- @cindex rodata segment origin, cmd line
- 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.
- @kindex -Tldata-segment=@var{org}
- @item -Tldata-segment=@var{org}
- @cindex ldata segment origin, cmd line
- 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.
- @kindex --unresolved-symbols
- @item --unresolved-symbols=@var{method}
- Determine how to handle unresolved symbols. There are four possible
- values for @samp{method}:
- @table @samp
- @item ignore-all
- Do not report any unresolved symbols.
- @item report-all
- Report all unresolved symbols. This is the default.
- @item ignore-in-object-files
- Report unresolved symbols that are contained in shared libraries, but
- ignore them if they come from regular object files.
- @item ignore-in-shared-libs
- 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.
- @end table
- The behaviour for shared libraries on their own can also be controlled
- by the @option{--[no-]allow-shlib-undefined} option.
- Normally the linker will generate an error message for each reported
- unresolved symbol but the option @option{--warn-unresolved-symbols}
- can change this to a warning.
- @kindex --verbose[=@var{NUMBER}]
- @cindex verbose[=@var{NUMBER}]
- @item --dll-verbose
- @itemx --verbose[=@var{NUMBER}]
- Display the version number for @command{ld} 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}
- argument > 1, plugin symbol status will also be displayed.
- @kindex --version-script=@var{version-scriptfile}
- @cindex version script, symbol versions
- @item --version-script=@var{version-scriptfile}
- 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 @ref{VERSION}. 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} in the version script will not be exported.
- @xref{WIN32}.
- @kindex --warn-common
- @cindex warnings, on combining symbols
- @cindex combining symbols, warnings on
- @item --warn-common
- 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.
- There are three kinds of global symbols, illustrated here by C examples:
- @table @samp
- @item int i = 1;
- A definition, which goes in the initialized data section of the output
- file.
- @item extern int i;
- An undefined reference, which does not allocate space.
- There must be either a definition or a common symbol for the
- variable somewhere.
- @item int i;
- 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.
- @end table
- The @samp{--warn-common} 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.
- @enumerate
- @item
- Turning a common symbol into a reference, because there is already a
- definition for the symbol.
- @smallexample
- @var{file}(@var{section}): warning: common of `@var{symbol}'
- overridden by definition
- @var{file}(@var{section}): warning: defined here
- @end smallexample
- @item
- 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.
- @smallexample
- @var{file}(@var{section}): warning: definition of `@var{symbol}'
- overriding common
- @var{file}(@var{section}): warning: common is here
- @end smallexample
- @item
- Merging a common symbol with a previous same-sized common symbol.
- @smallexample
- @var{file}(@var{section}): warning: multiple common
- of `@var{symbol}'
- @var{file}(@var{section}): warning: previous common is here
- @end smallexample
- @item
- Merging a common symbol with a previous larger common symbol.
- @smallexample
- @var{file}(@var{section}): warning: common of `@var{symbol}'
- overridden by larger common
- @var{file}(@var{section}): warning: larger common is here
- @end smallexample
- @item
- 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.
- @smallexample
- @var{file}(@var{section}): warning: common of `@var{symbol}'
- overriding smaller common
- @var{file}(@var{section}): warning: smaller common is here
- @end smallexample
- @end enumerate
- @kindex --warn-constructors
- @item --warn-constructors
- 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.
- @kindex --warn-multiple-gp
- @item --warn-multiple-gp
- 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.
- @kindex --warn-once
- @cindex warnings, on undefined symbols
- @cindex undefined symbols, warnings on
- @item --warn-once
- Only warn once for each undefined symbol, rather than once per module
- which refers to it.
- @kindex --warn-section-align
- @cindex warnings, on section alignment
- @cindex section alignment, warnings on
- @item --warn-section-align
- 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} command does not specify a start address for
- the section (@pxref{SECTIONS}).
- @kindex --warn-textrel
- @item --warn-textrel
- Warn if the linker adds DT_TEXTREL to a position-independent executable
- or shared object.
- @kindex --warn-alternate-em
- @item --warn-alternate-em
- Warn if an object has alternate ELF machine code.
- @kindex --warn-unresolved-symbols
- @item --warn-unresolved-symbols
- If the linker is going to report an unresolved symbol (see the option
- @option{--unresolved-symbols}) it will normally generate an error.
- This option makes it generate a warning instead.
- @kindex --error-unresolved-symbols
- @item --error-unresolved-symbols
- This restores the linker's default behaviour of generating errors when
- it is reporting unresolved symbols.
- @kindex --whole-archive
- @cindex including an entire archive
- @item --whole-archive
- For each archive mentioned on the command line after the
- @option{--whole-archive} 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.
- Two notes when using this option from gcc: First, gcc doesn't know
- about this option, so you have to use @option{-Wl,-whole-archive}.
- Second, don't forget to use @option{-Wl,-no-whole-archive} 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.
- @kindex --wrap=@var{symbol}
- @item --wrap=@var{symbol}
- Use a wrapper function for @var{symbol}. Any undefined reference to
- @var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
- undefined reference to @code{__real_@var{symbol}} will be resolved to
- @var{symbol}.
- This can be used to provide a wrapper for a system function. The
- wrapper function should be called @code{__wrap_@var{symbol}}. If it
- wishes to call the system function, it should call
- @code{__real_@var{symbol}}.
- Here is a trivial example:
- @smallexample
- void *
- __wrap_malloc (size_t c)
- @{
- printf ("malloc called with %zu\n", c);
- return __real_malloc (c);
- @}
- @end smallexample
- If you link other code with this file using @option{--wrap malloc}, then
- all calls to @code{malloc} will call the function @code{__wrap_malloc}
- instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
- call the real @code{malloc} function.
- You may wish to provide a @code{__real_malloc} function as well, so that
- links without the @option{--wrap} option will succeed. If you do this,
- you should not put the definition of @code{__real_malloc} in the same
- file as @code{__wrap_malloc}; if you do, the assembler may resolve the
- call before the linker has a chance to wrap it to @code{malloc}.
- Only undefined references are replaced by the linker. So, translation unit
- internal references to @var{symbol} are not resolved to
- @code{__wrap_@var{symbol}}. In the next example, the call to @code{f} in
- @code{g} is not resolved to @code{__wrap_f}.
- @smallexample
- int
- f (void)
- @{
- return 123;
- @}
- int
- g (void)
- @{
- return f();
- @}
- @end smallexample
- @kindex --eh-frame-hdr
- @kindex --no-eh-frame-hdr
- @item --eh-frame-hdr
- @itemx --no-eh-frame-hdr
- Request (@option{--eh-frame-hdr}) or suppress
- (@option{--no-eh-frame-hdr}) the creation of @code{.eh_frame_hdr}
- section and ELF @code{PT_GNU_EH_FRAME} segment header.
- @kindex --ld-generated-unwind-info
- @item --no-ld-generated-unwind-info
- Request creation of @code{.eh_frame} unwind info for linker
- generated code sections like PLT. This option is on by default
- if linker generated unwind info is supported.
- @kindex --enable-new-dtags
- @kindex --disable-new-dtags
- @item --enable-new-dtags
- @itemx --disable-new-dtags
- This linker can create the new dynamic tags in ELF. But the older ELF
- systems may not understand them. If you specify
- @option{--enable-new-dtags}, the new dynamic tags will be created as needed
- and older dynamic tags will be omitted.
- If you specify @option{--disable-new-dtags}, 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.
- @kindex --hash-size=@var{number}
- @item --hash-size=@var{number}
- Set the default size of the linker's hash tables to a prime number
- close to @var{number}. 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.
- @kindex --hash-style=@var{style}
- @item --hash-style=@var{style}
- Set the type of linker's hash table(s). @var{style} can be either
- @code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
- new style GNU @code{.gnu.hash} section or @code{both} for both
- the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
- hash tables. The default depends upon how the linker was configured,
- but for most Linux based systems it will be @code{both}.
- @kindex --compress-debug-sections=none
- @kindex --compress-debug-sections=zlib
- @kindex --compress-debug-sections=zlib-gnu
- @kindex --compress-debug-sections=zlib-gabi
- @item --compress-debug-sections=none
- @itemx --compress-debug-sections=zlib
- @itemx --compress-debug-sections=zlib-gnu
- @itemx --compress-debug-sections=zlib-gabi
- On ELF platforms, these options control how DWARF debug sections are
- compressed using zlib.
- @option{--compress-debug-sections=none} doesn't compress DWARF debug
- sections. @option{--compress-debug-sections=zlib-gnu} compresses
- DWARF debug sections and renames them to begin with @samp{.zdebug}
- instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi}
- also compresses DWARF debug sections, but rather than renaming them it
- sets the SHF_COMPRESSED flag in the sections' headers.
- The @option{--compress-debug-sections=zlib} option is an alias for
- @option{--compress-debug-sections=zlib-gabi}.
- Note that this option overrides any compression in input debug
- sections, so if a binary is linked with @option{--compress-debug-sections=none}
- for example, then any compressed debug sections in input files will be
- uncompressed before they are copied into the output binary.
- 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
- @option{--help} option.
- @kindex --reduce-memory-overheads
- @item --reduce-memory-overheads
- 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.
- 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 @option{--hash-size} switch
- has been used.
- The @option{--reduce-memory-overheads} switch may be also be used to
- enable other tradeoffs in future versions of the linker.
- @kindex --max-cache-size=@var{size}
- @item --max-cache-size=@var{size}
- @command{ld} 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}.
- @kindex --build-id
- @kindex --build-id=@var{style}
- @item --build-id
- @itemx --build-id=@var{style}
- Request the creation of a @code{.note.gnu.build-id} ELF note section
- or a @code{.buildid} COFF section. The contents of the note are
- unique bits identifying this linked file. @var{style} can be
- @code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit
- @sc{SHA1} hash on the normative parts of the output contents,
- @code{md5} to use a 128-bit @sc{MD5} hash on the normative parts of
- the output contents, or @code{0x@var{hexstring}} to use a chosen bit
- string specified as an even number of hexadecimal digits (@code{-} and
- @code{:} characters between digit pairs are ignored). If @var{style}
- is omitted, @code{sha1} is used.
- The @code{md5} and @code{sha1} 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.
- Passing @code{none} for @var{style} disables the setting from any
- @code{--build-id} options earlier on the command line.
- @end table
- @c man end
- @subsection Options Specific to i386 PE Targets
- @c man begin OPTIONS
- The i386 PE linker supports the @option{-shared} option, which causes
- the output to be a dynamically linked library (DLL) instead of a
- normal executable. You should name the output @code{*.dll} when you
- use this option. In addition, the linker fully supports the standard
- @code{*.def} 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).
- 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.
- @table @gcctabopt
- @kindex --add-stdcall-alias
- @item --add-stdcall-alias
- If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
- as-is and also with the suffix stripped.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --base-file
- @item --base-file @var{file}
- Use @var{file} as the name of a file in which to save the base
- addresses of all the relocations needed for generating DLLs with
- @file{dlltool}.
- [This is an i386 PE specific option]
- @kindex --dll
- @item --dll
- Create a DLL instead of a regular executable. You may also use
- @option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
- file.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --enable-long-section-names
- @kindex --disable-long-section-names
- @item --enable-long-section-names
- @itemx --disable-long-section-names
- 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, @command{ld} 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]
- @kindex --enable-stdcall-fixup
- @kindex --disable-stdcall-fixup
- @item --enable-stdcall-fixup
- @itemx --disable-stdcall-fixup
- 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} might be linked to the function
- @code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
- to the function @code{_bar}. 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 @option{--enable-stdcall-fixup}, this
- feature is fully enabled and warnings are not printed. If you specify
- @option{--disable-stdcall-fixup}, 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]
- @kindex --leading-underscore
- @kindex --no-leading-underscore
- @item --leading-underscore
- @itemx --no-leading-underscore
- 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.
- @cindex DLLs, creating
- @kindex --export-all-symbols
- @item --export-all-symbols
- 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{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
- @code{impure_ptr} 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_} or ending with
- @code{_iname}. In addition, no symbols from @code{libgcc},
- @code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
- Symbols whose names begin with @code{__rtti_} or @code{__builtin_} 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{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
- @code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
- @code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
- @code{cygwin_premain3}, and @code{environ}.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --exclude-symbols
- @item --exclude-symbols @var{symbol},@var{symbol},...
- 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]
- @kindex --exclude-all-symbols
- @item --exclude-all-symbols
- Specifies no symbols should be automatically exported.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --file-alignment
- @item --file-alignment
- 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]
- @cindex heap size
- @kindex --heap
- @item --heap @var{reserve}
- @itemx --heap @var{reserve},@var{commit}
- 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]
- @cindex image base
- @kindex --image-base
- @item --image-base @var{value}
- Use @var{value} 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]
- @kindex --kill-at
- @item --kill-at
- If given, the stdcall suffixes (@@@var{nn}) will be stripped from
- symbols before they are exported.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --large-address-aware
- @item --large-address-aware
- 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} 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]
- @kindex --disable-large-address-aware
- @item --disable-large-address-aware
- Reverts the effect of a previous @samp{--large-address-aware} option.
- This is useful if @samp{--large-address-aware} 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]
- @kindex --major-image-version
- @item --major-image-version @var{value}
- Sets the major number of the ``image version''. Defaults to 1.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --major-os-version
- @item --major-os-version @var{value}
- Sets the major number of the ``os version''. Defaults to 4.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --major-subsystem-version
- @item --major-subsystem-version @var{value}
- Sets the major number of the ``subsystem version''. Defaults to 4.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --minor-image-version
- @item --minor-image-version @var{value}
- Sets the minor number of the ``image version''. Defaults to 0.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --minor-os-version
- @item --minor-os-version @var{value}
- Sets the minor number of the ``os version''. Defaults to 0.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --minor-subsystem-version
- @item --minor-subsystem-version @var{value}
- Sets the minor number of the ``subsystem version''. Defaults to 0.
- [This option is specific to the i386 PE targeted port of the linker]
- @cindex DEF files, creating
- @cindex DLLs, creating
- @kindex --output-def
- @item --output-def @var{file}
- The linker will create the file @var{file} which will contain a DEF
- file corresponding to the DLL the linker is generating. This DEF file
- (which should be called @code{*.def}) may be used to create an import
- library with @code{dlltool} 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]
- @cindex DLLs, creating
- @kindex --enable-auto-image-base
- @item --enable-auto-image-base
- @itemx --enable-auto-image-base=@var{value}
- Automatically choose the image base for DLLs, optionally starting with base
- @var{value}, unless one is specified using the @code{--image-base} 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]
- @kindex --disable-auto-image-base
- @item --disable-auto-image-base
- Do not automatically generate a unique image base. If there is no
- user-specified image base (@code{--image-base}) then use the platform
- default.
- [This option is specific to the i386 PE targeted port of the linker]
- @cindex DLLs, linking to
- @kindex --dll-search-prefix
- @item --dll-search-prefix @var{string}
- When linking dynamically to a dll without an import library,
- search for @code{<string><basename>.dll} in preference to
- @code{lib<basename>.dll}. 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}.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --enable-auto-import
- @item --enable-auto-import
- Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} 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]
- The following remarks pertain to the original implementation of the
- feature and are obsolete nowadays for Cygwin and MinGW targets.
- 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.
- 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
- Using 'auto-import' generally will 'just work' -- but sometimes you may
- see this message:
- "variable '<var>' can't be auto-imported. Please read the
- documentation for ld's @code{--enable-auto-import} for details."
- 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.
- There are several ways to address this difficulty, regardless of the
- data type of the exported variable:
- 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.
- 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:
- @example
- extern type extern_array[];
- extern_array[1] -->
- @{ volatile type *t=extern_array; t[1] @}
- @end example
- or
- @example
- extern type extern_array[];
- extern_array[1] -->
- @{ volatile int t=1; extern_array[t] @}
- @end example
- For structs (and most other multiword data types) the only option
- is to make the struct itself (or the long long, or the ...) variable:
- @example
- extern struct s extern_struct;
- extern_struct.field -->
- @{ volatile struct s *t=&extern_struct; t->field @}
- @end example
- or
- @example
- extern long long extern_ll;
- extern_ll -->
- @{ volatile long long * local_ll=&extern_ll; *local_ll @}
- @end example
- A third method of dealing with this difficulty is to abandon
- 'auto-import' for the offending symbol and mark it with
- @code{__declspec(dllimport)}. 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:
- Original:
- @example
- --foo.h
- extern int arr[];
- --foo.c
- #include "foo.h"
- void main(int argc, char **argv)@{
- printf("%d\n",arr[1]);
- @}
- @end example
- Solution 1:
- @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]);
- @}
- @end example
- Solution 2:
- @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]);
- @}
- @end example
- 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).
- @kindex --disable-auto-import
- @item --disable-auto-import
- Do not attempt to do sophisticated linking of @code{_symbol} to
- @code{__imp__symbol} for DATA imports from DLLs.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --enable-runtime-pseudo-reloc
- @item --enable-runtime-pseudo-reloc
- 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]
- @kindex --disable-runtime-pseudo-reloc
- @item --disable-runtime-pseudo-reloc
- 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]
- @kindex --enable-extra-pe-debug
- @item --enable-extra-pe-debug
- Show additional debug info related to auto-import symbol thunking.
- [This option is specific to the i386 PE targeted port of the linker]
- @kindex --section-alignment
- @item --section-alignment
- 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]
- @cindex stack size
- @kindex --stack
- @item --stack @var{reserve}
- @itemx --stack @var{reserve},@var{commit}
- 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]
- @kindex --subsystem
- @item --subsystem @var{which}
- @itemx --subsystem @var{which}:@var{major}
- @itemx --subsystem @var{which}:@var{major}.@var{minor}
- Specifies the subsystem under which your program will execute. The
- legal values for @var{which} are @code{native}, @code{windows},
- @code{console}, @code{posix}, and @code{xbox}. You may optionally set
- the subsystem version also. Numeric values are also accepted for
- @var{which}.
- [This option is specific to the i386 PE targeted port of the linker]
- The following options set flags in the @code{DllCharacteristics} field
- of the PE file header:
- [These options are specific to PE targeted ports of the linker]
- @kindex --high-entropy-va
- @item --high-entropy-va
- @itemx --disable-high-entropy-va
- Image is compatible with 64-bit address space layout randomization
- (ASLR). This option is enabled by default for 64-bit PE images.
- This option also implies @option{--dynamicbase} and
- @option{--enable-reloc-section}.
- @kindex --dynamicbase
- @item --dynamicbase
- @itemx --disable-dynamicbase
- 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 @option{--disable-dynamicbase} option.
- This option also implies @option{--enable-reloc-section}.
- @kindex --forceinteg
- @item --forceinteg
- @itemx --disable-forceinteg
- Code integrity checks are enforced. This option is disabled by
- default.
- @kindex --nxcompat
- @item --nxcompat
- @item --disable-nxcompat
- 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.
- @kindex --no-isolation
- @item --no-isolation
- @itemx --disable-no-isolation
- Although the image understands isolation, do not isolate the image.
- This option is disabled by default.
- @kindex --no-seh
- @item --no-seh
- @itemx --disable-no-seh
- The image does not use SEH. No SE handler may be called from
- this image. This option is disabled by default.
- @kindex --no-bind
- @item --no-bind
- @itemx --disable-no-bind
- Do not bind this image. This option is disabled by default.
- @kindex --wdmdriver
- @item --wdmdriver
- @itemx --disable-wdmdriver
- The driver uses the MS Windows Driver Model. This option is disabled
- by default.
- @kindex --tsaware
- @item --tsaware
- @itemx --disable-tsaware
- The image is Terminal Server aware. This option is disabled by
- default.
- @kindex --insert-timestamp
- @item --insert-timestamp
- @itemx --no-insert-timestamp
- 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 @option{--no-insert-timestamp}
- can be used to insert a zero value for the timestamp, this ensuring
- that binaries produced from identical sources will compare
- identically.
- @kindex --enable-reloc-section
- @item --enable-reloc-section
- @itemx --disable-reloc-section
- 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.
- @end table
- @c man end
- @ifset C6X
- @subsection Options specific to C6X uClinux targets
- @c man begin OPTIONS
- 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.
- @table @gcctabopt
- @kindex --dsbt-size
- @item --dsbt-size @var{size}
- This option sets the number of entries in the DSBT of the current executable
- or shared library to @var{size}. The default is to create a table with 64
- entries.
- @kindex --dsbt-index
- @item --dsbt-index @var{index}
- This option sets the DSBT index of the current executable or shared library
- to @var{index}. 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} relocs are copied into the output file.
- @kindex --no-merge-exidx-entries
- The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent
- exidx entries in frame unwind info.
- @end table
- @c man end
- @end ifset
- @ifset CSKY
- @subsection Options specific to C-SKY targets
- @c man begin OPTIONS
- @table @gcctabopt
- @kindex --branch-stub on C-SKY
- @item --branch-stub
- 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.
- @kindex --stub-group-size on C-SKY
- @item --stub-group-size=@var{N}
- 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} 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} or @samp{-1} indicate that the
- linker should choose suitable defaults.
- @end table
- @c man end
- @end ifset
- @ifset M68HC11
- @subsection Options specific to Motorola 68HC11 and 68HC12 targets
- @c man begin OPTIONS
- The 68HC11 and 68HC12 linkers support specific options to control the
- memory bank switching mapping and trampoline code generation.
- @table @gcctabopt
- @kindex --no-trampoline
- @item --no-trampoline
- This option disables the generation of trampoline. By default a trampoline
- is generated for each far function which is called using a @code{jsr}
- instruction (this happens when a pointer to a far function is taken).
- @kindex --bank-window
- @item --bank-window @var{name}
- This option indicates to the linker the name of the memory region in
- the @samp{MEMORY} 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.
- @end table
- @c man end
- @end ifset
- @ifset M68K
- @subsection Options specific to Motorola 68K target
- @c man begin OPTIONS
- The following options are supported to control handling of GOT generation
- when linking for 68K targets.
- @table @gcctabopt
- @kindex --got
- @item --got=@var{type}
- This option tells the linker which GOT generation scheme to use.
- @var{type} should be one of @samp{single}, @samp{negative},
- @samp{multigot} or @samp{target}. For more information refer to the
- Info entry for @file{ld}.
- @end table
- @c man end
- @end ifset
- @ifset MIPS
- @subsection Options specific to MIPS targets
- @c man begin OPTIONS
- The following options are supported to control microMIPS instruction
- generation and branch relocation checks for ISA mode transitions when
- linking for MIPS targets.
- @table @gcctabopt
- @kindex --insn32
- @item --insn32
- @kindex --no-insn32
- @itemx --no-insn32
- 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} is used, then the linker only uses
- 32-bit instruction encodings. By default or if @samp{--no-insn32} is
- used, all instruction encodings are used, including 16-bit ones where
- possible.
- @kindex --ignore-branch-isa
- @item --ignore-branch-isa
- @kindex --no-ignore-branch-isa
- @itemx --no-ignore-branch-isa
- These options control branch relocation checks for invalid ISA mode
- transitions. If @samp{--ignore-branch-isa} 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}
- instructions which meet relaxation conditions and are converted to
- equivalent @code{JALX} instructions as the associated relocation is
- calculated. By default or if @samp{--no-ignore-branch-isa} is used
- a check is made causing the loss of an ISA mode transition to produce
- an error.
- @kindex --compact-branches
- @item --compact-branches
- @kindex --no-compact-branches
- @itemx --no-compact-branches
- These options control the generation of compact instructions by the linker
- in the PLT entries for MIPS R6.
- @end table
- @c man end
- @end ifset
- @ifset PDP11
- @subsection Options specific to PDP11 targets
- @c man begin OPTIONS
- 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} option, whereas for other
- targets @samp{--nmagic} is the default. The @samp{--imagic} option is
- defined only for the pdp11-aout target, while the others are described
- here as they apply to the pdp11-aout target.
- @table @gcctabopt
- @kindex -N
- @item -N
- @kindex --omagic
- @itemx --omagic
- Mark the output as @code{OMAGIC} (0407) in the @file{a.out} 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 @command{ld} on PDP11 Unix systems
- from the beginning through 2.11BSD.
- @kindex -n
- @item -n
- @kindex --nmagic
- @itemx --nmagic
- Mark the output as @code{NMAGIC} (0410) in the @file{a.out} 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 @emph{pure executable} format.
- @kindex -z
- @item -z
- @kindex --imagic
- @itemx --imagic
- Mark the output as @code{IMAGIC} (0411) in the @file{a.out} 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} option selected
- this format in 2.11BSD. This option creates a @emph{separate
- executable} format.
- @kindex --no-omagic
- @item --no-omagic
- Equivalent to @samp{--nmagic} for pdp11-aout.
- @end table
- @c man end
- @end ifset
- @ifset UsesEnvVars
- @node Environment
- @section Environment Variables
- @c man begin ENVIRONMENT
- You can change the behaviour of @command{ld} with the environment variables
- @ifclear SingleFormat
- @code{GNUTARGET},
- @end ifclear
- @code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}.
- @ifclear SingleFormat
- @kindex GNUTARGET
- @cindex default input format
- @code{GNUTARGET} determines the input-file object format if you don't
- use @samp{-b} (or its synonym @samp{--format}). Its value should be one
- of the BFD names for an input format (@pxref{BFD}). If there is no
- @code{GNUTARGET} in the environment, @command{ld} uses the natural format
- of the target. If @code{GNUTARGET} is set to @code{default} 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.
- @end ifclear
- @kindex LDEMULATION
- @cindex default emulation
- @cindex emulation, default
- @code{LDEMULATION} determines the default emulation if you don't use the
- @samp{-m} 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} or @samp{-V} options. If
- the @samp{-m} option is not used, and the @code{LDEMULATION} environment
- variable is not defined, the default emulation depends upon how the
- linker was configured.
- @kindex COLLECT_NO_DEMANGLE
- @cindex demangling, default
- Normally, the linker will default to demangling symbols. However, if
- @code{COLLECT_NO_DEMANGLE} 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} linker wrapper program. The default
- may be overridden by the @samp{--demangle} and @samp{--no-demangle}
- options.
- @c man end
- @end ifset
- @node Scripts
- @chapter Linker Scripts
- @cindex scripts
- @cindex linker scripts
- @cindex command files
- Every link is controlled by a @dfn{linker script}. This script is
- written in the linker command language.
- 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.
- 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} command-line option
- to display the default linker script. Certain command-line options,
- such as @samp{-r} or @samp{-N}, will affect the default linker script.
- You may supply your own linker script by using the @samp{-T} command
- line option. When you do this, your linker script will replace the
- default linker script.
- You may also use linker scripts implicitly by naming them as input files
- to the linker, as though they were files to be linked. @xref{Implicit
- Linker Scripts}.
- @menu
- * Basic Script Concepts:: Basic Linker Script Concepts
- * Script Format:: Linker Script Format
- * Simple Example:: Simple Linker Script Example
- * Simple Commands:: Simple Linker Script Commands
- * Assignments:: Assigning Values to Symbols
- * SECTIONS:: SECTIONS Command
- * MEMORY:: MEMORY Command
- * PHDRS:: PHDRS Command
- * VERSION:: VERSION Command
- * Expressions:: Expressions in Linker Scripts
- * Implicit Linker Scripts:: Implicit Linker Scripts
- @end menu
- @node Basic Script Concepts
- @section Basic Linker Script Concepts
- @cindex linker script concepts
- We need to define some basic concepts and vocabulary in order to
- describe the linker script language.
- 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
- @dfn{object file format}. Each file is called an @dfn{object file}.
- The output file is often called an @dfn{executable}, but for our
- purposes we will also call it an object file. Each object file has,
- among other things, a list of @dfn{sections}. We sometimes refer to a
- section in an input file as an @dfn{input section}; similarly, a section
- in the output file is an @dfn{output section}.
- Each section in an object file has a name and a size. Most sections
- also have an associated block of data, known as the @dfn{section
- contents}. A section may be marked as @dfn{loadable}, which means that
- the contents should be loaded into memory when the output file is run.
- A section with no contents may be @dfn{allocatable}, 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.
- Every loadable or allocatable output section has two addresses. The
- first is the @dfn{VMA}, or virtual memory address. This is the address
- the section will have when the output file is run. The second is the
- @dfn{LMA}, 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.
- You can see the sections in an object file by using the @code{objdump}
- program with the @samp{-h} option.
- Every object file also has a list of @dfn{symbols}, known as the
- @dfn{symbol table}. 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.
- You can see the symbols in an object file by using the @code{nm}
- program, or by using the @code{objdump} program with the @samp{-t}
- option.
- @node Script Format
- @section Linker Script Format
- @cindex linker script format
- Linker scripts are text files.
- 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.
- 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.
- You may include comments in linker scripts just as in C, delimited by
- @samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent
- to whitespace.
- @node Simple Example
- @section Simple Linker Script Example
- @cindex linker script example
- @cindex example of linker script
- Many linker scripts are fairly simple.
- The simplest possible linker script has just one command:
- @samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the
- memory layout of the output file.
- The @samp{SECTIONS} 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{.data}, and @samp{.bss} sections, respectively.
- Let's assume further that these are the only sections which appear in
- your input files.
- 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:
- @smallexample
- SECTIONS
- @{
- . = 0x10000;
- .text : @{ *(.text) @}
- . = 0x8000000;
- .data : @{ *(.data) @}
- .bss : @{ *(.bss) @}
- @}
- @end smallexample
- You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
- followed by a series of symbol assignments and output section
- descriptions enclosed in curly braces.
- The first line inside the @samp{SECTIONS} command of the above example
- sets the value of the special symbol @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} command, the location counter has the value @samp{0}.
- The second line defines an output section, @samp{.text}. 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{*} is a
- wildcard which matches any file name. The expression @samp{*(.text)}
- means all @samp{.text} input sections in all input files.
- Since the location counter is @samp{0x10000} when the output section
- @samp{.text} is defined, the linker will set the address of the
- @samp{.text} section in the output file to be @samp{0x10000}.
- The remaining lines define the @samp{.data} and @samp{.bss} sections in
- the output file. The linker will place the @samp{.data} output section
- at address @samp{0x8000000}. After the linker places the @samp{.data}
- output section, the value of the location counter will be
- @samp{0x8000000} plus the size of the @samp{.data} output section. The
- effect is that the linker will place the @samp{.bss} output section
- immediately after the @samp{.data} output section in memory.
- 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} and @samp{.data}
- sections will probably satisfy any alignment constraints, but the linker
- may have to create a small gap between the @samp{.data} and @samp{.bss}
- sections.
- That's it! That's a simple and complete linker script.
- @node Simple Commands
- @section Simple Linker Script Commands
- @cindex linker script simple commands
- In this section we describe the simple linker script commands.
- @menu
- * Entry Point:: Setting the entry point
- * File Commands:: Commands dealing with files
- @ifclear SingleFormat
- * Format Commands:: Commands dealing with object file formats
- @end ifclear
- * REGION_ALIAS:: Assign alias names to memory regions
- * Miscellaneous Commands:: Other linker script commands
- @end menu
- @node Entry Point
- @subsection Setting the Entry Point
- @kindex ENTRY(@var{symbol})
- @cindex start of execution
- @cindex first instruction
- @cindex entry point
- The first instruction to execute in a program is called the @dfn{entry
- point}. You can use the @code{ENTRY} linker script command to set the
- entry point. The argument is a symbol name:
- @smallexample
- ENTRY(@var{symbol})
- @end smallexample
- 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:
- @itemize @bullet
- @item
- the @samp{-e} @var{entry} command-line option;
- @item
- the @code{ENTRY(@var{symbol})} command in a linker script;
- @item
- the value of a target-specific symbol, if it is defined; For many
- targets this is @code{start}, but PE- and BeOS-based systems for example
- check a list of possible entry symbols, matching the first one found.
- @item
- 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}, but can be something else;
- @item
- The address @code{0}.
- @end itemize
- @node File Commands
- @subsection Commands Dealing with Files
- @cindex linker script file commands
- Several linker script commands deal with files.
- @table @code
- @item INCLUDE @var{filename}
- @kindex INCLUDE @var{filename}
- @cindex including a linker script
- Include the linker script @var{filename} at this point. The file will
- be searched for in the current directory, and in any directory specified
- with the @option{-L} option. You can nest calls to @code{INCLUDE} up to
- 10 levels deep.
- You can place @code{INCLUDE} directives at the top level, in @code{MEMORY} or
- @code{SECTIONS} commands, or in output section descriptions.
- @item INPUT(@var{file}, @var{file}, @dots{})
- @itemx INPUT(@var{file} @var{file} @dots{})
- @kindex INPUT(@var{files})
- @cindex input files in linker scripts
- @cindex input object files in linker scripts
- @cindex linker script input object files
- The @code{INPUT} command directs the linker to include the named files
- in the link, as though they were named on the command line.
- For example, if you always want to include @file{subr.o} 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)} in your linker script.
- 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} option.
- In case a @dfn{sysroot prefix} is configured, and the filename starts
- with the @samp{/} character, and the script being processed was
- located inside the @dfn{sysroot prefix}, the filename will be looked
- for in the @dfn{sysroot prefix}. The @dfn{sysroot prefix} can also be forced by specifying
- @code{=} as the first character in the filename path, or prefixing the
- filename path with @code{$SYSROOT}. See also the description of
- @samp{-L} in @ref{Options,,Command-line Options}.
- If a @dfn{sysroot prefix} 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.
- If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
- name to @code{lib@var{file}.a}, as with the command-line argument
- @samp{-l}.
- When you use the @code{INPUT} 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.
- @item GROUP(@var{file}, @var{file}, @dots{})
- @itemx GROUP(@var{file} @var{file} @dots{})
- @kindex GROUP(@var{files})
- @cindex grouping input files
- The @code{GROUP} command is like @code{INPUT}, 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{-(}
- in @ref{Options,,Command-line Options}.
- @item AS_NEEDED(@var{file}, @var{file}, @dots{})
- @itemx AS_NEEDED(@var{file} @var{file} @dots{})
- @kindex AS_NEEDED(@var{files})
- This construct can appear only inside of the @code{INPUT} or @code{GROUP}
- commands, among other filenames. The files listed will be handled
- as if they appear directly in the @code{INPUT} or @code{GROUP} commands,
- with the exception of ELF shared libraries, that will be added only
- when they are actually needed. This construct essentially enables
- @option{--as-needed} option for all the files listed inside of it
- and restores previous @option{--as-needed} resp. @option{--no-as-needed}
- setting afterwards.
- @item OUTPUT(@var{filename})
- @kindex OUTPUT(@var{filename})
- @cindex output file name in linker script
- The @code{OUTPUT} command names the output file. Using
- @code{OUTPUT(@var{filename})} in the linker script is exactly like using
- @samp{-o @var{filename}} on the command line (@pxref{Options,,Command
- Line Options}). If both are used, the command-line option takes
- precedence.
- You can use the @code{OUTPUT} command to define a default name for the
- output file other than the usual default of @file{a.out}.
- @item SEARCH_DIR(@var{path})
- @kindex SEARCH_DIR(@var{path})
- @cindex library search path in linker script
- @cindex archive search path in linker script
- @cindex search path in linker script
- The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
- @command{ld} looks for archive libraries. Using
- @code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
- on the command line (@pxref{Options,,Command-line Options}). If both
- are used, then the linker will search both paths. Paths specified using
- the command-line option are searched first.
- @item STARTUP(@var{filename})
- @kindex STARTUP(@var{filename})
- @cindex first input file
- The @code{STARTUP} command is just like the @code{INPUT} command, except
- that @var{filename} 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.
- @end table
- @ifclear SingleFormat
- @node Format Commands
- @subsection Commands Dealing with Object File Formats
- A couple of linker script commands deal with object file formats.
- @table @code
- @item OUTPUT_FORMAT(@var{bfdname})
- @itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
- @kindex OUTPUT_FORMAT(@var{bfdname})
- @cindex output file format in linker script
- The @code{OUTPUT_FORMAT} command names the BFD format to use for the
- output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is
- exactly like using @samp{--oformat @var{bfdname}} on the command line
- (@pxref{Options,,Command-line Options}). If both are used, the command
- line option takes precedence.
- You can use @code{OUTPUT_FORMAT} with three arguments to use different
- formats based on the @samp{-EB} and @samp{-EL} command-line options.
- This permits the linker script to set the output format based on the
- desired endianness.
- If neither @samp{-EB} nor @samp{-EL} are used, then the output format
- will be the first argument, @var{default}. If @samp{-EB} is used, the
- output format will be the second argument, @var{big}. If @samp{-EL} is
- used, the output format will be the third argument, @var{little}.
- For example, the default linker script for the MIPS ELF target uses this
- command:
- @smallexample
- OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
- @end smallexample
- This says that the default format for the output file is
- @samp{elf32-bigmips}, but if the user uses the @samp{-EL} command-line
- option, the output file will be created in the @samp{elf32-littlemips}
- format.
- @item TARGET(@var{bfdname})
- @kindex TARGET(@var{bfdname})
- @cindex input file format in linker script
- The @code{TARGET} command names the BFD format to use when reading input
- files. It affects subsequent @code{INPUT} and @code{GROUP} commands.
- This command is like using @samp{-b @var{bfdname}} on the command line
- (@pxref{Options,,Command-line Options}). If the @code{TARGET} command
- is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
- command is also used to set the format for the output file. @xref{BFD}.
- @end table
- @end ifclear
- @node REGION_ALIAS
- @subsection Assign alias names to memory regions
- @kindex REGION_ALIAS(@var{alias}, @var{region})
- @cindex region alias
- @cindex region names
- Alias names can be added to existing memory regions created with the
- @ref{MEMORY} command. Each name corresponds to at most one memory region.
- @smallexample
- REGION_ALIAS(@var{alias}, @var{region})
- @end smallexample
- The @code{REGION_ALIAS} function creates an alias name @var{alias} for the
- memory region @var{region}. This allows a flexible mapping of output sections
- to memory regions. An example follows.
- Suppose we have an application for embedded systems which come with various
- memory storage devices. All have a general purpose, volatile memory @code{RAM}
- that allows code execution or data storage. Some may have a read-only,
- non-volatile memory @code{ROM} that allows code execution and read-only data
- access. The last variant is a read-only, non-volatile memory @code{ROM2} with
- read-only data access and no code execution capability. We have four output
- sections:
- @itemize @bullet
- @item
- @code{.text} program code;
- @item
- @code{.rodata} read-only data;
- @item
- @code{.data} read-write initialized data;
- @item
- @code{.bss} read-write zero initialized data.
- @end itemize
- 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{B} and
- @code{C}:
- @multitable @columnfractions .25 .25 .25 .25
- @item Section @tab Variant A @tab Variant B @tab Variant C
- @item .text @tab RAM @tab ROM @tab ROM
- @item .rodata @tab RAM @tab ROM @tab ROM2
- @item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2
- @item .bss @tab RAM @tab RAM @tab RAM
- @end multitable
- The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is
- loaded into region @code{ROM} or @code{ROM2} respectively. Please note that
- the load address of the @code{.data} section starts in all three variants at
- the end of the @code{.rodata} section.
- The base linker script that deals with the output sections follows. It
- includes the system dependent @code{linkcmds.memory} file that describes the
- memory layout:
- @smallexample
- 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
- @}
- @end smallexample
- Now we need three different @code{linkcmds.memory} files to define memory
- regions and alias names. The content of @code{linkcmds.memory} for the three
- variants @code{A}, @code{B} and @code{C}:
- @table @code
- @item A
- Here everything goes into the @code{RAM}.
- @smallexample
- 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);
- @end smallexample
- @item B
- Program code and read-only data go into the @code{ROM}. Read-write data goes
- into the @code{RAM}. An image of the initialized data is loaded into the
- @code{ROM} and will be copied during system start into the @code{RAM}.
- @smallexample
- 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);
- @end smallexample
- @item C
- Program code goes into the @code{ROM}. Read-only data goes into the
- @code{ROM2}. Read-write data goes into the @code{RAM}. An image of the
- initialized data is loaded into the @code{ROM2} and will be copied during
- system start into the @code{RAM}.
- @smallexample
- 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);
- @end smallexample
- @end table
- It is possible to write a common system initialization routine to copy the
- @code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if
- necessary:
- @smallexample
- #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);
- @}
- @}
- @end smallexample
- @node Miscellaneous Commands
- @subsection Other Linker Script Commands
- There are a few other linker scripts commands.
- @table @code
- @item ASSERT(@var{exp}, @var{message})
- @kindex ASSERT
- @cindex assertion in linker script
- Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
- with an error code, and print @var{message}.
- 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:
- @smallexample
- .stack :
- @{
- PROVIDE (__stack = .);
- PROVIDE (__stack_size = 0x100);
- ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
- @}
- @end smallexample
- will fail if @code{__stack_size} is not defined elsewhere. Symbols
- PROVIDEd outside of section definitions are evaluated earlier, so they
- can be used inside ASSERTions. Thus:
- @smallexample
- PROVIDE (__stack_size = 0x100);
- .stack :
- @{
- PROVIDE (__stack = .);
- ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
- @}
- @end smallexample
- will work.
- @item EXTERN(@var{symbol} @var{symbol} @dots{})
- @kindex EXTERN
- @cindex undefined symbol in linker script
- Force @var{symbol} 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}s for
- each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This
- command has the same effect as the @samp{-u} command-line option.
- @item FORCE_COMMON_ALLOCATION
- @kindex FORCE_COMMON_ALLOCATION
- @cindex common allocation in linker script
- This command has the same effect as the @samp{-d} command-line option:
- to make @command{ld} assign space to common symbols even if a relocatable
- output file is specified (@samp{-r}).
- @item INHIBIT_COMMON_ALLOCATION
- @kindex INHIBIT_COMMON_ALLOCATION
- @cindex common allocation in linker script
- This command has the same effect as the @samp{--no-define-common}
- command-line option: to make @code{ld} omit the assignment of addresses
- to common symbols even for a non-relocatable output file.
- @item FORCE_GROUP_ALLOCATION
- @kindex FORCE_GROUP_ALLOCATION
- @cindex group allocation in linker script
- @cindex section groups
- @cindex COMDAT
- This command has the same effect as the
- @samp{--force-group-allocation} command-line option: to make
- @command{ld} place section group members like normal input sections,
- and to delete the section groups even if a relocatable output file is
- specified (@samp{-r}).
- @item INSERT [ AFTER | BEFORE ] @var{output_section}
- @kindex INSERT
- @cindex insert user script into default script
- This command is typically used in a script specified by @samp{-T} to
- augment the default @code{SECTIONS} with, for example, overlays. It
- inserts all prior linker script statements after (or before)
- @var{output_section}, and also causes @samp{-T} to not override the
- default linker script. The exact insertion point is as for orphan
- sections. @xref{Location Counter}. The insertion happens after the
- linker has mapped input sections to output sections. Prior to the
- insertion, since @samp{-T} scripts are parsed before the default
- linker script, statements in the @samp{-T} 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} output sections before those in the default script. Here
- is an example of how a @samp{-T} script using @code{INSERT} might look:
- @smallexample
- SECTIONS
- @{
- OVERLAY :
- @{
- .ov1 @{ ov1*(.text) @}
- .ov2 @{ ov2*(.text) @}
- @}
- @}
- INSERT AFTER .text;
- @end smallexample
- @item NOCROSSREFS(@var{section} @var{section} @dots{})
- @kindex NOCROSSREFS(@var{sections})
- @cindex cross references
- This command may be used to tell @command{ld} to issue an error about any
- references among certain output sections.
- 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.
- The @code{NOCROSSREFS} command takes a list of output section names. If
- @command{ld} detects any cross references between the sections, it reports
- an error and returns a non-zero exit status. Note that the
- @code{NOCROSSREFS} command uses output section names, not input section
- names.
- @item NOCROSSREFS_TO(@var{tosection} @var{fromsection} @dots{})
- @kindex NOCROSSREFS_TO(@var{tosection} @var{fromsections})
- @cindex cross references
- This command may be used to tell @command{ld} to issue an error about any
- references to one section from a list of other sections.
- The @code{NOCROSSREFS} 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.
- The @code{NOCROSSREFS_TO} command takes a list of output section names.
- The first section can not be referenced from any of the other sections.
- If @command{ld} 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} command uses output section
- names, not input section names.
- @ifclear SingleFormat
- @item OUTPUT_ARCH(@var{bfdarch})
- @kindex OUTPUT_ARCH(@var{bfdarch})
- @cindex machine architecture
- @cindex architecture
- Specify a particular output machine architecture. The argument is one
- of the names used by the BFD library (@pxref{BFD}). You can see the
- architecture of an object file by using the @code{objdump} program with
- the @samp{-f} option.
- @end ifclear
- @item LD_FEATURE(@var{string})
- @kindex LD_FEATURE(@var{string})
- This command may be used to modify @command{ld} behavior. If
- @var{string} is @code{"SANE_EXPR"} then absolute symbols and numbers
- in a script are simply treated as numbers everywhere.
- @xref{Expression Section}.
- @end table
- @node Assignments
- @section Assigning Values to Symbols
- @cindex assignment in scripts
- @cindex symbol definition, scripts
- @cindex variables, defining
- 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.
- @menu
- * Simple Assignments:: Simple Assignments
- * HIDDEN:: HIDDEN
- * PROVIDE:: PROVIDE
- * PROVIDE_HIDDEN:: PROVIDE_HIDDEN
- * Source Code Reference:: How to use a linker script defined symbol in source code
- @end menu
- @node Simple Assignments
- @subsection Simple Assignments
- You may assign to a symbol using any of the C assignment operators:
- @table @code
- @item @var{symbol} = @var{expression} ;
- @itemx @var{symbol} += @var{expression} ;
- @itemx @var{symbol} -= @var{expression} ;
- @itemx @var{symbol} *= @var{expression} ;
- @itemx @var{symbol} /= @var{expression} ;
- @itemx @var{symbol} <<= @var{expression} ;
- @itemx @var{symbol} >>= @var{expression} ;
- @itemx @var{symbol} &= @var{expression} ;
- @itemx @var{symbol} |= @var{expression} ;
- @end table
- The first case will define @var{symbol} to the value of
- @var{expression}. In the other cases, @var{symbol} must already be
- defined, and the value will be adjusted accordingly.
- The special symbol name @samp{.} indicates the location counter. You
- may only use this within a @code{SECTIONS} command. @xref{Location Counter}.
- The semicolon after @var{expression} is required.
- Expressions are defined below; see @ref{Expressions}.
- You may write symbol assignments as commands in their own right, or as
- statements within a @code{SECTIONS} command, or as part of an output
- section description in a @code{SECTIONS} command.
- The section of the symbol will be set from the section of the
- expression; for more information, see @ref{Expression Section}.
- Here is an example showing the three different places that symbol
- assignments may be used:
- @smallexample
- floating_point = 0;
- SECTIONS
- @{
- .text :
- @{
- *(.text)
- _etext = .;
- @}
- _bdata = (. + 3) & ~ 3;
- .data : @{ *(.data) @}
- @}
- @end smallexample
- @noindent
- In this example, the symbol @samp{floating_point} will be defined as
- zero. The symbol @samp{_etext} will be defined as the address following
- the last @samp{.text} input section. The symbol @samp{_bdata} will be
- defined as the address following the @samp{.text} output section aligned
- upward to a 4 byte boundary.
- @node HIDDEN
- @subsection HIDDEN
- @cindex HIDDEN
- For ELF targeted ports, define a symbol that will be hidden and won't be
- exported. The syntax is @code{HIDDEN(@var{symbol} = @var{expression})}.
- Here is the example from @ref{Simple Assignments}, rewritten to use
- @code{HIDDEN}:
- @smallexample
- HIDDEN(floating_point = 0);
- SECTIONS
- @{
- .text :
- @{
- *(.text)
- HIDDEN(_etext = .);
- @}
- HIDDEN(_bdata = (. + 3) & ~ 3);
- .data : @{ *(.data) @}
- @}
- @end smallexample
- @noindent
- In this case none of the three symbols will be visible outside this module.
- @node PROVIDE
- @subsection PROVIDE
- @cindex PROVIDE
- 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}. However, ANSI C requires that the user be able to use
- @samp{etext} as a function name without encountering an error. The
- @code{PROVIDE} keyword may be used to define a symbol, such as
- @samp{etext}, only if it is referenced but not defined. The syntax is
- @code{PROVIDE(@var{symbol} = @var{expression})}.
- Here is an example of using @code{PROVIDE} to define @samp{etext}:
- @smallexample
- SECTIONS
- @{
- .text :
- @{
- *(.text)
- _etext = .;
- PROVIDE(etext = .);
- @}
- @}
- @end smallexample
- In this example, if the program defines @samp{_etext} (with a leading
- underscore), the linker will give a multiple definition diagnostic. If,
- on the other hand, the program defines @samp{etext} (with no leading
- underscore), the linker will silently use the definition in the program.
- If the program references @samp{etext} but does not define it, the
- linker will use the definition in the linker script.
- Note - the @code{PROVIDE} directive considers a common symbol to be
- defined, even though such a symbol could be combined with the symbol
- that the @code{PROVIDE} would create. This is particularly important
- when considering constructor and destructor list symbols such as
- @samp{__CTOR_LIST__} as these are often defined as common symbols.
- @node PROVIDE_HIDDEN
- @subsection PROVIDE_HIDDEN
- @cindex PROVIDE_HIDDEN
- Similar to @code{PROVIDE}. For ELF targeted ports, the symbol will be
- hidden and won't be exported.
- @node Source Code Reference
- @subsection Source Code Reference
- 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.
- 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}. 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:
- @smallexample
- extern int foo;
- @end smallexample
- But in the linker script it might be defined as:
- @smallexample
- _foo = 1000;
- @end smallexample
- In the remaining examples however it is assumed that no name
- transformation has taken place.
- 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 @emph{value} of the symbol. The
- second is that the compiler creates an entry in the program's symbol
- table which holds the symbol's @emph{address}. 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:
- @smallexample
- int foo = 1000;
- @end smallexample
- creates an entry called @samp{foo} in the symbol table. This entry
- holds the address of an @samp{int} sized block of memory where the
- number 1000 is initially stored.
- 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:
- @smallexample
- foo = 1;
- @end smallexample
- looks up the symbol @samp{foo} in the symbol table, gets the address
- associated with this symbol and then writes the value 1 into that
- address. Whereas:
- @smallexample
- int * a = & foo;
- @end smallexample
- looks up the symbol @samp{foo} in the symbol table, gets its address
- and then copies this address into the block of memory associated with
- the variable @samp{a}.
- 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:
- @smallexample
- foo = 1000;
- @end smallexample
- creates an entry in the symbol table called @samp{foo} which holds
- the address of memory location 1000, but nothing special is stored at
- address 1000. This means that you cannot access the @emph{value} of a
- linker script defined symbol - it has no value - all you can do is
- access the @emph{address} of a linker script defined symbol.
- 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:
- @smallexample
- @group
- start_of_ROM = .ROM;
- end_of_ROM = .ROM + sizeof (.ROM);
- start_of_FLASH = .FLASH;
- @end group
- @end smallexample
- Then the C source code to perform the copy would be:
- @smallexample
- @group
- extern char start_of_ROM, end_of_ROM, start_of_FLASH;
- memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
- @end group
- @end smallexample
- Note the use of the @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:
- @smallexample
- @group
- extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
- memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);
- @end group
- @end smallexample
- Note how using this method does not require the use of @samp{&}
- operators.
- @node SECTIONS
- @section SECTIONS Command
- @kindex SECTIONS
- The @code{SECTIONS} command tells the linker how to map input sections
- into output sections, and how to place the output sections in memory.
- The format of the @code{SECTIONS} command is:
- @smallexample
- SECTIONS
- @{
- @var{sections-command}
- @var{sections-command}
- @dots{}
- @}
- @end smallexample
- Each @var{sections-command} may of be one of the following:
- @itemize @bullet
- @item
- an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
- @item
- a symbol assignment (@pxref{Assignments})
- @item
- an output section description
- @item
- an overlay description
- @end itemize
- The @code{ENTRY} command and symbol assignments are permitted inside the
- @code{SECTIONS} 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.
- Output section descriptions and overlay descriptions are described
- below.
- If you do not use a @code{SECTIONS} 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.
- @menu
- * Output Section Description:: Output section description
- * Output Section Name:: Output section name
- * Output Section Address:: Output section address
- * Input Section:: Input section description
- * Output Section Data:: Output section data
- * Output Section Keywords:: Output section keywords
- * Output Section Discarding:: Output section discarding
- * Output Section Attributes:: Output section attributes
- * Overlay Description:: Overlay description
- @end menu
- @node Output Section Description
- @subsection Output Section Description
- The full description of an output section looks like this:
- @smallexample
- @group
- @var{section} [@var{address}] [(@var{type})] :
- [AT(@var{lma})]
- [ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
- [SUBALIGN(@var{subsection_align})]
- [@var{constraint}]
- @{
- @var{output-section-command}
- @var{output-section-command}
- @dots{}
- @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] [,]
- @end group
- @end smallexample
- Most output sections do not use most of the optional section attributes.
- The whitespace around @var{section} 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} is used and
- the next @var{sections-command} looks like a continuation of the expression.
- The line breaks and other white space are optional.
- Each @var{output-section-command} may be one of the following:
- @itemize @bullet
- @item
- a symbol assignment (@pxref{Assignments})
- @item
- an input section description (@pxref{Input Section})
- @item
- data values to include directly (@pxref{Output Section Data})
- @item
- a special output section keyword (@pxref{Output Section Keywords})
- @end itemize
- @node Output Section Name
- @subsection Output Section Name
- @cindex name, section
- @cindex section name
- The name of the output section is @var{section}. @var{section} must
- meet the constraints of your output format. In formats which only
- support a limited number of sections, such as @code{a.out}, the name
- must be one of the names supported by the format (@code{a.out}, for
- example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). 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.
- The output section name @samp{/DISCARD/} is special; @ref{Output Section
- Discarding}.
- @node Output Section Address
- @subsection Output Section Address
- @cindex address, section
- @cindex section address
- The @var{address} 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.
- 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.
- The output section address heuristic is as follows:
- @itemize @bullet
- @item
- If an output memory @var{region} is set for the section then it
- is added to this region and its address will be the next free address
- in that region.
- @item
- 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; @ref{MEMORY}.
- @item
- 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.
- @end itemize
- @noindent
- For example:
- @smallexample
- .text . : @{ *(.text) @}
- @end smallexample
- @noindent
- and
- @smallexample
- .text : @{ *(.text) @}
- @end smallexample
- @noindent
- are subtly different. The first will set the address of the
- @samp{.text} 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}
- input sections.
- The @var{address} may be an arbitrary expression; @ref{Expressions}.
- 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:
- @smallexample
- .text ALIGN(0x10) : @{ *(.text) @}
- @end smallexample
- @noindent
- This works because @code{ALIGN} returns the current location counter
- aligned upward to the specified value.
- Specifying @var{address} for a section will change the value of the
- location counter, provided that the section is non-empty. (Empty
- sections are ignored).
- @node Input Section
- @subsection Input Section Description
- @cindex input sections
- @cindex mapping input sections to output sections
- The most common output section command is an input section description.
- 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.
- @menu
- * Input Section Basics:: Input section basics
- * Input Section Wildcards:: Input section wildcard patterns
- * Input Section Common:: Input section for common symbols
- * Input Section Keep:: Input section and garbage collection
- * Input Section Example:: Input section example
- @end menu
- @node Input Section Basics
- @subsubsection Input Section Basics
- @cindex input section basics
- An input section description consists of a file name optionally followed
- by a list of section names in parentheses.
- The file name and the section name may be wildcard patterns, which we
- describe further below (@pxref{Input Section Wildcards}).
- 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} sections, you would write:
- @smallexample
- *(.text)
- @end smallexample
- @noindent
- Here the @samp{*} is a wildcard which matches any file name. To exclude a list
- @cindex EXCLUDE_FILE
- 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:
- @smallexample
- EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors)
- @end smallexample
- @noindent
- will cause all .ctors sections from all files except @file{crtend.o}
- and @file{otherfile.o} to be included. The EXCLUDE_FILE can also be
- placed inside the section list, for example:
- @smallexample
- *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
- @end smallexample
- @noindent
- 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.
- There are two ways to include more than one section:
- @smallexample
- *(.text .rdata)
- *(.text) *(.rdata)
- @end smallexample
- @noindent
- The difference between these is the order in which the @samp{.text} and
- @samp{.rdata} 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} input sections will appear first, followed by all
- @samp{.rdata} input sections.
- 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:
- @smallexample
- *(EXCLUDE_FILE (*somefile.o) .text .rdata)
- @end smallexample
- @noindent
- will cause all @samp{.text} sections from all files except
- @file{somefile.o} to be included, while all @samp{.rdata} sections
- from all files, including @file{somefile.o}, will be included. To
- exclude the @samp{.rdata} sections from @file{somefile.o} the example
- could be modified to:
- @smallexample
- *(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
- @end smallexample
- @noindent
- 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:
- @smallexample
- EXCLUDE_FILE (*somefile.o) *(.text .rdata)
- @end smallexample
- 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:
- @smallexample
- data.o(.data)
- @end smallexample
- To refine the sections that are included based on the section flags
- of an input section, INPUT_SECTION_FLAGS may be used.
- Here is a simple example for using Section header flags for ELF sections:
- @smallexample
- @group
- SECTIONS @{
- .text : @{ INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) @}
- .text2 : @{ INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) @}
- @}
- @end group
- @end smallexample
- In this example, the output section @samp{.text} will be comprised of any
- input section matching the name *(.text) whose section header flags
- @code{SHF_MERGE} and @code{SHF_STRINGS} are set. The output section
- @samp{.text2} will be comprised of any input section matching the name *(.text)
- whose section header flag @code{SHF_WRITE} is clear.
- 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.
- @table @samp
- @item archive:file
- matches file within archive
- @item archive:
- matches the whole archive
- @item :file
- matches file but not one in an archive
- @end table
- Either one or both of @samp{archive} and @samp{file} 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} is a simple file specification, not @samp{myfile.o}
- within an archive called @samp{c}. @samp{archive:file} filespecs may
- also be used within an @code{EXCLUDE_FILE} 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} in an @code{INPUT}
- command.
- 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:
- @smallexample
- data.o
- @end smallexample
- When you use a file name which is not an @samp{archive:file} 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} 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} command, because the linker will not search for the file in
- the archive search path.
- @node Input Section Wildcards
- @subsubsection Input Section Wildcard Patterns
- @cindex input section wildcards
- @cindex wildcard file name patterns
- @cindex file name wildcard patterns
- @cindex section name wildcard patterns
- In an input section description, either the file name or the section
- name or both may be wildcard patterns.
- The file name of @samp{*} seen in many examples is a simple wildcard
- pattern for the file name.
- The wildcard patterns are like those used by the Unix shell.
- @table @samp
- @item *
- matches any number of characters
- @item ?
- matches any single character
- @item [@var{chars}]
- matches a single instance of any of the @var{chars}; the @samp{-}
- character may be used to specify a range of characters, as in
- @samp{[a-z]} to match any lower case letter
- @item \
- quotes the following character
- @end table
- File name wildcard patterns only match files which are explicitly
- specified on the command line or in an @code{INPUT} command. The linker
- does not search directories to expand wildcards.
- 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
- @file{data.o} rule will not be used:
- @smallexample
- .data : @{ *(.data) @}
- .data1 : @{ data.o(.data) @}
- @end smallexample
- @cindex SORT_BY_NAME
- 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} keyword, which appears before a wildcard
- pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}). When the
- @code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections
- into ascending order by name before placing them in the output file.
- @cindex SORT_BY_ALIGNMENT
- @code{SORT_BY_ALIGNMENT} is similar to @code{SORT_BY_NAME}.
- @code{SORT_BY_ALIGNMENT} 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.
- @cindex SORT_BY_INIT_PRIORITY
- @code{SORT_BY_INIT_PRIORITY} is also similar to @code{SORT_BY_NAME}.
- @code{SORT_BY_INIT_PRIORITY} 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} and @code{.fini_array.NNNNN}, @code{NNNNN} is
- the init_priority. In @code{.ctors.NNNNN} and @code{.dtors.NNNNN},
- @code{NNNNN} is 65535 minus the init_priority.
- @cindex SORT
- @code{SORT} is an alias for @code{SORT_BY_NAME}.
- When there are nested section sorting commands in linker script, there
- can be at most 1 level of nesting for section sorting commands.
- @enumerate
- @item
- @code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
- It will sort the input sections by name first, then by alignment if two
- sections have the same name.
- @item
- @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
- It will sort the input sections by alignment first, then by name if two
- sections have the same alignment.
- @item
- @code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
- treated the same as @code{SORT_BY_NAME} (wildcard section pattern).
- @item
- @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern))
- is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern).
- @item
- All other nested section sorting commands are invalid.
- @end enumerate
- 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.
- 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.
- @enumerate
- @item
- @code{SORT_BY_NAME} (wildcard section pattern ) with
- @option{--sort-sections alignment} is equivalent to
- @code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
- @item
- @code{SORT_BY_ALIGNMENT} (wildcard section pattern) with
- @option{--sort-section name} is equivalent to
- @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
- @end enumerate
- If the section sorting command in linker script is nested, the
- command-line option will be ignored.
- @cindex SORT_NONE
- @code{SORT_NONE} disables section sorting by ignoring the command-line
- section sorting option.
- If you ever get confused about where input sections are going, use the
- @samp{-M} linker option to generate a map file. The map file shows
- precisely how input sections are mapped to output sections.
- This example shows how wildcard patterns might be used to partition
- files. This linker script directs the linker to place all @samp{.text}
- sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
- The linker will place the @samp{.data} section from all files beginning
- with an upper case character in @samp{.DATA}; for all other files, the
- linker will place the @samp{.data} section in @samp{.data}.
- @smallexample
- @group
- SECTIONS @{
- .text : @{ *(.text) @}
- .DATA : @{ [A-Z]*(.data) @}
- .data : @{ *(.data) @}
- .bss : @{ *(.bss) @}
- @}
- @end group
- @end smallexample
- @node Input Section Common
- @subsubsection Input Section for Common Symbols
- @cindex common symbol placement
- @cindex uninitialized data placement
- 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}.
- You may use file names with the @samp{COMMON} 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.
- In most cases, common symbols in input files will be placed in the
- @samp{.bss} section in the output file. For example:
- @smallexample
- .bss @{ *(.bss) *(COMMON) @}
- @end smallexample
- @cindex scommon section
- @cindex small common symbols
- 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} for standard common
- symbols and @samp{.scommon} for small common symbols. This permits you
- to map the different types of common symbols into memory at different
- locations.
- @cindex [COMMON]
- You will sometimes see @samp{[COMMON]} in old linker scripts. This
- notation is now considered obsolete. It is equivalent to
- @samp{*(COMMON)}.
- @node Input Section Keep
- @subsubsection Input Section and Garbage Collection
- @cindex KEEP
- @cindex garbage collection
- When link-time garbage collection is in use (@samp{--gc-sections}),
- 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()}, as in @code{KEEP(*(.init))} or
- @code{KEEP(SORT_BY_NAME(*)(.ctors))}.
- @node Input Section Example
- @subsubsection Input Section Example
- The following example is a complete linker script. It tells the linker
- to read all of the sections from file @file{all.o} and place them at the
- start of output section @samp{outputa} which starts at location
- @samp{0x10000}. All of section @samp{.input1} from file @file{foo.o}
- follows immediately, in the same output section. All of section
- @samp{.input2} from @file{foo.o} goes into output section
- @samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
- All of the remaining @samp{.input1} and @samp{.input2} sections from any
- files are written to output section @samp{outputc}.
- @smallexample
- @group
- SECTIONS @{
- outputa 0x10000 :
- @{
- all.o
- foo.o (.input1)
- @}
- @end group
- @group
- outputb :
- @{
- foo.o (.input2)
- foo1.o (.input1)
- @}
- @end group
- @group
- outputc :
- @{
- *(.input1)
- *(.input2)
- @}
- @}
- @end group
- @end smallexample
- 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 @pxref{PROVIDE} 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{.} character.
- @node Output Section Data
- @subsection Output Section Data
- @cindex data
- @cindex section data
- @cindex output section data
- @kindex BYTE(@var{expression})
- @kindex SHORT(@var{expression})
- @kindex LONG(@var{expression})
- @kindex QUAD(@var{expression})
- @kindex SQUAD(@var{expression})
- You can include explicit bytes of data in an output section by using
- @code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
- an output section command. Each keyword is followed by an expression in
- parentheses providing the value to store (@pxref{Expressions}). The
- value of the expression is stored at the current value of the location
- counter.
- The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
- store one, two, four, and eight bytes (respectively). After storing the
- bytes, the location counter is incremented by the number of bytes
- stored.
- For example, this will store the byte 1 followed by the four byte value
- of the symbol @samp{addr}:
- @smallexample
- BYTE(1)
- LONG(addr)
- @end smallexample
- When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} 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} stores a 32 bit value zero extended to 64 bits, and
- @code{SQUAD} stores a 32 bit value sign extended to 64 bits.
- 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.
- Note---these commands only work inside a section description and not
- between them, so the following will produce an error from the linker:
- @smallexample
- SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
- @end smallexample
- whereas this will work:
- @smallexample
- SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
- @end smallexample
- @kindex FILL(@var{expression})
- @cindex holes, filling
- @cindex unspecified memory
- You may use the @code{FILL} 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} statement covers memory locations after the
- point at which it occurs in the section definition; by including more
- than one @code{FILL} statement, you can have different fill patterns in
- different parts of an output section.
- This example shows how to fill unspecified regions of memory with the
- value @samp{0x90}:
- @smallexample
- FILL(0x90909090)
- @end smallexample
- The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
- section attribute, but it only affects the
- part of the section following the @code{FILL} command, rather than the
- entire section. If both are used, the @code{FILL} command takes
- precedence. @xref{Output Section Fill}, for details on the fill
- expression.
- @node Output Section Keywords
- @subsection Output Section Keywords
- There are a couple of keywords which can appear as output section
- commands.
- @table @code
- @kindex CREATE_OBJECT_SYMBOLS
- @cindex input filename symbols
- @cindex filename symbols
- @item CREATE_OBJECT_SYMBOLS
- 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} command appears.
- This is conventional for the a.out object file format. It is not
- normally used for any other object file format.
- @kindex CONSTRUCTORS
- @cindex C++ constructors, arranging in link
- @cindex constructors, arranging in link
- @item CONSTRUCTORS
- 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} command tells the
- linker to place constructor information in the output section where the
- @code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is
- ignored for other object file formats.
- The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
- constructors, and the symbol @w{@code{__CTOR_END__}} marks the end.
- Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_END__}} 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 @sc{gnu} C++ normally calls constructors from a subroutine
- @code{__main}; a call to @code{__main} is automatically inserted into
- the startup code for @code{main}. @sc{gnu} C++ normally runs
- destructors either by using @code{atexit}, or directly from the function
- @code{exit}.
- For object file formats such as @code{COFF} or @code{ELF} which support
- arbitrary section names, @sc{gnu} C++ will normally arrange to put the
- addresses of global constructors and destructors into the @code{.ctors}
- and @code{.dtors} sections. Placing the following sequence into your
- linker script will build the sort of table which the @sc{gnu} C++
- runtime code expects to see.
- @smallexample
- __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__ = .;
- @end smallexample
- If you are using the @sc{gnu} 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}
- command, use @samp{SORT_BY_NAME(CONSTRUCTORS)} instead. When using the
- @code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and
- @samp{*(SORT_BY_NAME(.dtors))} instead of just @samp{*(.ctors)} and
- @samp{*(.dtors)}.
- 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.
- @end table
- @node Output Section Discarding
- @subsection Output Section Discarding
- @cindex discarding sections
- @cindex sections, discarding
- @cindex removing sections
- 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:
- @smallexample
- .foo : @{ *(.foo) @}
- @end smallexample
- @noindent
- will only create a @samp{.foo} section in the output file if there is a
- @samp{.foo} 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{. = . + 0}, @samp{. = sym},
- @samp{. = . + sym} and @samp{. = ALIGN (. != 0, expr, 1)} when
- @samp{sym} is an absolute symbol of value 0 defined in the script.
- This allows you to force output of an empty section with @samp{. = .}.
- The linker will ignore address assignments (@pxref{Output Section Address})
- 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.
- @cindex /DISCARD/
- The special output section name @samp{/DISCARD/} may be used to discard
- input sections. Any input sections which are assigned to an output
- section named @samp{/DISCARD/} are not included in the output file.
- This can be used to discard input sections marked with the ELF flag
- @code{SHF_GNU_RETAIN}, which would otherwise have been saved from linker
- garbage collection.
- Note, sections that match the @samp{/DISCARD/} 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.
- @node Output Section Attributes
- @subsection Output Section Attributes
- @cindex output section attributes
- We showed above that the full description of an output section looked
- like this:
- @smallexample
- @group
- @var{section} [@var{address}] [(@var{type})] :
- [AT(@var{lma})]
- [ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
- [SUBALIGN(@var{subsection_align})]
- [@var{constraint}]
- @{
- @var{output-section-command}
- @var{output-section-command}
- @dots{}
- @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
- @end group
- @end smallexample
- We've already described @var{section}, @var{address}, and
- @var{output-section-command}. In this section we will describe the
- remaining section attributes.
- @menu
- * Output Section Type:: Output section type
- * Output Section LMA:: Output section LMA
- * Forced Output Alignment:: Forced Output Alignment
- * Forced Input Alignment:: Forced Input Alignment
- * Output Section Constraint:: Output section constraint
- * Output Section Region:: Output section region
- * Output Section Phdr:: Output section phdr
- * Output Section Fill:: Output section fill
- @end menu
- @node Output Section Type
- @subsubsection Output Section Type
- Each output section may have a type. The type is a keyword in
- parentheses. The following types are defined:
- @table @code
- @item NOLOAD
- The section should be marked as not loadable, so that it will not be
- loaded into memory when the program is run.
- @item READONLY
- The section should be marked as read-only.
- @item DSECT
- @item COPY
- @item INFO
- @item OVERLAY
- 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.
- @item TYPE = @var{type}
- Set the section type to the integer @var{type}. When generating an ELF
- output file, type names @code{SHT_PROGBITS}, @code{SHT_STRTAB},
- @code{SHT_NOTE}, @code{SHT_NOBITS}, @code{SHT_INIT_ARRAY},
- @code{SHT_FINI_ARRAY}, and @code{SHT_PREINIT_ARRAY} are also allowed
- for @var{type}. It is the user's responsibility to ensure that any
- special requirements of the section type are met.
- @item READONLY ( TYPE = @var{type} )
- This form of the syntax combines the @var{READONLY} type with the
- type specified by @var{type}.
- @end table
- @kindex NOLOAD
- @cindex prevent unnecessary loading
- @cindex loading, preventing
- 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} section is addressed at memory location @samp{0} and does not
- need to be loaded when the program is run.
- @smallexample
- @group
- SECTIONS @{
- ROM 0 (NOLOAD) : @{ @dots{} @}
- @dots{}
- @}
- @end group
- @end smallexample
- @node Output Section LMA
- @subsubsection Output Section LMA
- @kindex AT>@var{lma_region}
- @kindex AT(@var{lma})
- @cindex load address
- @cindex section load address
- Every section has a virtual address (VMA) and a load address (LMA); see
- @ref{Basic Script Concepts}. The virtual address is specified by the
- @pxref{Output Section Address} described earlier. The load address is
- specified by the @code{AT} or @code{AT>} keywords. Specifying a load
- address is optional.
- The @code{AT} keyword takes an expression as an argument. This
- specifies the exact load address of the section. The @code{AT>} keyword
- takes the name of a memory region as an argument. @xref{MEMORY}. The
- load address of the section is set to the next free address in the
- region, aligned to the section's alignment requirements.
- If neither @code{AT} nor @code{AT>} is specified for an allocatable
- section, the linker will use the following heuristic to determine the
- load address:
- @itemize @bullet
- @item
- If the section has a specific VMA address, then this is used as
- the LMA address as well.
- @item
- If the section is not allocatable then its LMA is set to its VMA.
- @item
- 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.
- @item
- If no memory regions have been declared then a default region
- that covers the entire address space is used in the previous step.
- @item
- If no suitable region could be found, or there was no previous
- section then the LMA is set equal to the VMA.
- @end itemize
- @cindex ROM initialized data
- @cindex initialized data in ROM
- 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}, which starts at @code{0x1000}, one called
- @samp{.mdata}, which is loaded at the end of the @samp{.text} section
- even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
- uninitialized data at address @code{0x3000}. The symbol @code{_data} is
- defined with the value @code{0x2000}, which shows that the location
- counter holds the VMA value, not the LMA value.
- @smallexample
- @group
- SECTIONS
- @{
- .text 0x1000 : @{ *(.text) _etext = . ; @}
- .mdata 0x2000 :
- AT ( ADDR (.text) + SIZEOF (.text) )
- @{ _data = . ; *(.data); _edata = . ; @}
- .bss 0x3000 :
- @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
- @}
- @end group
- @end smallexample
- 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.
- @smallexample
- @group
- 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;
- @end group
- @end smallexample
- @node Forced Output Alignment
- @subsubsection Forced Output Alignment
- @kindex ALIGN(@var{section_align})
- @cindex forcing output section alignment
- @cindex output section alignment
- 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.
- @node Forced Input Alignment
- @subsubsection Forced Input Alignment
- @kindex SUBALIGN(@var{subsection_align})
- @cindex forcing input section alignment
- @cindex input section alignment
- 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.
- @node Output Section Constraint
- @subsubsection Output Section Constraint
- @kindex ONLY_IF_RO
- @kindex ONLY_IF_RW
- @cindex constraints on output sections
- 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} and
- @code{ONLY_IF_RW} respectively.
- @node Output Section Region
- @subsubsection Output Section Region
- @kindex >@var{region}
- @cindex section, assigning to memory region
- @cindex memory regions and sections
- You can assign a section to a previously defined region of memory by
- using @samp{>@var{region}}. @xref{MEMORY}.
- Here is a simple example:
- @smallexample
- @group
- MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
- SECTIONS @{ ROM : @{ *(.text) @} >rom @}
- @end group
- @end smallexample
- @node Output Section Phdr
- @subsubsection Output Section Phdr
- @kindex :@var{phdr}
- @cindex section, assigning to program header
- @cindex program headers and sections
- You can assign a section to a previously defined program segment by
- using @samp{:@var{phdr}}. @xref{PHDRS}. 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}} modifier. You can use @code{:NONE} to tell the
- linker to not put the section in any segment at all.
- Here is a simple example:
- @smallexample
- @group
- PHDRS @{ text PT_LOAD ; @}
- SECTIONS @{ .text : @{ *(.text) @} :text @}
- @end group
- @end smallexample
- @node Output Section Fill
- @subsubsection Output Section Fill
- @kindex =@var{fillexp}
- @cindex section fill pattern
- @cindex fill pattern, entire section
- You can set the fill pattern for an entire section by using
- @samp{=@var{fillexp}}. @var{fillexp} is an expression
- (@pxref{Expressions}). 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} and without a trailing @samp{k} or @samp{M}, 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{+}, the fill
- pattern is the four least significant bytes of the value of the
- expression. In all cases, the number is big-endian.
- You can also change the fill value with a @code{FILL} command in the
- output section commands; (@pxref{Output Section Data}).
- Here is a simple example:
- @smallexample
- @group
- SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
- @end group
- @end smallexample
- @node Overlay Description
- @subsection Overlay Description
- @kindex OVERLAY
- @cindex overlays
- 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.
- Overlays are described using the @code{OVERLAY} command. The
- @code{OVERLAY} command is used within a @code{SECTIONS} command, like an
- output section description. The full syntax of the @code{OVERLAY}
- command is as follows:
- @smallexample
- @group
- OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
- @{
- @var{secname1}
- @{
- @var{output-section-command}
- @var{output-section-command}
- @dots{}
- @} [:@var{phdr}@dots{}] [=@var{fill}]
- @var{secname2}
- @{
- @var{output-section-command}
- @var{output-section-command}
- @dots{}
- @} [:@var{phdr}@dots{}] [=@var{fill}]
- @dots{}
- @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] [,]
- @end group
- @end smallexample
- Everything is optional except @code{OVERLAY} (a keyword), and each
- section must have a name (@var{secname1} and @var{secname2} above). The
- section definitions within the @code{OVERLAY} construct are identical to
- those within the general @code{SECTIONS} construct (@pxref{SECTIONS}),
- except that no addresses and no memory regions may be defined for
- sections within an @code{OVERLAY}.
- The comma at the end may be required if a @var{fill} is used and
- the next @var{sections-command} looks like a continuation of the expression.
- 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} 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).
- If the @code{NOCROSSREFS} 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.
- @xref{Miscellaneous Commands, NOCROSSREFS}.
- For each section within the @code{OVERLAY}, the linker automatically
- provides two symbols. The symbol @code{__load_start_@var{secname}} is
- defined as the starting load address of the section. The symbol
- @code{__load_stop_@var{secname}} is defined as the final load address of
- the section. Any characters within @var{secname} 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.
- 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.
- Here is an example. Remember that this would appear inside a
- @code{SECTIONS} construct.
- @smallexample
- @group
- OVERLAY 0x1000 : AT (0x4000)
- @{
- .text0 @{ o1/*.o(.text) @}
- .text1 @{ o2/*.o(.text) @}
- @}
- @end group
- @end smallexample
- @noindent
- This will define both @samp{.text0} and @samp{.text1} to start at
- address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
- @samp{.text1} will be loaded immediately after @samp{.text0}. The
- following symbols will be defined if referenced: @code{__load_start_text0},
- @code{__load_stop_text0}, @code{__load_start_text1},
- @code{__load_stop_text1}.
- C code to copy overlay @code{.text1} into the overlay area might look
- like the following.
- @smallexample
- @group
- extern char __load_start_text1, __load_stop_text1;
- memcpy ((char *) 0x1000, &__load_start_text1,
- &__load_stop_text1 - &__load_start_text1);
- @end group
- @end smallexample
- Note that the @code{OVERLAY} 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.
- @smallexample
- @group
- .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));
- @end group
- @end smallexample
- @node MEMORY
- @section MEMORY Command
- @kindex MEMORY
- @cindex memory regions
- @cindex regions of memory
- @cindex allocating memory
- @cindex discontinuous memory
- The linker's default configuration permits allocation of all available
- memory. You can override this by using the @code{MEMORY} command.
- The @code{MEMORY} 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.
- A linker script may contain many uses of the @code{MEMORY} command,
- however, all memory blocks defined are treated as if they were
- specified inside a single @code{MEMORY} command. The syntax for
- @code{MEMORY} is:
- @smallexample
- @group
- MEMORY
- @{
- @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
- @dots{}
- @}
- @end group
- @end smallexample
- The @var{name} 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} command. However you can
- add later alias names to existing memory regions with the @ref{REGION_ALIAS}
- command.
- @cindex memory region attributes
- The @var{attr} 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
- @ref{SECTIONS}, 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.
- The @var{attr} string must consist only of the following characters:
- @table @samp
- @item R
- Read-only section
- @item W
- Read/write section
- @item X
- Executable section
- @item A
- Allocatable section
- @item I
- Initialized section
- @item L
- Same as @samp{I}
- @item !
- Invert the sense of any of the attributes that follow
- @end table
- If an unmapped section matches any of the listed attributes other than
- @samp{!}, it will be placed in the memory region. The @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} will match any unmapped section that has either
- or both of the @samp{R} and @samp{W} attributes, but only as long as
- the section does not also have the @samp{X} attribute.
- @kindex ORIGIN =
- @kindex o =
- @kindex org =
- The @var{origin} 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} may be
- abbreviated to @code{org} or @code{o} (but not, for example,
- @code{ORG}).
- @kindex LENGTH =
- @kindex len =
- @kindex l =
- The @var{len} is an expression for the size in bytes of the memory
- region. As with the @var{origin} expression, the expression must
- be numerical only and must evaluate to a constant. The keyword
- @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
- In the following example, we specify that there are two memory regions
- available for allocation: one starting at @samp{0} for 256 kilobytes,
- and the other starting at @samp{0x40000000} for four megabytes. The
- linker will place into the @samp{rom} 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} memory
- region.
- @smallexample
- @group
- MEMORY
- @{
- rom (rx) : ORIGIN = 0, LENGTH = 256K
- ram (!rx) : org = 0x40000000, l = 4M
- @}
- @end group
- @end smallexample
- 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}} output section attribute. For example, if you have
- a memory region named @samp{mem}, you would use @samp{>mem} in the
- output section definition. @xref{Output Section Region}. 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.
- It is possible to access the origin and length of a memory in an
- expression via the @code{ORIGIN(@var{memory})} and
- @code{LENGTH(@var{memory})} functions:
- @smallexample
- @group
- _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
- @end group
- @end smallexample
- @node PHDRS
- @section PHDRS Command
- @kindex PHDRS
- @cindex program headers
- @cindex ELF program headers
- @cindex program segments
- @cindex segments, ELF
- The ELF object file format uses @dfn{program headers}, also knows as
- @dfn{segments}. The program headers describe how the program should be
- loaded into memory. You can print them out by using the @code{objdump}
- program with the @samp{-p} option.
- 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.
- 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} command for this purpose. When
- the linker sees the @code{PHDRS} command in the linker script, it will
- not create any program headers other than the ones specified.
- The linker only pays attention to the @code{PHDRS} command when
- generating an ELF output file. In other cases, the linker will simply
- ignore @code{PHDRS}.
- This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
- @code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
- @smallexample
- @group
- PHDRS
- @{
- @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
- [ FLAGS ( @var{flags} ) ] ;
- @}
- @end group
- @end smallexample
- The @var{name} is used only for reference in the @code{SECTIONS} 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.
- 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}} output section
- attribute to place a section in a particular segment. @xref{Output
- Section Phdr}.
- 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}}, using it once for each segment which should
- contain the section.
- If you place a section in one or more segments using @samp{:@var{phdr}},
- then the linker will place all subsequent allocatable sections which do
- not specify @samp{:@var{phdr}} 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} to override the
- default segment and tell the linker to not put the section in any
- segment at all.
- @kindex FILEHDR
- @kindex PHDRS
- You may use the @code{FILEHDR} and @code{PHDRS} keywords after
- the program header type to further describe the contents of the segment.
- The @code{FILEHDR} keyword means that the segment should include the ELF
- file header. The @code{PHDRS} keyword means that the segment should
- include the ELF program headers themselves. If applied to a loadable
- segment (@code{PT_LOAD}), all prior loadable segments must have one of
- these keywords.
- The @var{type} may be one of the following. The numbers indicate the
- value of the keyword.
- @table @asis
- @item @code{PT_NULL} (0)
- Indicates an unused program header.
- @item @code{PT_LOAD} (1)
- Indicates that this program header describes a segment to be loaded from
- the file.
- @item @code{PT_DYNAMIC} (2)
- Indicates a segment where dynamic linking information can be found.
- @item @code{PT_INTERP} (3)
- Indicates a segment where the name of the program interpreter may be
- found.
- @item @code{PT_NOTE} (4)
- Indicates a segment holding note information.
- @item @code{PT_SHLIB} (5)
- A reserved program header type, defined but not specified by the ELF
- ABI.
- @item @code{PT_PHDR} (6)
- Indicates a segment where the program headers may be found.
- @item @code{PT_TLS} (7)
- Indicates a segment containing thread local storage.
- @item @var{expression}
- An expression giving the numeric type of the program header. This may
- be used for types not defined above.
- @end table
- You can specify that a segment should be loaded at a particular address
- in memory by using an @code{AT} expression. This is identical to the
- @code{AT} command used as an output section attribute (@pxref{Output
- Section LMA}). The @code{AT} command for a program header overrides the
- output section attribute.
- The linker will normally set the segment flags based on the sections
- which comprise the segment. You may use the @code{FLAGS} keyword to
- explicitly specify the segment flags. The value of @var{flags} must be
- an integer. It is used to set the @code{p_flags} field of the program
- header.
- Here is an example of @code{PHDRS}. This shows a typical set of program
- headers used on a native ELF system.
- @example
- @group
- 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 */
- @dots{}
- . = . + 0x1000; /* move to a new page in memory */
- .data : @{ *(.data) @} :data
- .dynamic : @{ *(.dynamic) @} :data :dynamic
- @dots{}
- @}
- @end group
- @end example
- @node VERSION
- @section VERSION Command
- @kindex VERSION @{script text@}
- @cindex symbol versions
- @cindex version script
- @cindex versions of symbols
- 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.
- 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} linker option.
- The syntax of the @code{VERSION} command is simply
- @smallexample
- VERSION @{ version-script-commands @}
- @end smallexample
- 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.
- The easiest way to demonstrate the version script language is with a few
- examples.
- @smallexample
- 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;
- @end smallexample
- This example version script defines three version nodes. The first
- version node defined is @samp{VERS_1.1}; it has no other dependencies.
- The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. 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{original}, or @samp{new}
- 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.
- Next, the version script defines node @samp{VERS_1.2}. This node
- depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
- to the version node @samp{VERS_1.2}.
- Finally, the version script defines node @samp{VERS_2.0}. This node
- depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1}
- and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
- 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: *;}
- 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.
- 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} version
- could just as well have appeared in between @samp{1.1} and @samp{1.2}.
- However, this would be a confusing way to write a version script.
- 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.
- @smallexample
- @{ global: foo; bar; local: *; @};
- @end smallexample
- 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.
- 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.
- 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:
- @smallexample
- __asm__(".symver original_foo,foo@@VERS_1.1");
- @end smallexample
- @noindent
- in the C source file. This renames the function @samp{original_foo} to
- be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
- The @samp{local:} directive can be used to prevent the symbol
- @samp{original_foo} from being exported. A @samp{.symver} directive
- takes precedence over a version script.
- 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.
- To do this, you must use multiple @samp{.symver} directives in the
- source file. Here is an example:
- @smallexample
- __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");
- @end smallexample
- In this example, @samp{foo@@} represents the symbol @samp{foo} 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{old_foo},
- @samp{old_foo1}, and @samp{new_foo}.
- 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} type of @samp{.symver} 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.
- 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}), or you can use the @samp{.symver} directive to
- specifically bind to an external version of the function in question.
- You can also specify the language in the version script:
- @smallexample
- VERSION extern "lang" @{ version-script-commands @}
- @end smallexample
- The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
- The linker will iterate over the list of symbols at the link time and
- demangle them according to @samp{lang} before matching them to the
- patterns specified in @samp{version-script-commands}. The default
- @samp{lang} is @samp{C}.
- 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.
- @node Expressions
- @section Expressions in Linker Scripts
- @cindex expressions
- @cindex arithmetic
- 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.
- You can use and set symbol values in expressions.
- The linker defines several special purpose builtin functions for use in
- expressions.
- @menu
- * Constants:: Constants
- * Symbolic Constants:: Symbolic constants
- * Symbols:: Symbol Names
- * Orphan Sections:: Orphan Sections
- * Location Counter:: The Location Counter
- * Operators:: Operators
- * Evaluation:: Evaluation
- * Expression Section:: The Section of an Expression
- * Builtin Functions:: Builtin Functions
- @end menu
- @node Constants
- @subsection Constants
- @cindex integer notation
- @cindex constants in linker scripts
- All constants are integers.
- As in C, the linker considers an integer beginning with @samp{0} to be
- octal, and an integer beginning with @samp{0x} or @samp{0X} to be
- hexadecimal. Alternatively the linker accepts suffixes of @samp{h} or
- @samp{H} for hexadecimal, @samp{o} or @samp{O} for octal, @samp{b} or
- @samp{B} for binary and @samp{d} or @samp{D} for decimal. Any integer
- value without a prefix or a suffix is considered to be decimal.
- @cindex scaled integers
- @cindex K and M integer suffixes
- @cindex M and K integer suffixes
- @cindex suffixes for integers
- @cindex integer suffixes
- In addition, you can use the suffixes @code{K} and @code{M} to scale a
- constant by
- @c TEXI2ROFF-KILL
- @ifnottex
- @c END TEXI2ROFF-KILL
- @code{1024} or @code{1024*1024}
- @c TEXI2ROFF-KILL
- @end ifnottex
- @tex
- ${\rm 1024}$ or ${\rm 1024}^2$
- @end tex
- @c END TEXI2ROFF-KILL
- respectively. For example, the following
- all refer to the same quantity:
- @smallexample
- _fourk_1 = 4K;
- _fourk_2 = 4096;
- _fourk_3 = 0x1000;
- _fourk_4 = 10000o;
- @end smallexample
- Note - the @code{K} and @code{M} suffixes cannot be used in
- conjunction with the base suffixes mentioned above.
- @node Symbolic Constants
- @subsection Symbolic Constants
- @cindex symbolic constants
- @kindex CONSTANT
- It is possible to refer to target-specific constants via the use of
- the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
- @table @code
- @item MAXPAGESIZE
- @kindex MAXPAGESIZE
- The target's maximum page size.
- @item COMMONPAGESIZE
- @kindex COMMONPAGESIZE
- The target's default page size.
- @end table
- So for example:
- @smallexample
- .text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @}
- @end smallexample
- will create a text section aligned to the largest page boundary
- supported by the target.
- @node Symbols
- @subsection Symbol Names
- @cindex symbol names
- @cindex names
- @cindex quoted symbol names
- @kindex "
- 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:
- @smallexample
- "SECTION" = 9;
- "with a space" = "also with a space" + 10;
- @end smallexample
- Since symbols can contain many non-alphabetic characters, it is safest
- to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
- whereas @samp{A - B} is an expression involving subtraction.
- @node Orphan Sections
- @subsection Orphan Sections
- @cindex orphan
- 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.
- 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.
- 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.
- 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.
- The command-line options @samp{--orphan-handling} and @samp{--unique}
- (@pxref{Options,,Command-line Options}) can be used to control which
- output sections an orphan is placed in.
- @node Location Counter
- @subsection The Location Counter
- @kindex .
- @cindex dot
- @cindex location counter
- @cindex current output location
- The special linker variable @dfn{dot} @samp{.} always contains the
- current output location counter. Since the @code{.} always refers to a
- location in an output section, it may only appear in an expression
- within a @code{SECTIONS} command. The @code{.} symbol may appear
- anywhere that an ordinary symbol is allowed in an expression.
- @cindex holes
- Assigning a value to @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.
- @smallexample
- SECTIONS
- @{
- output :
- @{
- file1(.text)
- . = . + 1000;
- file2(.text)
- . += 1000;
- file3(.text)
- @} = 0x12345678;
- @}
- @end smallexample
- @noindent
- In the previous example, the @samp{.text} section from @file{file1} is
- located at the beginning of the output section @samp{output}. It is
- followed by a 1000 byte gap. Then the @samp{.text} section from
- @file{file2} appears, also with a 1000 byte gap following before the
- @samp{.text} section from @file{file3}. The notation @samp{= 0x12345678}
- specifies what data to write in the gaps (@pxref{Output Section Fill}).
- @cindex dot inside sections
- Note: @code{.} actually refers to the byte offset from the start of the
- current containing object. Normally this is the @code{SECTIONS}
- statement, whose start address is 0, hence @code{.} can be used as an
- absolute address. If @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:
- @smallexample
- SECTIONS
- @{
- . = 0x100
- .text: @{
- *(.text)
- . = 0x200
- @}
- . = 0x500
- .data: @{
- *(.data)
- . += 0x600
- @}
- @}
- @end smallexample
- The @samp{.text} 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} 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{.} backwards). The @samp{.data} 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} input sections and before the end of
- the @samp{.data} output section itself.
- @cindex dot outside sections
- 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:
- @smallexample
- SECTIONS
- @{
- start_of_text = . ;
- .text: @{ *(.text) @}
- end_of_text = . ;
- start_of_data = . ;
- .data: @{ *(.data) @}
- end_of_data = . ;
- @}
- @end smallexample
- If the linker needs to place some input section, e.g. @code{.rodata},
- not mentioned in the script, it might choose to place that section
- between @code{.text} and @code{.data}. You might think the linker
- should place @code{.rodata} 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{.}. I.e., the linker will
- place the orphan @code{.rodata} section as if the script was written
- as follows:
- @smallexample
- SECTIONS
- @{
- start_of_text = . ;
- .text: @{ *(.text) @}
- end_of_text = . ;
- start_of_data = . ;
- .rodata: @{ *(.rodata) @}
- .data: @{ *(.data) @}
- end_of_data = . ;
- @}
- @end smallexample
- This may or may not be the script author's intention for the value of
- @code{start_of_data}. 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{.} is setting the start address of
- a following output section and thus should be grouped with that
- section. So you could write:
- @smallexample
- SECTIONS
- @{
- start_of_text = . ;
- .text: @{ *(.text) @}
- end_of_text = . ;
- . = . ;
- start_of_data = . ;
- .data: @{ *(.data) @}
- end_of_data = . ;
- @}
- @end smallexample
- Now, the orphan @code{.rodata} section will be placed between
- @code{end_of_text} and @code{start_of_data}.
- @need 2000
- @node Operators
- @subsection Operators
- @cindex operators for arithmetic
- @cindex arithmetic operators
- @cindex precedence in expressions
- The linker recognizes the standard C set of arithmetic operators, with
- the standard bindings and precedence levels:
- @c TEXI2ROFF-KILL
- @ifnottex
- @c END TEXI2ROFF-KILL
- @smallexample
- 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 right ? :
- 11 right &= += -= *= /= (2)
- (lowest)
- @end smallexample
- Notes:
- (1) Prefix operators
- (2) @xref{Assignments}.
- @c TEXI2ROFF-KILL
- @end ifnottex
- @tex
- \vskip \baselineskip
- %"lispnarrowing" is the extra indent used generally for smallexample
- \hskip\lispnarrowing\vbox{\offinterlineskip
- \hrule
- \halign
- {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
- height2pt&\omit&&\omit&&\omit&\cr
- &Precedence&& Associativity &&{\rm Operators}&\cr
- height2pt&\omit&&\omit&&\omit&\cr
- \noalign{\hrule}
- height2pt&\omit&&\omit&&\omit&\cr
- &highest&&&&&\cr
- % '176 is tilde, '~' in tt font
- &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
- &2&&left&&* / \%&\cr
- &3&&left&&+ -&\cr
- &4&&left&&>> <<&\cr
- &5&&left&&== != > < <= >=&\cr
- &6&&left&&\&&\cr
- &7&&left&&|&\cr
- &8&&left&&{\&\&}&\cr
- &9&&left&&||&\cr
- &10&&right&&? :&\cr
- &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
- &lowest&&&&&\cr
- height2pt&\omit&&\omit&&\omit&\cr}
- \hrule}
- @end tex
- @iftex
- {
- @obeylines@parskip=0pt@parindent=0pt
- @dag@quad Prefix operators.
- @ddag@quad @xref{Assignments}.
- }
- @end iftex
- @c END TEXI2ROFF-KILL
- @node Evaluation
- @subsection Evaluation
- @cindex lazy evaluation
- @cindex expression evaluation order
- The linker evaluates expressions lazily. It only computes the value of
- an expression when absolutely necessary.
- 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.
- 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.
- The sizes of sections cannot be known until after allocation, so
- assignments dependent upon these are not performed until after
- allocation.
- Some expressions, such as those depending upon the location counter
- @samp{.}, must be evaluated during section allocation.
- 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
- @smallexample
- @group
- SECTIONS
- @{
- .text 9+this_isnt_constant :
- @{ *(.text) @}
- @}
- @end group
- @end smallexample
- @noindent
- will cause the error message @samp{non constant expression for initial
- address}.
- @node Expression Section
- @subsection The Section of an Expression
- @cindex expression sections
- @cindex absolute expressions
- @cindex relative expressions
- @cindex absolute and relocatable symbols
- @cindex relocatable and absolute symbols
- @cindex symbols, relocatable and absolute
- Addresses and symbols may be section relative, or absolute. A section
- relative symbol is relocatable. If you request relocatable output
- using the @samp{-r} 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.
- 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{LOADADDR}, @code{ORIGIN} and
- @code{SEGMENT_START}. Other terms are simply numbers, or are builtin
- functions that return a non-address value, such as @code{LENGTH}.
- One complication is that unless you set @code{LD_FEATURE ("SANE_EXPR")}
- (@pxref{Miscellaneous Commands}), numbers and absolute symbols are treated
- differently depending on their location, for compatibility with older
- versions of @code{ld}. 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")} is
- given, then absolute symbols and numbers are simply treated as numbers
- everywhere.
- In the following simple example,
- @smallexample
- @group
- SECTIONS
- @{
- . = 0x100;
- __executable_start = 0x100;
- .data :
- @{
- . = 0x10;
- __data_start = 0x10;
- *(.data)
- @}
- @dots{}
- @}
- @end group
- @end smallexample
- both @code{.} and @code{__executable_start} are set to the absolute
- address 0x100 in the first two assignments, then both @code{.} and
- @code{__data_start} are set to 0x10 relative to the @code{.data}
- section in the second two assignments.
- For expressions involving numbers, relative addresses and absolute
- addresses, ld follows these rules to evaluate terms:
- @itemize @bullet
- @item
- 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).
- @item
- 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).
- @item
- 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.
- @end itemize
- The result section of each sub-expression is as follows:
- @itemize @bullet
- @item
- An operation involving only numbers results in a number.
- @item
- The result of comparisons, @samp{&&} and @samp{||} is also a number.
- @item
- 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")} or inside an output section definition
- but an absolute address otherwise.
- @item
- 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).
- @item
- The result of other operations on absolute addresses (after above
- conversions) is an absolute address.
- @end itemize
- You can use the builtin function @code{ABSOLUTE} 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}:
- @smallexample
- SECTIONS
- @{
- .data : @{ *(.data) _edata = ABSOLUTE(.); @}
- @}
- @end smallexample
- @noindent
- If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
- @samp{.data} section.
- Using @code{LOADADDR} also forces an expression absolute, since this
- particular builtin function returns an absolute address.
- @node Builtin Functions
- @subsection Builtin Functions
- @cindex functions in expressions
- The linker script language includes a number of builtin functions for
- use in linker script expressions.
- @table @code
- @item ABSOLUTE(@var{exp})
- @kindex ABSOLUTE(@var{exp})
- @cindex expression, absolute
- Return the absolute (non-relocatable, as opposed to non-negative) value
- of the expression @var{exp}. Primarily useful to assign an absolute
- value to a symbol within a section definition, where symbol values are
- normally section relative. @xref{Expression Section}.
- @item ADDR(@var{section})
- @kindex ADDR(@var{section})
- @cindex section address in expression
- Return the address (VMA) of the named @var{section}. Your
- script must previously have defined the location of that section. In
- the following example, @code{start_of_output_1}, @code{symbol_1} and
- @code{symbol_2} are assigned equivalent values, except that
- @code{symbol_1} will be relative to the @code{.output1} section while
- the other two will be absolute:
- @smallexample
- @group
- SECTIONS @{ @dots{}
- .output1 :
- @{
- start_of_output_1 = ABSOLUTE(.);
- @dots{}
- @}
- .output :
- @{
- symbol_1 = ADDR(.output1);
- symbol_2 = start_of_output_1;
- @}
- @dots{} @}
- @end group
- @end smallexample
- @item ALIGN(@var{align})
- @itemx ALIGN(@var{exp},@var{align})
- @kindex ALIGN(@var{align})
- @kindex ALIGN(@var{exp},@var{align})
- @cindex round up location counter
- @cindex align location counter
- @cindex round up expression
- @cindex align expression
- Return the location counter (@code{.}) or arbitrary expression aligned
- to the next @var{align} boundary. The single operand @code{ALIGN}
- doesn't change the value of the location counter---it just does
- arithmetic on it. The two operand @code{ALIGN} allows an arbitrary
- expression to be aligned upwards (@code{ALIGN(@var{align})} is
- equivalent to @code{ALIGN(ABSOLUTE(.), @var{align})}).
- Here is an example which aligns the output @code{.data} section to the
- next @code{0x2000} byte boundary after the preceding section and sets a
- variable within the section to the next @code{0x8000} boundary after the
- input sections:
- @smallexample
- @group
- SECTIONS @{ @dots{}
- .data ALIGN(0x2000): @{
- *(.data)
- variable = ALIGN(0x8000);
- @}
- @dots{} @}
- @end group
- @end smallexample
- @noindent
- The first use of @code{ALIGN} in this example specifies the location of
- a section because it is used as the optional @var{address} attribute of
- a section definition (@pxref{Output Section Address}). The second use
- of @code{ALIGN} is used to defines the value of a symbol.
- The builtin function @code{NEXT} is closely related to @code{ALIGN}.
- @item ALIGNOF(@var{section})
- @kindex ALIGNOF(@var{section})
- @cindex section alignment
- Return the alignment in bytes of the named @var{section}, if that section has
- been allocated. If the section has not been allocated when this is
- evaluated, the linker will report an error. In the following example,
- the alignment of the @code{.output} section is stored as the first
- value in that section.
- @smallexample
- @group
- SECTIONS@{ @dots{}
- .output @{
- LONG (ALIGNOF (.output))
- @dots{}
- @}
- @dots{} @}
- @end group
- @end smallexample
- @item BLOCK(@var{exp})
- @kindex BLOCK(@var{exp})
- This is a synonym for @code{ALIGN}, for compatibility with older linker
- scripts. It is most often seen when setting the address of an output
- section.
- @item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
- @kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
- This is equivalent to either
- @smallexample
- (ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
- @end smallexample
- or
- @smallexample
- (ALIGN(@var{maxpagesize})
- + ((. + @var{commonpagesize} - 1) & (@var{maxpagesize} - @var{commonpagesize})))
- @end smallexample
- @noindent
- depending on whether the latter uses fewer @var{commonpagesize} sized pages
- for the data segment (area between the result of this expression and
- @code{DATA_SEGMENT_END}) than the former or not.
- If the latter form is used, it means @var{commonpagesize} bytes of runtime
- memory will be saved at the expense of up to @var{commonpagesize} wasted
- bytes in the on-disk file.
- This expression can only be used directly in @code{SECTIONS} commands, not in
- any output section descriptions and only once in the linker script.
- @var{commonpagesize} should be less or equal to @var{maxpagesize} 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}. Note however
- that @samp{-z relro} protection will not be effective if the system
- page size is larger than @var{commonpagesize}.
- @noindent
- Example:
- @smallexample
- . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
- @end smallexample
- @item DATA_SEGMENT_END(@var{exp})
- @kindex DATA_SEGMENT_END(@var{exp})
- This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
- evaluation purposes.
- @smallexample
- . = DATA_SEGMENT_END(.);
- @end smallexample
- @item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
- @kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
- This defines the end of the @code{PT_GNU_RELRO} segment when
- @samp{-z relro} option is used.
- When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
- does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
- @var{exp} + @var{offset} is aligned to the @var{commonpagesize}
- argument given to @code{DATA_SEGMENT_ALIGN}. If present in the linker
- script, it must be placed between @code{DATA_SEGMENT_ALIGN} and
- @code{DATA_SEGMENT_END}. Evaluates to the second argument plus any
- padding needed at the end of the @code{PT_GNU_RELRO} segment due to
- section alignment.
- @smallexample
- . = DATA_SEGMENT_RELRO_END(24, .);
- @end smallexample
- @item DEFINED(@var{symbol})
- @kindex DEFINED(@var{symbol})
- @cindex symbol defaults
- Return 1 if @var{symbol} 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} to the first location in
- the @samp{.text} section---but if a symbol called @samp{begin} already
- existed, its value is preserved:
- @smallexample
- @group
- SECTIONS @{ @dots{}
- .text : @{
- begin = DEFINED(begin) ? begin : . ;
- @dots{}
- @}
- @dots{}
- @}
- @end group
- @end smallexample
- @item LENGTH(@var{memory})
- @kindex LENGTH(@var{memory})
- Return the length of the memory region named @var{memory}.
- @item LOADADDR(@var{section})
- @kindex LOADADDR(@var{section})
- @cindex section load address in expression
- Return the absolute LMA of the named @var{section}. (@pxref{Output
- Section LMA}).
- @item LOG2CEIL(@var{exp})
- @kindex LOG2CEIL(@var{exp})
- Return the binary logarithm of @var{exp} rounded towards infinity.
- @code{LOG2CEIL(0)} returns 0.
- @kindex MAX
- @item MAX(@var{exp1}, @var{exp2})
- Returns the maximum of @var{exp1} and @var{exp2}.
- @kindex MIN
- @item MIN(@var{exp1}, @var{exp2})
- Returns the minimum of @var{exp1} and @var{exp2}.
- @item NEXT(@var{exp})
- @kindex NEXT(@var{exp})
- @cindex unallocated address, next
- Return the next unallocated address that is a multiple of @var{exp}.
- This function is closely related to @code{ALIGN(@var{exp})}; unless you
- use the @code{MEMORY} command to define discontinuous memory for the
- output file, the two functions are equivalent.
- @item ORIGIN(@var{memory})
- @kindex ORIGIN(@var{memory})
- Return the origin of the memory region named @var{memory}.
- @item SEGMENT_START(@var{segment}, @var{default})
- @kindex SEGMENT_START(@var{segment}, @var{default})
- Return the base address of the named @var{segment}. If an explicit
- value has already been given for this segment (with a command-line
- @samp{-T} option) then that value will be returned otherwise the value
- will be @var{default}. At present, the @samp{-T} 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} with any segment
- name.
- @item SIZEOF(@var{section})
- @kindex SIZEOF(@var{section})
- @cindex section size
- Return the size in bytes of the named @var{section}, if that section has
- been allocated. If the section has not been allocated when this is
- evaluated, the linker will report an error. In the following example,
- @code{symbol_1} and @code{symbol_2} are assigned identical values:
- @smallexample
- @group
- SECTIONS@{ @dots{}
- .output @{
- .start = . ;
- @dots{}
- .end = . ;
- @}
- symbol_1 = .end - .start ;
- symbol_2 = SIZEOF(.output);
- @dots{} @}
- @end group
- @end smallexample
- @item SIZEOF_HEADERS
- @kindex SIZEOF_HEADERS
- @cindex header size
- 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.
- @cindex not enough room for program headers
- @cindex program headers, not enough room
- When producing an ELF output file, if the linker script uses the
- @code{SIZEOF_HEADERS} 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}. To avoid this error, you must avoid using
- the @code{SIZEOF_HEADERS} 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}
- command (@pxref{PHDRS}).
- @end table
- @node Implicit Linker Scripts
- @section Implicit Linker Scripts
- @cindex implicit linker scripts
- 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.
- An implicit linker script will not replace the default linker script.
- Typically an implicit linker script would contain only symbol
- assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
- commands.
- 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.
- @node Plugins
- @chapter Linker Plugins
- @cindex plugins
- @cindex linker plugins
- 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.
- Currently there is only one plugin shipped by default, but more may
- be added here later.
- @menu
- * libdep Plugin:: Static Library Dependencies Plugin
- @end menu
- @node libdep Plugin
- @section Static Library Dependencies Plugin
- @cindex static library dependencies
- 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.
- 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.
- The GNU @command{ar} utility now supports a @option{--record-libdeps} option
- to embed dependency lists into static libraries as well, and the @file{libdep}
- plugin may be used to read this dependency information at link time. The
- dependency information is stored as a single string, carrying @option{-l}
- and @option{-L} 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 @command{ar} is not
- being used to create the archive. The information is stored in an
- archive member named @samp{__.LIBDEP}.
- For example, given a library @file{libssl.a} that depends on another
- library @file{libcrypto.a} which may be found in @file{/usr/local/lib},
- the @samp{__.LIBDEP} member of @file{libssl.a} would contain
- @smallexample
- -L/usr/local/lib -lcrypto
- @end smallexample
- @ifset GENERIC
- @node Machine Dependent
- @chapter Machine Dependent Features
- @cindex machine dependencies
- @command{ld} has additional features on some platforms; the following
- sections describe them. Machines where @command{ld} has no additional
- functionality are not listed.
- @menu
- @ifset H8300
- * H8/300:: @command{ld} and the H8/300
- @end ifset
- @ifset M68HC11
- * M68HC11/68HC12:: @code{ld} and the Motorola 68HC11 and 68HC12 families
- @end ifset
- @ifset ARM
- * ARM:: @command{ld} and the ARM family
- @end ifset
- @ifset HPPA
- * HPPA ELF32:: @command{ld} and HPPA 32-bit ELF
- @end ifset
- @ifset M68K
- * M68K:: @command{ld} and the Motorola 68K family
- @end ifset
- @ifset MIPS
- * MIPS:: @command{ld} and the MIPS family
- @end ifset
- @ifset MMIX
- * MMIX:: @command{ld} and MMIX
- @end ifset
- @ifset MSP430
- * MSP430:: @command{ld} and MSP430
- @end ifset
- @ifset NDS32
- * NDS32:: @command{ld} and NDS32
- @end ifset
- @ifset NIOSII
- * Nios II:: @command{ld} and the Altera Nios II
- @end ifset
- @ifset POWERPC
- * PowerPC ELF32:: @command{ld} and PowerPC 32-bit ELF Support
- @end ifset
- @ifset POWERPC64
- * PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support
- @end ifset
- @ifset S/390
- * S/390 ELF:: @command{ld} and S/390 ELF Support
- @end ifset
- @ifset SPU
- * SPU ELF:: @command{ld} and SPU ELF Support
- @end ifset
- @ifset TICOFF
- * TI COFF:: @command{ld} and TI COFF
- @end ifset
- @ifset WIN32
- * WIN32:: @command{ld} and WIN32 (cygwin/mingw)
- @end ifset
- @ifset XTENSA
- * Xtensa:: @command{ld} and Xtensa Processors
- @end ifset
- @end menu
- @end ifset
- @ifset H8300
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node H8/300
- @section @command{ld} and the H8/300
- @cindex H8/300 support
- For the H8/300, @command{ld} can perform these global optimizations when
- you specify the @samp{--relax} command-line option.
- @table @emph
- @cindex relaxing on H8/300
- @item relaxing address modes
- @command{ld} finds all @code{jsr} and @code{jmp} instructions whose
- targets are within eight bits, and turns them into eight-bit
- program-counter relative @code{bsr} and @code{bra} instructions,
- respectively.
- @cindex synthesizing on H8/300
- @item synthesizing instructions
- @c FIXME: specifically mov.b, or any mov instructions really? -> mov.b only, at least on H8, H8H, H8S
- @command{ld} finds all @code{mov.b} 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{@@}@var{aa}:16} into
- @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
- top page of memory).
- @command{ld} finds all @code{mov} 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{@@}@var{d}:32,ERx} into @samp{mov.b @code{@@}@var{d}:16,ERx}
- whenever the displacement @var{d} is in the 16 bit signed integer
- range. Only implemented in ELF-format ld).
- @item bit manipulation instructions
- @command{ld} finds all bit manipulation instructions like @code{band, bclr,
- biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor}
- 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{@@}@var{aa}:32} into
- @samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in
- the top page of memory).
- @item system control instructions
- @command{ld} finds all @code{ldc.w, stc.w} 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{@@}@var{aa}:32,ccr} into
- @samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in
- the top page of memory).
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifclear GENERIC
- @ifset Renesas
- @c This stuff is pointless to say unless you're especially concerned
- @c with Renesas chips; don't enable it for generic case, please.
- @node Renesas
- @chapter @command{ld} and Other Renesas Chips
- @command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
- H8/500, and SH chips. No special features, commands, or command-line
- options are required for these chips.
- @end ifset
- @end ifclear
- @ifset ARM
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @ifset M68HC11
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node M68HC11/68HC12
- @section @command{ld} and the Motorola 68HC11 and 68HC12 families
- @cindex M68HC11 and 68HC12 support
- @subsection Linker Relaxation
- For the Motorola 68HC11, @command{ld} can perform these global
- optimizations when you specify the @samp{--relax} command-line option.
- @table @emph
- @cindex relaxing on M68HC11
- @item relaxing address modes
- @command{ld} finds all @code{jsr} and @code{jmp} instructions whose
- targets are within eight bits, and turns them into eight-bit
- program-counter relative @code{bsr} and @code{bra} instructions,
- respectively.
- @command{ld} 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).
- @item relaxing gcc instruction group
- When @command{gcc} is called with @option{-mrelax}, it can emit group
- of instructions that the linker can optimize to use a 68HC11 direct
- addressing mode. These instructions consists of @code{bclr} or
- @code{bset} instructions.
- @end table
- @subsection Trampoline Generation
- @cindex trampoline generation on M68HC11
- @cindex trampoline generation on M68HC12
- For 68HC11 and 68HC12, @command{ld} can generate trampoline code to
- call a far function using a normal @code{jsr} 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.
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @node ARM
- @section @command{ld} and the ARM family
- @cindex ARM interworking support
- @kindex --support-old-code
- For the ARM, @command{ld} 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} 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} 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.
- @cindex thumb entry point
- @cindex entry point, thumb
- @kindex --thumb-entry=@var{entry}
- The @samp{--thumb-entry} switch is a duplicate of the generic
- @samp{--entry} 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.
- @cindex PE import table prefixing
- @kindex --use-nul-prefixed-import-tables
- The @samp{--use-nul-prefixed-import-tables} 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.
- @cindex BE8
- @kindex --be8
- The @samp{--be8} switch instructs @command{ld} to generate BE8 format
- executables. This option is only valid when linking big-endian
- objects - ie ones which have been assembled with the @option{-EB}
- option. The resulting image will contain big-endian data and
- little-endian code.
- @cindex TARGET1
- @kindex --target1-rel
- @kindex --target1-abs
- The @samp{R_ARM_TARGET1} relocation is typically used for entries in the
- @samp{.init_array} section. It is interpreted as either @samp{R_ARM_REL32}
- or @samp{R_ARM_ABS32}, depending on the target. The @samp{--target1-rel}
- and @samp{--target1-abs} switches override the default.
- @cindex TARGET2
- @kindex --target2=@var{type}
- The @samp{--target2=type} switch overrides the default definition of the
- @samp{R_ARM_TARGET2} relocation. Valid values for @samp{type}, their
- meanings, and target defaults are as follows:
- @table @samp
- @item rel
- @samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi)
- @item abs
- @samp{R_ARM_ABS32}
- @item got-rel
- @samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd)
- @end table
- @cindex FIX_V4BX
- @kindex --fix-v4bx
- The @samp{R_ARM_V4BX} 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.
- In the latter case, the switch @option{--fix-v4bx} must be passed to the
- linker, which causes v4t @code{BX rM} instructions to be rewritten as
- @code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction.
- In the former case, the switch should not be used, and @samp{R_ARM_V4BX}
- relocations are ignored.
- @cindex FIX_V4BX_INTERWORKING
- @kindex --fix-v4bx-interworking
- Replace @code{BX rM} instructions identified by @samp{R_ARM_V4BX}
- relocations with a branch to the following veneer:
- @smallexample
- TST rM, #1
- MOVEQ PC, rM
- BX Rn
- @end smallexample
- 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.
- @cindex USE_BLX
- @kindex --use-blx
- The @samp{--use-blx} 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.
- @cindex VFP11_DENORM_FIX
- @kindex --vfp11-denorm-fix
- The @samp{--vfp11-denorm-fix} 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.
- 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.
- If you know you are using buggy VFP11 hardware, you can
- enable this workaround by specifying the linker option
- @samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar
- mode only, or @samp{--vfp-denorm-fix=vector} if you are using
- vector mode (the latter also works for scalar code). The default is
- @samp{--vfp-denorm-fix=none}.
- 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.
- @cindex ARM1176 erratum workaround
- @kindex --fix-arm1176
- @kindex --no-fix-arm1176
- The @samp{--fix-arm1176} 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}.
- 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/.
- @cindex STM32L4xx erratum workaround
- @kindex --fix-stm32l4xx-629360
- The @samp{--fix-stm32l4xx-629360} 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.
- The bug can be avoided by splitting memory accesses into the
- necessary chunks to keep bus reads below 8 words.
- The workaround is not enabled by default, this is equivalent to use
- @samp{--fix-stm32l4xx-629360=none}. If you know you are using buggy
- STM32L4xx hardware, you can enable the workaround by specifying the
- linker option @samp{--fix-stm32l4xx-629360}, or the equivalent
- @samp{--fix-stm32l4xx-629360=default}.
- 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.
- The workaround does not always preserve the memory access order for
- the LDMDB instruction, when the instruction loads the PC.
- 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.
- The workaround is not able to replace problematic instructions with a
- PC-relative branch instruction if the @samp{.text} 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.
- @cindex NO_ENUM_SIZE_WARNING
- @kindex --no-enum-size-warning
- The @option{--no-enum-size-warning} 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.
- @cindex NO_WCHAR_SIZE_WARNING
- @kindex --no-wchar-size-warning
- The @option{--no-wchar-size-warning} switch prevents the linker from
- warning when linking object files that specify incompatible EABI
- @code{wchar_t} size attributes. For example, with this switch enabled,
- linking of an object file using 32-bit @code{wchar_t} values with another
- using 16-bit @code{wchar_t} values will not be diagnosed.
- @cindex PIC_VENEER
- @kindex --pic-veneer
- The @samp{--pic-veneer} 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} is used to generate relocatable binaries.
- @cindex STUB_GROUP_SIZE
- @kindex --stub-group-size=@var{N}
- 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 @option{--stub-group-size=N}.
- 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.
- The value of @samp{N}, the parameter to the
- @option{--stub-group-size=} 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} 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} greater than 1 (or smaller than -1) tells the
- linker that a single group of stubs can service at most @samp{N} bytes
- from the input sections.
- The default, if @option{--stub-group-size=} is not specified, is
- @samp{N = +1}.
- Farcalls stubs insertion is fully supported for the ARM-EABI target
- only, because it relies on object files properties not present
- otherwise.
- @cindex Cortex-A8 erratum workaround
- @kindex --fix-cortex-a8
- @kindex --no-fix-cortex-a8
- The @samp{--fix-cortex-a8} 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}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
- The erratum only affects Thumb-2 code. Please contact ARM for further details.
- @cindex Cortex-A53 erratum 835769 workaround
- @kindex --fix-cortex-a53-835769
- @kindex --no-fix-cortex-a53-835769
- The @samp{--fix-cortex-a53-835769} 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}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a53-835769}.
- Please contact ARM for further details.
- @kindex --merge-exidx-entries
- @kindex --no-merge-exidx-entries
- @cindex Merging exidx entries
- The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
- @kindex --long-plt
- @cindex 32-bit PLT entries
- The @samp{--long-plt} 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.
- @kindex --no-apply-dynamic-relocs
- @cindex AArch64 rela addend
- The @samp{--no-apply-dynamic-relocs} option makes AArch64 linker do not apply
- link-time values for dynamic relocations.
- @cindex Placement of SG veneers
- All SG veneers are placed in the special output section @code{.gnu.sgstubs}.
- Its start address must be set, either with the command-line option
- @samp{--section-start} or in a linker script, to indicate where to place these
- veneers in memory.
- @kindex --cmse-implib
- @cindex Secure gateway import library
- The @samp{--cmse-implib} option requests that the import libraries
- specified by the @samp{--out-implib} and @samp{--in-implib} options are
- secure gateway import libraries, suitable for linking a non-secure
- executable against secure code as per ARMv8-M Security Extensions.
- @kindex --in-implib=@var{file}
- @cindex Input import library
- The @samp{--in-implib=file} 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} is given but new symbols have been introduced
- in the executable that should be listed in its import library. Otherwise, if
- @samp{--out-implib} 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} is
- specified.
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset HPPA
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node HPPA ELF32
- @section @command{ld} and HPPA 32-bit ELF Support
- @cindex HPPA multiple sub-space stubs
- @kindex --multi-subspace
- When generating a shared library, @command{ld} will by default generate
- import stubs suitable for use with a single sub-space application.
- The @samp{--multi-subspace} switch causes @command{ld} to generate export
- stubs, and different (larger) import stubs suitable for use with
- multiple sub-spaces.
- @cindex HPPA stub grouping
- @kindex --stub-group-size=@var{N}
- Long branch stubs and import/export stubs are placed by @command{ld} in
- stub sections located between groups of input sections.
- @samp{--stub-group-size} 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} chooses this scheme, ensuring that
- branches to stubs always use a negative offset. Two special values of
- @samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
- @command{ld} 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} respectively.
- Note that @samp{--stub-group-size} 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.
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset M68K
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node M68K
- @section @command{ld} and the Motorola 68K family
- @cindex Motorola 68K GOT generation
- @kindex --got=@var{type}
- The @samp{--got=@var{type}} option lets you choose the GOT generation scheme.
- The choices are @samp{single}, @samp{negative}, @samp{multigot} and
- @samp{target}. When @samp{target} is selected the linker chooses
- the default GOT generation scheme for the current target.
- @samp{single} tells the linker to generate a single GOT with
- entries only at non-negative offsets.
- @samp{negative} instructs the linker to generate a single GOT with
- entries at both negative and positive offsets. Not all environments
- support such GOTs.
- @samp{multigot} 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.
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset MIPS
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node MIPS
- @section @command{ld} and the MIPS family
- @cindex MIPS microMIPS instruction choice selection
- @kindex --insn32
- @kindex --no-insn32
- The @samp{--insn32} and @samp{--no-insn32} 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} is
- used, then the linker only uses 32-bit instruction encodings. By default
- or if @samp{--no-insn32} is used, all instruction encodings are used,
- including 16-bit ones where possible.
- @cindex MIPS branch relocation check control
- @kindex --ignore-branch-isa
- @kindex --no-ignore-branch-isa
- The @samp{--ignore-branch-isa} and @samp{--no-ignore-branch-isa} options
- control branch relocation checks for invalid ISA mode transitions. If
- @samp{--ignore-branch-isa} 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} instructions which meet
- relaxation conditions and are converted to equivalent @code{JALX}
- instructions as the associated relocation is calculated. By default
- or if @samp{--no-ignore-branch-isa} is used a check is made causing
- the loss of an ISA mode transition to produce an error.
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset MMIX
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node MMIX
- @section @code{ld} and MMIX
- For MMIX, there is a choice of generating @code{ELF} object files or
- @code{mmo} object files when linking. The simulator @code{mmix}
- understands the @code{mmo} format. The binutils @code{objcopy} utility
- can translate between the two formats.
- There is one special section, the @samp{.MMIX.reg_contents} 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} section corresponds to the first allocated
- global register multiplied by 8. Register @code{$255} is not included in
- this section; it is always set to the program entry, which is at the
- symbol @code{Main} for @code{mmo} files.
- Global symbols with the prefix @code{__.MMIX.start.}, for example
- @code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special.
- The default linker script uses these to set the default start address
- of a section.
- Initial and trailing multiples of zero-valued 32-bit words in a section,
- are left out from an mmo file.
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset MSP430
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node MSP430
- @section @code{ld} and MSP430
- For the MSP430 it is possible to select the MPU architecture. The flag @samp{-m [mpu type]}
- will select an appropriate linker script for selected MPU type. (To get a list of known MPUs
- just pass @samp{-m help} option to the linker).
- @cindex MSP430 extra sections
- The linker will recognize some extra sections which are MSP430 specific:
- @table @code
- @item @samp{.vectors}
- Defines a portion of ROM where interrupt vectors located.
- @item @samp{.bootloader}
- Defines the bootloader portion of the ROM (if applicable). Any code
- in this section will be uploaded to the MPU.
- @item @samp{.infomem}
- Defines an information memory section (if applicable). Any code in
- this section will be uploaded to the MPU.
- @item @samp{.infomemnobits}
- This is the same as the @samp{.infomem} section except that any code
- in this section will not be uploaded to the MPU.
- @item @samp{.noinit}
- Denotes a portion of RAM located above @samp{.bss} section.
- The last two sections are used by gcc.
- @end table
- @table @option
- @cindex MSP430 Options
- @kindex --code-region
- @item --code-region=[either,lower,upper,none]
- 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.
- @kindex --data-region
- @item --data-region=[either,lower,upper,none]
- 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.
- @kindex --disable-sec-transformation
- @item --disable-sec-transformation
- Prevent the transformation of sections as specified by the @code{--code-region}
- and @code{--data-region} 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.
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset NDS32
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node NDS32
- @section @code{ld} and NDS32
- @kindex relaxing on NDS32
- For NDS32, there are some options to select relaxation behavior. The linker
- relaxes objects according to these options.
- @table @code
- @item @samp{--m[no-]fp-as-gp}
- Disable/enable fp-as-gp relaxation.
- @item @samp{--mexport-symbols=FILE}
- Exporting symbols and their address into FILE as linker script.
- @item @samp{--m[no-]ex9}
- Disable/enable link-time EX9 relaxation.
- @item @samp{--mexport-ex9=FILE}
- Export the EX9 table after linking.
- @item @samp{--mimport-ex9=FILE}
- Import the Ex9 table for EX9 relaxation.
- @item @samp{--mupdate-ex9}
- Update the existing EX9 table.
- @item @samp{--mex9-limit=NUM}
- Maximum number of entries in the ex9 table.
- @item @samp{--mex9-loop-aware}
- Avoid generating the EX9 instruction inside the loop.
- @item @samp{--m[no-]ifc}
- Disable/enable the link-time IFC optimization.
- @item @samp{--mifc-loop-aware}
- Avoid generating the IFC instruction inside the loop.
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset NIOSII
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node Nios II
- @section @command{ld} and the Altera Nios II
- @cindex Nios II call relaxation
- @kindex --relax on Nios II
- 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 @command{ld} giving
- @samp{relocation truncated to fit} errors with very large programs.
- The command-line option @option{--relax} enables the generation of
- trampolines that can access the entire 32-bit address space for calls
- outside the normal @code{call} and @code{jmpi} 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.
- The @option{--relax} option is enabled by default unless @option{-r}
- is also specified. You can disable trampoline generation by using the
- @option{--no-relax} linker option. You can also disable this optimization
- locally by using the @samp{set .noat} directive in assembly-language
- source files, as the linker-inserted trampolines use the @code{at}
- register as a temporary.
- Note that the linker @option{--relax} option is independent of assembler
- relaxation options, and that using the GNU assembler's @option{-relax-all}
- option interferes with the linker's more selective call instruction relaxation.
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset POWERPC
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node PowerPC ELF32
- @section @command{ld} and PowerPC 32-bit ELF Support
- @cindex PowerPC long branches
- @kindex --relax on PowerPC
- Branches on PowerPC processors are limited to a signed 26-bit
- displacement, which may result in @command{ld} giving
- @samp{relocation truncated to fit} errors with very large programs.
- @samp{--relax} 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} and
- @samp{--relax} 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.
- @cindex PowerPC ELF32 options
- @table @option
- @cindex PowerPC PLT
- @kindex --bss-plt
- @item --bss-plt
- Current PowerPC GCC accepts a @samp{-msecure-plt} 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
- @command{ld} 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{--bss-plt} forces the old
- BSS PLT (and GOT layout) which can give slightly better performance.
- @kindex --secure-plt
- @item --secure-plt
- @command{ld} will use the new PLT and GOT layout if it is linking new
- @samp{-fpic} or @samp{-fPIC} 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.
- @cindex PowerPC GOT
- @kindex --sdata-got
- @item --sdata-got
- 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} must change because the new secure PLT is an initialized
- section while the old PLT is uninitialized. The reason for the
- @code{.got} change is more subtle: The new placement allows
- @code{.got} to be read-only in applications linked with
- @samp{-z relro -z now}. However, this placement means that
- @code{.sdata} cannot always be used in shared libraries, because the
- PowerPC ABI accesses @code{.sdata} in shared libraries from the GOT
- pointer. @samp{--sdata-got} forces the old GOT placement. PowerPC
- GCC doesn't use @code{.sdata} in shared libraries, so this option is
- really only useful for other compilers that may do so.
- @cindex PowerPC stub symbols
- @kindex --emit-stub-syms
- @item --emit-stub-syms
- This option causes @command{ld} to label linker stubs with a local
- symbol that encodes the stub type and destination.
- @cindex PowerPC TLS optimization
- @kindex --no-tls-optimize
- @item --no-tls-optimize
- PowerPC @command{ld} normally performs some optimization of code
- sequences used to access Thread-Local Storage. Use this option to
- disable the optimization.
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset POWERPC64
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node PowerPC64 ELF64
- @section @command{ld} and PowerPC64 64-bit ELF Support
- @cindex PowerPC64 ELF64 options
- @table @option
- @cindex PowerPC64 stub grouping
- @kindex --stub-group-size
- @item --stub-group-size
- Long branch stubs, PLT call stubs and TOC adjusting stubs are placed
- by @command{ld} in stub sections located between groups of input sections.
- @samp{--stub-group-size} 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} chooses this scheme, ensuring that
- branches to stubs always use a negative offset. Two special values of
- @samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
- @command{ld} 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} respectively.
- Note that @samp{--stub-group-size} 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.
- @cindex PowerPC64 stub symbols
- @kindex --emit-stub-syms
- @item --emit-stub-syms
- This option causes @command{ld} to label linker stubs with a local
- symbol that encodes the stub type and destination.
- @cindex PowerPC64 dot symbols
- @kindex --dotsyms
- @kindex --no-dotsyms
- @item --dotsyms
- @itemx --no-dotsyms
- These two options control how @command{ld} 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{.}). To
- properly version a function @samp{foo}, the version script thus needs
- to control both @samp{foo} and @samp{.foo}. The option
- @samp{--dotsyms}, on by default, automatically adds the required
- dot-prefixed patterns. Use @samp{--no-dotsyms} to disable this
- feature.
- @cindex PowerPC64 register save/restore functions
- @kindex --save-restore-funcs
- @kindex --no-save-restore-funcs
- @item --save-restore-funcs
- @itemx --no-save-restore-funcs
- These two options control whether PowerPC64 @command{ld} automatically
- provides out-of-line register save and restore functions used by
- @samp{-Os} code. The default is to provide any such referenced
- function for a normal final link, and to not do so for a relocatable
- link.
- @cindex PowerPC64 TLS optimization
- @kindex --no-tls-optimize
- @item --no-tls-optimize
- PowerPC64 @command{ld} normally performs some optimization of code
- sequences used to access Thread-Local Storage. Use this option to
- disable the optimization.
- @cindex PowerPC64 __tls_get_addr optimization
- @kindex --tls-get-addr-optimize
- @kindex --no-tls-get-addr-optimize
- @kindex --tls-get-addr-regsave
- @kindex --no-tls-get-addr-regsave
- @item --tls-get-addr-optimize
- @itemx --no-tls-get-addr-optimize
- These options control how PowerPC64 @command{ld} 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} 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 @option{--tls-get-addr-optimize} 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.
- @option{--tls-get-addr-regsave} 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.
- @option{--no-tls-get-addr-regsave} disables generation of the
- register saves.
- @cindex PowerPC64 OPD optimization
- @kindex --no-opd-optimize
- @item --no-opd-optimize
- PowerPC64 @command{ld} normally removes @code{.opd} section entries
- corresponding to deleted link-once functions, or functions removed by
- the action of @samp{--gc-sections} or linker script @code{/DISCARD/}.
- Use this option to disable @code{.opd} optimization.
- @cindex PowerPC64 OPD spacing
- @kindex --non-overlapping-opd
- @item --non-overlapping-opd
- Some PowerPC64 compilers have an option to generate compressed
- @code{.opd} 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.
- @cindex PowerPC64 TOC optimization
- @kindex --no-toc-optimize
- @item --no-toc-optimize
- PowerPC64 @command{ld} normally removes unused @code{.toc} 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.
- @cindex PowerPC64 inline PLT call optimization
- @kindex --no-inline-optimize
- @item --no-inline-optimize
- PowerPC64 @command{ld} normally replaces inline PLT call sequences
- marked with @code{R_PPC64_PLTSEQ}, @code{R_PPC64_PLTCALL},
- @code{R_PPC64_PLT16_HA} and @code{R_PPC64_PLT16_LO_DS} relocations by
- a number of @code{nop}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.
- @cindex PowerPC64 multi-TOC
- @kindex --no-multi-toc
- @item --no-multi-toc
- If given any toc option besides @code{-mcmodel=medium} or
- @code{-mcmodel=large}, 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 @command{ld} 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. @command{ld} does not split apart input sections, so cannot
- help if a single input file has a @code{.toc} section that exceeds
- 64K, most likely from linking multiple files with @command{ld -r}.
- Use this option to turn off this feature.
- @cindex PowerPC64 TOC sorting
- @kindex --no-toc-sort
- @item --no-toc-sort
- By default, @command{ld} sorts TOC sections so that those whose file
- happens to have a section called @code{.init} or @code{.fini} are
- placed first, followed by TOC sections referenced by code generated
- with PowerPC64 gcc's @code{-mcmodel=small}, and lastly TOC sections
- referenced only by code generated with PowerPC64 gcc's
- @code{-mcmodel=medium} or @code{-mcmodel=large} options. Doing this
- results in better TOC grouping for multi-TOC. Use this option to turn
- off this feature.
- @cindex PowerPC64 PLT stub alignment
- @kindex --plt-align
- @kindex --no-plt-align
- @item --plt-align
- @itemx --no-plt-align
- 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=}. 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.
- @cindex PowerPC64 PLT call stub static chain
- @kindex --plt-static-chain
- @kindex --no-plt-static-chain
- @item --plt-static-chain
- @itemx --no-plt-static-chain
- Use these options to control whether PLT call stubs load the static
- chain pointer (r11). @code{ld} defaults to not loading the static
- chain since there is never any need to do so on a PLT call.
- @cindex PowerPC64 PLT call stub thread safety
- @kindex --plt-thread-safe
- @kindex --no-plt-thread-safe
- @item --plt-thread-safe
- @itemx --no-plt-thread-safe
- 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}
- 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.
- @cindex PowerPC64 ELFv2 PLT localentry optimization
- @kindex --plt-localentry
- @kindex --no-plt-localentry
- @item --plt-localentry
- @itemx --no-localentry
- 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. @option{--no-plt-localentry} is the default.
- @cindex PowerPC64 Power10 stubs
- @kindex --power10-stubs
- @kindex --no-power10-stubs
- @item --power10-stubs
- @itemx --no-power10-stubs
- When PowerPC64 @command{ld} 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} PLT calls where @code{r2} is not known. The
- power10 notoc stubs are smaller and faster, so are preferred for
- power10. @option{--power10-stubs} and @option{--no-power10-stubs}
- allow you to override the linker's selection of stub instructions.
- @option{--power10-stubs=auto} allows the user to select the default
- auto mode.
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset S/390
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node S/390 ELF
- @section @command{ld} and S/390 ELF Support
- @cindex S/390 ELF options
- @table @option
- @cindex S/390
- @kindex --s390-pgste
- @item --s390-pgste
- This option marks the result file with a @code{PT_S390_PGSTE}
- segment. The Linux kernel is supposed to allocate 4k page tables for
- binaries marked that way.
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset SPU
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node SPU ELF
- @section @command{ld} and SPU ELF Support
- @cindex SPU ELF options
- @table @option
- @cindex SPU plugins
- @kindex --plugin
- @item --plugin
- This option marks an executable as a PIC plugin module.
- @cindex SPU overlays
- @kindex --no-overlays
- @item --no-overlays
- Normally, @command{ld} recognizes calls to functions within overlay
- regions, and redirects such calls to an overlay manager via a stub.
- @command{ld} also provides a built-in overlay manager. This option
- turns off all this special overlay handling.
- @cindex SPU overlay stub symbols
- @kindex --emit-stub-syms
- @item --emit-stub-syms
- This option causes @command{ld} to label overlay stubs with a local
- symbol that encodes the stub type and destination.
- @cindex SPU extra overlay stubs
- @kindex --extra-overlay-stubs
- @item --extra-overlay-stubs
- This option causes @command{ld} to add overlay call stubs on all
- function calls out of overlay regions. Normally stubs are not added
- on calls to non-overlay regions.
- @cindex SPU local store size
- @kindex --local-store=lo:hi
- @item --local-store=lo:hi
- @command{ld} 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 @option{--local-store=0:0}.
- @cindex SPU
- @kindex --stack-analysis
- @item --stack-analysis
- 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,
- @command{ld} will provide an estimate of maximum stack usage.
- @command{ld} 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.
- @cindex SPU
- @kindex --emit-stack-syms
- @item --emit-stack-syms
- This option, if given along with @option{--stack-analysis} will result
- in @command{ld} emitting stack sizing symbols for each function.
- These take the form @code{__stack_<function_name>} for global
- functions, and @code{__stack_<number>_<function_name>} for static
- functions. @code{<number>} 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}, binding
- @code{STB_LOCAL}, and section @code{SHN_ABS}.
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset TICOFF
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node TI COFF
- @section @command{ld}'s Support for Various TI COFF Versions
- @cindex TI COFF versions
- @kindex --format=@var{version}
- The @samp{--format} 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; @command{ld} will read any version or byte order, but the output
- header format depends on the default specified by the specific target.
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset WIN32
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node WIN32
- @section @command{ld} and WIN32 (cygwin/mingw)
- This section describes some of the win32 specific @command{ld} issues.
- See @ref{Options,,Command-line Options} for detailed description of the
- command-line options mentioned here.
- @table @emph
- @cindex import libraries
- @item import libraries
- 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 @command{ld} have specific
- support for creating such libraries provided with the
- @samp{--out-implib} command-line option.
- @item exporting DLL symbols
- @cindex exporting DLL symbols
- The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
- @table @emph
- @item using auto-export functionality
- @cindex using auto-export functionality
- By default @command{ld} exports symbols with the auto-export functionality,
- which is controlled by the following command-line options:
- @itemize
- @item --export-all-symbols [This is the default]
- @item --exclude-symbols
- @item --exclude-libs
- @item --exclude-modules-for-implib
- @item --version-script
- @end itemize
- When auto-export is in operation, @command{ld} 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} option can be used in order to see the
- final list of exported symbols with all exclusions taken into effect.
- If @samp{--export-all-symbols} is not given explicitly on the
- command line, then the default auto-export behavior will be @emph{disabled}
- if either of the following are true:
- @itemize
- @item A DEF file is used.
- @item Any symbol in any object file was marked with the __declspec(dllexport) attribute.
- @end itemize
- @item using a DEF file
- @cindex using a DEF file
- 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} and is added as any other object file to the linker's
- command line. The file's name must end in @samp{.def} or @samp{.DEF}.
- @example
- gcc -o <output> <objectfiles> <dll name>.def
- @end example
- Using a DEF file turns off the normal auto-export behavior, unless the
- @samp{--export-all-symbols} option is also used.
- Here is an example of a DEF file for a shared library called @samp{xyz.dll}:
- @example
- LIBRARY "xyz.dll" BASE=0x20000000
- EXPORTS
- foo
- bar
- _bar = bar
- another_foo = abc.dll.afoo
- var1 DATA
- doo = foo == foo2
- eoo DATA == var1
- @end example
- This example defines a DLL with a non-default base address and seven
- symbols in the export table. The third exported symbol @code{_bar} is an
- alias for the second. The fourth symbol, @code{another_foo} is resolved
- by "forwarding" to another module and treating it as an alias for
- @code{afoo} exported from the DLL @samp{abc.dll}. The final symbol
- @code{var1} is declared to be a data object. The @samp{doo} symbol in
- export library is an alias of @samp{foo}, which gets the string name
- in export table @samp{foo2}. The @samp{eoo} symbol is an data export
- symbol, which gets in export table the name @samp{var1}.
- The optional @code{LIBRARY <name>} command indicates the @emph{internal}
- name of the output DLL. If @samp{<name>} does not include a suffix,
- the default library suffix, @samp{.DLL} is appended.
- When the .DEF file is used to build an application, rather than a
- library, the @code{NAME <name>} command should be used instead of
- @code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
- executable suffix, @samp{.EXE} is appended.
- With either @code{LIBRARY <name>} or @code{NAME <name>} the optional
- specification @code{BASE = <number>} may be used to specify a
- non-default base address for the image.
- If neither @code{LIBRARY <name>} nor @code{NAME <name>} is specified,
- or they specify an empty string, the internal name is the same as the
- filename specified on the command line.
- The complete specification of an export symbol is:
- @example
- EXPORTS
- ( ( ( <name1> [ = <name2> ] )
- | ( <name1> = <module-name> . <external-name>))
- [ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
- @end example
- Declares @samp{<name1>} as an exported symbol from the DLL, or declares
- @samp{<name1>} as an exported alias for @samp{<name2>}; or declares
- @samp{<name1>} as a "forward" alias for the symbol
- @samp{<external-name>} in the DLL @samp{<module-name>}.
- Optionally, the symbol may be exported by the specified ordinal
- @samp{<integer>} alias. The optional @samp{<name3>} is the to be used
- string in import/export table for the symbol.
- The optional keywords that follow the declaration indicate:
- @code{NONAME}: 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} is also specified.
- @code{DATA}: The symbol is a variable or object, rather than a function.
- The import lib will export only an indirect reference to @code{foo} as
- the symbol @code{_imp__foo} (ie, @code{foo} must be resolved as
- @code{*_imp__foo}).
- @code{CONSTANT}: Like @code{DATA}, but put the undecorated @code{foo} as
- well as @code{_imp__foo} 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} attribute and also fails to explicitly add the
- extra indirection that the use of the attribute enforces, the
- application will behave unexpectedly.
- @code{PRIVATE}: 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}
- API at runtime or by using the GNU ld extension of linking directly to
- the DLL without an import library.
- See ld/deffilep.y in the binutils sources for the full specification of
- other DEF file statements
- @cindex creating a DEF file
- While linking a shared dll, @command{ld} is able to create a DEF file
- with the @samp{--output-def <file>} command-line option.
- @item Using decorations
- @cindex Using decorations
- 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:
- @example
- __declspec(dllexport) int a_variable
- __declspec(dllexport) void a_function(int with_args)
- @end example
- 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} option is also used.
- Note that object files that wish to access these symbols must @emph{not}
- decorate them with dllexport. Instead, they should use dllimport,
- instead:
- @example
- __declspec(dllimport) int a_variable
- __declspec(dllimport) void a_function(int with_args)
- @end example
- 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} and @samp{automatic data imports} for more
- information.
- @end table
- @cindex automatic data imports
- @item automatic data imports
- 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}
- command-line option, although it is enabled by default on cygwin/mingw.
- The @samp{--enable-auto-import} option itself now serves mainly to
- suppress any warnings that are ordinarily emitted when linked objects
- trigger the feature's use.
- auto-import of variables does not always work flawlessly without
- additional assistance. Sometimes, you will see this message
- "variable '<var>' can't be auto-imported. Please read the
- documentation for ld's @code{--enable-auto-import} for details."
- The @samp{--enable-auto-import} documentation explains why this error
- occurs, and several methods that can be used to overcome this difficulty.
- One of these methods is the @emph{runtime pseudo-relocs} feature, described
- below.
- @cindex runtime pseudo-relocation
- For complex variables imported from DLLs (such as structs or classes),
- object files typically contain a base address for the variable and an
- offset (@emph{addend}) 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.
- The @samp{--enable-runtime-pseudo-relocs} 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.
- @samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly
- enabled as needed.
- @cindex direct linking to a dll
- @item direct linking to a dll
- The cygwin/mingw ports of @command{ld} 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 @command{ld} 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.
- Linking directly to a dll uses no extra command-line switches other than
- @samp{-L} and @samp{-l}, because @command{ld} 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.
- For instance, when ld is called with the argument @samp{-lxxx} it will attempt
- to find, in the first directory of its search path,
- @example
- libxxx.dll.a
- xxx.dll.a
- libxxx.a
- xxx.lib
- libxxx.lib
- cygxxx.dll (*)
- libxxx.dll
- xxx.dll
- @end example
- before moving on to the next directory in the search path.
- (*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll},
- where @samp{<prefix>} is set by the @command{ld} option
- @samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec
- file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for
- @samp{cygxxx.dll}.
- Other win32-based unix environments, such as mingw or pw32, may use other
- @samp{<prefix>}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.
- The generic cygwin/mingw path layout uses a @samp{bin} directory for
- applications and dll's and a @samp{lib} directory for the import
- libraries (using cygwin nomenclature):
- @example
- bin/
- cygxxx.dll
- lib/
- libxxx.dll.a (in case of dll's)
- libxxx.a (in case of static archive)
- @end example
- Linking directly to a dll without using the import library can be
- done two ways:
- 1. Use the dll directly by adding the @samp{bin} path to the link line
- @example
- gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
- @end example
- However, as the dll's often have version numbers appended to their names
- (@samp{cygncurses-5.dll}) this will often fail, unless one specifies
- @samp{-L../bin -lncurses-5} to include the version. Import libs are generally
- not versioned, and do not have this difficulty.
- 2. Create a symbolic link from the dll to a file in the @samp{lib}
- 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.
- @example
- ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
- @end example
- Then you can link without any make environment changes.
- @example
- gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
- @end example
- This technique also avoids the version number problems, because the following is
- perfectly legal
- @example
- bin/
- cygxxx-5.dll
- lib/
- libxxx.dll.a -> ../bin/cygxxx-5.dll
- @end example
- 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} is used.
- Given the improvements in speed and memory usage, one might justifiably
- wonder why import libraries are used at all. There are three reasons:
- 1. Until recently, the link-directly-to-dll functionality did @emph{not}
- work with auto-imported data.
- 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.
- 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.
- 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.
- @item symbol aliasing
- @table @emph
- @item adding additional names
- Sometimes, it is useful to export symbols with additional names.
- A symbol @samp{foo} will be exported as @samp{foo}, but it can also be
- exported as @samp{_foo} 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:
- @example
- LIBRARY "xyz.dll" BASE=0x61000000
- EXPORTS
- foo
- _foo = foo
- @end example
- The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}.
- Another method for creating a symbol alias is to create it in the
- source code using the "weak" attribute:
- @example
- void foo () @{ /* Do something. */; @}
- void _foo () __attribute__ ((weak, alias ("foo")));
- @end example
- See the gcc manual for more information about attributes and weak
- symbols.
- @item renaming symbols
- Sometimes it is useful to rename exports. For instance, the cygwin
- kernel does this regularly. A symbol @samp{_foo} can be exported as
- @samp{foo} but not as @samp{_foo} by using special directives in the
- DEF file. (This will also affect the import library, if it is
- created). In the following example:
- @example
- LIBRARY "xyz.dll" BASE=0x61000000
- EXPORTS
- _foo = foo
- @end example
- The line @samp{_foo = foo} maps the exported symbol @samp{foo} to
- @samp{_foo}.
- @end table
- Note: using a DEF file disables the default auto-export behavior,
- unless the @samp{--export-all-symbols} command-line option is used.
- If, however, you are trying to rename symbols, then you should list
- @emph{all} desired exports in the DEF file, including the symbols
- that are not being renamed, and do @emph{not} use the
- @samp{--export-all-symbols} option. If you list only the
- renamed symbols in the DEF file, and use @samp{--export-all-symbols}
- to handle the other symbols, then the both the new names @emph{and}
- 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.
- @cindex weak externals
- @item weak externals
- 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:
- @itemize
- @item Definition is searched for in objects and libraries, historically
- called lazy externals.
- @item Definition is searched for only in other objects, not in libraries.
- This form is not presently implemented.
- @item No search; the symbol is an alias. This form is not presently
- implemented.
- @end itemize
- 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.
- @cindex aligned common symbols
- @item aligned common symbols
- 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} section, which are recognized
- by @command{ld} 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.
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifset XTENSA
- @ifclear GENERIC
- @raisesections
- @end ifclear
- @node Xtensa
- @section @code{ld} and Xtensa Processors
- @cindex Xtensa processors
- The default @command{ld} behavior for Xtensa processors is to interpret
- @code{SECTIONS} 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:
- @smallexample
- SECTIONS
- @{
- .text : @{
- *(.literal .text)
- @}
- @}
- @end smallexample
- @noindent
- @command{ld} may interleave some of the @code{.literal}
- and @code{.text} 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} sections from an initial
- group of files followed by the @code{.text} sections of that group of
- files. Then, the @code{.literal} sections from the rest of the files
- and the @code{.text} sections from the rest of the files would follow.
- @cindex @option{--relax} on Xtensa
- @cindex relaxing on Xtensa
- Relaxation is enabled by default for the Xtensa version of @command{ld} 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} 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} instructions. The second optimization is to remove
- unnecessary overhead from assembler-generated ``longcall'' sequences of
- @code{L32R}/@code{CALLX@var{n}} when the target functions are within
- range of direct @code{CALL@var{n}} instructions.
- 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}}
- instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R}
- instruction, and remove the literal referenced by the @code{L32R}
- instruction if it is not used for anything else. Removing the
- @code{L32R} 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}
- instruction that was removed. If code size is more important than
- performance, the @option{--size-opt} 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.
- The following Xtensa-specific command-line options can be used to
- control the linker:
- @cindex Xtensa options
- @table @option
- @item --size-opt
- 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.
- @item --abi-windowed
- @itemx --abi-call0
- 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} 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.
- @end table
- @ifclear GENERIC
- @lowersections
- @end ifclear
- @end ifset
- @ifclear SingleFormat
- @node BFD
- @chapter BFD
- @cindex back end
- @cindex object file management
- @cindex object formats available
- @kindex objdump -i
- 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}
- (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
- list all the formats available for your configuration.
- @cindex BFD requirements
- @cindex requirements for BFD
- 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.
- 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. @xref{BFD information loss}.
- @menu
- * BFD outline:: How it works: an outline of BFD
- @end menu
- @node BFD outline
- @section How It Works: An Outline of BFD
- @cindex opening object files
- @include bfdsumm.texi
- @end ifclear
- @node Reporting Bugs
- @chapter Reporting Bugs
- @cindex bugs in @command{ld}
- @cindex reporting bugs in @command{ld}
- Your bug reports play an essential role in making @command{ld} reliable.
- Reporting a bug may help you by bringing a solution to your problem, or
- it may not. But in any case the principal function of a bug report is
- to help the entire community by making the next version of @command{ld}
- work better. Bug reports are your contribution to the maintenance of
- @command{ld}.
- In order for a bug report to serve its purpose, you must include the
- information that enables us to fix the bug.
- @menu
- * Bug Criteria:: Have you found a bug?
- * Bug Reporting:: How to report bugs
- @end menu
- @node Bug Criteria
- @section Have You Found a Bug?
- @cindex bug criteria
- If you are not sure whether you have found a bug, here are some guidelines:
- @itemize @bullet
- @cindex fatal signal
- @cindex linker crash
- @cindex crash of linker
- @item
- If the linker gets a fatal signal, for any input whatever, that is a
- @command{ld} bug. Reliable linkers never crash.
- @cindex error on valid input
- @item
- If @command{ld} produces an error message for valid input, that is a bug.
- @cindex invalid input
- @item
- If @command{ld} 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.
- @item
- If you are an experienced user of linkers, your suggestions for
- improvement of @command{ld} are welcome in any case.
- @end itemize
- @node Bug Reporting
- @section How to Report Bugs
- @cindex bug reports
- @cindex @command{ld} bugs, reporting
- A number of companies and individuals offer support for @sc{gnu}
- products. If you obtained @command{ld} from a support organization, we
- recommend you contact that organization first.
- You can find contact information for many support companies and
- individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
- distribution.
- @ifset BUGURL
- Otherwise, send bug reports for @command{ld} to
- @value{BUGURL}.
- @end ifset
- The fundamental principle of reporting bugs usefully is this:
- @strong{report all the facts}. If you are not sure whether to state a
- fact or leave it out, state it!
- Often people omit facts because they think they know what causes the
- problem and assume that some details do not matter. Thus, you might
- assume that the name of 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.
- 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.
- 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.
- To enable us to fix the bug, you should include all these things:
- @itemize @bullet
- @item
- The version of @command{ld}. @command{ld} announces it if you start it with
- the @samp{--version} argument.
- Without this, we will not know whether there is any point in looking for
- the bug in the current version of @command{ld}.
- @item
- Any patches you may have applied to the @command{ld} source, including any
- patches made to the @code{BFD} library.
- @item
- The type of machine you are using, and the operating system name and
- version number.
- @item
- What compiler (and its version) was used to compile @command{ld}---e.g.
- ``@code{gcc-2.7}''.
- @item
- 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.
- If we were to try to guess the arguments, we would probably guess wrong
- and then we might not encounter the bug.
- @item
- A complete input 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.
- If the source files were assembled using @code{gas} or compiled using
- @code{gcc}, 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} or @code{gcc} was used to produce the object files. Also say
- how @code{gas} or @code{gcc} were configured.
- @item
- A description of what behavior you observe that you believe is
- incorrect. For example, ``It gets a fatal signal.''
- Of course, if the bug is that @command{ld} gets a fatal signal, then we
- will certainly notice it. But if the bug is incorrect output, we might
- not notice unless it is glaringly wrong. You might as well not give us
- a chance to make a mistake.
- Even if the problem you experience is a fatal signal, you should still
- say so explicitly. Suppose something strange is going on, such as, your
- copy of @command{ld} 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.
- @item
- If you wish to suggest changes to the @command{ld} source, send us context
- diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
- @samp{-p} option. Always send diffs from the old file to the new file.
- If you even discuss something in the @command{ld} source, refer to it by
- context, not by line number.
- The line numbers in our development sources will not match those in your
- sources. Your line numbers would convey no useful information to us.
- @end itemize
- Here are some things that are not necessary:
- @itemize @bullet
- @item
- A description of the envelope of the bug.
- Often people who encounter a bug spend a lot of time investigating
- which changes to the input file will make the bug go away and which
- changes will not affect it.
- This is often time consuming and not very useful, because the way we
- will find the bug is by running a single example under the debugger
- with breakpoints, not by pure deduction from a series of examples.
- We recommend that you save your time for something else.
- Of course, if you can find a simpler example to report @emph{instead}
- of the original one, that is a convenience for us. Errors in the
- output will be easier to spot, running under the debugger will take
- less time, and so on.
- However, simplification is not vital; if you do not want to do this,
- report the bug anyway and send us the entire test case you used.
- @item
- A patch for the bug.
- A patch for the bug does help us if it is a good one. But do not omit
- the necessary information, such as the test case, on the assumption that
- a patch is all we need. We might see problems with your patch and decide
- to fix the problem another way, or we might not understand it at all.
- Sometimes with a program as complicated as @command{ld} it is very hard to
- construct an example that will make the program follow a certain path
- through the code. If you do not send us the example, we will not be
- able to construct one, so we will not be able to verify that the bug is
- fixed.
- And if we cannot understand what bug you are trying to fix, or why your
- patch should be an improvement, we will not install it. A test case will
- help us to understand.
- @item
- A guess about what the bug is or what it depends on.
- Such guesses are usually wrong. Even we cannot guess right about such
- things without first using the debugger to find the facts.
- @end itemize
- @node MRI
- @appendix MRI Compatible Script Files
- @cindex MRI compatibility
- To aid users making the transition to @sc{gnu} @command{ld} from the MRI
- linker, @command{ld} can use MRI compatible linker scripts as an
- alternative to the more general-purpose linker scripting language
- described in @ref{Scripts}. MRI compatible linker scripts have a much
- simpler command set than the scripting language otherwise used with
- @command{ld}. @sc{gnu} @command{ld} supports the most commonly used MRI
- linker commands; these commands are described here.
- In general, MRI scripts aren't of much use with the @code{a.out} object
- file format, since it only has three sections and MRI scripts lack some
- features to make use of them.
- You can specify a file containing an MRI-compatible script using the
- @samp{-c} command-line option.
- 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, @command{ld}
- issues a warning message, but continues processing the script.
- Lines beginning with @samp{*} are comments.
- You can write these commands using all upper-case letters, or all
- lower case; for example, @samp{chip} is the same as @samp{CHIP}.
- The following list shows only the upper-case form of each command.
- @table @code
- @cindex @code{ABSOLUTE} (MRI)
- @item ABSOLUTE @var{secname}
- @itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
- Normally, @command{ld} includes in the output file all sections from all
- the input files. However, in an MRI-compatible script, you can use the
- @code{ABSOLUTE} command to restrict the sections that will be present in
- your output program. If the @code{ABSOLUTE} command is used at all in a
- script, then only the sections named explicitly in @code{ABSOLUTE}
- 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}) to resolve addresses in the output file.
- @cindex @code{ALIAS} (MRI)
- @item ALIAS @var{out-secname}, @var{in-secname}
- Use this command to place the data from input section @var{in-secname}
- in a section called @var{out-secname} in the linker output file.
- @var{in-secname} may be an integer.
- @cindex @code{ALIGN} (MRI)
- @item ALIGN @var{secname} = @var{expression}
- Align the section called @var{secname} to @var{expression}. The
- @var{expression} should be a power of two.
- @cindex @code{BASE} (MRI)
- @item BASE @var{expression}
- Use the value of @var{expression} as the lowest address (other than
- absolute addresses) in the output file.
- @cindex @code{CHIP} (MRI)
- @item CHIP @var{expression}
- @itemx CHIP @var{expression}, @var{expression}
- This command does nothing; it is accepted only for compatibility.
- @cindex @code{END} (MRI)
- @item END
- This command does nothing whatever; it's only accepted for compatibility.
- @cindex @code{FORMAT} (MRI)
- @item FORMAT @var{output-format}
- Similar to the @code{OUTPUT_FORMAT} command in the more general linker
- language, but restricted to S-records, if @var{output-format} is @samp{S}
- @cindex @code{LIST} (MRI)
- @item LIST @var{anything}@dots{}
- Print (to the standard output file) a link map, as produced by the
- @command{ld} command-line option @samp{-M}.
- The keyword @code{LIST} may be followed by anything on the
- same line, with no change in its effect.
- @cindex @code{LOAD} (MRI)
- @item LOAD @var{filename}
- @itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
- Include one or more object file @var{filename} in the link; this has the
- same effect as specifying @var{filename} directly on the @command{ld}
- command line.
- @cindex @code{NAME} (MRI)
- @item NAME @var{output-name}
- @var{output-name} is the name for the program produced by @command{ld}; the
- MRI-compatible command @code{NAME} is equivalent to the command-line
- option @samp{-o} or the general script language command @code{OUTPUT}.
- @cindex @code{ORDER} (MRI)
- @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
- @itemx ORDER @var{secname} @var{secname} @var{secname}
- Normally, @command{ld} 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} command. The
- sections you list with @code{ORDER} will appear first in your output
- file, in the order specified.
- @cindex @code{PUBLIC} (MRI)
- @item PUBLIC @var{name}=@var{expression}
- @itemx PUBLIC @var{name},@var{expression}
- @itemx PUBLIC @var{name} @var{expression}
- Supply a value (@var{expression}) for external symbol
- @var{name} used in the linker input files.
- @cindex @code{SECT} (MRI)
- @item SECT @var{secname}, @var{expression}
- @itemx SECT @var{secname}=@var{expression}
- @itemx SECT @var{secname} @var{expression}
- You can use any of these three forms of the @code{SECT} command to
- specify the start address (@var{expression}) for section @var{secname}.
- If you have more than one @code{SECT} statement for the same
- @var{secname}, only the @emph{first} sets the start address.
- @end table
- @node GNU Free Documentation License
- @appendix GNU Free Documentation License
- @include fdl.texi
- @node LD Index
- @unnumbered LD Index
- @printindex cp
- @tex
- % I think something like @@colophon should be in texinfo. In the
- % meantime:
- \long\def\colophon{\hbox to0pt{}\vfill
- \centerline{The body of this manual is set in}
- \centerline{\fontname\tenrm,}
- \centerline{with headings in {\bf\fontname\tenbf}}
- \centerline{and examples in {\tt\fontname\tentt}.}
- \centerline{{\it\fontname\tenit\/} and}
- \centerline{{\sl\fontname\tensl\/}}
- \centerline{are used for emphasis.}\vfill}
- \page\colophon
- % Blame: doc@@cygnus.com, 28mar91.
- @end tex
- @bye
|