libc.info-3 285 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638
  1. This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
  2. This file documents the GNU C Library.
  3. This is ‘The GNU C Library Reference Manual’, for version 2.25.
  4. Copyright © 1993–2017 Free Software Foundation, Inc.
  5. Permission is granted to copy, distribute and/or modify this document
  6. under the terms of the GNU Free Documentation License, Version 1.3 or
  7. any later version published by the Free Software Foundation; with the
  8. Invariant Sections being “Free Software Needs Free Documentation” and
  9. “GNU Lesser General Public License”, the Front-Cover texts being “A GNU
  10. Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
  11. license is included in the section entitled "GNU Free Documentation
  12. License".
  13. (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
  14. modify this GNU manual. Buying copies from the FSF supports it in
  15. developing GNU and promoting software freedom.”
  16. INFO-DIR-SECTION Software libraries
  17. START-INFO-DIR-ENTRY
  18. * Libc: (libc). C library.
  19. END-INFO-DIR-ENTRY
  20. INFO-DIR-SECTION GNU C library functions and macros
  21. START-INFO-DIR-ENTRY
  22. * a64l: (libc)Encode Binary Data.
  23. * abort: (libc)Aborting a Program.
  24. * abs: (libc)Absolute Value.
  25. * accept: (libc)Accepting Connections.
  26. * access: (libc)Testing File Access.
  27. * acosf: (libc)Inverse Trig Functions.
  28. * acoshf: (libc)Hyperbolic Functions.
  29. * acosh: (libc)Hyperbolic Functions.
  30. * acoshl: (libc)Hyperbolic Functions.
  31. * acos: (libc)Inverse Trig Functions.
  32. * acosl: (libc)Inverse Trig Functions.
  33. * addmntent: (libc)mtab.
  34. * addseverity: (libc)Adding Severity Classes.
  35. * adjtime: (libc)High-Resolution Calendar.
  36. * adjtimex: (libc)High-Resolution Calendar.
  37. * aio_cancel64: (libc)Cancel AIO Operations.
  38. * aio_cancel: (libc)Cancel AIO Operations.
  39. * aio_error64: (libc)Status of AIO Operations.
  40. * aio_error: (libc)Status of AIO Operations.
  41. * aio_fsync64: (libc)Synchronizing AIO Operations.
  42. * aio_fsync: (libc)Synchronizing AIO Operations.
  43. * aio_init: (libc)Configuration of AIO.
  44. * aio_read64: (libc)Asynchronous Reads/Writes.
  45. * aio_read: (libc)Asynchronous Reads/Writes.
  46. * aio_return64: (libc)Status of AIO Operations.
  47. * aio_return: (libc)Status of AIO Operations.
  48. * aio_suspend64: (libc)Synchronizing AIO Operations.
  49. * aio_suspend: (libc)Synchronizing AIO Operations.
  50. * aio_write64: (libc)Asynchronous Reads/Writes.
  51. * aio_write: (libc)Asynchronous Reads/Writes.
  52. * alarm: (libc)Setting an Alarm.
  53. * aligned_alloc: (libc)Aligned Memory Blocks.
  54. * alloca: (libc)Variable Size Automatic.
  55. * alphasort64: (libc)Scanning Directory Content.
  56. * alphasort: (libc)Scanning Directory Content.
  57. * ALTWERASE: (libc)Local Modes.
  58. * ARG_MAX: (libc)General Limits.
  59. * argp_error: (libc)Argp Helper Functions.
  60. * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
  61. * argp_failure: (libc)Argp Helper Functions.
  62. * argp_help: (libc)Argp Help.
  63. * argp_parse: (libc)Argp.
  64. * argp_state_help: (libc)Argp Helper Functions.
  65. * argp_usage: (libc)Argp Helper Functions.
  66. * argz_add: (libc)Argz Functions.
  67. * argz_add_sep: (libc)Argz Functions.
  68. * argz_append: (libc)Argz Functions.
  69. * argz_count: (libc)Argz Functions.
  70. * argz_create: (libc)Argz Functions.
  71. * argz_create_sep: (libc)Argz Functions.
  72. * argz_delete: (libc)Argz Functions.
  73. * argz_extract: (libc)Argz Functions.
  74. * argz_insert: (libc)Argz Functions.
  75. * argz_next: (libc)Argz Functions.
  76. * argz_replace: (libc)Argz Functions.
  77. * argz_stringify: (libc)Argz Functions.
  78. * asctime: (libc)Formatting Calendar Time.
  79. * asctime_r: (libc)Formatting Calendar Time.
  80. * asinf: (libc)Inverse Trig Functions.
  81. * asinhf: (libc)Hyperbolic Functions.
  82. * asinh: (libc)Hyperbolic Functions.
  83. * asinhl: (libc)Hyperbolic Functions.
  84. * asin: (libc)Inverse Trig Functions.
  85. * asinl: (libc)Inverse Trig Functions.
  86. * asprintf: (libc)Dynamic Output.
  87. * assert: (libc)Consistency Checking.
  88. * assert_perror: (libc)Consistency Checking.
  89. * atan2f: (libc)Inverse Trig Functions.
  90. * atan2: (libc)Inverse Trig Functions.
  91. * atan2l: (libc)Inverse Trig Functions.
  92. * atanf: (libc)Inverse Trig Functions.
  93. * atanhf: (libc)Hyperbolic Functions.
  94. * atanh: (libc)Hyperbolic Functions.
  95. * atanhl: (libc)Hyperbolic Functions.
  96. * atan: (libc)Inverse Trig Functions.
  97. * atanl: (libc)Inverse Trig Functions.
  98. * atexit: (libc)Cleanups on Exit.
  99. * atof: (libc)Parsing of Floats.
  100. * atoi: (libc)Parsing of Integers.
  101. * atol: (libc)Parsing of Integers.
  102. * atoll: (libc)Parsing of Integers.
  103. * backtrace: (libc)Backtraces.
  104. * backtrace_symbols_fd: (libc)Backtraces.
  105. * backtrace_symbols: (libc)Backtraces.
  106. * basename: (libc)Finding Tokens in a String.
  107. * basename: (libc)Finding Tokens in a String.
  108. * BC_BASE_MAX: (libc)Utility Limits.
  109. * BC_DIM_MAX: (libc)Utility Limits.
  110. * bcmp: (libc)String/Array Comparison.
  111. * bcopy: (libc)Copying Strings and Arrays.
  112. * BC_SCALE_MAX: (libc)Utility Limits.
  113. * BC_STRING_MAX: (libc)Utility Limits.
  114. * bind: (libc)Setting Address.
  115. * bind_textdomain_codeset: (libc)Charset conversion in gettext.
  116. * bindtextdomain: (libc)Locating gettext catalog.
  117. * BRKINT: (libc)Input Modes.
  118. * brk: (libc)Resizing the Data Segment.
  119. * bsearch: (libc)Array Search Function.
  120. * btowc: (libc)Converting a Character.
  121. * BUFSIZ: (libc)Controlling Buffering.
  122. * bzero: (libc)Copying Strings and Arrays.
  123. * cabsf: (libc)Absolute Value.
  124. * cabs: (libc)Absolute Value.
  125. * cabsl: (libc)Absolute Value.
  126. * cacosf: (libc)Inverse Trig Functions.
  127. * cacoshf: (libc)Hyperbolic Functions.
  128. * cacosh: (libc)Hyperbolic Functions.
  129. * cacoshl: (libc)Hyperbolic Functions.
  130. * cacos: (libc)Inverse Trig Functions.
  131. * cacosl: (libc)Inverse Trig Functions.
  132. * calloc: (libc)Allocating Cleared Space.
  133. * canonicalize_file_name: (libc)Symbolic Links.
  134. * canonicalizef: (libc)FP Bit Twiddling.
  135. * canonicalize: (libc)FP Bit Twiddling.
  136. * canonicalizel: (libc)FP Bit Twiddling.
  137. * cargf: (libc)Operations on Complex.
  138. * carg: (libc)Operations on Complex.
  139. * cargl: (libc)Operations on Complex.
  140. * casinf: (libc)Inverse Trig Functions.
  141. * casinhf: (libc)Hyperbolic Functions.
  142. * casinh: (libc)Hyperbolic Functions.
  143. * casinhl: (libc)Hyperbolic Functions.
  144. * casin: (libc)Inverse Trig Functions.
  145. * casinl: (libc)Inverse Trig Functions.
  146. * catanf: (libc)Inverse Trig Functions.
  147. * catanhf: (libc)Hyperbolic Functions.
  148. * catanh: (libc)Hyperbolic Functions.
  149. * catanhl: (libc)Hyperbolic Functions.
  150. * catan: (libc)Inverse Trig Functions.
  151. * catanl: (libc)Inverse Trig Functions.
  152. * catclose: (libc)The catgets Functions.
  153. * catgets: (libc)The catgets Functions.
  154. * catopen: (libc)The catgets Functions.
  155. * cbc_crypt: (libc)DES Encryption.
  156. * cbrtf: (libc)Exponents and Logarithms.
  157. * cbrt: (libc)Exponents and Logarithms.
  158. * cbrtl: (libc)Exponents and Logarithms.
  159. * ccosf: (libc)Trig Functions.
  160. * ccoshf: (libc)Hyperbolic Functions.
  161. * ccosh: (libc)Hyperbolic Functions.
  162. * ccoshl: (libc)Hyperbolic Functions.
  163. * ccos: (libc)Trig Functions.
  164. * ccosl: (libc)Trig Functions.
  165. * CCTS_OFLOW: (libc)Control Modes.
  166. * ceilf: (libc)Rounding Functions.
  167. * ceil: (libc)Rounding Functions.
  168. * ceill: (libc)Rounding Functions.
  169. * cexpf: (libc)Exponents and Logarithms.
  170. * cexp: (libc)Exponents and Logarithms.
  171. * cexpl: (libc)Exponents and Logarithms.
  172. * cfgetispeed: (libc)Line Speed.
  173. * cfgetospeed: (libc)Line Speed.
  174. * cfmakeraw: (libc)Noncanonical Input.
  175. * cfree: (libc)Freeing after Malloc.
  176. * cfsetispeed: (libc)Line Speed.
  177. * cfsetospeed: (libc)Line Speed.
  178. * cfsetspeed: (libc)Line Speed.
  179. * chdir: (libc)Working Directory.
  180. * CHILD_MAX: (libc)General Limits.
  181. * chmod: (libc)Setting Permissions.
  182. * chown: (libc)File Owner.
  183. * CIGNORE: (libc)Control Modes.
  184. * cimagf: (libc)Operations on Complex.
  185. * cimag: (libc)Operations on Complex.
  186. * cimagl: (libc)Operations on Complex.
  187. * clearenv: (libc)Environment Access.
  188. * clearerr: (libc)Error Recovery.
  189. * clearerr_unlocked: (libc)Error Recovery.
  190. * CLK_TCK: (libc)Processor Time.
  191. * CLOCAL: (libc)Control Modes.
  192. * clock: (libc)CPU Time.
  193. * CLOCKS_PER_SEC: (libc)CPU Time.
  194. * clog10f: (libc)Exponents and Logarithms.
  195. * clog10: (libc)Exponents and Logarithms.
  196. * clog10l: (libc)Exponents and Logarithms.
  197. * clogf: (libc)Exponents and Logarithms.
  198. * clog: (libc)Exponents and Logarithms.
  199. * clogl: (libc)Exponents and Logarithms.
  200. * closedir: (libc)Reading/Closing Directory.
  201. * close: (libc)Opening and Closing Files.
  202. * closelog: (libc)closelog.
  203. * COLL_WEIGHTS_MAX: (libc)Utility Limits.
  204. * _Complex_I: (libc)Complex Numbers.
  205. * confstr: (libc)String Parameters.
  206. * conjf: (libc)Operations on Complex.
  207. * conj: (libc)Operations on Complex.
  208. * conjl: (libc)Operations on Complex.
  209. * connect: (libc)Connecting.
  210. * copysignf: (libc)FP Bit Twiddling.
  211. * copysign: (libc)FP Bit Twiddling.
  212. * copysignl: (libc)FP Bit Twiddling.
  213. * cosf: (libc)Trig Functions.
  214. * coshf: (libc)Hyperbolic Functions.
  215. * cosh: (libc)Hyperbolic Functions.
  216. * coshl: (libc)Hyperbolic Functions.
  217. * cos: (libc)Trig Functions.
  218. * cosl: (libc)Trig Functions.
  219. * cpowf: (libc)Exponents and Logarithms.
  220. * cpow: (libc)Exponents and Logarithms.
  221. * cpowl: (libc)Exponents and Logarithms.
  222. * cprojf: (libc)Operations on Complex.
  223. * cproj: (libc)Operations on Complex.
  224. * cprojl: (libc)Operations on Complex.
  225. * CPU_CLR: (libc)CPU Affinity.
  226. * CPU_ISSET: (libc)CPU Affinity.
  227. * CPU_SET: (libc)CPU Affinity.
  228. * CPU_SETSIZE: (libc)CPU Affinity.
  229. * CPU_ZERO: (libc)CPU Affinity.
  230. * CREAD: (libc)Control Modes.
  231. * crealf: (libc)Operations on Complex.
  232. * creal: (libc)Operations on Complex.
  233. * creall: (libc)Operations on Complex.
  234. * creat64: (libc)Opening and Closing Files.
  235. * creat: (libc)Opening and Closing Files.
  236. * CRTS_IFLOW: (libc)Control Modes.
  237. * crypt: (libc)crypt.
  238. * crypt_r: (libc)crypt.
  239. * CS5: (libc)Control Modes.
  240. * CS6: (libc)Control Modes.
  241. * CS7: (libc)Control Modes.
  242. * CS8: (libc)Control Modes.
  243. * csinf: (libc)Trig Functions.
  244. * csinhf: (libc)Hyperbolic Functions.
  245. * csinh: (libc)Hyperbolic Functions.
  246. * csinhl: (libc)Hyperbolic Functions.
  247. * csin: (libc)Trig Functions.
  248. * csinl: (libc)Trig Functions.
  249. * CSIZE: (libc)Control Modes.
  250. * csqrtf: (libc)Exponents and Logarithms.
  251. * csqrt: (libc)Exponents and Logarithms.
  252. * csqrtl: (libc)Exponents and Logarithms.
  253. * CSTOPB: (libc)Control Modes.
  254. * ctanf: (libc)Trig Functions.
  255. * ctanhf: (libc)Hyperbolic Functions.
  256. * ctanh: (libc)Hyperbolic Functions.
  257. * ctanhl: (libc)Hyperbolic Functions.
  258. * ctan: (libc)Trig Functions.
  259. * ctanl: (libc)Trig Functions.
  260. * ctermid: (libc)Identifying the Terminal.
  261. * ctime: (libc)Formatting Calendar Time.
  262. * ctime_r: (libc)Formatting Calendar Time.
  263. * cuserid: (libc)Who Logged In.
  264. * dcgettext: (libc)Translation with gettext.
  265. * dcngettext: (libc)Advanced gettext functions.
  266. * DES_FAILED: (libc)DES Encryption.
  267. * des_setparity: (libc)DES Encryption.
  268. * dgettext: (libc)Translation with gettext.
  269. * difftime: (libc)Elapsed Time.
  270. * dirfd: (libc)Opening a Directory.
  271. * dirname: (libc)Finding Tokens in a String.
  272. * div: (libc)Integer Division.
  273. * dngettext: (libc)Advanced gettext functions.
  274. * drand48: (libc)SVID Random.
  275. * drand48_r: (libc)SVID Random.
  276. * dremf: (libc)Remainder Functions.
  277. * drem: (libc)Remainder Functions.
  278. * dreml: (libc)Remainder Functions.
  279. * DTTOIF: (libc)Directory Entries.
  280. * dup2: (libc)Duplicating Descriptors.
  281. * dup: (libc)Duplicating Descriptors.
  282. * E2BIG: (libc)Error Codes.
  283. * EACCES: (libc)Error Codes.
  284. * EADDRINUSE: (libc)Error Codes.
  285. * EADDRNOTAVAIL: (libc)Error Codes.
  286. * EADV: (libc)Error Codes.
  287. * EAFNOSUPPORT: (libc)Error Codes.
  288. * EAGAIN: (libc)Error Codes.
  289. * EALREADY: (libc)Error Codes.
  290. * EAUTH: (libc)Error Codes.
  291. * EBACKGROUND: (libc)Error Codes.
  292. * EBADE: (libc)Error Codes.
  293. * EBADFD: (libc)Error Codes.
  294. * EBADF: (libc)Error Codes.
  295. * EBADMSG: (libc)Error Codes.
  296. * EBADR: (libc)Error Codes.
  297. * EBADRPC: (libc)Error Codes.
  298. * EBADRQC: (libc)Error Codes.
  299. * EBADSLT: (libc)Error Codes.
  300. * EBFONT: (libc)Error Codes.
  301. * EBUSY: (libc)Error Codes.
  302. * ECANCELED: (libc)Error Codes.
  303. * ecb_crypt: (libc)DES Encryption.
  304. * ECHILD: (libc)Error Codes.
  305. * ECHOCTL: (libc)Local Modes.
  306. * ECHOE: (libc)Local Modes.
  307. * ECHOKE: (libc)Local Modes.
  308. * ECHOK: (libc)Local Modes.
  309. * ECHO: (libc)Local Modes.
  310. * ECHONL: (libc)Local Modes.
  311. * ECHOPRT: (libc)Local Modes.
  312. * ECHRNG: (libc)Error Codes.
  313. * ECOMM: (libc)Error Codes.
  314. * ECONNABORTED: (libc)Error Codes.
  315. * ECONNREFUSED: (libc)Error Codes.
  316. * ECONNRESET: (libc)Error Codes.
  317. * ecvt: (libc)System V Number Conversion.
  318. * ecvt_r: (libc)System V Number Conversion.
  319. * EDEADLK: (libc)Error Codes.
  320. * EDEADLOCK: (libc)Error Codes.
  321. * EDESTADDRREQ: (libc)Error Codes.
  322. * EDIED: (libc)Error Codes.
  323. * ED: (libc)Error Codes.
  324. * EDOM: (libc)Error Codes.
  325. * EDOTDOT: (libc)Error Codes.
  326. * EDQUOT: (libc)Error Codes.
  327. * EEXIST: (libc)Error Codes.
  328. * EFAULT: (libc)Error Codes.
  329. * EFBIG: (libc)Error Codes.
  330. * EFTYPE: (libc)Error Codes.
  331. * EGRATUITOUS: (libc)Error Codes.
  332. * EGREGIOUS: (libc)Error Codes.
  333. * EHOSTDOWN: (libc)Error Codes.
  334. * EHOSTUNREACH: (libc)Error Codes.
  335. * EHWPOISON: (libc)Error Codes.
  336. * EIDRM: (libc)Error Codes.
  337. * EIEIO: (libc)Error Codes.
  338. * EILSEQ: (libc)Error Codes.
  339. * EINPROGRESS: (libc)Error Codes.
  340. * EINTR: (libc)Error Codes.
  341. * EINVAL: (libc)Error Codes.
  342. * EIO: (libc)Error Codes.
  343. * EISCONN: (libc)Error Codes.
  344. * EISDIR: (libc)Error Codes.
  345. * EISNAM: (libc)Error Codes.
  346. * EKEYEXPIRED: (libc)Error Codes.
  347. * EKEYREJECTED: (libc)Error Codes.
  348. * EKEYREVOKED: (libc)Error Codes.
  349. * EL2HLT: (libc)Error Codes.
  350. * EL2NSYNC: (libc)Error Codes.
  351. * EL3HLT: (libc)Error Codes.
  352. * EL3RST: (libc)Error Codes.
  353. * ELIBACC: (libc)Error Codes.
  354. * ELIBBAD: (libc)Error Codes.
  355. * ELIBEXEC: (libc)Error Codes.
  356. * ELIBMAX: (libc)Error Codes.
  357. * ELIBSCN: (libc)Error Codes.
  358. * ELNRNG: (libc)Error Codes.
  359. * ELOOP: (libc)Error Codes.
  360. * EMEDIUMTYPE: (libc)Error Codes.
  361. * EMFILE: (libc)Error Codes.
  362. * EMLINK: (libc)Error Codes.
  363. * EMSGSIZE: (libc)Error Codes.
  364. * EMULTIHOP: (libc)Error Codes.
  365. * ENAMETOOLONG: (libc)Error Codes.
  366. * ENAVAIL: (libc)Error Codes.
  367. * encrypt: (libc)DES Encryption.
  368. * encrypt_r: (libc)DES Encryption.
  369. * endfsent: (libc)fstab.
  370. * endgrent: (libc)Scanning All Groups.
  371. * endhostent: (libc)Host Names.
  372. * endmntent: (libc)mtab.
  373. * endnetent: (libc)Networks Database.
  374. * endnetgrent: (libc)Lookup Netgroup.
  375. * endprotoent: (libc)Protocols Database.
  376. * endpwent: (libc)Scanning All Users.
  377. * endservent: (libc)Services Database.
  378. * endutent: (libc)Manipulating the Database.
  379. * endutxent: (libc)XPG Functions.
  380. * ENEEDAUTH: (libc)Error Codes.
  381. * ENETDOWN: (libc)Error Codes.
  382. * ENETRESET: (libc)Error Codes.
  383. * ENETUNREACH: (libc)Error Codes.
  384. * ENFILE: (libc)Error Codes.
  385. * ENOANO: (libc)Error Codes.
  386. * ENOBUFS: (libc)Error Codes.
  387. * ENOCSI: (libc)Error Codes.
  388. * ENODATA: (libc)Error Codes.
  389. * ENODEV: (libc)Error Codes.
  390. * ENOENT: (libc)Error Codes.
  391. * ENOEXEC: (libc)Error Codes.
  392. * ENOKEY: (libc)Error Codes.
  393. * ENOLCK: (libc)Error Codes.
  394. * ENOLINK: (libc)Error Codes.
  395. * ENOMEDIUM: (libc)Error Codes.
  396. * ENOMEM: (libc)Error Codes.
  397. * ENOMSG: (libc)Error Codes.
  398. * ENONET: (libc)Error Codes.
  399. * ENOPKG: (libc)Error Codes.
  400. * ENOPROTOOPT: (libc)Error Codes.
  401. * ENOSPC: (libc)Error Codes.
  402. * ENOSR: (libc)Error Codes.
  403. * ENOSTR: (libc)Error Codes.
  404. * ENOSYS: (libc)Error Codes.
  405. * ENOTBLK: (libc)Error Codes.
  406. * ENOTCONN: (libc)Error Codes.
  407. * ENOTDIR: (libc)Error Codes.
  408. * ENOTEMPTY: (libc)Error Codes.
  409. * ENOTNAM: (libc)Error Codes.
  410. * ENOTRECOVERABLE: (libc)Error Codes.
  411. * ENOTSOCK: (libc)Error Codes.
  412. * ENOTSUP: (libc)Error Codes.
  413. * ENOTTY: (libc)Error Codes.
  414. * ENOTUNIQ: (libc)Error Codes.
  415. * envz_add: (libc)Envz Functions.
  416. * envz_entry: (libc)Envz Functions.
  417. * envz_get: (libc)Envz Functions.
  418. * envz_merge: (libc)Envz Functions.
  419. * envz_remove: (libc)Envz Functions.
  420. * envz_strip: (libc)Envz Functions.
  421. * ENXIO: (libc)Error Codes.
  422. * EOF: (libc)EOF and Errors.
  423. * EOPNOTSUPP: (libc)Error Codes.
  424. * EOVERFLOW: (libc)Error Codes.
  425. * EOWNERDEAD: (libc)Error Codes.
  426. * EPERM: (libc)Error Codes.
  427. * EPFNOSUPPORT: (libc)Error Codes.
  428. * EPIPE: (libc)Error Codes.
  429. * EPROCLIM: (libc)Error Codes.
  430. * EPROCUNAVAIL: (libc)Error Codes.
  431. * EPROGMISMATCH: (libc)Error Codes.
  432. * EPROGUNAVAIL: (libc)Error Codes.
  433. * EPROTO: (libc)Error Codes.
  434. * EPROTONOSUPPORT: (libc)Error Codes.
  435. * EPROTOTYPE: (libc)Error Codes.
  436. * EQUIV_CLASS_MAX: (libc)Utility Limits.
  437. * erand48: (libc)SVID Random.
  438. * erand48_r: (libc)SVID Random.
  439. * ERANGE: (libc)Error Codes.
  440. * EREMCHG: (libc)Error Codes.
  441. * EREMOTEIO: (libc)Error Codes.
  442. * EREMOTE: (libc)Error Codes.
  443. * ERESTART: (libc)Error Codes.
  444. * erfcf: (libc)Special Functions.
  445. * erfc: (libc)Special Functions.
  446. * erfcl: (libc)Special Functions.
  447. * erff: (libc)Special Functions.
  448. * ERFKILL: (libc)Error Codes.
  449. * erf: (libc)Special Functions.
  450. * erfl: (libc)Special Functions.
  451. * EROFS: (libc)Error Codes.
  452. * ERPCMISMATCH: (libc)Error Codes.
  453. * err: (libc)Error Messages.
  454. * errno: (libc)Checking for Errors.
  455. * error_at_line: (libc)Error Messages.
  456. * error: (libc)Error Messages.
  457. * errx: (libc)Error Messages.
  458. * ESHUTDOWN: (libc)Error Codes.
  459. * ESOCKTNOSUPPORT: (libc)Error Codes.
  460. * ESPIPE: (libc)Error Codes.
  461. * ESRCH: (libc)Error Codes.
  462. * ESRMNT: (libc)Error Codes.
  463. * ESTALE: (libc)Error Codes.
  464. * ESTRPIPE: (libc)Error Codes.
  465. * ETIMEDOUT: (libc)Error Codes.
  466. * ETIME: (libc)Error Codes.
  467. * ETOOMANYREFS: (libc)Error Codes.
  468. * ETXTBSY: (libc)Error Codes.
  469. * EUCLEAN: (libc)Error Codes.
  470. * EUNATCH: (libc)Error Codes.
  471. * EUSERS: (libc)Error Codes.
  472. * EWOULDBLOCK: (libc)Error Codes.
  473. * EXDEV: (libc)Error Codes.
  474. * execle: (libc)Executing a File.
  475. * execl: (libc)Executing a File.
  476. * execlp: (libc)Executing a File.
  477. * execve: (libc)Executing a File.
  478. * execv: (libc)Executing a File.
  479. * execvp: (libc)Executing a File.
  480. * EXFULL: (libc)Error Codes.
  481. * EXIT_FAILURE: (libc)Exit Status.
  482. * exit: (libc)Normal Termination.
  483. * _exit: (libc)Termination Internals.
  484. * _Exit: (libc)Termination Internals.
  485. * EXIT_SUCCESS: (libc)Exit Status.
  486. * exp10f: (libc)Exponents and Logarithms.
  487. * exp10: (libc)Exponents and Logarithms.
  488. * exp10l: (libc)Exponents and Logarithms.
  489. * exp2f: (libc)Exponents and Logarithms.
  490. * exp2: (libc)Exponents and Logarithms.
  491. * exp2l: (libc)Exponents and Logarithms.
  492. * expf: (libc)Exponents and Logarithms.
  493. * exp: (libc)Exponents and Logarithms.
  494. * explicit_bzero: (libc)Erasing Sensitive Data.
  495. * expl: (libc)Exponents and Logarithms.
  496. * expm1f: (libc)Exponents and Logarithms.
  497. * expm1: (libc)Exponents and Logarithms.
  498. * expm1l: (libc)Exponents and Logarithms.
  499. * EXPR_NEST_MAX: (libc)Utility Limits.
  500. * fabsf: (libc)Absolute Value.
  501. * fabs: (libc)Absolute Value.
  502. * fabsl: (libc)Absolute Value.
  503. * __fbufsize: (libc)Controlling Buffering.
  504. * fchdir: (libc)Working Directory.
  505. * fchmod: (libc)Setting Permissions.
  506. * fchown: (libc)File Owner.
  507. * fcloseall: (libc)Closing Streams.
  508. * fclose: (libc)Closing Streams.
  509. * fcntl: (libc)Control Operations.
  510. * fcvt: (libc)System V Number Conversion.
  511. * fcvt_r: (libc)System V Number Conversion.
  512. * fdatasync: (libc)Synchronizing I/O.
  513. * FD_CLOEXEC: (libc)Descriptor Flags.
  514. * FD_CLR: (libc)Waiting for I/O.
  515. * fdimf: (libc)Misc FP Arithmetic.
  516. * fdim: (libc)Misc FP Arithmetic.
  517. * fdiml: (libc)Misc FP Arithmetic.
  518. * FD_ISSET: (libc)Waiting for I/O.
  519. * fdopendir: (libc)Opening a Directory.
  520. * fdopen: (libc)Descriptors and Streams.
  521. * FD_SET: (libc)Waiting for I/O.
  522. * FD_SETSIZE: (libc)Waiting for I/O.
  523. * F_DUPFD: (libc)Duplicating Descriptors.
  524. * FD_ZERO: (libc)Waiting for I/O.
  525. * feclearexcept: (libc)Status bit operations.
  526. * fedisableexcept: (libc)Control Functions.
  527. * feenableexcept: (libc)Control Functions.
  528. * fegetenv: (libc)Control Functions.
  529. * fegetexceptflag: (libc)Status bit operations.
  530. * fegetexcept: (libc)Control Functions.
  531. * fegetmode: (libc)Control Functions.
  532. * fegetround: (libc)Rounding.
  533. * feholdexcept: (libc)Control Functions.
  534. * feof: (libc)EOF and Errors.
  535. * feof_unlocked: (libc)EOF and Errors.
  536. * feraiseexcept: (libc)Status bit operations.
  537. * ferror: (libc)EOF and Errors.
  538. * ferror_unlocked: (libc)EOF and Errors.
  539. * fesetenv: (libc)Control Functions.
  540. * fesetexceptflag: (libc)Status bit operations.
  541. * fesetexcept: (libc)Status bit operations.
  542. * fesetmode: (libc)Control Functions.
  543. * fesetround: (libc)Rounding.
  544. * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
  545. * fetestexceptflag: (libc)Status bit operations.
  546. * fetestexcept: (libc)Status bit operations.
  547. * feupdateenv: (libc)Control Functions.
  548. * fflush: (libc)Flushing Buffers.
  549. * fflush_unlocked: (libc)Flushing Buffers.
  550. * fgetc: (libc)Character Input.
  551. * fgetc_unlocked: (libc)Character Input.
  552. * F_GETFD: (libc)Descriptor Flags.
  553. * F_GETFL: (libc)Getting File Status Flags.
  554. * fgetgrent: (libc)Scanning All Groups.
  555. * fgetgrent_r: (libc)Scanning All Groups.
  556. * F_GETLK: (libc)File Locks.
  557. * F_GETOWN: (libc)Interrupt Input.
  558. * fgetpos64: (libc)Portable Positioning.
  559. * fgetpos: (libc)Portable Positioning.
  560. * fgetpwent: (libc)Scanning All Users.
  561. * fgetpwent_r: (libc)Scanning All Users.
  562. * fgets: (libc)Line Input.
  563. * fgets_unlocked: (libc)Line Input.
  564. * fgetwc: (libc)Character Input.
  565. * fgetwc_unlocked: (libc)Character Input.
  566. * fgetws: (libc)Line Input.
  567. * fgetws_unlocked: (libc)Line Input.
  568. * FILENAME_MAX: (libc)Limits for Files.
  569. * fileno: (libc)Descriptors and Streams.
  570. * fileno_unlocked: (libc)Descriptors and Streams.
  571. * finitef: (libc)Floating Point Classes.
  572. * finite: (libc)Floating Point Classes.
  573. * finitel: (libc)Floating Point Classes.
  574. * __flbf: (libc)Controlling Buffering.
  575. * flockfile: (libc)Streams and Threads.
  576. * floorf: (libc)Rounding Functions.
  577. * floor: (libc)Rounding Functions.
  578. * floorl: (libc)Rounding Functions.
  579. * _flushlbf: (libc)Flushing Buffers.
  580. * FLUSHO: (libc)Local Modes.
  581. * fmaf: (libc)Misc FP Arithmetic.
  582. * fma: (libc)Misc FP Arithmetic.
  583. * fmal: (libc)Misc FP Arithmetic.
  584. * fmaxf: (libc)Misc FP Arithmetic.
  585. * fmax: (libc)Misc FP Arithmetic.
  586. * fmaxl: (libc)Misc FP Arithmetic.
  587. * fmaxmagf: (libc)Misc FP Arithmetic.
  588. * fmaxmag: (libc)Misc FP Arithmetic.
  589. * fmaxmagl: (libc)Misc FP Arithmetic.
  590. * fmemopen: (libc)String Streams.
  591. * fminf: (libc)Misc FP Arithmetic.
  592. * fmin: (libc)Misc FP Arithmetic.
  593. * fminl: (libc)Misc FP Arithmetic.
  594. * fminmagf: (libc)Misc FP Arithmetic.
  595. * fminmag: (libc)Misc FP Arithmetic.
  596. * fminmagl: (libc)Misc FP Arithmetic.
  597. * fmodf: (libc)Remainder Functions.
  598. * fmod: (libc)Remainder Functions.
  599. * fmodl: (libc)Remainder Functions.
  600. * fmtmsg: (libc)Printing Formatted Messages.
  601. * fnmatch: (libc)Wildcard Matching.
  602. * F_OFD_GETLK: (libc)Open File Description Locks.
  603. * F_OFD_SETLK: (libc)Open File Description Locks.
  604. * F_OFD_SETLKW: (libc)Open File Description Locks.
  605. * F_OK: (libc)Testing File Access.
  606. * fopen64: (libc)Opening Streams.
  607. * fopencookie: (libc)Streams and Cookies.
  608. * fopen: (libc)Opening Streams.
  609. * FOPEN_MAX: (libc)Opening Streams.
  610. * fork: (libc)Creating a Process.
  611. * forkpty: (libc)Pseudo-Terminal Pairs.
  612. * fpathconf: (libc)Pathconf.
  613. * fpclassify: (libc)Floating Point Classes.
  614. * __fpending: (libc)Controlling Buffering.
  615. * FP_ILOGB0: (libc)Exponents and Logarithms.
  616. * FP_ILOGBNAN: (libc)Exponents and Logarithms.
  617. * FP_LLOGB0: (libc)Exponents and Logarithms.
  618. * FP_LLOGBNAN: (libc)Exponents and Logarithms.
  619. * fprintf: (libc)Formatted Output Functions.
  620. * __fpurge: (libc)Flushing Buffers.
  621. * fputc: (libc)Simple Output.
  622. * fputc_unlocked: (libc)Simple Output.
  623. * fputs: (libc)Simple Output.
  624. * fputs_unlocked: (libc)Simple Output.
  625. * fputwc: (libc)Simple Output.
  626. * fputwc_unlocked: (libc)Simple Output.
  627. * fputws: (libc)Simple Output.
  628. * fputws_unlocked: (libc)Simple Output.
  629. * __freadable: (libc)Opening Streams.
  630. * __freading: (libc)Opening Streams.
  631. * fread: (libc)Block Input/Output.
  632. * fread_unlocked: (libc)Block Input/Output.
  633. * free: (libc)Freeing after Malloc.
  634. * freopen64: (libc)Opening Streams.
  635. * freopen: (libc)Opening Streams.
  636. * frexpf: (libc)Normalization Functions.
  637. * frexp: (libc)Normalization Functions.
  638. * frexpl: (libc)Normalization Functions.
  639. * fromfpf: (libc)Rounding Functions.
  640. * fromfp: (libc)Rounding Functions.
  641. * fromfpl: (libc)Rounding Functions.
  642. * fromfpxf: (libc)Rounding Functions.
  643. * fromfpx: (libc)Rounding Functions.
  644. * fromfpxl: (libc)Rounding Functions.
  645. * fscanf: (libc)Formatted Input Functions.
  646. * fseek: (libc)File Positioning.
  647. * fseeko64: (libc)File Positioning.
  648. * fseeko: (libc)File Positioning.
  649. * F_SETFD: (libc)Descriptor Flags.
  650. * F_SETFL: (libc)Getting File Status Flags.
  651. * F_SETLK: (libc)File Locks.
  652. * F_SETLKW: (libc)File Locks.
  653. * __fsetlocking: (libc)Streams and Threads.
  654. * F_SETOWN: (libc)Interrupt Input.
  655. * fsetpos64: (libc)Portable Positioning.
  656. * fsetpos: (libc)Portable Positioning.
  657. * fstat64: (libc)Reading Attributes.
  658. * fstat: (libc)Reading Attributes.
  659. * fsync: (libc)Synchronizing I/O.
  660. * ftell: (libc)File Positioning.
  661. * ftello64: (libc)File Positioning.
  662. * ftello: (libc)File Positioning.
  663. * ftruncate64: (libc)File Size.
  664. * ftruncate: (libc)File Size.
  665. * ftrylockfile: (libc)Streams and Threads.
  666. * ftw64: (libc)Working with Directory Trees.
  667. * ftw: (libc)Working with Directory Trees.
  668. * funlockfile: (libc)Streams and Threads.
  669. * futimes: (libc)File Times.
  670. * fwide: (libc)Streams and I18N.
  671. * fwprintf: (libc)Formatted Output Functions.
  672. * __fwritable: (libc)Opening Streams.
  673. * fwrite: (libc)Block Input/Output.
  674. * fwrite_unlocked: (libc)Block Input/Output.
  675. * __fwriting: (libc)Opening Streams.
  676. * fwscanf: (libc)Formatted Input Functions.
  677. * gammaf: (libc)Special Functions.
  678. * gamma: (libc)Special Functions.
  679. * gammal: (libc)Special Functions.
  680. * __gconv_end_fct: (libc)glibc iconv Implementation.
  681. * __gconv_fct: (libc)glibc iconv Implementation.
  682. * __gconv_init_fct: (libc)glibc iconv Implementation.
  683. * gcvt: (libc)System V Number Conversion.
  684. * getauxval: (libc)Auxiliary Vector.
  685. * get_avphys_pages: (libc)Query Memory Parameters.
  686. * getchar: (libc)Character Input.
  687. * getchar_unlocked: (libc)Character Input.
  688. * getc: (libc)Character Input.
  689. * getcontext: (libc)System V contexts.
  690. * getc_unlocked: (libc)Character Input.
  691. * get_current_dir_name: (libc)Working Directory.
  692. * getcwd: (libc)Working Directory.
  693. * getdate: (libc)General Time String Parsing.
  694. * getdate_r: (libc)General Time String Parsing.
  695. * getdelim: (libc)Line Input.
  696. * getdomainnname: (libc)Host Identification.
  697. * getegid: (libc)Reading Persona.
  698. * getentropy: (libc)Unpredictable Bytes.
  699. * getenv: (libc)Environment Access.
  700. * geteuid: (libc)Reading Persona.
  701. * getfsent: (libc)fstab.
  702. * getfsfile: (libc)fstab.
  703. * getfsspec: (libc)fstab.
  704. * getgid: (libc)Reading Persona.
  705. * getgrent: (libc)Scanning All Groups.
  706. * getgrent_r: (libc)Scanning All Groups.
  707. * getgrgid: (libc)Lookup Group.
  708. * getgrgid_r: (libc)Lookup Group.
  709. * getgrnam: (libc)Lookup Group.
  710. * getgrnam_r: (libc)Lookup Group.
  711. * getgrouplist: (libc)Setting Groups.
  712. * getgroups: (libc)Reading Persona.
  713. * gethostbyaddr: (libc)Host Names.
  714. * gethostbyaddr_r: (libc)Host Names.
  715. * gethostbyname2: (libc)Host Names.
  716. * gethostbyname2_r: (libc)Host Names.
  717. * gethostbyname: (libc)Host Names.
  718. * gethostbyname_r: (libc)Host Names.
  719. * gethostent: (libc)Host Names.
  720. * gethostid: (libc)Host Identification.
  721. * gethostname: (libc)Host Identification.
  722. * getitimer: (libc)Setting an Alarm.
  723. * getline: (libc)Line Input.
  724. * getloadavg: (libc)Processor Resources.
  725. * getlogin: (libc)Who Logged In.
  726. * getmntent: (libc)mtab.
  727. * getmntent_r: (libc)mtab.
  728. * getnetbyaddr: (libc)Networks Database.
  729. * getnetbyname: (libc)Networks Database.
  730. * getnetent: (libc)Networks Database.
  731. * getnetgrent: (libc)Lookup Netgroup.
  732. * getnetgrent_r: (libc)Lookup Netgroup.
  733. * get_nprocs_conf: (libc)Processor Resources.
  734. * get_nprocs: (libc)Processor Resources.
  735. * getopt: (libc)Using Getopt.
  736. * getopt_long: (libc)Getopt Long Options.
  737. * getopt_long_only: (libc)Getopt Long Options.
  738. * getpagesize: (libc)Query Memory Parameters.
  739. * getpass: (libc)getpass.
  740. * getpayloadf: (libc)FP Bit Twiddling.
  741. * getpayload: (libc)FP Bit Twiddling.
  742. * getpayloadl: (libc)FP Bit Twiddling.
  743. * getpeername: (libc)Who is Connected.
  744. * getpgid: (libc)Process Group Functions.
  745. * getpgrp: (libc)Process Group Functions.
  746. * get_phys_pages: (libc)Query Memory Parameters.
  747. * getpid: (libc)Process Identification.
  748. * getppid: (libc)Process Identification.
  749. * getpriority: (libc)Traditional Scheduling Functions.
  750. * getprotobyname: (libc)Protocols Database.
  751. * getprotobynumber: (libc)Protocols Database.
  752. * getprotoent: (libc)Protocols Database.
  753. * getpt: (libc)Allocation.
  754. * getpwent: (libc)Scanning All Users.
  755. * getpwent_r: (libc)Scanning All Users.
  756. * getpwnam: (libc)Lookup User.
  757. * getpwnam_r: (libc)Lookup User.
  758. * getpwuid: (libc)Lookup User.
  759. * getpwuid_r: (libc)Lookup User.
  760. * getrandom: (libc)Unpredictable Bytes.
  761. * getrlimit64: (libc)Limits on Resources.
  762. * getrlimit: (libc)Limits on Resources.
  763. * getrusage: (libc)Resource Usage.
  764. * getservbyname: (libc)Services Database.
  765. * getservbyport: (libc)Services Database.
  766. * getservent: (libc)Services Database.
  767. * getsid: (libc)Process Group Functions.
  768. * gets: (libc)Line Input.
  769. * getsockname: (libc)Reading Address.
  770. * getsockopt: (libc)Socket Option Functions.
  771. * getsubopt: (libc)Suboptions.
  772. * gettext: (libc)Translation with gettext.
  773. * gettimeofday: (libc)High-Resolution Calendar.
  774. * getuid: (libc)Reading Persona.
  775. * getumask: (libc)Setting Permissions.
  776. * getutent: (libc)Manipulating the Database.
  777. * getutent_r: (libc)Manipulating the Database.
  778. * getutid: (libc)Manipulating the Database.
  779. * getutid_r: (libc)Manipulating the Database.
  780. * getutline: (libc)Manipulating the Database.
  781. * getutline_r: (libc)Manipulating the Database.
  782. * getutmp: (libc)XPG Functions.
  783. * getutmpx: (libc)XPG Functions.
  784. * getutxent: (libc)XPG Functions.
  785. * getutxid: (libc)XPG Functions.
  786. * getutxline: (libc)XPG Functions.
  787. * getwchar: (libc)Character Input.
  788. * getwchar_unlocked: (libc)Character Input.
  789. * getwc: (libc)Character Input.
  790. * getwc_unlocked: (libc)Character Input.
  791. * getwd: (libc)Working Directory.
  792. * getw: (libc)Character Input.
  793. * glob64: (libc)Calling Glob.
  794. * globfree64: (libc)More Flags for Globbing.
  795. * globfree: (libc)More Flags for Globbing.
  796. * glob: (libc)Calling Glob.
  797. * gmtime: (libc)Broken-down Time.
  798. * gmtime_r: (libc)Broken-down Time.
  799. * grantpt: (libc)Allocation.
  800. * gsignal: (libc)Signaling Yourself.
  801. * gtty: (libc)BSD Terminal Modes.
  802. * hasmntopt: (libc)mtab.
  803. * hcreate: (libc)Hash Search Function.
  804. * hcreate_r: (libc)Hash Search Function.
  805. * hdestroy: (libc)Hash Search Function.
  806. * hdestroy_r: (libc)Hash Search Function.
  807. * hsearch: (libc)Hash Search Function.
  808. * hsearch_r: (libc)Hash Search Function.
  809. * htonl: (libc)Byte Order.
  810. * htons: (libc)Byte Order.
  811. * HUGE_VALF: (libc)Math Error Reporting.
  812. * HUGE_VAL: (libc)Math Error Reporting.
  813. * HUGE_VALL: (libc)Math Error Reporting.
  814. * HUPCL: (libc)Control Modes.
  815. * hypotf: (libc)Exponents and Logarithms.
  816. * hypot: (libc)Exponents and Logarithms.
  817. * hypotl: (libc)Exponents and Logarithms.
  818. * ICANON: (libc)Local Modes.
  819. * iconv_close: (libc)Generic Conversion Interface.
  820. * iconv: (libc)Generic Conversion Interface.
  821. * iconv_open: (libc)Generic Conversion Interface.
  822. * ICRNL: (libc)Input Modes.
  823. * IEXTEN: (libc)Local Modes.
  824. * if_freenameindex: (libc)Interface Naming.
  825. * if_indextoname: (libc)Interface Naming.
  826. * if_nameindex: (libc)Interface Naming.
  827. * if_nametoindex: (libc)Interface Naming.
  828. * IFNAMSIZ: (libc)Interface Naming.
  829. * IFTODT: (libc)Directory Entries.
  830. * IGNBRK: (libc)Input Modes.
  831. * IGNCR: (libc)Input Modes.
  832. * IGNPAR: (libc)Input Modes.
  833. * I: (libc)Complex Numbers.
  834. * ilogbf: (libc)Exponents and Logarithms.
  835. * ilogb: (libc)Exponents and Logarithms.
  836. * ilogbl: (libc)Exponents and Logarithms.
  837. * _Imaginary_I: (libc)Complex Numbers.
  838. * imaxabs: (libc)Absolute Value.
  839. * IMAXBEL: (libc)Input Modes.
  840. * imaxdiv: (libc)Integer Division.
  841. * in6addr_any: (libc)Host Address Data Type.
  842. * in6addr_loopback: (libc)Host Address Data Type.
  843. * INADDR_ANY: (libc)Host Address Data Type.
  844. * INADDR_BROADCAST: (libc)Host Address Data Type.
  845. * INADDR_LOOPBACK: (libc)Host Address Data Type.
  846. * INADDR_NONE: (libc)Host Address Data Type.
  847. * index: (libc)Search Functions.
  848. * inet_addr: (libc)Host Address Functions.
  849. * inet_aton: (libc)Host Address Functions.
  850. * inet_lnaof: (libc)Host Address Functions.
  851. * inet_makeaddr: (libc)Host Address Functions.
  852. * inet_netof: (libc)Host Address Functions.
  853. * inet_network: (libc)Host Address Functions.
  854. * inet_ntoa: (libc)Host Address Functions.
  855. * inet_ntop: (libc)Host Address Functions.
  856. * inet_pton: (libc)Host Address Functions.
  857. * INFINITY: (libc)Infinity and NaN.
  858. * initgroups: (libc)Setting Groups.
  859. * initstate: (libc)BSD Random.
  860. * initstate_r: (libc)BSD Random.
  861. * INLCR: (libc)Input Modes.
  862. * innetgr: (libc)Netgroup Membership.
  863. * INPCK: (libc)Input Modes.
  864. * ioctl: (libc)IOCTLs.
  865. * _IOFBF: (libc)Controlling Buffering.
  866. * _IOLBF: (libc)Controlling Buffering.
  867. * _IONBF: (libc)Controlling Buffering.
  868. * IPPORT_RESERVED: (libc)Ports.
  869. * IPPORT_USERRESERVED: (libc)Ports.
  870. * isalnum: (libc)Classification of Characters.
  871. * isalpha: (libc)Classification of Characters.
  872. * isascii: (libc)Classification of Characters.
  873. * isatty: (libc)Is It a Terminal.
  874. * isblank: (libc)Classification of Characters.
  875. * iscanonical: (libc)Floating Point Classes.
  876. * iscntrl: (libc)Classification of Characters.
  877. * isdigit: (libc)Classification of Characters.
  878. * iseqsig: (libc)FP Comparison Functions.
  879. * isfinite: (libc)Floating Point Classes.
  880. * isgraph: (libc)Classification of Characters.
  881. * isgreaterequal: (libc)FP Comparison Functions.
  882. * isgreater: (libc)FP Comparison Functions.
  883. * ISIG: (libc)Local Modes.
  884. * isinff: (libc)Floating Point Classes.
  885. * isinf: (libc)Floating Point Classes.
  886. * isinfl: (libc)Floating Point Classes.
  887. * islessequal: (libc)FP Comparison Functions.
  888. * islessgreater: (libc)FP Comparison Functions.
  889. * isless: (libc)FP Comparison Functions.
  890. * islower: (libc)Classification of Characters.
  891. * isnanf: (libc)Floating Point Classes.
  892. * isnan: (libc)Floating Point Classes.
  893. * isnan: (libc)Floating Point Classes.
  894. * isnanl: (libc)Floating Point Classes.
  895. * isnormal: (libc)Floating Point Classes.
  896. * isprint: (libc)Classification of Characters.
  897. * ispunct: (libc)Classification of Characters.
  898. * issignaling: (libc)Floating Point Classes.
  899. * isspace: (libc)Classification of Characters.
  900. * issubnormal: (libc)Floating Point Classes.
  901. * ISTRIP: (libc)Input Modes.
  902. * isunordered: (libc)FP Comparison Functions.
  903. * isupper: (libc)Classification of Characters.
  904. * iswalnum: (libc)Classification of Wide Characters.
  905. * iswalpha: (libc)Classification of Wide Characters.
  906. * iswblank: (libc)Classification of Wide Characters.
  907. * iswcntrl: (libc)Classification of Wide Characters.
  908. * iswctype: (libc)Classification of Wide Characters.
  909. * iswdigit: (libc)Classification of Wide Characters.
  910. * iswgraph: (libc)Classification of Wide Characters.
  911. * iswlower: (libc)Classification of Wide Characters.
  912. * iswprint: (libc)Classification of Wide Characters.
  913. * iswpunct: (libc)Classification of Wide Characters.
  914. * iswspace: (libc)Classification of Wide Characters.
  915. * iswupper: (libc)Classification of Wide Characters.
  916. * iswxdigit: (libc)Classification of Wide Characters.
  917. * isxdigit: (libc)Classification of Characters.
  918. * iszero: (libc)Floating Point Classes.
  919. * IXANY: (libc)Input Modes.
  920. * IXOFF: (libc)Input Modes.
  921. * IXON: (libc)Input Modes.
  922. * j0f: (libc)Special Functions.
  923. * j0: (libc)Special Functions.
  924. * j0l: (libc)Special Functions.
  925. * j1f: (libc)Special Functions.
  926. * j1: (libc)Special Functions.
  927. * j1l: (libc)Special Functions.
  928. * jnf: (libc)Special Functions.
  929. * jn: (libc)Special Functions.
  930. * jnl: (libc)Special Functions.
  931. * jrand48: (libc)SVID Random.
  932. * jrand48_r: (libc)SVID Random.
  933. * kill: (libc)Signaling Another Process.
  934. * killpg: (libc)Signaling Another Process.
  935. * l64a: (libc)Encode Binary Data.
  936. * labs: (libc)Absolute Value.
  937. * lcong48: (libc)SVID Random.
  938. * lcong48_r: (libc)SVID Random.
  939. * L_ctermid: (libc)Identifying the Terminal.
  940. * L_cuserid: (libc)Who Logged In.
  941. * ldexpf: (libc)Normalization Functions.
  942. * ldexp: (libc)Normalization Functions.
  943. * ldexpl: (libc)Normalization Functions.
  944. * ldiv: (libc)Integer Division.
  945. * lfind: (libc)Array Search Function.
  946. * lgammaf: (libc)Special Functions.
  947. * lgammaf_r: (libc)Special Functions.
  948. * lgamma: (libc)Special Functions.
  949. * lgammal: (libc)Special Functions.
  950. * lgammal_r: (libc)Special Functions.
  951. * lgamma_r: (libc)Special Functions.
  952. * LINE_MAX: (libc)Utility Limits.
  953. * link: (libc)Hard Links.
  954. * LINK_MAX: (libc)Limits for Files.
  955. * lio_listio64: (libc)Asynchronous Reads/Writes.
  956. * lio_listio: (libc)Asynchronous Reads/Writes.
  957. * listen: (libc)Listening.
  958. * llabs: (libc)Absolute Value.
  959. * lldiv: (libc)Integer Division.
  960. * llogbf: (libc)Exponents and Logarithms.
  961. * llogb: (libc)Exponents and Logarithms.
  962. * llogbl: (libc)Exponents and Logarithms.
  963. * llrintf: (libc)Rounding Functions.
  964. * llrint: (libc)Rounding Functions.
  965. * llrintl: (libc)Rounding Functions.
  966. * llroundf: (libc)Rounding Functions.
  967. * llround: (libc)Rounding Functions.
  968. * llroundl: (libc)Rounding Functions.
  969. * localeconv: (libc)The Lame Way to Locale Data.
  970. * localtime: (libc)Broken-down Time.
  971. * localtime_r: (libc)Broken-down Time.
  972. * log10f: (libc)Exponents and Logarithms.
  973. * log10: (libc)Exponents and Logarithms.
  974. * log10l: (libc)Exponents and Logarithms.
  975. * log1pf: (libc)Exponents and Logarithms.
  976. * log1p: (libc)Exponents and Logarithms.
  977. * log1pl: (libc)Exponents and Logarithms.
  978. * log2f: (libc)Exponents and Logarithms.
  979. * log2: (libc)Exponents and Logarithms.
  980. * log2l: (libc)Exponents and Logarithms.
  981. * logbf: (libc)Exponents and Logarithms.
  982. * logb: (libc)Exponents and Logarithms.
  983. * logbl: (libc)Exponents and Logarithms.
  984. * logf: (libc)Exponents and Logarithms.
  985. * login: (libc)Logging In and Out.
  986. * login_tty: (libc)Logging In and Out.
  987. * log: (libc)Exponents and Logarithms.
  988. * logl: (libc)Exponents and Logarithms.
  989. * logout: (libc)Logging In and Out.
  990. * logwtmp: (libc)Logging In and Out.
  991. * longjmp: (libc)Non-Local Details.
  992. * lrand48: (libc)SVID Random.
  993. * lrand48_r: (libc)SVID Random.
  994. * lrintf: (libc)Rounding Functions.
  995. * lrint: (libc)Rounding Functions.
  996. * lrintl: (libc)Rounding Functions.
  997. * lroundf: (libc)Rounding Functions.
  998. * lround: (libc)Rounding Functions.
  999. * lroundl: (libc)Rounding Functions.
  1000. * lsearch: (libc)Array Search Function.
  1001. * lseek64: (libc)File Position Primitive.
  1002. * lseek: (libc)File Position Primitive.
  1003. * lstat64: (libc)Reading Attributes.
  1004. * lstat: (libc)Reading Attributes.
  1005. * L_tmpnam: (libc)Temporary Files.
  1006. * lutimes: (libc)File Times.
  1007. * madvise: (libc)Memory-mapped I/O.
  1008. * makecontext: (libc)System V contexts.
  1009. * mallinfo: (libc)Statistics of Malloc.
  1010. * malloc: (libc)Basic Allocation.
  1011. * mallopt: (libc)Malloc Tunable Parameters.
  1012. * MAX_CANON: (libc)Limits for Files.
  1013. * MAX_INPUT: (libc)Limits for Files.
  1014. * MAXNAMLEN: (libc)Limits for Files.
  1015. * MAXSYMLINKS: (libc)Symbolic Links.
  1016. * MB_CUR_MAX: (libc)Selecting the Conversion.
  1017. * mblen: (libc)Non-reentrant Character Conversion.
  1018. * MB_LEN_MAX: (libc)Selecting the Conversion.
  1019. * mbrlen: (libc)Converting a Character.
  1020. * mbrtowc: (libc)Converting a Character.
  1021. * mbsinit: (libc)Keeping the state.
  1022. * mbsnrtowcs: (libc)Converting Strings.
  1023. * mbsrtowcs: (libc)Converting Strings.
  1024. * mbstowcs: (libc)Non-reentrant String Conversion.
  1025. * mbtowc: (libc)Non-reentrant Character Conversion.
  1026. * mcheck: (libc)Heap Consistency Checking.
  1027. * MDMBUF: (libc)Control Modes.
  1028. * memalign: (libc)Aligned Memory Blocks.
  1029. * memccpy: (libc)Copying Strings and Arrays.
  1030. * memchr: (libc)Search Functions.
  1031. * memcmp: (libc)String/Array Comparison.
  1032. * memcpy: (libc)Copying Strings and Arrays.
  1033. * memfrob: (libc)Trivial Encryption.
  1034. * memmem: (libc)Search Functions.
  1035. * memmove: (libc)Copying Strings and Arrays.
  1036. * mempcpy: (libc)Copying Strings and Arrays.
  1037. * memrchr: (libc)Search Functions.
  1038. * memset: (libc)Copying Strings and Arrays.
  1039. * mkdir: (libc)Creating Directories.
  1040. * mkdtemp: (libc)Temporary Files.
  1041. * mkfifo: (libc)FIFO Special Files.
  1042. * mknod: (libc)Making Special Files.
  1043. * mkstemp: (libc)Temporary Files.
  1044. * mktemp: (libc)Temporary Files.
  1045. * mktime: (libc)Broken-down Time.
  1046. * mlockall: (libc)Page Lock Functions.
  1047. * mlock: (libc)Page Lock Functions.
  1048. * mmap64: (libc)Memory-mapped I/O.
  1049. * mmap: (libc)Memory-mapped I/O.
  1050. * modff: (libc)Rounding Functions.
  1051. * modf: (libc)Rounding Functions.
  1052. * modfl: (libc)Rounding Functions.
  1053. * mount: (libc)Mount-Unmount-Remount.
  1054. * mprobe: (libc)Heap Consistency Checking.
  1055. * mrand48: (libc)SVID Random.
  1056. * mrand48_r: (libc)SVID Random.
  1057. * mremap: (libc)Memory-mapped I/O.
  1058. * MSG_DONTROUTE: (libc)Socket Data Options.
  1059. * MSG_OOB: (libc)Socket Data Options.
  1060. * MSG_PEEK: (libc)Socket Data Options.
  1061. * msync: (libc)Memory-mapped I/O.
  1062. * mtrace: (libc)Tracing malloc.
  1063. * munlockall: (libc)Page Lock Functions.
  1064. * munlock: (libc)Page Lock Functions.
  1065. * munmap: (libc)Memory-mapped I/O.
  1066. * muntrace: (libc)Tracing malloc.
  1067. * NAME_MAX: (libc)Limits for Files.
  1068. * nanf: (libc)FP Bit Twiddling.
  1069. * nan: (libc)FP Bit Twiddling.
  1070. * NAN: (libc)Infinity and NaN.
  1071. * nanl: (libc)FP Bit Twiddling.
  1072. * nanosleep: (libc)Sleeping.
  1073. * NCCS: (libc)Mode Data Types.
  1074. * nearbyintf: (libc)Rounding Functions.
  1075. * nearbyint: (libc)Rounding Functions.
  1076. * nearbyintl: (libc)Rounding Functions.
  1077. * nextafterf: (libc)FP Bit Twiddling.
  1078. * nextafter: (libc)FP Bit Twiddling.
  1079. * nextafterl: (libc)FP Bit Twiddling.
  1080. * nextdownf: (libc)FP Bit Twiddling.
  1081. * nextdown: (libc)FP Bit Twiddling.
  1082. * nextdownl: (libc)FP Bit Twiddling.
  1083. * nexttowardf: (libc)FP Bit Twiddling.
  1084. * nexttoward: (libc)FP Bit Twiddling.
  1085. * nexttowardl: (libc)FP Bit Twiddling.
  1086. * nextupf: (libc)FP Bit Twiddling.
  1087. * nextup: (libc)FP Bit Twiddling.
  1088. * nextupl: (libc)FP Bit Twiddling.
  1089. * nftw64: (libc)Working with Directory Trees.
  1090. * nftw: (libc)Working with Directory Trees.
  1091. * ngettext: (libc)Advanced gettext functions.
  1092. * NGROUPS_MAX: (libc)General Limits.
  1093. * nice: (libc)Traditional Scheduling Functions.
  1094. * nl_langinfo: (libc)The Elegant and Fast Way.
  1095. * NOFLSH: (libc)Local Modes.
  1096. * NOKERNINFO: (libc)Local Modes.
  1097. * nrand48: (libc)SVID Random.
  1098. * nrand48_r: (libc)SVID Random.
  1099. * NSIG: (libc)Standard Signals.
  1100. * ntohl: (libc)Byte Order.
  1101. * ntohs: (libc)Byte Order.
  1102. * ntp_adjtime: (libc)High Accuracy Clock.
  1103. * ntp_gettime: (libc)High Accuracy Clock.
  1104. * NULL: (libc)Null Pointer Constant.
  1105. * O_ACCMODE: (libc)Access Modes.
  1106. * O_APPEND: (libc)Operating Modes.
  1107. * O_ASYNC: (libc)Operating Modes.
  1108. * obstack_1grow_fast: (libc)Extra Fast Growing.
  1109. * obstack_1grow: (libc)Growing Objects.
  1110. * obstack_alignment_mask: (libc)Obstacks Data Alignment.
  1111. * obstack_alloc: (libc)Allocation in an Obstack.
  1112. * obstack_base: (libc)Status of an Obstack.
  1113. * obstack_blank_fast: (libc)Extra Fast Growing.
  1114. * obstack_blank: (libc)Growing Objects.
  1115. * obstack_chunk_size: (libc)Obstack Chunks.
  1116. * obstack_copy0: (libc)Allocation in an Obstack.
  1117. * obstack_copy: (libc)Allocation in an Obstack.
  1118. * obstack_finish: (libc)Growing Objects.
  1119. * obstack_free: (libc)Freeing Obstack Objects.
  1120. * obstack_grow0: (libc)Growing Objects.
  1121. * obstack_grow: (libc)Growing Objects.
  1122. * obstack_init: (libc)Preparing for Obstacks.
  1123. * obstack_int_grow_fast: (libc)Extra Fast Growing.
  1124. * obstack_int_grow: (libc)Growing Objects.
  1125. * obstack_next_free: (libc)Status of an Obstack.
  1126. * obstack_object_size: (libc)Growing Objects.
  1127. * obstack_object_size: (libc)Status of an Obstack.
  1128. * obstack_printf: (libc)Dynamic Output.
  1129. * obstack_ptr_grow_fast: (libc)Extra Fast Growing.
  1130. * obstack_ptr_grow: (libc)Growing Objects.
  1131. * obstack_room: (libc)Extra Fast Growing.
  1132. * obstack_vprintf: (libc)Variable Arguments Output.
  1133. * O_CREAT: (libc)Open-time Flags.
  1134. * O_EXCL: (libc)Open-time Flags.
  1135. * O_EXEC: (libc)Access Modes.
  1136. * O_EXLOCK: (libc)Open-time Flags.
  1137. * offsetof: (libc)Structure Measurement.
  1138. * O_FSYNC: (libc)Operating Modes.
  1139. * O_IGNORE_CTTY: (libc)Open-time Flags.
  1140. * O_NDELAY: (libc)Operating Modes.
  1141. * on_exit: (libc)Cleanups on Exit.
  1142. * ONLCR: (libc)Output Modes.
  1143. * O_NOATIME: (libc)Operating Modes.
  1144. * O_NOCTTY: (libc)Open-time Flags.
  1145. * ONOEOT: (libc)Output Modes.
  1146. * O_NOLINK: (libc)Open-time Flags.
  1147. * O_NONBLOCK: (libc)Open-time Flags.
  1148. * O_NONBLOCK: (libc)Operating Modes.
  1149. * O_NOTRANS: (libc)Open-time Flags.
  1150. * open64: (libc)Opening and Closing Files.
  1151. * opendir: (libc)Opening a Directory.
  1152. * open: (libc)Opening and Closing Files.
  1153. * openlog: (libc)openlog.
  1154. * OPEN_MAX: (libc)General Limits.
  1155. * open_memstream: (libc)String Streams.
  1156. * openpty: (libc)Pseudo-Terminal Pairs.
  1157. * OPOST: (libc)Output Modes.
  1158. * O_RDONLY: (libc)Access Modes.
  1159. * O_RDWR: (libc)Access Modes.
  1160. * O_READ: (libc)Access Modes.
  1161. * O_SHLOCK: (libc)Open-time Flags.
  1162. * O_SYNC: (libc)Operating Modes.
  1163. * O_TRUNC: (libc)Open-time Flags.
  1164. * O_WRITE: (libc)Access Modes.
  1165. * O_WRONLY: (libc)Access Modes.
  1166. * OXTABS: (libc)Output Modes.
  1167. * PA_FLAG_MASK: (libc)Parsing a Template String.
  1168. * PARENB: (libc)Control Modes.
  1169. * PARMRK: (libc)Input Modes.
  1170. * PARODD: (libc)Control Modes.
  1171. * parse_printf_format: (libc)Parsing a Template String.
  1172. * pathconf: (libc)Pathconf.
  1173. * PATH_MAX: (libc)Limits for Files.
  1174. * _PATH_UTMP: (libc)Manipulating the Database.
  1175. * _PATH_WTMP: (libc)Manipulating the Database.
  1176. * pause: (libc)Using Pause.
  1177. * pclose: (libc)Pipe to a Subprocess.
  1178. * PENDIN: (libc)Local Modes.
  1179. * perror: (libc)Error Messages.
  1180. * PF_FILE: (libc)Local Namespace Details.
  1181. * PF_INET6: (libc)Internet Namespace.
  1182. * PF_INET: (libc)Internet Namespace.
  1183. * PF_LOCAL: (libc)Local Namespace Details.
  1184. * PF_UNIX: (libc)Local Namespace Details.
  1185. * PIPE_BUF: (libc)Limits for Files.
  1186. * pipe: (libc)Creating a Pipe.
  1187. * popen: (libc)Pipe to a Subprocess.
  1188. * _POSIX2_C_DEV: (libc)System Options.
  1189. * _POSIX2_C_VERSION: (libc)Version Supported.
  1190. * _POSIX2_FORT_DEV: (libc)System Options.
  1191. * _POSIX2_FORT_RUN: (libc)System Options.
  1192. * _POSIX2_LOCALEDEF: (libc)System Options.
  1193. * _POSIX2_SW_DEV: (libc)System Options.
  1194. * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
  1195. * posix_fallocate64: (libc)Storage Allocation.
  1196. * posix_fallocate: (libc)Storage Allocation.
  1197. * _POSIX_JOB_CONTROL: (libc)System Options.
  1198. * posix_memalign: (libc)Aligned Memory Blocks.
  1199. * _POSIX_NO_TRUNC: (libc)Options for Files.
  1200. * _POSIX_SAVED_IDS: (libc)System Options.
  1201. * _POSIX_VDISABLE: (libc)Options for Files.
  1202. * _POSIX_VERSION: (libc)Version Supported.
  1203. * pow10f: (libc)Exponents and Logarithms.
  1204. * pow10: (libc)Exponents and Logarithms.
  1205. * pow10l: (libc)Exponents and Logarithms.
  1206. * powf: (libc)Exponents and Logarithms.
  1207. * pow: (libc)Exponents and Logarithms.
  1208. * powl: (libc)Exponents and Logarithms.
  1209. * __ppc_get_timebase_freq: (libc)PowerPC.
  1210. * __ppc_get_timebase: (libc)PowerPC.
  1211. * __ppc_mdoio: (libc)PowerPC.
  1212. * __ppc_mdoom: (libc)PowerPC.
  1213. * __ppc_set_ppr_low: (libc)PowerPC.
  1214. * __ppc_set_ppr_med_high: (libc)PowerPC.
  1215. * __ppc_set_ppr_med: (libc)PowerPC.
  1216. * __ppc_set_ppr_med_low: (libc)PowerPC.
  1217. * __ppc_set_ppr_very_low: (libc)PowerPC.
  1218. * __ppc_yield: (libc)PowerPC.
  1219. * pread64: (libc)I/O Primitives.
  1220. * pread: (libc)I/O Primitives.
  1221. * printf: (libc)Formatted Output Functions.
  1222. * printf_size_info: (libc)Predefined Printf Handlers.
  1223. * printf_size: (libc)Predefined Printf Handlers.
  1224. * psignal: (libc)Signal Messages.
  1225. * pthread_getattr_default_np: (libc)Default Thread Attributes.
  1226. * pthread_getspecific: (libc)Thread-specific Data.
  1227. * pthread_key_create: (libc)Thread-specific Data.
  1228. * pthread_key_delete: (libc)Thread-specific Data.
  1229. * pthread_setattr_default_np: (libc)Default Thread Attributes.
  1230. * pthread_setspecific: (libc)Thread-specific Data.
  1231. * P_tmpdir: (libc)Temporary Files.
  1232. * ptsname: (libc)Allocation.
  1233. * ptsname_r: (libc)Allocation.
  1234. * putchar: (libc)Simple Output.
  1235. * putchar_unlocked: (libc)Simple Output.
  1236. * putc: (libc)Simple Output.
  1237. * putc_unlocked: (libc)Simple Output.
  1238. * putenv: (libc)Environment Access.
  1239. * putpwent: (libc)Writing a User Entry.
  1240. * puts: (libc)Simple Output.
  1241. * pututline: (libc)Manipulating the Database.
  1242. * pututxline: (libc)XPG Functions.
  1243. * putwchar: (libc)Simple Output.
  1244. * putwchar_unlocked: (libc)Simple Output.
  1245. * putwc: (libc)Simple Output.
  1246. * putwc_unlocked: (libc)Simple Output.
  1247. * putw: (libc)Simple Output.
  1248. * pwrite64: (libc)I/O Primitives.
  1249. * pwrite: (libc)I/O Primitives.
  1250. * qecvt: (libc)System V Number Conversion.
  1251. * qecvt_r: (libc)System V Number Conversion.
  1252. * qfcvt: (libc)System V Number Conversion.
  1253. * qfcvt_r: (libc)System V Number Conversion.
  1254. * qgcvt: (libc)System V Number Conversion.
  1255. * qsort: (libc)Array Sort Function.
  1256. * raise: (libc)Signaling Yourself.
  1257. * rand: (libc)ISO Random.
  1258. * RAND_MAX: (libc)ISO Random.
  1259. * random: (libc)BSD Random.
  1260. * random_r: (libc)BSD Random.
  1261. * rand_r: (libc)ISO Random.
  1262. * rawmemchr: (libc)Search Functions.
  1263. * readdir64: (libc)Reading/Closing Directory.
  1264. * readdir64_r: (libc)Reading/Closing Directory.
  1265. * readdir: (libc)Reading/Closing Directory.
  1266. * readdir_r: (libc)Reading/Closing Directory.
  1267. * read: (libc)I/O Primitives.
  1268. * readlink: (libc)Symbolic Links.
  1269. * readv: (libc)Scatter-Gather.
  1270. * realloc: (libc)Changing Block Size.
  1271. * realpath: (libc)Symbolic Links.
  1272. * recvfrom: (libc)Receiving Datagrams.
  1273. * recv: (libc)Receiving Data.
  1274. * recvmsg: (libc)Receiving Datagrams.
  1275. * RE_DUP_MAX: (libc)General Limits.
  1276. * regcomp: (libc)POSIX Regexp Compilation.
  1277. * regerror: (libc)Regexp Cleanup.
  1278. * regexec: (libc)Matching POSIX Regexps.
  1279. * regfree: (libc)Regexp Cleanup.
  1280. * register_printf_function: (libc)Registering New Conversions.
  1281. * remainderf: (libc)Remainder Functions.
  1282. * remainder: (libc)Remainder Functions.
  1283. * remainderl: (libc)Remainder Functions.
  1284. * remove: (libc)Deleting Files.
  1285. * rename: (libc)Renaming Files.
  1286. * rewinddir: (libc)Random Access Directory.
  1287. * rewind: (libc)File Positioning.
  1288. * rindex: (libc)Search Functions.
  1289. * rintf: (libc)Rounding Functions.
  1290. * rint: (libc)Rounding Functions.
  1291. * rintl: (libc)Rounding Functions.
  1292. * RLIM_INFINITY: (libc)Limits on Resources.
  1293. * rmdir: (libc)Deleting Files.
  1294. * R_OK: (libc)Testing File Access.
  1295. * roundevenf: (libc)Rounding Functions.
  1296. * roundeven: (libc)Rounding Functions.
  1297. * roundevenl: (libc)Rounding Functions.
  1298. * roundf: (libc)Rounding Functions.
  1299. * round: (libc)Rounding Functions.
  1300. * roundl: (libc)Rounding Functions.
  1301. * rpmatch: (libc)Yes-or-No Questions.
  1302. * SA_NOCLDSTOP: (libc)Flags for Sigaction.
  1303. * SA_ONSTACK: (libc)Flags for Sigaction.
  1304. * SA_RESTART: (libc)Flags for Sigaction.
  1305. * sbrk: (libc)Resizing the Data Segment.
  1306. * scalbf: (libc)Normalization Functions.
  1307. * scalb: (libc)Normalization Functions.
  1308. * scalbl: (libc)Normalization Functions.
  1309. * scalblnf: (libc)Normalization Functions.
  1310. * scalbln: (libc)Normalization Functions.
  1311. * scalblnl: (libc)Normalization Functions.
  1312. * scalbnf: (libc)Normalization Functions.
  1313. * scalbn: (libc)Normalization Functions.
  1314. * scalbnl: (libc)Normalization Functions.
  1315. * scandir64: (libc)Scanning Directory Content.
  1316. * scandir: (libc)Scanning Directory Content.
  1317. * scanf: (libc)Formatted Input Functions.
  1318. * sched_getaffinity: (libc)CPU Affinity.
  1319. * sched_getparam: (libc)Basic Scheduling Functions.
  1320. * sched_get_priority_max: (libc)Basic Scheduling Functions.
  1321. * sched_get_priority_min: (libc)Basic Scheduling Functions.
  1322. * sched_getscheduler: (libc)Basic Scheduling Functions.
  1323. * sched_rr_get_interval: (libc)Basic Scheduling Functions.
  1324. * sched_setaffinity: (libc)CPU Affinity.
  1325. * sched_setparam: (libc)Basic Scheduling Functions.
  1326. * sched_setscheduler: (libc)Basic Scheduling Functions.
  1327. * sched_yield: (libc)Basic Scheduling Functions.
  1328. * secure_getenv: (libc)Environment Access.
  1329. * seed48: (libc)SVID Random.
  1330. * seed48_r: (libc)SVID Random.
  1331. * SEEK_CUR: (libc)File Positioning.
  1332. * seekdir: (libc)Random Access Directory.
  1333. * SEEK_END: (libc)File Positioning.
  1334. * SEEK_SET: (libc)File Positioning.
  1335. * select: (libc)Waiting for I/O.
  1336. * sem_close: (libc)Semaphores.
  1337. * semctl: (libc)Semaphores.
  1338. * sem_destroy: (libc)Semaphores.
  1339. * semget: (libc)Semaphores.
  1340. * sem_getvalue: (libc)Semaphores.
  1341. * sem_init: (libc)Semaphores.
  1342. * sem_open: (libc)Semaphores.
  1343. * semop: (libc)Semaphores.
  1344. * sem_post: (libc)Semaphores.
  1345. * semtimedop: (libc)Semaphores.
  1346. * sem_timedwait: (libc)Semaphores.
  1347. * sem_trywait: (libc)Semaphores.
  1348. * sem_unlink: (libc)Semaphores.
  1349. * sem_wait: (libc)Semaphores.
  1350. * send: (libc)Sending Data.
  1351. * sendmsg: (libc)Receiving Datagrams.
  1352. * sendto: (libc)Sending Datagrams.
  1353. * setbuffer: (libc)Controlling Buffering.
  1354. * setbuf: (libc)Controlling Buffering.
  1355. * setcontext: (libc)System V contexts.
  1356. * setdomainname: (libc)Host Identification.
  1357. * setegid: (libc)Setting Groups.
  1358. * setenv: (libc)Environment Access.
  1359. * seteuid: (libc)Setting User ID.
  1360. * setfsent: (libc)fstab.
  1361. * setgid: (libc)Setting Groups.
  1362. * setgrent: (libc)Scanning All Groups.
  1363. * setgroups: (libc)Setting Groups.
  1364. * sethostent: (libc)Host Names.
  1365. * sethostid: (libc)Host Identification.
  1366. * sethostname: (libc)Host Identification.
  1367. * setitimer: (libc)Setting an Alarm.
  1368. * setjmp: (libc)Non-Local Details.
  1369. * setkey: (libc)DES Encryption.
  1370. * setkey_r: (libc)DES Encryption.
  1371. * setlinebuf: (libc)Controlling Buffering.
  1372. * setlocale: (libc)Setting the Locale.
  1373. * setlogmask: (libc)setlogmask.
  1374. * setmntent: (libc)mtab.
  1375. * setnetent: (libc)Networks Database.
  1376. * setnetgrent: (libc)Lookup Netgroup.
  1377. * setpayloadf: (libc)FP Bit Twiddling.
  1378. * setpayload: (libc)FP Bit Twiddling.
  1379. * setpayloadl: (libc)FP Bit Twiddling.
  1380. * setpayloadsigf: (libc)FP Bit Twiddling.
  1381. * setpayloadsig: (libc)FP Bit Twiddling.
  1382. * setpayloadsigl: (libc)FP Bit Twiddling.
  1383. * setpgid: (libc)Process Group Functions.
  1384. * setpgrp: (libc)Process Group Functions.
  1385. * setpriority: (libc)Traditional Scheduling Functions.
  1386. * setprotoent: (libc)Protocols Database.
  1387. * setpwent: (libc)Scanning All Users.
  1388. * setregid: (libc)Setting Groups.
  1389. * setreuid: (libc)Setting User ID.
  1390. * setrlimit64: (libc)Limits on Resources.
  1391. * setrlimit: (libc)Limits on Resources.
  1392. * setservent: (libc)Services Database.
  1393. * setsid: (libc)Process Group Functions.
  1394. * setsockopt: (libc)Socket Option Functions.
  1395. * setstate: (libc)BSD Random.
  1396. * setstate_r: (libc)BSD Random.
  1397. * settimeofday: (libc)High-Resolution Calendar.
  1398. * setuid: (libc)Setting User ID.
  1399. * setutent: (libc)Manipulating the Database.
  1400. * setutxent: (libc)XPG Functions.
  1401. * setvbuf: (libc)Controlling Buffering.
  1402. * shm_open: (libc)Memory-mapped I/O.
  1403. * shm_unlink: (libc)Memory-mapped I/O.
  1404. * shutdown: (libc)Closing a Socket.
  1405. * S_IFMT: (libc)Testing File Type.
  1406. * SIGABRT: (libc)Program Error Signals.
  1407. * sigaction: (libc)Advanced Signal Handling.
  1408. * sigaddset: (libc)Signal Sets.
  1409. * SIGALRM: (libc)Alarm Signals.
  1410. * sigaltstack: (libc)Signal Stack.
  1411. * sigblock: (libc)BSD Signal Handling.
  1412. * SIGBUS: (libc)Program Error Signals.
  1413. * SIGCHLD: (libc)Job Control Signals.
  1414. * SIGCLD: (libc)Job Control Signals.
  1415. * SIGCONT: (libc)Job Control Signals.
  1416. * sigdelset: (libc)Signal Sets.
  1417. * sigemptyset: (libc)Signal Sets.
  1418. * SIGEMT: (libc)Program Error Signals.
  1419. * SIG_ERR: (libc)Basic Signal Handling.
  1420. * sigfillset: (libc)Signal Sets.
  1421. * SIGFPE: (libc)Program Error Signals.
  1422. * SIGHUP: (libc)Termination Signals.
  1423. * SIGILL: (libc)Program Error Signals.
  1424. * SIGINFO: (libc)Miscellaneous Signals.
  1425. * siginterrupt: (libc)BSD Signal Handling.
  1426. * SIGINT: (libc)Termination Signals.
  1427. * SIGIO: (libc)Asynchronous I/O Signals.
  1428. * SIGIOT: (libc)Program Error Signals.
  1429. * sigismember: (libc)Signal Sets.
  1430. * SIGKILL: (libc)Termination Signals.
  1431. * siglongjmp: (libc)Non-Local Exits and Signals.
  1432. * SIGLOST: (libc)Operation Error Signals.
  1433. * sigmask: (libc)BSD Signal Handling.
  1434. * signal: (libc)Basic Signal Handling.
  1435. * signbit: (libc)FP Bit Twiddling.
  1436. * significandf: (libc)Normalization Functions.
  1437. * significand: (libc)Normalization Functions.
  1438. * significandl: (libc)Normalization Functions.
  1439. * sigpause: (libc)BSD Signal Handling.
  1440. * sigpending: (libc)Checking for Pending Signals.
  1441. * SIGPIPE: (libc)Operation Error Signals.
  1442. * SIGPOLL: (libc)Asynchronous I/O Signals.
  1443. * sigprocmask: (libc)Process Signal Mask.
  1444. * SIGPROF: (libc)Alarm Signals.
  1445. * SIGQUIT: (libc)Termination Signals.
  1446. * SIGSEGV: (libc)Program Error Signals.
  1447. * sigsetjmp: (libc)Non-Local Exits and Signals.
  1448. * sigsetmask: (libc)BSD Signal Handling.
  1449. * sigstack: (libc)Signal Stack.
  1450. * SIGSTOP: (libc)Job Control Signals.
  1451. * sigsuspend: (libc)Sigsuspend.
  1452. * SIGSYS: (libc)Program Error Signals.
  1453. * SIGTERM: (libc)Termination Signals.
  1454. * SIGTRAP: (libc)Program Error Signals.
  1455. * SIGTSTP: (libc)Job Control Signals.
  1456. * SIGTTIN: (libc)Job Control Signals.
  1457. * SIGTTOU: (libc)Job Control Signals.
  1458. * SIGURG: (libc)Asynchronous I/O Signals.
  1459. * SIGUSR1: (libc)Miscellaneous Signals.
  1460. * SIGUSR2: (libc)Miscellaneous Signals.
  1461. * SIGVTALRM: (libc)Alarm Signals.
  1462. * SIGWINCH: (libc)Miscellaneous Signals.
  1463. * SIGXCPU: (libc)Operation Error Signals.
  1464. * SIGXFSZ: (libc)Operation Error Signals.
  1465. * sincosf: (libc)Trig Functions.
  1466. * sincos: (libc)Trig Functions.
  1467. * sincosl: (libc)Trig Functions.
  1468. * sinf: (libc)Trig Functions.
  1469. * sinhf: (libc)Hyperbolic Functions.
  1470. * sinh: (libc)Hyperbolic Functions.
  1471. * sinhl: (libc)Hyperbolic Functions.
  1472. * sin: (libc)Trig Functions.
  1473. * sinl: (libc)Trig Functions.
  1474. * S_ISBLK: (libc)Testing File Type.
  1475. * S_ISCHR: (libc)Testing File Type.
  1476. * S_ISDIR: (libc)Testing File Type.
  1477. * S_ISFIFO: (libc)Testing File Type.
  1478. * S_ISLNK: (libc)Testing File Type.
  1479. * S_ISREG: (libc)Testing File Type.
  1480. * S_ISSOCK: (libc)Testing File Type.
  1481. * sleep: (libc)Sleeping.
  1482. * SNANF: (libc)Infinity and NaN.
  1483. * SNAN: (libc)Infinity and NaN.
  1484. * SNANL: (libc)Infinity and NaN.
  1485. * snprintf: (libc)Formatted Output Functions.
  1486. * SOCK_DGRAM: (libc)Communication Styles.
  1487. * socket: (libc)Creating a Socket.
  1488. * socketpair: (libc)Socket Pairs.
  1489. * SOCK_RAW: (libc)Communication Styles.
  1490. * SOCK_RDM: (libc)Communication Styles.
  1491. * SOCK_SEQPACKET: (libc)Communication Styles.
  1492. * SOCK_STREAM: (libc)Communication Styles.
  1493. * SOL_SOCKET: (libc)Socket-Level Options.
  1494. * sprintf: (libc)Formatted Output Functions.
  1495. * sqrtf: (libc)Exponents and Logarithms.
  1496. * sqrt: (libc)Exponents and Logarithms.
  1497. * sqrtl: (libc)Exponents and Logarithms.
  1498. * srand48: (libc)SVID Random.
  1499. * srand48_r: (libc)SVID Random.
  1500. * srand: (libc)ISO Random.
  1501. * srandom: (libc)BSD Random.
  1502. * srandom_r: (libc)BSD Random.
  1503. * sscanf: (libc)Formatted Input Functions.
  1504. * ssignal: (libc)Basic Signal Handling.
  1505. * SSIZE_MAX: (libc)General Limits.
  1506. * stat64: (libc)Reading Attributes.
  1507. * stat: (libc)Reading Attributes.
  1508. * stime: (libc)Simple Calendar Time.
  1509. * stpcpy: (libc)Copying Strings and Arrays.
  1510. * stpncpy: (libc)Truncating Strings.
  1511. * strcasecmp: (libc)String/Array Comparison.
  1512. * strcasestr: (libc)Search Functions.
  1513. * strcat: (libc)Concatenating Strings.
  1514. * strchr: (libc)Search Functions.
  1515. * strchrnul: (libc)Search Functions.
  1516. * strcmp: (libc)String/Array Comparison.
  1517. * strcoll: (libc)Collation Functions.
  1518. * strcpy: (libc)Copying Strings and Arrays.
  1519. * strcspn: (libc)Search Functions.
  1520. * strdupa: (libc)Copying Strings and Arrays.
  1521. * strdup: (libc)Copying Strings and Arrays.
  1522. * STREAM_MAX: (libc)General Limits.
  1523. * strerror: (libc)Error Messages.
  1524. * strerror_r: (libc)Error Messages.
  1525. * strfmon: (libc)Formatting Numbers.
  1526. * strfromd: (libc)Printing of Floats.
  1527. * strfromf: (libc)Printing of Floats.
  1528. * strfroml: (libc)Printing of Floats.
  1529. * strfry: (libc)strfry.
  1530. * strftime: (libc)Formatting Calendar Time.
  1531. * strlen: (libc)String Length.
  1532. * strncasecmp: (libc)String/Array Comparison.
  1533. * strncat: (libc)Truncating Strings.
  1534. * strncmp: (libc)String/Array Comparison.
  1535. * strncpy: (libc)Truncating Strings.
  1536. * strndupa: (libc)Truncating Strings.
  1537. * strndup: (libc)Truncating Strings.
  1538. * strnlen: (libc)String Length.
  1539. * strpbrk: (libc)Search Functions.
  1540. * strptime: (libc)Low-Level Time String Parsing.
  1541. * strrchr: (libc)Search Functions.
  1542. * strsep: (libc)Finding Tokens in a String.
  1543. * strsignal: (libc)Signal Messages.
  1544. * strspn: (libc)Search Functions.
  1545. * strstr: (libc)Search Functions.
  1546. * strtod: (libc)Parsing of Floats.
  1547. * strtof: (libc)Parsing of Floats.
  1548. * strtoimax: (libc)Parsing of Integers.
  1549. * strtok: (libc)Finding Tokens in a String.
  1550. * strtok_r: (libc)Finding Tokens in a String.
  1551. * strtold: (libc)Parsing of Floats.
  1552. * strtol: (libc)Parsing of Integers.
  1553. * strtoll: (libc)Parsing of Integers.
  1554. * strtoq: (libc)Parsing of Integers.
  1555. * strtoul: (libc)Parsing of Integers.
  1556. * strtoull: (libc)Parsing of Integers.
  1557. * strtoumax: (libc)Parsing of Integers.
  1558. * strtouq: (libc)Parsing of Integers.
  1559. * strverscmp: (libc)String/Array Comparison.
  1560. * strxfrm: (libc)Collation Functions.
  1561. * stty: (libc)BSD Terminal Modes.
  1562. * S_TYPEISMQ: (libc)Testing File Type.
  1563. * S_TYPEISSEM: (libc)Testing File Type.
  1564. * S_TYPEISSHM: (libc)Testing File Type.
  1565. * SUN_LEN: (libc)Local Namespace Details.
  1566. * swapcontext: (libc)System V contexts.
  1567. * swprintf: (libc)Formatted Output Functions.
  1568. * swscanf: (libc)Formatted Input Functions.
  1569. * symlink: (libc)Symbolic Links.
  1570. * sync: (libc)Synchronizing I/O.
  1571. * syscall: (libc)System Calls.
  1572. * sysconf: (libc)Sysconf Definition.
  1573. * sysctl: (libc)System Parameters.
  1574. * syslog: (libc)syslog; vsyslog.
  1575. * system: (libc)Running a Command.
  1576. * sysv_signal: (libc)Basic Signal Handling.
  1577. * tanf: (libc)Trig Functions.
  1578. * tanhf: (libc)Hyperbolic Functions.
  1579. * tanh: (libc)Hyperbolic Functions.
  1580. * tanhl: (libc)Hyperbolic Functions.
  1581. * tan: (libc)Trig Functions.
  1582. * tanl: (libc)Trig Functions.
  1583. * tcdrain: (libc)Line Control.
  1584. * tcflow: (libc)Line Control.
  1585. * tcflush: (libc)Line Control.
  1586. * tcgetattr: (libc)Mode Functions.
  1587. * tcgetpgrp: (libc)Terminal Access Functions.
  1588. * tcgetsid: (libc)Terminal Access Functions.
  1589. * tcsendbreak: (libc)Line Control.
  1590. * tcsetattr: (libc)Mode Functions.
  1591. * tcsetpgrp: (libc)Terminal Access Functions.
  1592. * tdelete: (libc)Tree Search Function.
  1593. * tdestroy: (libc)Tree Search Function.
  1594. * telldir: (libc)Random Access Directory.
  1595. * tempnam: (libc)Temporary Files.
  1596. * textdomain: (libc)Locating gettext catalog.
  1597. * tfind: (libc)Tree Search Function.
  1598. * tgammaf: (libc)Special Functions.
  1599. * tgamma: (libc)Special Functions.
  1600. * tgammal: (libc)Special Functions.
  1601. * timegm: (libc)Broken-down Time.
  1602. * time: (libc)Simple Calendar Time.
  1603. * timelocal: (libc)Broken-down Time.
  1604. * times: (libc)Processor Time.
  1605. * tmpfile64: (libc)Temporary Files.
  1606. * tmpfile: (libc)Temporary Files.
  1607. * TMP_MAX: (libc)Temporary Files.
  1608. * tmpnam: (libc)Temporary Files.
  1609. * tmpnam_r: (libc)Temporary Files.
  1610. * toascii: (libc)Case Conversion.
  1611. * _tolower: (libc)Case Conversion.
  1612. * tolower: (libc)Case Conversion.
  1613. * TOSTOP: (libc)Local Modes.
  1614. * totalorderf: (libc)FP Comparison Functions.
  1615. * totalorder: (libc)FP Comparison Functions.
  1616. * totalorderl: (libc)FP Comparison Functions.
  1617. * totalordermagf: (libc)FP Comparison Functions.
  1618. * totalordermag: (libc)FP Comparison Functions.
  1619. * totalordermagl: (libc)FP Comparison Functions.
  1620. * _toupper: (libc)Case Conversion.
  1621. * toupper: (libc)Case Conversion.
  1622. * towctrans: (libc)Wide Character Case Conversion.
  1623. * towlower: (libc)Wide Character Case Conversion.
  1624. * towupper: (libc)Wide Character Case Conversion.
  1625. * truncate64: (libc)File Size.
  1626. * truncate: (libc)File Size.
  1627. * truncf: (libc)Rounding Functions.
  1628. * trunc: (libc)Rounding Functions.
  1629. * truncl: (libc)Rounding Functions.
  1630. * tsearch: (libc)Tree Search Function.
  1631. * ttyname: (libc)Is It a Terminal.
  1632. * ttyname_r: (libc)Is It a Terminal.
  1633. * twalk: (libc)Tree Search Function.
  1634. * TZNAME_MAX: (libc)General Limits.
  1635. * tzset: (libc)Time Zone Functions.
  1636. * ufromfpf: (libc)Rounding Functions.
  1637. * ufromfp: (libc)Rounding Functions.
  1638. * ufromfpl: (libc)Rounding Functions.
  1639. * ufromfpxf: (libc)Rounding Functions.
  1640. * ufromfpx: (libc)Rounding Functions.
  1641. * ufromfpxl: (libc)Rounding Functions.
  1642. * ulimit: (libc)Limits on Resources.
  1643. * umask: (libc)Setting Permissions.
  1644. * umount2: (libc)Mount-Unmount-Remount.
  1645. * umount: (libc)Mount-Unmount-Remount.
  1646. * uname: (libc)Platform Type.
  1647. * ungetc: (libc)How Unread.
  1648. * ungetwc: (libc)How Unread.
  1649. * unlink: (libc)Deleting Files.
  1650. * unlockpt: (libc)Allocation.
  1651. * unsetenv: (libc)Environment Access.
  1652. * updwtmp: (libc)Manipulating the Database.
  1653. * utime: (libc)File Times.
  1654. * utimes: (libc)File Times.
  1655. * utmpname: (libc)Manipulating the Database.
  1656. * utmpxname: (libc)XPG Functions.
  1657. * va_arg: (libc)Argument Macros.
  1658. * __va_copy: (libc)Argument Macros.
  1659. * va_copy: (libc)Argument Macros.
  1660. * va_end: (libc)Argument Macros.
  1661. * valloc: (libc)Aligned Memory Blocks.
  1662. * vasprintf: (libc)Variable Arguments Output.
  1663. * va_start: (libc)Argument Macros.
  1664. * VDISCARD: (libc)Other Special.
  1665. * VDSUSP: (libc)Signal Characters.
  1666. * VEOF: (libc)Editing Characters.
  1667. * VEOL2: (libc)Editing Characters.
  1668. * VEOL: (libc)Editing Characters.
  1669. * VERASE: (libc)Editing Characters.
  1670. * verr: (libc)Error Messages.
  1671. * verrx: (libc)Error Messages.
  1672. * versionsort64: (libc)Scanning Directory Content.
  1673. * versionsort: (libc)Scanning Directory Content.
  1674. * vfork: (libc)Creating a Process.
  1675. * vfprintf: (libc)Variable Arguments Output.
  1676. * vfscanf: (libc)Variable Arguments Input.
  1677. * vfwprintf: (libc)Variable Arguments Output.
  1678. * vfwscanf: (libc)Variable Arguments Input.
  1679. * VINTR: (libc)Signal Characters.
  1680. * VKILL: (libc)Editing Characters.
  1681. * vlimit: (libc)Limits on Resources.
  1682. * VLNEXT: (libc)Other Special.
  1683. * VMIN: (libc)Noncanonical Input.
  1684. * vprintf: (libc)Variable Arguments Output.
  1685. * VQUIT: (libc)Signal Characters.
  1686. * VREPRINT: (libc)Editing Characters.
  1687. * vscanf: (libc)Variable Arguments Input.
  1688. * vsnprintf: (libc)Variable Arguments Output.
  1689. * vsprintf: (libc)Variable Arguments Output.
  1690. * vsscanf: (libc)Variable Arguments Input.
  1691. * VSTART: (libc)Start/Stop Characters.
  1692. * VSTATUS: (libc)Other Special.
  1693. * VSTOP: (libc)Start/Stop Characters.
  1694. * VSUSP: (libc)Signal Characters.
  1695. * vswprintf: (libc)Variable Arguments Output.
  1696. * vswscanf: (libc)Variable Arguments Input.
  1697. * vsyslog: (libc)syslog; vsyslog.
  1698. * VTIME: (libc)Noncanonical Input.
  1699. * vtimes: (libc)Resource Usage.
  1700. * vwarn: (libc)Error Messages.
  1701. * vwarnx: (libc)Error Messages.
  1702. * VWERASE: (libc)Editing Characters.
  1703. * vwprintf: (libc)Variable Arguments Output.
  1704. * vwscanf: (libc)Variable Arguments Input.
  1705. * wait3: (libc)BSD Wait Functions.
  1706. * wait4: (libc)Process Completion.
  1707. * wait: (libc)Process Completion.
  1708. * waitpid: (libc)Process Completion.
  1709. * warn: (libc)Error Messages.
  1710. * warnx: (libc)Error Messages.
  1711. * WCHAR_MAX: (libc)Extended Char Intro.
  1712. * WCHAR_MIN: (libc)Extended Char Intro.
  1713. * WCOREDUMP: (libc)Process Completion Status.
  1714. * wcpcpy: (libc)Copying Strings and Arrays.
  1715. * wcpncpy: (libc)Truncating Strings.
  1716. * wcrtomb: (libc)Converting a Character.
  1717. * wcscasecmp: (libc)String/Array Comparison.
  1718. * wcscat: (libc)Concatenating Strings.
  1719. * wcschr: (libc)Search Functions.
  1720. * wcschrnul: (libc)Search Functions.
  1721. * wcscmp: (libc)String/Array Comparison.
  1722. * wcscoll: (libc)Collation Functions.
  1723. * wcscpy: (libc)Copying Strings and Arrays.
  1724. * wcscspn: (libc)Search Functions.
  1725. * wcsdup: (libc)Copying Strings and Arrays.
  1726. * wcsftime: (libc)Formatting Calendar Time.
  1727. * wcslen: (libc)String Length.
  1728. * wcsncasecmp: (libc)String/Array Comparison.
  1729. * wcsncat: (libc)Truncating Strings.
  1730. * wcsncmp: (libc)String/Array Comparison.
  1731. * wcsncpy: (libc)Truncating Strings.
  1732. * wcsnlen: (libc)String Length.
  1733. * wcsnrtombs: (libc)Converting Strings.
  1734. * wcspbrk: (libc)Search Functions.
  1735. * wcsrchr: (libc)Search Functions.
  1736. * wcsrtombs: (libc)Converting Strings.
  1737. * wcsspn: (libc)Search Functions.
  1738. * wcsstr: (libc)Search Functions.
  1739. * wcstod: (libc)Parsing of Floats.
  1740. * wcstof: (libc)Parsing of Floats.
  1741. * wcstoimax: (libc)Parsing of Integers.
  1742. * wcstok: (libc)Finding Tokens in a String.
  1743. * wcstold: (libc)Parsing of Floats.
  1744. * wcstol: (libc)Parsing of Integers.
  1745. * wcstoll: (libc)Parsing of Integers.
  1746. * wcstombs: (libc)Non-reentrant String Conversion.
  1747. * wcstoq: (libc)Parsing of Integers.
  1748. * wcstoul: (libc)Parsing of Integers.
  1749. * wcstoull: (libc)Parsing of Integers.
  1750. * wcstoumax: (libc)Parsing of Integers.
  1751. * wcstouq: (libc)Parsing of Integers.
  1752. * wcswcs: (libc)Search Functions.
  1753. * wcsxfrm: (libc)Collation Functions.
  1754. * wctob: (libc)Converting a Character.
  1755. * wctomb: (libc)Non-reentrant Character Conversion.
  1756. * wctrans: (libc)Wide Character Case Conversion.
  1757. * wctype: (libc)Classification of Wide Characters.
  1758. * WEOF: (libc)EOF and Errors.
  1759. * WEOF: (libc)Extended Char Intro.
  1760. * WEXITSTATUS: (libc)Process Completion Status.
  1761. * WIFEXITED: (libc)Process Completion Status.
  1762. * WIFSIGNALED: (libc)Process Completion Status.
  1763. * WIFSTOPPED: (libc)Process Completion Status.
  1764. * wmemchr: (libc)Search Functions.
  1765. * wmemcmp: (libc)String/Array Comparison.
  1766. * wmemcpy: (libc)Copying Strings and Arrays.
  1767. * wmemmove: (libc)Copying Strings and Arrays.
  1768. * wmempcpy: (libc)Copying Strings and Arrays.
  1769. * wmemset: (libc)Copying Strings and Arrays.
  1770. * W_OK: (libc)Testing File Access.
  1771. * wordexp: (libc)Calling Wordexp.
  1772. * wordfree: (libc)Calling Wordexp.
  1773. * wprintf: (libc)Formatted Output Functions.
  1774. * write: (libc)I/O Primitives.
  1775. * writev: (libc)Scatter-Gather.
  1776. * wscanf: (libc)Formatted Input Functions.
  1777. * WSTOPSIG: (libc)Process Completion Status.
  1778. * WTERMSIG: (libc)Process Completion Status.
  1779. * X_OK: (libc)Testing File Access.
  1780. * y0f: (libc)Special Functions.
  1781. * y0: (libc)Special Functions.
  1782. * y0l: (libc)Special Functions.
  1783. * y1f: (libc)Special Functions.
  1784. * y1: (libc)Special Functions.
  1785. * y1l: (libc)Special Functions.
  1786. * ynf: (libc)Special Functions.
  1787. * yn: (libc)Special Functions.
  1788. * ynl: (libc)Special Functions.
  1789. END-INFO-DIR-ENTRY
  1790. 
  1791. File: libc.info, Node: Converting Strings, Next: Multibyte Conversion Example, Prev: Converting a Character, Up: Restartable multibyte conversion
  1792. 6.3.4 Converting Multibyte and Wide Character Strings
  1793. -----------------------------------------------------
  1794. The functions described in the previous section only convert a single
  1795. character at a time. Most operations to be performed in real-world
  1796. programs include strings and therefore the ISO C standard also defines
  1797. conversions on entire strings. However, the defined set of functions is
  1798. quite limited; therefore, the GNU C Library contains a few extensions
  1799. that can help in some important situations.
  1800. -- Function: size_t mbsrtowcs (wchar_t *restrict DST, const char
  1801. **restrict SRC, size_t LEN, mbstate_t *restrict PS)
  1802. Preliminary: | MT-Unsafe race:mbsrtowcs/!ps | AS-Unsafe corrupt
  1803. heap lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX
  1804. Safety Concepts::.
  1805. The ‘mbsrtowcs’ function (“multibyte string restartable to wide
  1806. character string”) converts the NUL-terminated multibyte character
  1807. string at ‘*SRC’ into an equivalent wide character string,
  1808. including the NUL wide character at the end. The conversion is
  1809. started using the state information from the object pointed to by
  1810. PS or from an internal object of ‘mbsrtowcs’ if PS is a null
  1811. pointer. Before returning, the state object is updated to match
  1812. the state after the last converted character. The state is the
  1813. initial state if the terminating NUL byte is reached and converted.
  1814. If DST is not a null pointer, the result is stored in the array
  1815. pointed to by DST; otherwise, the conversion result is not
  1816. available since it is stored in an internal buffer.
  1817. If LEN wide characters are stored in the array DST before reaching
  1818. the end of the input string, the conversion stops and LEN is
  1819. returned. If DST is a null pointer, LEN is never checked.
  1820. Another reason for a premature return from the function call is if
  1821. the input string contains an invalid multibyte sequence. In this
  1822. case the global variable ‘errno’ is set to ‘EILSEQ’ and the
  1823. function returns ‘(size_t) -1’.
  1824. In all other cases the function returns the number of wide
  1825. characters converted during this call. If DST is not null,
  1826. ‘mbsrtowcs’ stores in the pointer pointed to by SRC either a null
  1827. pointer (if the NUL byte in the input string was reached) or the
  1828. address of the byte following the last converted multibyte
  1829. character.
  1830. ‘mbsrtowcs’ was introduced in Amendment 1 to ISO C90 and is
  1831. declared in ‘wchar.h’.
  1832. The definition of the ‘mbsrtowcs’ function has one important
  1833. limitation. The requirement that DST has to be a NUL-terminated string
  1834. provides problems if one wants to convert buffers with text. A buffer
  1835. is not normally a collection of NUL-terminated strings but instead a
  1836. continuous collection of lines, separated by newline characters. Now
  1837. assume that a function to convert one line from a buffer is needed.
  1838. Since the line is not NUL-terminated, the source pointer cannot directly
  1839. point into the unmodified text buffer. This means, either one inserts
  1840. the NUL byte at the appropriate place for the time of the ‘mbsrtowcs’
  1841. function call (which is not doable for a read-only buffer or in a
  1842. multi-threaded application) or one copies the line in an extra buffer
  1843. where it can be terminated by a NUL byte. Note that it is not in
  1844. general possible to limit the number of characters to convert by setting
  1845. the parameter LEN to any specific value. Since it is not known how many
  1846. bytes each multibyte character sequence is in length, one can only
  1847. guess.
  1848. There is still a problem with the method of NUL-terminating a line
  1849. right after the newline character, which could lead to very strange
  1850. results. As said in the description of the ‘mbsrtowcs’ function above,
  1851. the conversion state is guaranteed to be in the initial shift state
  1852. after processing the NUL byte at the end of the input string. But this
  1853. NUL byte is not really part of the text (i.e., the conversion state
  1854. after the newline in the original text could be something different than
  1855. the initial shift state and therefore the first character of the next
  1856. line is encoded using this state). But the state in question is never
  1857. accessible to the user since the conversion stops after the NUL byte
  1858. (which resets the state). Most stateful character sets in use today
  1859. require that the shift state after a newline be the initial state–but
  1860. this is not a strict guarantee. Therefore, simply NUL-terminating a
  1861. piece of a running text is not always an adequate solution and,
  1862. therefore, should never be used in generally used code.
  1863. The generic conversion interface (*note Generic Charset Conversion::)
  1864. does not have this limitation (it simply works on buffers, not strings),
  1865. and the GNU C Library contains a set of functions that take additional
  1866. parameters specifying the maximal number of bytes that are consumed from
  1867. the input string. This way the problem of ‘mbsrtowcs’’s example above
  1868. could be solved by determining the line length and passing this length
  1869. to the function.
  1870. -- Function: size_t wcsrtombs (char *restrict DST, const wchar_t
  1871. **restrict SRC, size_t LEN, mbstate_t *restrict PS)
  1872. Preliminary: | MT-Unsafe race:wcsrtombs/!ps | AS-Unsafe corrupt
  1873. heap lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX
  1874. Safety Concepts::.
  1875. The ‘wcsrtombs’ function (“wide character string restartable to
  1876. multibyte string”) converts the NUL-terminated wide character
  1877. string at ‘*SRC’ into an equivalent multibyte character string and
  1878. stores the result in the array pointed to by DST. The NUL wide
  1879. character is also converted. The conversion starts in the state
  1880. described in the object pointed to by PS or by a state object local
  1881. to ‘wcsrtombs’ in case PS is a null pointer. If DST is a null
  1882. pointer, the conversion is performed as usual but the result is not
  1883. available. If all characters of the input string were successfully
  1884. converted and if DST is not a null pointer, the pointer pointed to
  1885. by SRC gets assigned a null pointer.
  1886. If one of the wide characters in the input string has no valid
  1887. multibyte character equivalent, the conversion stops early, sets
  1888. the global variable ‘errno’ to ‘EILSEQ’, and returns ‘(size_t) -1’.
  1889. Another reason for a premature stop is if DST is not a null pointer
  1890. and the next converted character would require more than LEN bytes
  1891. in total to the array DST. In this case (and if DST is not a null
  1892. pointer) the pointer pointed to by SRC is assigned a value pointing
  1893. to the wide character right after the last one successfully
  1894. converted.
  1895. Except in the case of an encoding error the return value of the
  1896. ‘wcsrtombs’ function is the number of bytes in all the multibyte
  1897. character sequences stored in DST. Before returning, the state in
  1898. the object pointed to by PS (or the internal object in case PS is a
  1899. null pointer) is updated to reflect the state after the last
  1900. conversion. The state is the initial shift state in case the
  1901. terminating NUL wide character was converted.
  1902. The ‘wcsrtombs’ function was introduced in Amendment 1 to ISO C90
  1903. and is declared in ‘wchar.h’.
  1904. The restriction mentioned above for the ‘mbsrtowcs’ function applies
  1905. here also. There is no possibility of directly controlling the number
  1906. of input characters. One has to place the NUL wide character at the
  1907. correct place or control the consumed input indirectly via the available
  1908. output array size (the LEN parameter).
  1909. -- Function: size_t mbsnrtowcs (wchar_t *restrict DST, const char
  1910. **restrict SRC, size_t NMC, size_t LEN, mbstate_t *restrict
  1911. PS)
  1912. Preliminary: | MT-Unsafe race:mbsnrtowcs/!ps | AS-Unsafe corrupt
  1913. heap lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX
  1914. Safety Concepts::.
  1915. The ‘mbsnrtowcs’ function is very similar to the ‘mbsrtowcs’
  1916. function. All the parameters are the same except for NMC, which is
  1917. new. The return value is the same as for ‘mbsrtowcs’.
  1918. This new parameter specifies how many bytes at most can be used
  1919. from the multibyte character string. In other words, the multibyte
  1920. character string ‘*SRC’ need not be NUL-terminated. But if a NUL
  1921. byte is found within the NMC first bytes of the string, the
  1922. conversion stops there.
  1923. This function is a GNU extension. It is meant to work around the
  1924. problems mentioned above. Now it is possible to convert a buffer
  1925. with multibyte character text piece by piece without having to care
  1926. about inserting NUL bytes and the effect of NUL bytes on the
  1927. conversion state.
  1928. A function to convert a multibyte string into a wide character string
  1929. and display it could be written like this (this is not a really useful
  1930. example):
  1931. void
  1932. showmbs (const char *src, FILE *fp)
  1933. {
  1934. mbstate_t state;
  1935. int cnt = 0;
  1936. memset (&state, '\0', sizeof (state));
  1937. while (1)
  1938. {
  1939. wchar_t linebuf[100];
  1940. const char *endp = strchr (src, '\n');
  1941. size_t n;
  1942. /* Exit if there is no more line. */
  1943. if (endp == NULL)
  1944. break;
  1945. n = mbsnrtowcs (linebuf, &src, endp - src, 99, &state);
  1946. linebuf[n] = L'\0';
  1947. fprintf (fp, "line %d: \"%S\"\n", linebuf);
  1948. }
  1949. }
  1950. There is no problem with the state after a call to ‘mbsnrtowcs’.
  1951. Since we don’t insert characters in the strings that were not in there
  1952. right from the beginning and we use STATE only for the conversion of the
  1953. given buffer, there is no problem with altering the state.
  1954. -- Function: size_t wcsnrtombs (char *restrict DST, const wchar_t
  1955. **restrict SRC, size_t NWC, size_t LEN, mbstate_t *restrict
  1956. PS)
  1957. Preliminary: | MT-Unsafe race:wcsnrtombs/!ps | AS-Unsafe corrupt
  1958. heap lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX
  1959. Safety Concepts::.
  1960. The ‘wcsnrtombs’ function implements the conversion from wide
  1961. character strings to multibyte character strings. It is similar to
  1962. ‘wcsrtombs’ but, just like ‘mbsnrtowcs’, it takes an extra
  1963. parameter, which specifies the length of the input string.
  1964. No more than NWC wide characters from the input string ‘*SRC’ are
  1965. converted. If the input string contains a NUL wide character in
  1966. the first NWC characters, the conversion stops at this place.
  1967. The ‘wcsnrtombs’ function is a GNU extension and just like
  1968. ‘mbsnrtowcs’ helps in situations where no NUL-terminated input
  1969. strings are available.
  1970. 
  1971. File: libc.info, Node: Multibyte Conversion Example, Prev: Converting Strings, Up: Restartable multibyte conversion
  1972. 6.3.5 A Complete Multibyte Conversion Example
  1973. ---------------------------------------------
  1974. The example programs given in the last sections are only brief and do
  1975. not contain all the error checking, etc. Presented here is a complete
  1976. and documented example. It features the ‘mbrtowc’ function but it
  1977. should be easy to derive versions using the other functions.
  1978. int
  1979. file_mbsrtowcs (int input, int output)
  1980. {
  1981. /* Note the use of ‘MB_LEN_MAX’.
  1982. ‘MB_CUR_MAX’ cannot portably be used here. */
  1983. char buffer[BUFSIZ + MB_LEN_MAX];
  1984. mbstate_t state;
  1985. int filled = 0;
  1986. int eof = 0;
  1987. /* Initialize the state. */
  1988. memset (&state, '\0', sizeof (state));
  1989. while (!eof)
  1990. {
  1991. ssize_t nread;
  1992. ssize_t nwrite;
  1993. char *inp = buffer;
  1994. wchar_t outbuf[BUFSIZ];
  1995. wchar_t *outp = outbuf;
  1996. /* Fill up the buffer from the input file. */
  1997. nread = read (input, buffer + filled, BUFSIZ);
  1998. if (nread < 0)
  1999. {
  2000. perror ("read");
  2001. return 0;
  2002. }
  2003. /* If we reach end of file, make a note to read no more. */
  2004. if (nread == 0)
  2005. eof = 1;
  2006. /* ‘filled’ is now the number of bytes in ‘buffer’. */
  2007. filled += nread;
  2008. /* Convert those bytes to wide characters–as many as we can. */
  2009. while (1)
  2010. {
  2011. size_t thislen = mbrtowc (outp, inp, filled, &state);
  2012. /* Stop converting at invalid character;
  2013. this can mean we have read just the first part
  2014. of a valid character. */
  2015. if (thislen == (size_t) -1)
  2016. break;
  2017. /* We want to handle embedded NUL bytes
  2018. but the return value is 0. Correct this. */
  2019. if (thislen == 0)
  2020. thislen = 1;
  2021. /* Advance past this character. */
  2022. inp += thislen;
  2023. filled -= thislen;
  2024. ++outp;
  2025. }
  2026. /* Write the wide characters we just made. */
  2027. nwrite = write (output, outbuf,
  2028. (outp - outbuf) * sizeof (wchar_t));
  2029. if (nwrite < 0)
  2030. {
  2031. perror ("write");
  2032. return 0;
  2033. }
  2034. /* See if we have a _real_ invalid character. */
  2035. if ((eof && filled > 0) || filled >= MB_CUR_MAX)
  2036. {
  2037. error (0, 0, "invalid multibyte character");
  2038. return 0;
  2039. }
  2040. /* If any characters must be carried forward,
  2041. put them at the beginning of ‘buffer’. */
  2042. if (filled > 0)
  2043. memmove (buffer, inp, filled);
  2044. }
  2045. return 1;
  2046. }
  2047. 
  2048. File: libc.info, Node: Non-reentrant Conversion, Next: Generic Charset Conversion, Prev: Restartable multibyte conversion, Up: Character Set Handling
  2049. 6.4 Non-reentrant Conversion Function
  2050. =====================================
  2051. The functions described in the previous chapter are defined in Amendment 1
  2052. to ISO C90, but the original ISO C90 standard also contained functions
  2053. for character set conversion. The reason that these original functions
  2054. are not described first is that they are almost entirely useless.
  2055. The problem is that all the conversion functions described in the
  2056. original ISO C90 use a local state. Using a local state implies that
  2057. multiple conversions at the same time (not only when using threads)
  2058. cannot be done, and that you cannot first convert single characters and
  2059. then strings since you cannot tell the conversion functions which state
  2060. to use.
  2061. These original functions are therefore usable only in a very limited
  2062. set of situations. One must complete converting the entire string
  2063. before starting a new one, and each string/text must be converted with
  2064. the same function (there is no problem with the library itself; it is
  2065. guaranteed that no library function changes the state of any of these
  2066. functions). *For the above reasons it is highly requested that the
  2067. functions described in the previous section be used in place of
  2068. non-reentrant conversion functions.*
  2069. * Menu:
  2070. * Non-reentrant Character Conversion:: Non-reentrant Conversion of Single
  2071. Characters.
  2072. * Non-reentrant String Conversion:: Non-reentrant Conversion of Strings.
  2073. * Shift State:: States in Non-reentrant Functions.
  2074. 
  2075. File: libc.info, Node: Non-reentrant Character Conversion, Next: Non-reentrant String Conversion, Up: Non-reentrant Conversion
  2076. 6.4.1 Non-reentrant Conversion of Single Characters
  2077. ---------------------------------------------------
  2078. -- Function: int mbtowc (wchar_t *restrict RESULT, const char *restrict
  2079. STRING, size_t SIZE)
  2080. Preliminary: | MT-Unsafe race | AS-Unsafe corrupt heap lock dlopen
  2081. | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  2082. The ‘mbtowc’ (“multibyte to wide character”) function when called
  2083. with non-null STRING converts the first multibyte character
  2084. beginning at STRING to its corresponding wide character code. It
  2085. stores the result in ‘*RESULT’.
  2086. ‘mbtowc’ never examines more than SIZE bytes. (The idea is to
  2087. supply for SIZE the number of bytes of data you have in hand.)
  2088. ‘mbtowc’ with non-null STRING distinguishes three possibilities:
  2089. the first SIZE bytes at STRING start with valid multibyte
  2090. characters, they start with an invalid byte sequence or just part
  2091. of a character, or STRING points to an empty string (a null
  2092. character).
  2093. For a valid multibyte character, ‘mbtowc’ converts it to a wide
  2094. character and stores that in ‘*RESULT’, and returns the number of
  2095. bytes in that character (always at least 1 and never more than
  2096. SIZE).
  2097. For an invalid byte sequence, ‘mbtowc’ returns -1. For an empty
  2098. string, it returns 0, also storing ‘'\0'’ in ‘*RESULT’.
  2099. If the multibyte character code uses shift characters, then
  2100. ‘mbtowc’ maintains and updates a shift state as it scans. If you
  2101. call ‘mbtowc’ with a null pointer for STRING, that initializes the
  2102. shift state to its standard initial value. It also returns nonzero
  2103. if the multibyte character code in use actually has a shift state.
  2104. *Note Shift State::.
  2105. -- Function: int wctomb (char *STRING, wchar_t WCHAR)
  2106. Preliminary: | MT-Unsafe race | AS-Unsafe corrupt heap lock dlopen
  2107. | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  2108. The ‘wctomb’ (“wide character to multibyte”) function converts the
  2109. wide character code WCHAR to its corresponding multibyte character
  2110. sequence, and stores the result in bytes starting at STRING. At
  2111. most ‘MB_CUR_MAX’ characters are stored.
  2112. ‘wctomb’ with non-null STRING distinguishes three possibilities for
  2113. WCHAR: a valid wide character code (one that can be translated to a
  2114. multibyte character), an invalid code, and ‘L'\0'’.
  2115. Given a valid code, ‘wctomb’ converts it to a multibyte character,
  2116. storing the bytes starting at STRING. Then it returns the number
  2117. of bytes in that character (always at least 1 and never more than
  2118. ‘MB_CUR_MAX’).
  2119. If WCHAR is an invalid wide character code, ‘wctomb’ returns -1.
  2120. If WCHAR is ‘L'\0'’, it returns ‘0’, also storing ‘'\0'’ in
  2121. ‘*STRING’.
  2122. If the multibyte character code uses shift characters, then
  2123. ‘wctomb’ maintains and updates a shift state as it scans. If you
  2124. call ‘wctomb’ with a null pointer for STRING, that initializes the
  2125. shift state to its standard initial value. It also returns nonzero
  2126. if the multibyte character code in use actually has a shift state.
  2127. *Note Shift State::.
  2128. Calling this function with a WCHAR argument of zero when STRING is
  2129. not null has the side-effect of reinitializing the stored shift
  2130. state _as well as_ storing the multibyte character ‘'\0'’ and
  2131. returning 0.
  2132. Similar to ‘mbrlen’ there is also a non-reentrant function that
  2133. computes the length of a multibyte character. It can be defined in
  2134. terms of ‘mbtowc’.
  2135. -- Function: int mblen (const char *STRING, size_t SIZE)
  2136. Preliminary: | MT-Unsafe race | AS-Unsafe corrupt heap lock dlopen
  2137. | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  2138. The ‘mblen’ function with a non-null STRING argument returns the
  2139. number of bytes that make up the multibyte character beginning at
  2140. STRING, never examining more than SIZE bytes. (The idea is to
  2141. supply for SIZE the number of bytes of data you have in hand.)
  2142. The return value of ‘mblen’ distinguishes three possibilities: the
  2143. first SIZE bytes at STRING start with valid multibyte characters,
  2144. they start with an invalid byte sequence or just part of a
  2145. character, or STRING points to an empty string (a null character).
  2146. For a valid multibyte character, ‘mblen’ returns the number of
  2147. bytes in that character (always at least ‘1’ and never more than
  2148. SIZE). For an invalid byte sequence, ‘mblen’ returns -1. For an
  2149. empty string, it returns 0.
  2150. If the multibyte character code uses shift characters, then ‘mblen’
  2151. maintains and updates a shift state as it scans. If you call
  2152. ‘mblen’ with a null pointer for STRING, that initializes the shift
  2153. state to its standard initial value. It also returns a nonzero
  2154. value if the multibyte character code in use actually has a shift
  2155. state. *Note Shift State::.
  2156. The function ‘mblen’ is declared in ‘stdlib.h’.
  2157. 
  2158. File: libc.info, Node: Non-reentrant String Conversion, Next: Shift State, Prev: Non-reentrant Character Conversion, Up: Non-reentrant Conversion
  2159. 6.4.2 Non-reentrant Conversion of Strings
  2160. -----------------------------------------
  2161. For convenience the ISO C90 standard also defines functions to convert
  2162. entire strings instead of single characters. These functions suffer
  2163. from the same problems as their reentrant counterparts from Amendment 1
  2164. to ISO C90; see *note Converting Strings::.
  2165. -- Function: size_t mbstowcs (wchar_t *WSTRING, const char *STRING,
  2166. size_t SIZE)
  2167. Preliminary: | MT-Safe | AS-Unsafe corrupt heap lock dlopen |
  2168. AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  2169. The ‘mbstowcs’ (“multibyte string to wide character string”)
  2170. function converts the null-terminated string of multibyte
  2171. characters STRING to an array of wide character codes, storing not
  2172. more than SIZE wide characters into the array beginning at WSTRING.
  2173. The terminating null character counts towards the size, so if SIZE
  2174. is less than the actual number of wide characters resulting from
  2175. STRING, no terminating null character is stored.
  2176. The conversion of characters from STRING begins in the initial
  2177. shift state.
  2178. If an invalid multibyte character sequence is found, the ‘mbstowcs’
  2179. function returns a value of -1. Otherwise, it returns the number
  2180. of wide characters stored in the array WSTRING. This number does
  2181. not include the terminating null character, which is present if the
  2182. number is less than SIZE.
  2183. Here is an example showing how to convert a string of multibyte
  2184. characters, allocating enough space for the result.
  2185. wchar_t *
  2186. mbstowcs_alloc (const char *string)
  2187. {
  2188. size_t size = strlen (string) + 1;
  2189. wchar_t *buf = xmalloc (size * sizeof (wchar_t));
  2190. size = mbstowcs (buf, string, size);
  2191. if (size == (size_t) -1)
  2192. return NULL;
  2193. buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
  2194. return buf;
  2195. }
  2196. -- Function: size_t wcstombs (char *STRING, const wchar_t *WSTRING,
  2197. size_t SIZE)
  2198. Preliminary: | MT-Safe | AS-Unsafe corrupt heap lock dlopen |
  2199. AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  2200. The ‘wcstombs’ (“wide character string to multibyte string”)
  2201. function converts the null-terminated wide character array WSTRING
  2202. into a string containing multibyte characters, storing not more
  2203. than SIZE bytes starting at STRING, followed by a terminating null
  2204. character if there is room. The conversion of characters begins in
  2205. the initial shift state.
  2206. The terminating null character counts towards the size, so if SIZE
  2207. is less than or equal to the number of bytes needed in WSTRING, no
  2208. terminating null character is stored.
  2209. If a code that does not correspond to a valid multibyte character
  2210. is found, the ‘wcstombs’ function returns a value of -1.
  2211. Otherwise, the return value is the number of bytes stored in the
  2212. array STRING. This number does not include the terminating null
  2213. character, which is present if the number is less than SIZE.
  2214. 
  2215. File: libc.info, Node: Shift State, Prev: Non-reentrant String Conversion, Up: Non-reentrant Conversion
  2216. 6.4.3 States in Non-reentrant Functions
  2217. ---------------------------------------
  2218. In some multibyte character codes, the _meaning_ of any particular byte
  2219. sequence is not fixed; it depends on what other sequences have come
  2220. earlier in the same string. Typically there are just a few sequences
  2221. that can change the meaning of other sequences; these few are called
  2222. "shift sequences" and we say that they set the "shift state" for other
  2223. sequences that follow.
  2224. To illustrate shift state and shift sequences, suppose we decide that
  2225. the sequence ‘0200’ (just one byte) enters Japanese mode, in which pairs
  2226. of bytes in the range from ‘0240’ to ‘0377’ are single characters, while
  2227. ‘0201’ enters Latin-1 mode, in which single bytes in the range from
  2228. ‘0240’ to ‘0377’ are characters, and interpreted according to the ISO
  2229. Latin-1 character set. This is a multibyte code that has two
  2230. alternative shift states (“Japanese mode” and “Latin-1 mode”), and two
  2231. shift sequences that specify particular shift states.
  2232. When the multibyte character code in use has shift states, then
  2233. ‘mblen’, ‘mbtowc’, and ‘wctomb’ must maintain and update the current
  2234. shift state as they scan the string. To make this work properly, you
  2235. must follow these rules:
  2236. • Before starting to scan a string, call the function with a null
  2237. pointer for the multibyte character address—for example, ‘mblen
  2238. (NULL, 0)’. This initializes the shift state to its standard
  2239. initial value.
  2240. • Scan the string one character at a time, in order. Do not “back
  2241. up” and rescan characters already scanned, and do not intersperse
  2242. the processing of different strings.
  2243. Here is an example of using ‘mblen’ following these rules:
  2244. void
  2245. scan_string (char *s)
  2246. {
  2247. int length = strlen (s);
  2248. /* Initialize shift state. */
  2249. mblen (NULL, 0);
  2250. while (1)
  2251. {
  2252. int thischar = mblen (s, length);
  2253. /* Deal with end of string and invalid characters. */
  2254. if (thischar == 0)
  2255. break;
  2256. if (thischar == -1)
  2257. {
  2258. error ("invalid multibyte character");
  2259. break;
  2260. }
  2261. /* Advance past this character. */
  2262. s += thischar;
  2263. length -= thischar;
  2264. }
  2265. }
  2266. The functions ‘mblen’, ‘mbtowc’ and ‘wctomb’ are not reentrant when
  2267. using a multibyte code that uses a shift state. However, no other
  2268. library functions call these functions, so you don’t have to worry that
  2269. the shift state will be changed mysteriously.
  2270. 
  2271. File: libc.info, Node: Generic Charset Conversion, Prev: Non-reentrant Conversion, Up: Character Set Handling
  2272. 6.5 Generic Charset Conversion
  2273. ==============================
  2274. The conversion functions mentioned so far in this chapter all had in
  2275. common that they operate on character sets that are not directly
  2276. specified by the functions. The multibyte encoding used is specified by
  2277. the currently selected locale for the ‘LC_CTYPE’ category. The wide
  2278. character set is fixed by the implementation (in the case of the GNU C
  2279. Library it is always UCS-4 encoded ISO 10646).
  2280. This has of course several problems when it comes to general
  2281. character conversion:
  2282. • For every conversion where neither the source nor the destination
  2283. character set is the character set of the locale for the ‘LC_CTYPE’
  2284. category, one has to change the ‘LC_CTYPE’ locale using
  2285. ‘setlocale’.
  2286. Changing the ‘LC_CTYPE’ locale introduces major problems for the
  2287. rest of the programs since several more functions (e.g., the
  2288. character classification functions, *note Classification of
  2289. Characters::) use the ‘LC_CTYPE’ category.
  2290. • Parallel conversions to and from different character sets are not
  2291. possible since the ‘LC_CTYPE’ selection is global and shared by all
  2292. threads.
  2293. • If neither the source nor the destination character set is the
  2294. character set used for ‘wchar_t’ representation, there is at least
  2295. a two-step process necessary to convert a text using the functions
  2296. above. One would have to select the source character set as the
  2297. multibyte encoding, convert the text into a ‘wchar_t’ text, select
  2298. the destination character set as the multibyte encoding, and
  2299. convert the wide character text to the multibyte (= destination)
  2300. character set.
  2301. Even if this is possible (which is not guaranteed) it is a very
  2302. tiring work. Plus it suffers from the other two raised points even
  2303. more due to the steady changing of the locale.
  2304. The XPG2 standard defines a completely new set of functions, which
  2305. has none of these limitations. They are not at all coupled to the
  2306. selected locales, and they have no constraints on the character sets
  2307. selected for source and destination. Only the set of available
  2308. conversions limits them. The standard does not specify that any
  2309. conversion at all must be available. Such availability is a measure of
  2310. the quality of the implementation.
  2311. In the following text first the interface to ‘iconv’ and then the
  2312. conversion function, will be described. Comparisons with other
  2313. implementations will show what obstacles stand in the way of portable
  2314. applications. Finally, the implementation is described in so far as
  2315. might interest the advanced user who wants to extend conversion
  2316. capabilities.
  2317. * Menu:
  2318. * Generic Conversion Interface:: Generic Character Set Conversion Interface.
  2319. * iconv Examples:: A complete ‘iconv’ example.
  2320. * Other iconv Implementations:: Some Details about other ‘iconv’
  2321. Implementations.
  2322. * glibc iconv Implementation:: The ‘iconv’ Implementation in the GNU C
  2323. library.
  2324. 
  2325. File: libc.info, Node: Generic Conversion Interface, Next: iconv Examples, Up: Generic Charset Conversion
  2326. 6.5.1 Generic Character Set Conversion Interface
  2327. ------------------------------------------------
  2328. This set of functions follows the traditional cycle of using a resource:
  2329. open–use–close. The interface consists of three functions, each of
  2330. which implements one step.
  2331. Before the interfaces are described it is necessary to introduce a
  2332. data type. Just like other open–use–close interfaces the functions
  2333. introduced here work using handles and the ‘iconv.h’ header defines a
  2334. special type for the handles used.
  2335. -- Data Type: iconv_t
  2336. This data type is an abstract type defined in ‘iconv.h’. The user
  2337. must not assume anything about the definition of this type; it must
  2338. be completely opaque.
  2339. Objects of this type can be assigned handles for the conversions
  2340. using the ‘iconv’ functions. The objects themselves need not be
  2341. freed, but the conversions for which the handles stand for have to.
  2342. The first step is the function to create a handle.
  2343. -- Function: iconv_t iconv_open (const char *TOCODE, const char
  2344. *FROMCODE)
  2345. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
  2346. | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  2347. The ‘iconv_open’ function has to be used before starting a
  2348. conversion. The two parameters this function takes determine the
  2349. source and destination character set for the conversion, and if the
  2350. implementation has the possibility to perform such a conversion,
  2351. the function returns a handle.
  2352. If the wanted conversion is not available, the ‘iconv_open’
  2353. function returns ‘(iconv_t) -1’. In this case the global variable
  2354. ‘errno’ can have the following values:
  2355. ‘EMFILE’
  2356. The process already has ‘OPEN_MAX’ file descriptors open.
  2357. ‘ENFILE’
  2358. The system limit of open files is reached.
  2359. ‘ENOMEM’
  2360. Not enough memory to carry out the operation.
  2361. ‘EINVAL’
  2362. The conversion from FROMCODE to TOCODE is not supported.
  2363. It is not possible to use the same descriptor in different threads
  2364. to perform independent conversions. The data structures associated
  2365. with the descriptor include information about the conversion state.
  2366. This must not be messed up by using it in different conversions.
  2367. An ‘iconv’ descriptor is like a file descriptor as for every use a
  2368. new descriptor must be created. The descriptor does not stand for
  2369. all of the conversions from FROMSET to TOSET.
  2370. The GNU C Library implementation of ‘iconv_open’ has one
  2371. significant extension to other implementations. To ease the
  2372. extension of the set of available conversions, the implementation
  2373. allows storing the necessary files with data and code in an
  2374. arbitrary number of directories. How this extension must be
  2375. written will be explained below (*note glibc iconv
  2376. Implementation::). Here it is only important to say that all
  2377. directories mentioned in the ‘GCONV_PATH’ environment variable are
  2378. considered only if they contain a file ‘gconv-modules’. These
  2379. directories need not necessarily be created by the system
  2380. administrator. In fact, this extension is introduced to help users
  2381. writing and using their own, new conversions. Of course, this does
  2382. not work for security reasons in SUID binaries; in this case only
  2383. the system directory is considered and this normally is
  2384. ‘PREFIX/lib/gconv’. The ‘GCONV_PATH’ environment variable is
  2385. examined exactly once at the first call of the ‘iconv_open’
  2386. function. Later modifications of the variable have no effect.
  2387. The ‘iconv_open’ function was introduced early in the X/Open
  2388. Portability Guide, version 2. It is supported by all commercial
  2389. Unices as it is required for the Unix branding. However, the
  2390. quality and completeness of the implementation varies widely. The
  2391. ‘iconv_open’ function is declared in ‘iconv.h’.
  2392. The ‘iconv’ implementation can associate large data structure with
  2393. the handle returned by ‘iconv_open’. Therefore, it is crucial to free
  2394. all the resources once all conversions are carried out and the
  2395. conversion is not needed anymore.
  2396. -- Function: int iconv_close (iconv_t CD)
  2397. Preliminary: | MT-Safe | AS-Unsafe corrupt heap lock dlopen |
  2398. AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
  2399. The ‘iconv_close’ function frees all resources associated with the
  2400. handle CD, which must have been returned by a successful call to
  2401. the ‘iconv_open’ function.
  2402. If the function call was successful the return value is 0.
  2403. Otherwise it is -1 and ‘errno’ is set appropriately. Defined
  2404. errors are:
  2405. ‘EBADF’
  2406. The conversion descriptor is invalid.
  2407. The ‘iconv_close’ function was introduced together with the rest of
  2408. the ‘iconv’ functions in XPG2 and is declared in ‘iconv.h’.
  2409. The standard defines only one actual conversion function. This has,
  2410. therefore, the most general interface: it allows conversion from one
  2411. buffer to another. Conversion from a file to a buffer, vice versa, or
  2412. even file to file can be implemented on top of it.
  2413. -- Function: size_t iconv (iconv_t CD, char **INBUF, size_t
  2414. *INBYTESLEFT, char **OUTBUF, size_t *OUTBYTESLEFT)
  2415. Preliminary: | MT-Safe race:cd | AS-Safe | AC-Unsafe corrupt |
  2416. *Note POSIX Safety Concepts::.
  2417. The ‘iconv’ function converts the text in the input buffer
  2418. according to the rules associated with the descriptor CD and stores
  2419. the result in the output buffer. It is possible to call the
  2420. function for the same text several times in a row since for
  2421. stateful character sets the necessary state information is kept in
  2422. the data structures associated with the descriptor.
  2423. The input buffer is specified by ‘*INBUF’ and it contains
  2424. ‘*INBYTESLEFT’ bytes. The extra indirection is necessary for
  2425. communicating the used input back to the caller (see below). It is
  2426. important to note that the buffer pointer is of type ‘char’ and the
  2427. length is measured in bytes even if the input text is encoded in
  2428. wide characters.
  2429. The output buffer is specified in a similar way. ‘*OUTBUF’ points
  2430. to the beginning of the buffer with at least ‘*OUTBYTESLEFT’ bytes
  2431. room for the result. The buffer pointer again is of type ‘char’
  2432. and the length is measured in bytes. If OUTBUF or ‘*OUTBUF’ is a
  2433. null pointer, the conversion is performed but no output is
  2434. available.
  2435. If INBUF is a null pointer, the ‘iconv’ function performs the
  2436. necessary action to put the state of the conversion into the
  2437. initial state. This is obviously a no-op for non-stateful
  2438. encodings, but if the encoding has a state, such a function call
  2439. might put some byte sequences in the output buffer, which perform
  2440. the necessary state changes. The next call with INBUF not being a
  2441. null pointer then simply goes on from the initial state. It is
  2442. important that the programmer never makes any assumption as to
  2443. whether the conversion has to deal with states. Even if the input
  2444. and output character sets are not stateful, the implementation
  2445. might still have to keep states. This is due to the implementation
  2446. chosen for the GNU C Library as it is described below. Therefore
  2447. an ‘iconv’ call to reset the state should always be performed if
  2448. some protocol requires this for the output text.
  2449. The conversion stops for one of three reasons. The first is that
  2450. all characters from the input buffer are converted. This actually
  2451. can mean two things: either all bytes from the input buffer are
  2452. consumed or there are some bytes at the end of the buffer that
  2453. possibly can form a complete character but the input is incomplete.
  2454. The second reason for a stop is that the output buffer is full.
  2455. And the third reason is that the input contains invalid characters.
  2456. In all of these cases the buffer pointers after the last successful
  2457. conversion, for the input and output buffers, are stored in INBUF
  2458. and OUTBUF, and the available room in each buffer is stored in
  2459. INBYTESLEFT and OUTBYTESLEFT.
  2460. Since the character sets selected in the ‘iconv_open’ call can be
  2461. almost arbitrary, there can be situations where the input buffer
  2462. contains valid characters, which have no identical representation
  2463. in the output character set. The behavior in this situation is
  2464. undefined. The _current_ behavior of the GNU C Library in this
  2465. situation is to return with an error immediately. This certainly
  2466. is not the most desirable solution; therefore, future versions will
  2467. provide better ones, but they are not yet finished.
  2468. If all input from the input buffer is successfully converted and
  2469. stored in the output buffer, the function returns the number of
  2470. non-reversible conversions performed. In all other cases the
  2471. return value is ‘(size_t) -1’ and ‘errno’ is set appropriately. In
  2472. such cases the value pointed to by INBYTESLEFT is nonzero.
  2473. ‘EILSEQ’
  2474. The conversion stopped because of an invalid byte sequence in
  2475. the input. After the call, ‘*INBUF’ points at the first byte
  2476. of the invalid byte sequence.
  2477. ‘E2BIG’
  2478. The conversion stopped because it ran out of space in the
  2479. output buffer.
  2480. ‘EINVAL’
  2481. The conversion stopped because of an incomplete byte sequence
  2482. at the end of the input buffer.
  2483. ‘EBADF’
  2484. The CD argument is invalid.
  2485. The ‘iconv’ function was introduced in the XPG2 standard and is
  2486. declared in the ‘iconv.h’ header.
  2487. The definition of the ‘iconv’ function is quite good overall. It
  2488. provides quite flexible functionality. The only problems lie in the
  2489. boundary cases, which are incomplete byte sequences at the end of the
  2490. input buffer and invalid input. A third problem, which is not really a
  2491. design problem, is the way conversions are selected. The standard does
  2492. not say anything about the legitimate names, a minimal set of available
  2493. conversions. We will see how this negatively impacts other
  2494. implementations, as demonstrated below.
  2495. 
  2496. File: libc.info, Node: iconv Examples, Next: Other iconv Implementations, Prev: Generic Conversion Interface, Up: Generic Charset Conversion
  2497. 6.5.2 A complete ‘iconv’ example
  2498. --------------------------------
  2499. The example below features a solution for a common problem. Given that
  2500. one knows the internal encoding used by the system for ‘wchar_t’
  2501. strings, one often is in the position to read text from a file and store
  2502. it in wide character buffers. One can do this using ‘mbsrtowcs’, but
  2503. then we run into the problems discussed above.
  2504. int
  2505. file2wcs (int fd, const char *charset, wchar_t *outbuf, size_t avail)
  2506. {
  2507. char inbuf[BUFSIZ];
  2508. size_t insize = 0;
  2509. char *wrptr = (char *) outbuf;
  2510. int result = 0;
  2511. iconv_t cd;
  2512. cd = iconv_open ("WCHAR_T", charset);
  2513. if (cd == (iconv_t) -1)
  2514. {
  2515. /* Something went wrong. */
  2516. if (errno == EINVAL)
  2517. error (0, 0, "conversion from '%s' to wchar_t not available",
  2518. charset);
  2519. else
  2520. perror ("iconv_open");
  2521. /* Terminate the output string. */
  2522. *outbuf = L'\0';
  2523. return -1;
  2524. }
  2525. while (avail > 0)
  2526. {
  2527. size_t nread;
  2528. size_t nconv;
  2529. char *inptr = inbuf;
  2530. /* Read more input. */
  2531. nread = read (fd, inbuf + insize, sizeof (inbuf) - insize);
  2532. if (nread == 0)
  2533. {
  2534. /* When we come here the file is completely read.
  2535. This still could mean there are some unused
  2536. characters in the ‘inbuf’. Put them back. */
  2537. if (lseek (fd, -insize, SEEK_CUR) == -1)
  2538. result = -1;
  2539. /* Now write out the byte sequence to get into the
  2540. initial state if this is necessary. */
  2541. iconv (cd, NULL, NULL, &wrptr, &avail);
  2542. break;
  2543. }
  2544. insize += nread;
  2545. /* Do the conversion. */
  2546. nconv = iconv (cd, &inptr, &insize, &wrptr, &avail);
  2547. if (nconv == (size_t) -1)
  2548. {
  2549. /* Not everything went right. It might only be
  2550. an unfinished byte sequence at the end of the
  2551. buffer. Or it is a real problem. */
  2552. if (errno == EINVAL)
  2553. /* This is harmless. Simply move the unused
  2554. bytes to the beginning of the buffer so that
  2555. they can be used in the next round. */
  2556. memmove (inbuf, inptr, insize);
  2557. else
  2558. {
  2559. /* It is a real problem. Maybe we ran out of
  2560. space in the output buffer or we have invalid
  2561. input. In any case back the file pointer to
  2562. the position of the last processed byte. */
  2563. lseek (fd, -insize, SEEK_CUR);
  2564. result = -1;
  2565. break;
  2566. }
  2567. }
  2568. }
  2569. /* Terminate the output string. */
  2570. if (avail >= sizeof (wchar_t))
  2571. *((wchar_t *) wrptr) = L'\0';
  2572. if (iconv_close (cd) != 0)
  2573. perror ("iconv_close");
  2574. return (wchar_t *) wrptr - outbuf;
  2575. }
  2576. This example shows the most important aspects of using the ‘iconv’
  2577. functions. It shows how successive calls to ‘iconv’ can be used to
  2578. convert large amounts of text. The user does not have to care about
  2579. stateful encodings as the functions take care of everything.
  2580. An interesting point is the case where ‘iconv’ returns an error and
  2581. ‘errno’ is set to ‘EINVAL’. This is not really an error in the
  2582. transformation. It can happen whenever the input character set contains
  2583. byte sequences of more than one byte for some character and texts are
  2584. not processed in one piece. In this case there is a chance that a
  2585. multibyte sequence is cut. The caller can then simply read the
  2586. remainder of the takes and feed the offending bytes together with new
  2587. character from the input to ‘iconv’ and continue the work. The internal
  2588. state kept in the descriptor is _not_ unspecified after such an event as
  2589. is the case with the conversion functions from the ISO C standard.
  2590. The example also shows the problem of using wide character strings
  2591. with ‘iconv’. As explained in the description of the ‘iconv’ function
  2592. above, the function always takes a pointer to a ‘char’ array and the
  2593. available space is measured in bytes. In the example, the output buffer
  2594. is a wide character buffer; therefore, we use a local variable WRPTR of
  2595. type ‘char *’, which is used in the ‘iconv’ calls.
  2596. This looks rather innocent but can lead to problems on platforms that
  2597. have tight restriction on alignment. Therefore the caller of ‘iconv’
  2598. has to make sure that the pointers passed are suitable for access of
  2599. characters from the appropriate character set. Since, in the above
  2600. case, the input parameter to the function is a ‘wchar_t’ pointer, this
  2601. is the case (unless the user violates alignment when computing the
  2602. parameter). But in other situations, especially when writing generic
  2603. functions where one does not know what type of character set one uses
  2604. and, therefore, treats text as a sequence of bytes, it might become
  2605. tricky.
  2606. 
  2607. File: libc.info, Node: Other iconv Implementations, Next: glibc iconv Implementation, Prev: iconv Examples, Up: Generic Charset Conversion
  2608. 6.5.3 Some Details about other ‘iconv’ Implementations
  2609. ------------------------------------------------------
  2610. This is not really the place to discuss the ‘iconv’ implementation of
  2611. other systems but it is necessary to know a bit about them to write
  2612. portable programs. The above mentioned problems with the specification
  2613. of the ‘iconv’ functions can lead to portability issues.
  2614. The first thing to notice is that, due to the large number of
  2615. character sets in use, it is certainly not practical to encode the
  2616. conversions directly in the C library. Therefore, the conversion
  2617. information must come from files outside the C library. This is usually
  2618. done in one or both of the following ways:
  2619. • The C library contains a set of generic conversion functions that
  2620. can read the needed conversion tables and other information from
  2621. data files. These files get loaded when necessary.
  2622. This solution is problematic as it requires a great deal of effort
  2623. to apply to all character sets (potentially an infinite set). The
  2624. differences in the structure of the different character sets is so
  2625. large that many different variants of the table-processing
  2626. functions must be developed. In addition, the generic nature of
  2627. these functions make them slower than specifically implemented
  2628. functions.
  2629. • The C library only contains a framework that can dynamically load
  2630. object files and execute the conversion functions contained
  2631. therein.
  2632. This solution provides much more flexibility. The C library itself
  2633. contains only very little code and therefore reduces the general
  2634. memory footprint. Also, with a documented interface between the C
  2635. library and the loadable modules it is possible for third parties
  2636. to extend the set of available conversion modules. A drawback of
  2637. this solution is that dynamic loading must be available.
  2638. Some implementations in commercial Unices implement a mixture of
  2639. these possibilities; the majority implement only the second solution.
  2640. Using loadable modules moves the code out of the library itself and
  2641. keeps the door open for extensions and improvements, but this design is
  2642. also limiting on some platforms since not many platforms support dynamic
  2643. loading in statically linked programs. On platforms without this
  2644. capability it is therefore not possible to use this interface in
  2645. statically linked programs. The GNU C Library has, on ELF platforms, no
  2646. problems with dynamic loading in these situations; therefore, this point
  2647. is moot. The danger is that one gets acquainted with this situation and
  2648. forgets about the restrictions on other systems.
  2649. A second thing to know about other ‘iconv’ implementations is that
  2650. the number of available conversions is often very limited. Some
  2651. implementations provide, in the standard release (not special
  2652. international or developer releases), at most 100 to 200 conversion
  2653. possibilities. This does not mean 200 different character sets are
  2654. supported; for example, conversions from one character set to a set of
  2655. 10 others might count as 10 conversions. Together with the other
  2656. direction this makes 20 conversion possibilities used up by one
  2657. character set. One can imagine the thin coverage these platforms
  2658. provide. Some Unix vendors even provide only a handful of conversions,
  2659. which renders them useless for almost all uses.
  2660. This directly leads to a third and probably the most problematic
  2661. point. The way the ‘iconv’ conversion functions are implemented on all
  2662. known Unix systems and the availability of the conversion functions from
  2663. character set A to B and the conversion from B to C does _not_ imply
  2664. that the conversion from A to C is available.
  2665. This might not seem unreasonable and problematic at first, but it is
  2666. a quite big problem as one will notice shortly after hitting it. To
  2667. show the problem we assume to write a program that has to convert from A
  2668. to C. A call like
  2669. cd = iconv_open ("C", "A");
  2670. fails according to the assumption above. But what does the program do
  2671. now? The conversion is necessary; therefore, simply giving up is not an
  2672. option.
  2673. This is a nuisance. The ‘iconv’ function should take care of this.
  2674. But how should the program proceed from here on? If it tries to convert
  2675. to character set B, first the two ‘iconv_open’ calls
  2676. cd1 = iconv_open ("B", "A");
  2677. and
  2678. cd2 = iconv_open ("C", "B");
  2679. will succeed, but how to find B?
  2680. Unfortunately, the answer is: there is no general solution. On some
  2681. systems guessing might help. On those systems most character sets can
  2682. convert to and from UTF-8 encoded ISO 10646 or Unicode text. Besides
  2683. this only some very system-specific methods can help. Since the
  2684. conversion functions come from loadable modules and these modules must
  2685. be stored somewhere in the filesystem, one _could_ try to find them and
  2686. determine from the available file which conversions are available and
  2687. whether there is an indirect route from A to C.
  2688. This example shows one of the design errors of ‘iconv’ mentioned
  2689. above. It should at least be possible to determine the list of
  2690. available conversions programmatically so that if ‘iconv_open’ says
  2691. there is no such conversion, one could make sure this also is true for
  2692. indirect routes.
  2693. 
  2694. File: libc.info, Node: glibc iconv Implementation, Prev: Other iconv Implementations, Up: Generic Charset Conversion
  2695. 6.5.4 The ‘iconv’ Implementation in the GNU C Library
  2696. -----------------------------------------------------
  2697. After reading about the problems of ‘iconv’ implementations in the last
  2698. section it is certainly good to note that the implementation in the GNU
  2699. C Library has none of the problems mentioned above. What follows is a
  2700. step-by-step analysis of the points raised above. The evaluation is
  2701. based on the current state of the development (as of January 1999). The
  2702. development of the ‘iconv’ functions is not complete, but basic
  2703. functionality has solidified.
  2704. The GNU C Library’s ‘iconv’ implementation uses shared loadable
  2705. modules to implement the conversions. A very small number of
  2706. conversions are built into the library itself but these are only rather
  2707. trivial conversions.
  2708. All the benefits of loadable modules are available in the GNU C
  2709. Library implementation. This is especially appealing since the
  2710. interface is well documented (see below), and it, therefore, is easy to
  2711. write new conversion modules. The drawback of using loadable objects is
  2712. not a problem in the GNU C Library, at least on ELF systems. Since the
  2713. library is able to load shared objects even in statically linked
  2714. binaries, static linking need not be forbidden in case one wants to use
  2715. ‘iconv’.
  2716. The second mentioned problem is the number of supported conversions.
  2717. Currently, the GNU C Library supports more than 150 character sets. The
  2718. way the implementation is designed the number of supported conversions
  2719. is greater than 22350 (150 times 149). If any conversion from or to a
  2720. character set is missing, it can be added easily.
  2721. Particularly impressive as it may be, this high number is due to the
  2722. fact that the GNU C Library implementation of ‘iconv’ does not have the
  2723. third problem mentioned above (i.e., whenever there is a conversion from
  2724. a character set A to B and from B to C it is always possible to convert
  2725. from A to C directly). If the ‘iconv_open’ returns an error and sets
  2726. ‘errno’ to ‘EINVAL’, there is no known way, directly or indirectly, to
  2727. perform the wanted conversion.
  2728. Triangulation is achieved by providing for each character set a
  2729. conversion from and to UCS-4 encoded ISO 10646. Using ISO 10646 as an
  2730. intermediate representation it is possible to "triangulate" (i.e.,
  2731. convert with an intermediate representation).
  2732. There is no inherent requirement to provide a conversion to ISO 10646
  2733. for a new character set, and it is also possible to provide other
  2734. conversions where neither source nor destination character set is
  2735. ISO 10646. The existing set of conversions is simply meant to cover all
  2736. conversions that might be of interest.
  2737. All currently available conversions use the triangulation method
  2738. above, making conversion run unnecessarily slow. If, for example,
  2739. somebody often needs the conversion from ISO-2022-JP to EUC-JP, a
  2740. quicker solution would involve direct conversion between the two
  2741. character sets, skipping the input to ISO 10646 first. The two
  2742. character sets of interest are much more similar to each other than to
  2743. ISO 10646.
  2744. In such a situation one easily can write a new conversion and provide
  2745. it as a better alternative. The GNU C Library ‘iconv’ implementation
  2746. would automatically use the module implementing the conversion if it is
  2747. specified to be more efficient.
  2748. 6.5.4.1 Format of ‘gconv-modules’ files
  2749. .......................................
  2750. All information about the available conversions comes from a file named
  2751. ‘gconv-modules’, which can be found in any of the directories along the
  2752. ‘GCONV_PATH’. The ‘gconv-modules’ files are line-oriented text files,
  2753. where each of the lines has one of the following formats:
  2754. • If the first non-whitespace character is a ‘#’ the line contains
  2755. only comments and is ignored.
  2756. • Lines starting with ‘alias’ define an alias name for a character
  2757. set. Two more words are expected on the line. The first word
  2758. defines the alias name, and the second defines the original name of
  2759. the character set. The effect is that it is possible to use the
  2760. alias name in the FROMSET or TOSET parameters of ‘iconv_open’ and
  2761. achieve the same result as when using the real character set name.
  2762. This is quite important as a character set has often many different
  2763. names. There is normally an official name but this need not
  2764. correspond to the most popular name. Besides this many character
  2765. sets have special names that are somehow constructed. For example,
  2766. all character sets specified by the ISO have an alias of the form
  2767. ‘ISO-IR-NNN’ where NNN is the registration number. This allows
  2768. programs that know about the registration number to construct
  2769. character set names and use them in ‘iconv_open’ calls. More on
  2770. the available names and aliases follows below.
  2771. • Lines starting with ‘module’ introduce an available conversion
  2772. module. These lines must contain three or four more words.
  2773. The first word specifies the source character set, the second word
  2774. the destination character set of conversion implemented in this
  2775. module, and the third word is the name of the loadable module. The
  2776. filename is constructed by appending the usual shared object suffix
  2777. (normally ‘.so’) and this file is then supposed to be found in the
  2778. same directory the ‘gconv-modules’ file is in. The last word on
  2779. the line, which is optional, is a numeric value representing the
  2780. cost of the conversion. If this word is missing, a cost of 1 is
  2781. assumed. The numeric value itself does not matter that much; what
  2782. counts are the relative values of the sums of costs for all
  2783. possible conversion paths. Below is a more precise description of
  2784. the use of the cost value.
  2785. Returning to the example above where one has written a module to
  2786. directly convert from ISO-2022-JP to EUC-JP and back. All that has to
  2787. be done is to put the new module, let its name be ISO2022JP-EUCJP.so, in
  2788. a directory and add a file ‘gconv-modules’ with the following content in
  2789. the same directory:
  2790. module ISO-2022-JP// EUC-JP// ISO2022JP-EUCJP 1
  2791. module EUC-JP// ISO-2022-JP// ISO2022JP-EUCJP 1
  2792. To see why this is sufficient, it is necessary to understand how the
  2793. conversion used by ‘iconv’ (and described in the descriptor) is
  2794. selected. The approach to this problem is quite simple.
  2795. At the first call of the ‘iconv_open’ function the program reads all
  2796. available ‘gconv-modules’ files and builds up two tables: one containing
  2797. all the known aliases and another that contains the information about
  2798. the conversions and which shared object implements them.
  2799. 6.5.4.2 Finding the conversion path in ‘iconv’
  2800. ..............................................
  2801. The set of available conversions form a directed graph with weighted
  2802. edges. The weights on the edges are the costs specified in the
  2803. ‘gconv-modules’ files. The ‘iconv_open’ function uses an algorithm
  2804. suitable for search for the best path in such a graph and so constructs
  2805. a list of conversions that must be performed in succession to get the
  2806. transformation from the source to the destination character set.
  2807. Explaining why the above ‘gconv-modules’ files allows the ‘iconv’
  2808. implementation to resolve the specific ISO-2022-JP to EUC-JP conversion
  2809. module instead of the conversion coming with the library itself is
  2810. straightforward. Since the latter conversion takes two steps (from
  2811. ISO-2022-JP to ISO 10646 and then from ISO 10646 to EUC-JP), the cost is
  2812. 1+1 = 2. The above ‘gconv-modules’ file, however, specifies that the
  2813. new conversion modules can perform this conversion with only the cost of
  2814. 1.
  2815. A mysterious item about the ‘gconv-modules’ file above (and also the
  2816. file coming with the GNU C Library) are the names of the character sets
  2817. specified in the ‘module’ lines. Why do almost all the names end in
  2818. ‘//’? And this is not all: the names can actually be regular
  2819. expressions. At this point in time this mystery should not be revealed,
  2820. unless you have the relevant spell-casting materials: ashes from an
  2821. original DOS 6.2 boot disk burnt in effigy, a crucifix blessed by St.
  2822. Emacs, assorted herbal roots from Central America, sand from Cebu, etc.
  2823. Sorry! *The part of the implementation where this is used is not yet
  2824. finished. For now please simply follow the existing examples. It’ll
  2825. become clearer once it is. –drepper*
  2826. A last remark about the ‘gconv-modules’ is about the names not ending
  2827. with ‘//’. A character set named ‘INTERNAL’ is often mentioned. From
  2828. the discussion above and the chosen name it should have become clear
  2829. that this is the name for the representation used in the intermediate
  2830. step of the triangulation. We have said that this is UCS-4 but actually
  2831. that is not quite right. The UCS-4 specification also includes the
  2832. specification of the byte ordering used. Since a UCS-4 value consists
  2833. of four bytes, a stored value is affected by byte ordering. The
  2834. internal representation is _not_ the same as UCS-4 in case the byte
  2835. ordering of the processor (or at least the running process) is not the
  2836. same as the one required for UCS-4. This is done for performance
  2837. reasons as one does not want to perform unnecessary byte-swapping
  2838. operations if one is not interested in actually seeing the result in
  2839. UCS-4. To avoid trouble with endianness, the internal representation
  2840. consistently is named ‘INTERNAL’ even on big-endian systems where the
  2841. representations are identical.
  2842. 6.5.4.3 ‘iconv’ module data structures
  2843. ......................................
  2844. So far this section has described how modules are located and considered
  2845. to be used. What remains to be described is the interface of the
  2846. modules so that one can write new ones. This section describes the
  2847. interface as it is in use in January 1999. The interface will change a
  2848. bit in the future but, with luck, only in an upwardly compatible way.
  2849. The definitions necessary to write new modules are publicly available
  2850. in the non-standard header ‘gconv.h’. The following text, therefore,
  2851. describes the definitions from this header file. First, however, it is
  2852. necessary to get an overview.
  2853. From the perspective of the user of ‘iconv’ the interface is quite
  2854. simple: the ‘iconv_open’ function returns a handle that can be used in
  2855. calls to ‘iconv’, and finally the handle is freed with a call to
  2856. ‘iconv_close’. The problem is that the handle has to be able to
  2857. represent the possibly long sequences of conversion steps and also the
  2858. state of each conversion since the handle is all that is passed to the
  2859. ‘iconv’ function. Therefore, the data structures are really the
  2860. elements necessary to understanding the implementation.
  2861. We need two different kinds of data structures. The first describes
  2862. the conversion and the second describes the state etc. There are really
  2863. two type definitions like this in ‘gconv.h’.
  2864. -- Data type: struct __gconv_step
  2865. This data structure describes one conversion a module can perform.
  2866. For each function in a loaded module with conversion functions
  2867. there is exactly one object of this type. This object is shared by
  2868. all users of the conversion (i.e., this object does not contain any
  2869. information corresponding to an actual conversion; it only
  2870. describes the conversion itself).
  2871. ‘struct __gconv_loaded_object *__shlib_handle’
  2872. ‘const char *__modname’
  2873. ‘int __counter’
  2874. All these elements of the structure are used internally in the
  2875. C library to coordinate loading and unloading the shared
  2876. object. One must not expect any of the other elements to be
  2877. available or initialized.
  2878. ‘const char *__from_name’
  2879. ‘const char *__to_name’
  2880. ‘__from_name’ and ‘__to_name’ contain the names of the source
  2881. and destination character sets. They can be used to identify
  2882. the actual conversion to be carried out since one module might
  2883. implement conversions for more than one character set and/or
  2884. direction.
  2885. ‘gconv_fct __fct’
  2886. ‘gconv_init_fct __init_fct’
  2887. ‘gconv_end_fct __end_fct’
  2888. These elements contain pointers to the functions in the
  2889. loadable module. The interface will be explained below.
  2890. ‘int __min_needed_from’
  2891. ‘int __max_needed_from’
  2892. ‘int __min_needed_to’
  2893. ‘int __max_needed_to;’
  2894. These values have to be supplied in the init function of the
  2895. module. The ‘__min_needed_from’ value specifies how many
  2896. bytes a character of the source character set at least needs.
  2897. The ‘__max_needed_from’ specifies the maximum value that also
  2898. includes possible shift sequences.
  2899. The ‘__min_needed_to’ and ‘__max_needed_to’ values serve the
  2900. same purpose as ‘__min_needed_from’ and ‘__max_needed_from’
  2901. but this time for the destination character set.
  2902. It is crucial that these values be accurate since otherwise
  2903. the conversion functions will have problems or not work at
  2904. all.
  2905. ‘int __stateful’
  2906. This element must also be initialized by the init function.
  2907. ‘int __stateful’ is nonzero if the source character set is
  2908. stateful. Otherwise it is zero.
  2909. ‘void *__data’
  2910. This element can be used freely by the conversion functions in
  2911. the module. ‘void *__data’ can be used to communicate extra
  2912. information from one call to another. ‘void *__data’ need not
  2913. be initialized if not needed at all. If ‘void *__data’
  2914. element is assigned a pointer to dynamically allocated memory
  2915. (presumably in the init function) it has to be made sure that
  2916. the end function deallocates the memory. Otherwise the
  2917. application will leak memory.
  2918. It is important to be aware that this data structure is shared
  2919. by all users of this specification conversion and therefore
  2920. the ‘__data’ element must not contain data specific to one
  2921. specific use of the conversion function.
  2922. -- Data type: struct __gconv_step_data
  2923. This is the data structure that contains the information specific
  2924. to each use of the conversion functions.
  2925. ‘char *__outbuf’
  2926. ‘char *__outbufend’
  2927. These elements specify the output buffer for the conversion
  2928. step. The ‘__outbuf’ element points to the beginning of the
  2929. buffer, and ‘__outbufend’ points to the byte following the
  2930. last byte in the buffer. The conversion function must not
  2931. assume anything about the size of the buffer but it can be
  2932. safely assumed there is room for at least one complete
  2933. character in the output buffer.
  2934. Once the conversion is finished, if the conversion is the last
  2935. step, the ‘__outbuf’ element must be modified to point after
  2936. the last byte written into the buffer to signal how much
  2937. output is available. If this conversion step is not the last
  2938. one, the element must not be modified. The ‘__outbufend’
  2939. element must not be modified.
  2940. ‘int __is_last’
  2941. This element is nonzero if this conversion step is the last
  2942. one. This information is necessary for the recursion. See
  2943. the description of the conversion function internals below.
  2944. This element must never be modified.
  2945. ‘int __invocation_counter’
  2946. The conversion function can use this element to see how many
  2947. calls of the conversion function already happened. Some
  2948. character sets require a certain prolog when generating
  2949. output, and by comparing this value with zero, one can find
  2950. out whether it is the first call and whether, therefore, the
  2951. prolog should be emitted. This element must never be
  2952. modified.
  2953. ‘int __internal_use’
  2954. This element is another one rarely used but needed in certain
  2955. situations. It is assigned a nonzero value in case the
  2956. conversion functions are used to implement ‘mbsrtowcs’ et.al.
  2957. (i.e., the function is not used directly through the ‘iconv’
  2958. interface).
  2959. This sometimes makes a difference as it is expected that the
  2960. ‘iconv’ functions are used to translate entire texts while the
  2961. ‘mbsrtowcs’ functions are normally used only to convert single
  2962. strings and might be used multiple times to convert entire
  2963. texts.
  2964. But in this situation we would have problem complying with
  2965. some rules of the character set specification. Some character
  2966. sets require a prolog, which must appear exactly once for an
  2967. entire text. If a number of ‘mbsrtowcs’ calls are used to
  2968. convert the text, only the first call must add the prolog.
  2969. However, because there is no communication between the
  2970. different calls of ‘mbsrtowcs’, the conversion functions have
  2971. no possibility to find this out. The situation is different
  2972. for sequences of ‘iconv’ calls since the handle allows access
  2973. to the needed information.
  2974. The ‘int __internal_use’ element is mostly used together with
  2975. ‘__invocation_counter’ as follows:
  2976. if (!data->__internal_use
  2977. && data->__invocation_counter == 0)
  2978. /* Emit prolog. */
  2979. This element must never be modified.
  2980. ‘mbstate_t *__statep’
  2981. The ‘__statep’ element points to an object of type ‘mbstate_t’
  2982. (*note Keeping the state::). The conversion of a stateful
  2983. character set must use the object pointed to by ‘__statep’ to
  2984. store information about the conversion state. The ‘__statep’
  2985. element itself must never be modified.
  2986. ‘mbstate_t __state’
  2987. This element must _never_ be used directly. It is only part
  2988. of this structure to have the needed space allocated.
  2989. 6.5.4.4 ‘iconv’ module interfaces
  2990. .................................
  2991. With the knowledge about the data structures we now can describe the
  2992. conversion function itself. To understand the interface a bit of
  2993. knowledge is necessary about the functionality in the C library that
  2994. loads the objects with the conversions.
  2995. It is often the case that one conversion is used more than once
  2996. (i.e., there are several ‘iconv_open’ calls for the same set of
  2997. character sets during one program run). The ‘mbsrtowcs’ et.al.
  2998. functions in the GNU C Library also use the ‘iconv’ functionality, which
  2999. increases the number of uses of the same functions even more.
  3000. Because of this multiple use of conversions, the modules do not get
  3001. loaded exclusively for one conversion. Instead a module once loaded can
  3002. be used by an arbitrary number of ‘iconv’ or ‘mbsrtowcs’ calls at the
  3003. same time. The splitting of the information between conversion-
  3004. function-specific information and conversion data makes this possible.
  3005. The last section showed the two data structures used to do this.
  3006. This is of course also reflected in the interface and semantics of
  3007. the functions that the modules must provide. There are three functions
  3008. that must have the following names:
  3009. ‘gconv_init’
  3010. The ‘gconv_init’ function initializes the conversion function
  3011. specific data structure. This very same object is shared by all
  3012. conversions that use this conversion and, therefore, no state
  3013. information about the conversion itself must be stored in here. If
  3014. a module implements more than one conversion, the ‘gconv_init’
  3015. function will be called multiple times.
  3016. ‘gconv_end’
  3017. The ‘gconv_end’ function is responsible for freeing all resources
  3018. allocated by the ‘gconv_init’ function. If there is nothing to do,
  3019. this function can be missing. Special care must be taken if the
  3020. module implements more than one conversion and the ‘gconv_init’
  3021. function does not allocate the same resources for all conversions.
  3022. ‘gconv’
  3023. This is the actual conversion function. It is called to convert
  3024. one block of text. It gets passed the conversion step information
  3025. initialized by ‘gconv_init’ and the conversion data, specific to
  3026. this use of the conversion functions.
  3027. There are three data types defined for the three module interface
  3028. functions and these define the interface.
  3029. -- Data type: int (*__gconv_init_fct) (struct __gconv_step *)
  3030. This specifies the interface of the initialization function of the
  3031. module. It is called exactly once for each conversion the module
  3032. implements.
  3033. As explained in the description of the ‘struct __gconv_step’ data
  3034. structure above the initialization function has to initialize parts
  3035. of it.
  3036. ‘__min_needed_from’
  3037. ‘__max_needed_from’
  3038. ‘__min_needed_to’
  3039. ‘__max_needed_to’
  3040. These elements must be initialized to the exact numbers of the
  3041. minimum and maximum number of bytes used by one character in
  3042. the source and destination character sets, respectively. If
  3043. the characters all have the same size, the minimum and maximum
  3044. values are the same.
  3045. ‘__stateful’
  3046. This element must be initialized to a nonzero value if the
  3047. source character set is stateful. Otherwise it must be zero.
  3048. If the initialization function needs to communicate some
  3049. information to the conversion function, this communication can
  3050. happen using the ‘__data’ element of the ‘__gconv_step’ structure.
  3051. But since this data is shared by all the conversions, it must not
  3052. be modified by the conversion function. The example below shows
  3053. how this can be used.
  3054. #define MIN_NEEDED_FROM 1
  3055. #define MAX_NEEDED_FROM 4
  3056. #define MIN_NEEDED_TO 4
  3057. #define MAX_NEEDED_TO 4
  3058. int
  3059. gconv_init (struct __gconv_step *step)
  3060. {
  3061. /* Determine which direction. */
  3062. struct iso2022jp_data *new_data;
  3063. enum direction dir = illegal_dir;
  3064. enum variant var = illegal_var;
  3065. int result;
  3066. if (__strcasecmp (step->__from_name, "ISO-2022-JP//") == 0)
  3067. {
  3068. dir = from_iso2022jp;
  3069. var = iso2022jp;
  3070. }
  3071. else if (__strcasecmp (step->__to_name, "ISO-2022-JP//") == 0)
  3072. {
  3073. dir = to_iso2022jp;
  3074. var = iso2022jp;
  3075. }
  3076. else if (__strcasecmp (step->__from_name, "ISO-2022-JP-2//") == 0)
  3077. {
  3078. dir = from_iso2022jp;
  3079. var = iso2022jp2;
  3080. }
  3081. else if (__strcasecmp (step->__to_name, "ISO-2022-JP-2//") == 0)
  3082. {
  3083. dir = to_iso2022jp;
  3084. var = iso2022jp2;
  3085. }
  3086. result = __GCONV_NOCONV;
  3087. if (dir != illegal_dir)
  3088. {
  3089. new_data = (struct iso2022jp_data *)
  3090. malloc (sizeof (struct iso2022jp_data));
  3091. result = __GCONV_NOMEM;
  3092. if (new_data != NULL)
  3093. {
  3094. new_data->dir = dir;
  3095. new_data->var = var;
  3096. step->__data = new_data;
  3097. if (dir == from_iso2022jp)
  3098. {
  3099. step->__min_needed_from = MIN_NEEDED_FROM;
  3100. step->__max_needed_from = MAX_NEEDED_FROM;
  3101. step->__min_needed_to = MIN_NEEDED_TO;
  3102. step->__max_needed_to = MAX_NEEDED_TO;
  3103. }
  3104. else
  3105. {
  3106. step->__min_needed_from = MIN_NEEDED_TO;
  3107. step->__max_needed_from = MAX_NEEDED_TO;
  3108. step->__min_needed_to = MIN_NEEDED_FROM;
  3109. step->__max_needed_to = MAX_NEEDED_FROM + 2;
  3110. }
  3111. /* Yes, this is a stateful encoding. */
  3112. step->__stateful = 1;
  3113. result = __GCONV_OK;
  3114. }
  3115. }
  3116. return result;
  3117. }
  3118. The function first checks which conversion is wanted. The module
  3119. from which this function is taken implements four different
  3120. conversions; which one is selected can be determined by comparing
  3121. the names. The comparison should always be done without paying
  3122. attention to the case.
  3123. Next, a data structure, which contains the necessary information
  3124. about which conversion is selected, is allocated. The data
  3125. structure ‘struct iso2022jp_data’ is locally defined since, outside
  3126. the module, this data is not used at all. Please note that if all
  3127. four conversions this module supports are requested there are four
  3128. data blocks.
  3129. One interesting thing is the initialization of the ‘__min_’ and
  3130. ‘__max_’ elements of the step data object. A single ISO-2022-JP
  3131. character can consist of one to four bytes. Therefore the
  3132. ‘MIN_NEEDED_FROM’ and ‘MAX_NEEDED_FROM’ macros are defined this
  3133. way. The output is always the ‘INTERNAL’ character set (aka UCS-4)
  3134. and therefore each character consists of exactly four bytes. For
  3135. the conversion from ‘INTERNAL’ to ISO-2022-JP we have to take into
  3136. account that escape sequences might be necessary to switch the
  3137. character sets. Therefore the ‘__max_needed_to’ element for this
  3138. direction gets assigned ‘MAX_NEEDED_FROM + 2’. This takes into
  3139. account the two bytes needed for the escape sequences to signal the
  3140. switching. The asymmetry in the maximum values for the two
  3141. directions can be explained easily: when reading ISO-2022-JP text,
  3142. escape sequences can be handled alone (i.e., it is not necessary to
  3143. process a real character since the effect of the escape sequence
  3144. can be recorded in the state information). The situation is
  3145. different for the other direction. Since it is in general not
  3146. known which character comes next, one cannot emit escape sequences
  3147. to change the state in advance. This means the escape sequences
  3148. have to be emitted together with the next character. Therefore one
  3149. needs more room than only for the character itself.
  3150. The possible return values of the initialization function are:
  3151. ‘__GCONV_OK’
  3152. The initialization succeeded
  3153. ‘__GCONV_NOCONV’
  3154. The requested conversion is not supported in the module. This
  3155. can happen if the ‘gconv-modules’ file has errors.
  3156. ‘__GCONV_NOMEM’
  3157. Memory required to store additional information could not be
  3158. allocated.
  3159. The function called before the module is unloaded is significantly
  3160. easier. It often has nothing at all to do; in which case it can be left
  3161. out completely.
  3162. -- Data type: void (*__gconv_end_fct) (struct gconv_step *)
  3163. The task of this function is to free all resources allocated in the
  3164. initialization function. Therefore only the ‘__data’ element of
  3165. the object pointed to by the argument is of interest. Continuing
  3166. the example from the initialization function, the finalization
  3167. function looks like this:
  3168. void
  3169. gconv_end (struct __gconv_step *data)
  3170. {
  3171. free (data->__data);
  3172. }
  3173. The most important function is the conversion function itself, which
  3174. can get quite complicated for complex character sets. But since this is
  3175. not of interest here, we will only describe a possible skeleton for the
  3176. conversion function.
  3177. -- Data type: int (*__gconv_fct) (struct __gconv_step *, struct
  3178. __gconv_step_data *, const char **, const char *, size_t *,
  3179. int)
  3180. The conversion function can be called for two basic reasons: to
  3181. convert text or to reset the state. From the description of the
  3182. ‘iconv’ function it can be seen why the flushing mode is necessary.
  3183. What mode is selected is determined by the sixth argument, an
  3184. integer. This argument being nonzero means that flushing is
  3185. selected.
  3186. Common to both modes is where the output buffer can be found. The
  3187. information about this buffer is stored in the conversion step
  3188. data. A pointer to this information is passed as the second
  3189. argument to this function. The description of the ‘struct
  3190. __gconv_step_data’ structure has more information on the conversion
  3191. step data.
  3192. What has to be done for flushing depends on the source character
  3193. set. If the source character set is not stateful, nothing has to
  3194. be done. Otherwise the function has to emit a byte sequence to
  3195. bring the state object into the initial state. Once this all
  3196. happened the other conversion modules in the chain of conversions
  3197. have to get the same chance. Whether another step follows can be
  3198. determined from the ‘__is_last’ element of the step data structure
  3199. to which the first parameter points.
  3200. The more interesting mode is when actual text has to be converted.
  3201. The first step in this case is to convert as much text as possible
  3202. from the input buffer and store the result in the output buffer.
  3203. The start of the input buffer is determined by the third argument,
  3204. which is a pointer to a pointer variable referencing the beginning
  3205. of the buffer. The fourth argument is a pointer to the byte right
  3206. after the last byte in the buffer.
  3207. The conversion has to be performed according to the current state
  3208. if the character set is stateful. The state is stored in an object
  3209. pointed to by the ‘__statep’ element of the step data (second
  3210. argument). Once either the input buffer is empty or the output
  3211. buffer is full the conversion stops. At this point, the pointer
  3212. variable referenced by the third parameter must point to the byte
  3213. following the last processed byte (i.e., if all of the input is
  3214. consumed, this pointer and the fourth parameter have the same
  3215. value).
  3216. What now happens depends on whether this step is the last one. If
  3217. it is the last step, the only thing that has to be done is to
  3218. update the ‘__outbuf’ element of the step data structure to point
  3219. after the last written byte. This update gives the caller the
  3220. information on how much text is available in the output buffer. In
  3221. addition, the variable pointed to by the fifth parameter, which is
  3222. of type ‘size_t’, must be incremented by the number of characters
  3223. (_not bytes_) that were converted in a non-reversible way. Then,
  3224. the function can return.
  3225. In case the step is not the last one, the later conversion
  3226. functions have to get a chance to do their work. Therefore, the
  3227. appropriate conversion function has to be called. The information
  3228. about the functions is stored in the conversion data structures,
  3229. passed as the first parameter. This information and the step data
  3230. are stored in arrays, so the next element in both cases can be
  3231. found by simple pointer arithmetic:
  3232. int
  3233. gconv (struct __gconv_step *step, struct __gconv_step_data *data,
  3234. const char **inbuf, const char *inbufend, size_t *written,
  3235. int do_flush)
  3236. {
  3237. struct __gconv_step *next_step = step + 1;
  3238. struct __gconv_step_data *next_data = data + 1;
  3239. The ‘next_step’ pointer references the next step information and
  3240. ‘next_data’ the next data record. The call of the next function
  3241. therefore will look similar to this:
  3242. next_step->__fct (next_step, next_data, &outerr, outbuf,
  3243. written, 0)
  3244. But this is not yet all. Once the function call returns the
  3245. conversion function might have some more to do. If the return
  3246. value of the function is ‘__GCONV_EMPTY_INPUT’, more room is
  3247. available in the output buffer. Unless the input buffer is empty,
  3248. the conversion functions start all over again and process the rest
  3249. of the input buffer. If the return value is not
  3250. ‘__GCONV_EMPTY_INPUT’, something went wrong and we have to recover
  3251. from this.
  3252. A requirement for the conversion function is that the input buffer
  3253. pointer (the third argument) always point to the last character
  3254. that was put in converted form into the output buffer. This is
  3255. trivially true after the conversion performed in the current step,
  3256. but if the conversion functions deeper downstream stop prematurely,
  3257. not all characters from the output buffer are consumed and,
  3258. therefore, the input buffer pointers must be backed off to the
  3259. right position.
  3260. Correcting the input buffers is easy to do if the input and output
  3261. character sets have a fixed width for all characters. In this
  3262. situation we can compute how many characters are left in the output
  3263. buffer and, therefore, can correct the input buffer pointer
  3264. appropriately with a similar computation. Things are getting
  3265. tricky if either character set has characters represented with
  3266. variable length byte sequences, and it gets even more complicated
  3267. if the conversion has to take care of the state. In these cases
  3268. the conversion has to be performed once again, from the known state
  3269. before the initial conversion (i.e., if necessary the state of the
  3270. conversion has to be reset and the conversion loop has to be
  3271. executed again). The difference now is that it is known how much
  3272. input must be created, and the conversion can stop before
  3273. converting the first unused character. Once this is done the input
  3274. buffer pointers must be updated again and the function can return.
  3275. One final thing should be mentioned. If it is necessary for the
  3276. conversion to know whether it is the first invocation (in case a
  3277. prolog has to be emitted), the conversion function should increment
  3278. the ‘__invocation_counter’ element of the step data structure just
  3279. before returning to the caller. See the description of the ‘struct
  3280. __gconv_step_data’ structure above for more information on how this
  3281. can be used.
  3282. The return value must be one of the following values:
  3283. ‘__GCONV_EMPTY_INPUT’
  3284. All input was consumed and there is room left in the output
  3285. buffer.
  3286. ‘__GCONV_FULL_OUTPUT’
  3287. No more room in the output buffer. In case this is not the
  3288. last step this value is propagated down from the call of the
  3289. next conversion function in the chain.
  3290. ‘__GCONV_INCOMPLETE_INPUT’
  3291. The input buffer is not entirely empty since it contains an
  3292. incomplete character sequence.
  3293. The following example provides a framework for a conversion
  3294. function. In case a new conversion has to be written the holes in
  3295. this implementation have to be filled and that is it.
  3296. int
  3297. gconv (struct __gconv_step *step, struct __gconv_step_data *data,
  3298. const char **inbuf, const char *inbufend, size_t *written,
  3299. int do_flush)
  3300. {
  3301. struct __gconv_step *next_step = step + 1;
  3302. struct __gconv_step_data *next_data = data + 1;
  3303. gconv_fct fct = next_step->__fct;
  3304. int status;
  3305. /* If the function is called with no input this means we have
  3306. to reset to the initial state. The possibly partly
  3307. converted input is dropped. */
  3308. if (do_flush)
  3309. {
  3310. status = __GCONV_OK;
  3311. /* Possible emit a byte sequence which put the state object
  3312. into the initial state. */
  3313. /* Call the steps down the chain if there are any but only
  3314. if we successfully emitted the escape sequence. */
  3315. if (status == __GCONV_OK && ! data->__is_last)
  3316. status = fct (next_step, next_data, NULL, NULL,
  3317. written, 1);
  3318. }
  3319. else
  3320. {
  3321. /* We preserve the initial values of the pointer variables. */
  3322. const char *inptr = *inbuf;
  3323. char *outbuf = data->__outbuf;
  3324. char *outend = data->__outbufend;
  3325. char *outptr;
  3326. do
  3327. {
  3328. /* Remember the start value for this round. */
  3329. inptr = *inbuf;
  3330. /* The outbuf buffer is empty. */
  3331. outptr = outbuf;
  3332. /* For stateful encodings the state must be safe here. */
  3333. /* Run the conversion loop. ‘status’ is set
  3334. appropriately afterwards. */
  3335. /* If this is the last step, leave the loop. There is
  3336. nothing we can do. */
  3337. if (data->__is_last)
  3338. {
  3339. /* Store information about how many bytes are
  3340. available. */
  3341. data->__outbuf = outbuf;
  3342. /* If any non-reversible conversions were performed,
  3343. add the number to ‘*written’. */
  3344. break;
  3345. }
  3346. /* Write out all output that was produced. */
  3347. if (outbuf > outptr)
  3348. {
  3349. const char *outerr = data->__outbuf;
  3350. int result;
  3351. result = fct (next_step, next_data, &outerr,
  3352. outbuf, written, 0);
  3353. if (result != __GCONV_EMPTY_INPUT)
  3354. {
  3355. if (outerr != outbuf)
  3356. {
  3357. /* Reset the input buffer pointer. We
  3358. document here the complex case. */
  3359. size_t nstatus;
  3360. /* Reload the pointers. */
  3361. *inbuf = inptr;
  3362. outbuf = outptr;
  3363. /* Possibly reset the state. */
  3364. /* Redo the conversion, but this time
  3365. the end of the output buffer is at
  3366. ‘outerr’. */
  3367. }
  3368. /* Change the status. */
  3369. status = result;
  3370. }
  3371. else
  3372. /* All the output is consumed, we can make
  3373. another run if everything was ok. */
  3374. if (status == __GCONV_FULL_OUTPUT)
  3375. status = __GCONV_OK;
  3376. }
  3377. }
  3378. while (status == __GCONV_OK);
  3379. /* We finished one use of this step. */
  3380. ++data->__invocation_counter;
  3381. }
  3382. return status;
  3383. }
  3384. This information should be sufficient to write new modules. Anybody
  3385. doing so should also take a look at the available source code in the GNU
  3386. C Library sources. It contains many examples of working and optimized
  3387. modules.
  3388. 
  3389. File: libc.info, Node: Locales, Next: Message Translation, Prev: Character Set Handling, Up: Top
  3390. 7 Locales and Internationalization
  3391. **********************************
  3392. Different countries and cultures have varying conventions for how to
  3393. communicate. These conventions range from very simple ones, such as the
  3394. format for representing dates and times, to very complex ones, such as
  3395. the language spoken.
  3396. "Internationalization" of software means programming it to be able to
  3397. adapt to the user’s favorite conventions. In ISO C,
  3398. internationalization works by means of "locales". Each locale specifies
  3399. a collection of conventions, one convention for each purpose. The user
  3400. chooses a set of conventions by specifying a locale (via environment
  3401. variables).
  3402. All programs inherit the chosen locale as part of their environment.
  3403. Provided the programs are written to obey the choice of locale, they
  3404. will follow the conventions preferred by the user.
  3405. * Menu:
  3406. * Effects of Locale:: Actions affected by the choice of
  3407. locale.
  3408. * Choosing Locale:: How the user specifies a locale.
  3409. * Locale Categories:: Different purposes for which you can
  3410. select a locale.
  3411. * Setting the Locale:: How a program specifies the locale
  3412. with library functions.
  3413. * Standard Locales:: Locale names available on all systems.
  3414. * Locale Names:: Format of system-specific locale names.
  3415. * Locale Information:: How to access the information for the locale.
  3416. * Formatting Numbers:: A dedicated function to format numbers.
  3417. * Yes-or-No Questions:: Check a Response against the locale.
  3418. 
  3419. File: libc.info, Node: Effects of Locale, Next: Choosing Locale, Up: Locales
  3420. 7.1 What Effects a Locale Has
  3421. =============================
  3422. Each locale specifies conventions for several purposes, including the
  3423. following:
  3424. • What multibyte character sequences are valid, and how they are
  3425. interpreted (*note Character Set Handling::).
  3426. • Classification of which characters in the local character set are
  3427. considered alphabetic, and upper- and lower-case conversion
  3428. conventions (*note Character Handling::).
  3429. • The collating sequence for the local language and character set
  3430. (*note Collation Functions::).
  3431. • Formatting of numbers and currency amounts (*note General
  3432. Numeric::).
  3433. • Formatting of dates and times (*note Formatting Calendar Time::).
  3434. • What language to use for output, including error messages (*note
  3435. Message Translation::).
  3436. • What language to use for user answers to yes-or-no questions (*note
  3437. Yes-or-No Questions::).
  3438. • What language to use for more complex user input. (The C library
  3439. doesn’t yet help you implement this.)
  3440. Some aspects of adapting to the specified locale are handled
  3441. automatically by the library subroutines. For example, all your program
  3442. needs to do in order to use the collating sequence of the chosen locale
  3443. is to use ‘strcoll’ or ‘strxfrm’ to compare strings.
  3444. Other aspects of locales are beyond the comprehension of the library.
  3445. For example, the library can’t automatically translate your program’s
  3446. output messages into other languages. The only way you can support
  3447. output in the user’s favorite language is to program this more or less
  3448. by hand. The C library provides functions to handle translations for
  3449. multiple languages easily.
  3450. This chapter discusses the mechanism by which you can modify the
  3451. current locale. The effects of the current locale on specific library
  3452. functions are discussed in more detail in the descriptions of those
  3453. functions.
  3454. 
  3455. File: libc.info, Node: Choosing Locale, Next: Locale Categories, Prev: Effects of Locale, Up: Locales
  3456. 7.2 Choosing a Locale
  3457. =====================
  3458. The simplest way for the user to choose a locale is to set the
  3459. environment variable ‘LANG’. This specifies a single locale to use for
  3460. all purposes. For example, a user could specify a hypothetical locale
  3461. named ‘espana-castellano’ to use the standard conventions of most of
  3462. Spain.
  3463. The set of locales supported depends on the operating system you are
  3464. using, and so do their names, except that the standard locale called ‘C’
  3465. or ‘POSIX’ always exist. *Note Locale Names::.
  3466. In order to force the system to always use the default locale, the
  3467. user can set the ‘LC_ALL’ environment variable to ‘C’.
  3468. A user also has the option of specifying different locales for
  3469. different purposes—in effect, choosing a mixture of multiple locales.
  3470. *Note Locale Categories::.
  3471. For example, the user might specify the locale ‘espana-castellano’
  3472. for most purposes, but specify the locale ‘usa-english’ for currency
  3473. formatting. This might make sense if the user is a Spanish-speaking
  3474. American, working in Spanish, but representing monetary amounts in US
  3475. dollars.
  3476. Note that both locales ‘espana-castellano’ and ‘usa-english’, like
  3477. all locales, would include conventions for all of the purposes to which
  3478. locales apply. However, the user can choose to use each locale for a
  3479. particular subset of those purposes.
  3480. 
  3481. File: libc.info, Node: Locale Categories, Next: Setting the Locale, Prev: Choosing Locale, Up: Locales
  3482. 7.3 Locale Categories
  3483. =====================
  3484. The purposes that locales serve are grouped into "categories", so that a
  3485. user or a program can choose the locale for each category independently.
  3486. Here is a table of categories; each name is both an environment variable
  3487. that a user can set, and a macro name that you can use as the first
  3488. argument to ‘setlocale’.
  3489. The contents of the environment variable (or the string in the second
  3490. argument to ‘setlocale’) has to be a valid locale name. *Note Locale
  3491. Names::.
  3492. ‘LC_COLLATE’
  3493. This category applies to collation of strings (functions ‘strcoll’
  3494. and ‘strxfrm’); see *note Collation Functions::.
  3495. ‘LC_CTYPE’
  3496. This category applies to classification and conversion of
  3497. characters, and to multibyte and wide characters; see *note
  3498. Character Handling::, and *note Character Set Handling::.
  3499. ‘LC_MONETARY’
  3500. This category applies to formatting monetary values; see *note
  3501. General Numeric::.
  3502. ‘LC_NUMERIC’
  3503. This category applies to formatting numeric values that are not
  3504. monetary; see *note General Numeric::.
  3505. ‘LC_TIME’
  3506. This category applies to formatting date and time values; see *note
  3507. Formatting Calendar Time::.
  3508. ‘LC_MESSAGES’
  3509. This category applies to selecting the language used in the user
  3510. interface for message translation (*note The Uniforum approach::;
  3511. *note Message catalogs a la X/Open::) and contains regular
  3512. expressions for affirmative and negative responses.
  3513. ‘LC_ALL’
  3514. This is not a category; it is only a macro that you can use with
  3515. ‘setlocale’ to set a single locale for all purposes. Setting this
  3516. environment variable overwrites all selections by the other ‘LC_*’
  3517. variables or ‘LANG’.
  3518. ‘LANG’
  3519. If this environment variable is defined, its value specifies the
  3520. locale to use for all purposes except as overridden by the
  3521. variables above.
  3522. When developing the message translation functions it was felt that
  3523. the functionality provided by the variables above is not sufficient.
  3524. For example, it should be possible to specify more than one locale name.
  3525. Take a Swedish user who better speaks German than English, and a program
  3526. whose messages are output in English by default. It should be possible
  3527. to specify that the first choice of language is Swedish, the second
  3528. German, and if this also fails to use English. This is possible with
  3529. the variable ‘LANGUAGE’. For further description of this GNU extension
  3530. see *note Using gettextized software::.
  3531. 
  3532. File: libc.info, Node: Setting the Locale, Next: Standard Locales, Prev: Locale Categories, Up: Locales
  3533. 7.4 How Programs Set the Locale
  3534. ===============================
  3535. A C program inherits its locale environment variables when it starts up.
  3536. This happens automatically. However, these variables do not
  3537. automatically control the locale used by the library functions, because ISO C
  3538. says that all programs start by default in the standard ‘C’ locale. To
  3539. use the locales specified by the environment, you must call ‘setlocale’.
  3540. Call it as follows:
  3541. setlocale (LC_ALL, "");
  3542. to select a locale based on the user choice of the appropriate
  3543. environment variables.
  3544. You can also use ‘setlocale’ to specify a particular locale, for
  3545. general use or for a specific category.
  3546. The symbols in this section are defined in the header file
  3547. ‘locale.h’.
  3548. -- Function: char * setlocale (int CATEGORY, const char *LOCALE)
  3549. Preliminary: | MT-Unsafe const:locale env | AS-Unsafe init lock
  3550. heap corrupt | AC-Unsafe init corrupt lock mem fd | *Note POSIX
  3551. Safety Concepts::.
  3552. The function ‘setlocale’ sets the current locale for category
  3553. CATEGORY to LOCALE.
  3554. If CATEGORY is ‘LC_ALL’, this specifies the locale for all
  3555. purposes. The other possible values of CATEGORY specify a single
  3556. purpose (*note Locale Categories::).
  3557. You can also use this function to find out the current locale by
  3558. passing a null pointer as the LOCALE argument. In this case,
  3559. ‘setlocale’ returns a string that is the name of the locale
  3560. currently selected for category CATEGORY.
  3561. The string returned by ‘setlocale’ can be overwritten by subsequent
  3562. calls, so you should make a copy of the string (*note Copying
  3563. Strings and Arrays::) if you want to save it past any further calls
  3564. to ‘setlocale’. (The standard library is guaranteed never to call
  3565. ‘setlocale’ itself.)
  3566. You should not modify the string returned by ‘setlocale’. It might
  3567. be the same string that was passed as an argument in a previous
  3568. call to ‘setlocale’. One requirement is that the CATEGORY must be
  3569. the same in the call the string was returned and the one when the
  3570. string is passed in as LOCALE parameter.
  3571. When you read the current locale for category ‘LC_ALL’, the value
  3572. encodes the entire combination of selected locales for all
  3573. categories. If you specify the same “locale name” with ‘LC_ALL’ in
  3574. a subsequent call to ‘setlocale’, it restores the same combination
  3575. of locale selections.
  3576. To be sure you can use the returned string encoding the currently
  3577. selected locale at a later time, you must make a copy of the
  3578. string. It is not guaranteed that the returned pointer remains
  3579. valid over time.
  3580. When the LOCALE argument is not a null pointer, the string returned
  3581. by ‘setlocale’ reflects the newly-modified locale.
  3582. If you specify an empty string for LOCALE, this means to read the
  3583. appropriate environment variable and use its value to select the
  3584. locale for CATEGORY.
  3585. If a nonempty string is given for LOCALE, then the locale of that
  3586. name is used if possible.
  3587. The effective locale name (either the second argument to
  3588. ‘setlocale’, or if the argument is an empty string, the name
  3589. obtained from the process environment) must be a valid locale name.
  3590. *Note Locale Names::.
  3591. If you specify an invalid locale name, ‘setlocale’ returns a null
  3592. pointer and leaves the current locale unchanged.
  3593. Here is an example showing how you might use ‘setlocale’ to
  3594. temporarily switch to a new locale.
  3595. #include <stddef.h>
  3596. #include <locale.h>
  3597. #include <stdlib.h>
  3598. #include <string.h>
  3599. void
  3600. with_other_locale (char *new_locale,
  3601. void (*subroutine) (int),
  3602. int argument)
  3603. {
  3604. char *old_locale, *saved_locale;
  3605. /* Get the name of the current locale. */
  3606. old_locale = setlocale (LC_ALL, NULL);
  3607. /* Copy the name so it won’t be clobbered by ‘setlocale’. */
  3608. saved_locale = strdup (old_locale);
  3609. if (saved_locale == NULL)
  3610. fatal ("Out of memory");
  3611. /* Now change the locale and do some stuff with it. */
  3612. setlocale (LC_ALL, new_locale);
  3613. (*subroutine) (argument);
  3614. /* Restore the original locale. */
  3615. setlocale (LC_ALL, saved_locale);
  3616. free (saved_locale);
  3617. }
  3618. *Portability Note:* Some ISO C systems may define additional locale
  3619. categories, and future versions of the library will do so. For
  3620. portability, assume that any symbol beginning with ‘LC_’ might be
  3621. defined in ‘locale.h’.
  3622. 
  3623. File: libc.info, Node: Standard Locales, Next: Locale Names, Prev: Setting the Locale, Up: Locales
  3624. 7.5 Standard Locales
  3625. ====================
  3626. The only locale names you can count on finding on all operating systems
  3627. are these three standard ones:
  3628. ‘"C"’
  3629. This is the standard C locale. The attributes and behavior it
  3630. provides are specified in the ISO C standard. When your program
  3631. starts up, it initially uses this locale by default.
  3632. ‘"POSIX"’
  3633. This is the standard POSIX locale. Currently, it is an alias for
  3634. the standard C locale.
  3635. ‘""’
  3636. The empty name says to select a locale based on environment
  3637. variables. *Note Locale Categories::.
  3638. Defining and installing named locales is normally a responsibility of
  3639. the system administrator at your site (or the person who installed the
  3640. GNU C Library). It is also possible for the user to create private
  3641. locales. All this will be discussed later when describing the tool to
  3642. do so.
  3643. If your program needs to use something other than the ‘C’ locale, it
  3644. will be more portable if you use whatever locale the user specifies with
  3645. the environment, rather than trying to specify some non-standard locale
  3646. explicitly by name. Remember, different machines might have different
  3647. sets of locales installed.
  3648. 
  3649. File: libc.info, Node: Locale Names, Next: Locale Information, Prev: Standard Locales, Up: Locales
  3650. 7.6 Locale Names
  3651. ================
  3652. The following command prints a list of locales supported by the system:
  3653. locale -a
  3654. *Portability Note:* With the notable exception of the standard locale
  3655. names ‘C’ and ‘POSIX’, locale names are system-specific.
  3656. Most locale names follow XPG syntax and consist of up to four parts:
  3657. LANGUAGE[_TERRITORY[.CODESET]][@MODIFIER]
  3658. Beside the first part, all of them are allowed to be missing. If the
  3659. full specified locale is not found, less specific ones are looked for.
  3660. The various parts will be stripped off, in the following order:
  3661. 1. codeset
  3662. 2. normalized codeset
  3663. 3. territory
  3664. 4. modifier
  3665. For example, the locale name ‘de_AT.iso885915@euro’ denotes a
  3666. German-language locale for use in Austria, using the ISO-8859-15
  3667. (Latin-9) character set, and with the Euro as the currency symbol.
  3668. In addition to locale names which follow XPG syntax, systems may
  3669. provide aliases such as ‘german’. Both categories of names must not
  3670. contain the slash character ‘/’.
  3671. If the locale name starts with a slash ‘/’, it is treated as a path
  3672. relative to the configured locale directories; see ‘LOCPATH’ below. The
  3673. specified path must not contain a component ‘..’, or the name is
  3674. invalid, and ‘setlocale’ will fail.
  3675. *Portability Note:* POSIX suggests that if a locale name starts with
  3676. a slash ‘/’, it is resolved as an absolute path. However, the GNU C
  3677. Library treats it as a relative path under the directories listed in
  3678. ‘LOCPATH’ (or the default locale directory if ‘LOCPATH’ is unset).
  3679. Locale names which are longer than an implementation-defined limit
  3680. are invalid and cause ‘setlocale’ to fail.
  3681. As a special case, locale names used with ‘LC_ALL’ can combine
  3682. several locales, reflecting different locale settings for different
  3683. categories. For example, you might want to use a U.S. locale with ISO
  3684. A4 paper format, so you set ‘LANG’ to ‘en_US.UTF-8’, and ‘LC_PAPER’ to
  3685. ‘de_DE.UTF-8’. In this case, the ‘LC_ALL’-style combined locale name is
  3686. LC_CTYPE=en_US.UTF-8;LC_TIME=en_US.UTF-8;LC_PAPER=de_DE.UTF-8;…
  3687. followed by other category settings not shown here.
  3688. The path used for finding locale data can be set using the ‘LOCPATH’
  3689. environment variable. This variable lists the directories in which to
  3690. search for locale definitions, separated by a colon ‘:’.
  3691. The default path for finding locale data is system specific. A
  3692. typical value for the ‘LOCPATH’ default is:
  3693. /usr/share/locale
  3694. The value of ‘LOCPATH’ is ignored by privileged programs for security
  3695. reasons, and only the default directory is used.
  3696. 
  3697. File: libc.info, Node: Locale Information, Next: Formatting Numbers, Prev: Locale Names, Up: Locales
  3698. 7.7 Accessing Locale Information
  3699. ================================
  3700. There are several ways to access locale information. The simplest way
  3701. is to let the C library itself do the work. Several of the functions in
  3702. this library implicitly access the locale data, and use what information
  3703. is provided by the currently selected locale. This is how the locale
  3704. model is meant to work normally.
  3705. As an example take the ‘strftime’ function, which is meant to nicely
  3706. format date and time information (*note Formatting Calendar Time::).
  3707. Part of the standard information contained in the ‘LC_TIME’ category is
  3708. the names of the months. Instead of requiring the programmer to take
  3709. care of providing the translations the ‘strftime’ function does this all
  3710. by itself. ‘%A’ in the format string is replaced by the appropriate
  3711. weekday name of the locale currently selected by ‘LC_TIME’. This is an
  3712. easy example, and wherever possible functions do things automatically in
  3713. this way.
  3714. But there are quite often situations when there is simply no function
  3715. to perform the task, or it is simply not possible to do the work
  3716. automatically. For these cases it is necessary to access the
  3717. information in the locale directly. To do this the C library provides
  3718. two functions: ‘localeconv’ and ‘nl_langinfo’. The former is part of ISO C
  3719. and therefore portable, but has a brain-damaged interface. The second
  3720. is part of the Unix interface and is portable in as far as the system
  3721. follows the Unix standards.
  3722. * Menu:
  3723. * The Lame Way to Locale Data:: ISO C’s ‘localeconv’.
  3724. * The Elegant and Fast Way:: X/Open’s ‘nl_langinfo’.
  3725. 
  3726. File: libc.info, Node: The Lame Way to Locale Data, Next: The Elegant and Fast Way, Up: Locale Information
  3727. 7.7.1 ‘localeconv’: It is portable but …
  3728. ----------------------------------------
  3729. Together with the ‘setlocale’ function the ISO C people invented the
  3730. ‘localeconv’ function. It is a masterpiece of poor design. It is
  3731. expensive to use, not extensible, and not generally usable as it
  3732. provides access to only ‘LC_MONETARY’ and ‘LC_NUMERIC’ related
  3733. information. Nevertheless, if it is applicable to a given situation it
  3734. should be used since it is very portable. The function ‘strfmon’
  3735. formats monetary amounts according to the selected locale using this
  3736. information.
  3737. -- Function: struct lconv * localeconv (void)
  3738. Preliminary: | MT-Unsafe race:localeconv locale | AS-Unsafe |
  3739. AC-Safe | *Note POSIX Safety Concepts::.
  3740. The ‘localeconv’ function returns a pointer to a structure whose
  3741. components contain information about how numeric and monetary
  3742. values should be formatted in the current locale.
  3743. You should not modify the structure or its contents. The structure
  3744. might be overwritten by subsequent calls to ‘localeconv’, or by
  3745. calls to ‘setlocale’, but no other function in the library
  3746. overwrites this value.
  3747. -- Data Type: struct lconv
  3748. ‘localeconv’’s return value is of this data type. Its elements are
  3749. described in the following subsections.
  3750. If a member of the structure ‘struct lconv’ has type ‘char’, and the
  3751. value is ‘CHAR_MAX’, it means that the current locale has no value for
  3752. that parameter.
  3753. * Menu:
  3754. * General Numeric:: Parameters for formatting numbers and
  3755. currency amounts.
  3756. * Currency Symbol:: How to print the symbol that identifies an
  3757. amount of money (e.g. ‘$’).
  3758. * Sign of Money Amount:: How to print the (positive or negative) sign
  3759. for a monetary amount, if one exists.
  3760. 
  3761. File: libc.info, Node: General Numeric, Next: Currency Symbol, Up: The Lame Way to Locale Data
  3762. 7.7.1.1 Generic Numeric Formatting Parameters
  3763. .............................................
  3764. These are the standard members of ‘struct lconv’; there may be others.
  3765. ‘char *decimal_point’
  3766. ‘char *mon_decimal_point’
  3767. These are the decimal-point separators used in formatting
  3768. non-monetary and monetary quantities, respectively. In the ‘C’
  3769. locale, the value of ‘decimal_point’ is ‘"."’, and the value of
  3770. ‘mon_decimal_point’ is ‘""’.
  3771. ‘char *thousands_sep’
  3772. ‘char *mon_thousands_sep’
  3773. These are the separators used to delimit groups of digits to the
  3774. left of the decimal point in formatting non-monetary and monetary
  3775. quantities, respectively. In the ‘C’ locale, both members have a
  3776. value of ‘""’ (the empty string).
  3777. ‘char *grouping’
  3778. ‘char *mon_grouping’
  3779. These are strings that specify how to group the digits to the left
  3780. of the decimal point. ‘grouping’ applies to non-monetary
  3781. quantities and ‘mon_grouping’ applies to monetary quantities. Use
  3782. either ‘thousands_sep’ or ‘mon_thousands_sep’ to separate the digit
  3783. groups.
  3784. Each member of these strings is to be interpreted as an integer
  3785. value of type ‘char’. Successive numbers (from left to right) give
  3786. the sizes of successive groups (from right to left, starting at the
  3787. decimal point.) The last member is either ‘0’, in which case the
  3788. previous member is used over and over again for all the remaining
  3789. groups, or ‘CHAR_MAX’, in which case there is no more grouping—or,
  3790. put another way, any remaining digits form one large group without
  3791. separators.
  3792. For example, if ‘grouping’ is ‘"\04\03\02"’, the correct grouping
  3793. for the number ‘123456787654321’ is ‘12’, ‘34’, ‘56’, ‘78’, ‘765’,
  3794. ‘4321’. This uses a group of 4 digits at the end, preceded by a
  3795. group of 3 digits, preceded by groups of 2 digits (as many as
  3796. needed). With a separator of ‘,’, the number would be printed as
  3797. ‘12,34,56,78,765,4321’.
  3798. A value of ‘"\03"’ indicates repeated groups of three digits, as
  3799. normally used in the U.S.
  3800. In the standard ‘C’ locale, both ‘grouping’ and ‘mon_grouping’ have
  3801. a value of ‘""’. This value specifies no grouping at all.
  3802. ‘char int_frac_digits’
  3803. ‘char frac_digits’
  3804. These are small integers indicating how many fractional digits (to
  3805. the right of the decimal point) should be displayed in a monetary
  3806. value in international and local formats, respectively. (Most
  3807. often, both members have the same value.)
  3808. In the standard ‘C’ locale, both of these members have the value
  3809. ‘CHAR_MAX’, meaning “unspecified”. The ISO standard doesn’t say
  3810. what to do when you find this value; we recommend printing no
  3811. fractional digits. (This locale also specifies the empty string
  3812. for ‘mon_decimal_point’, so printing any fractional digits would be
  3813. confusing!)
  3814. 
  3815. File: libc.info, Node: Currency Symbol, Next: Sign of Money Amount, Prev: General Numeric, Up: The Lame Way to Locale Data
  3816. 7.7.1.2 Printing the Currency Symbol
  3817. ....................................
  3818. These members of the ‘struct lconv’ structure specify how to print the
  3819. symbol to identify a monetary value—the international analog of ‘$’ for
  3820. US dollars.
  3821. Each country has two standard currency symbols. The "local currency
  3822. symbol" is used commonly within the country, while the "international
  3823. currency symbol" is used internationally to refer to that country’s
  3824. currency when it is necessary to indicate the country unambiguously.
  3825. For example, many countries use the dollar as their monetary unit,
  3826. and when dealing with international currencies it’s important to specify
  3827. that one is dealing with (say) Canadian dollars instead of U.S. dollars
  3828. or Australian dollars. But when the context is known to be Canada,
  3829. there is no need to make this explicit—dollar amounts are implicitly
  3830. assumed to be in Canadian dollars.
  3831. ‘char *currency_symbol’
  3832. The local currency symbol for the selected locale.
  3833. In the standard ‘C’ locale, this member has a value of ‘""’ (the
  3834. empty string), meaning “unspecified”. The ISO standard doesn’t say
  3835. what to do when you find this value; we recommend you simply print
  3836. the empty string as you would print any other string pointed to by
  3837. this variable.
  3838. ‘char *int_curr_symbol’
  3839. The international currency symbol for the selected locale.
  3840. The value of ‘int_curr_symbol’ should normally consist of a
  3841. three-letter abbreviation determined by the international standard
  3842. ‘ISO 4217 Codes for the Representation of Currency and Funds’,
  3843. followed by a one-character separator (often a space).
  3844. In the standard ‘C’ locale, this member has a value of ‘""’ (the
  3845. empty string), meaning “unspecified”. We recommend you simply
  3846. print the empty string as you would print any other string pointed
  3847. to by this variable.
  3848. ‘char p_cs_precedes’
  3849. ‘char n_cs_precedes’
  3850. ‘char int_p_cs_precedes’
  3851. ‘char int_n_cs_precedes’
  3852. These members are ‘1’ if the ‘currency_symbol’ or ‘int_curr_symbol’
  3853. strings should precede the value of a monetary amount, or ‘0’ if
  3854. the strings should follow the value. The ‘p_cs_precedes’ and
  3855. ‘int_p_cs_precedes’ members apply to positive amounts (or zero),
  3856. and the ‘n_cs_precedes’ and ‘int_n_cs_precedes’ members apply to
  3857. negative amounts.
  3858. In the standard ‘C’ locale, all of these members have a value of
  3859. ‘CHAR_MAX’, meaning “unspecified”. The ISO standard doesn’t say
  3860. what to do when you find this value. We recommend printing the
  3861. currency symbol before the amount, which is right for most
  3862. countries. In other words, treat all nonzero values alike in these
  3863. members.
  3864. The members with the ‘int_’ prefix apply to the ‘int_curr_symbol’
  3865. while the other two apply to ‘currency_symbol’.
  3866. ‘char p_sep_by_space’
  3867. ‘char n_sep_by_space’
  3868. ‘char int_p_sep_by_space’
  3869. ‘char int_n_sep_by_space’
  3870. These members are ‘1’ if a space should appear between the
  3871. ‘currency_symbol’ or ‘int_curr_symbol’ strings and the amount, or
  3872. ‘0’ if no space should appear. The ‘p_sep_by_space’ and
  3873. ‘int_p_sep_by_space’ members apply to positive amounts (or zero),
  3874. and the ‘n_sep_by_space’ and ‘int_n_sep_by_space’ members apply to
  3875. negative amounts.
  3876. In the standard ‘C’ locale, all of these members have a value of
  3877. ‘CHAR_MAX’, meaning “unspecified”. The ISO standard doesn’t say
  3878. what you should do when you find this value; we suggest you treat
  3879. it as 1 (print a space). In other words, treat all nonzero values
  3880. alike in these members.
  3881. The members with the ‘int_’ prefix apply to the ‘int_curr_symbol’
  3882. while the other two apply to ‘currency_symbol’. There is one
  3883. specialty with the ‘int_curr_symbol’, though. Since all legal
  3884. values contain a space at the end of the string one either prints
  3885. this space (if the currency symbol must appear in front and must be
  3886. separated) or one has to avoid printing this character at all
  3887. (especially when at the end of the string).
  3888. 
  3889. File: libc.info, Node: Sign of Money Amount, Prev: Currency Symbol, Up: The Lame Way to Locale Data
  3890. 7.7.1.3 Printing the Sign of a Monetary Amount
  3891. ..............................................
  3892. These members of the ‘struct lconv’ structure specify how to print the
  3893. sign (if any) of a monetary value.
  3894. ‘char *positive_sign’
  3895. ‘char *negative_sign’
  3896. These are strings used to indicate positive (or zero) and negative
  3897. monetary quantities, respectively.
  3898. In the standard ‘C’ locale, both of these members have a value of
  3899. ‘""’ (the empty string), meaning “unspecified”.
  3900. The ISO standard doesn’t say what to do when you find this value;
  3901. we recommend printing ‘positive_sign’ as you find it, even if it is
  3902. empty. For a negative value, print ‘negative_sign’ as you find it
  3903. unless both it and ‘positive_sign’ are empty, in which case print
  3904. ‘-’ instead. (Failing to indicate the sign at all seems rather
  3905. unreasonable.)
  3906. ‘char p_sign_posn’
  3907. ‘char n_sign_posn’
  3908. ‘char int_p_sign_posn’
  3909. ‘char int_n_sign_posn’
  3910. These members are small integers that indicate how to position the
  3911. sign for nonnegative and negative monetary quantities,
  3912. respectively. (The string used for the sign is what was specified
  3913. with ‘positive_sign’ or ‘negative_sign’.) The possible values are
  3914. as follows:
  3915. ‘0’
  3916. The currency symbol and quantity should be surrounded by
  3917. parentheses.
  3918. ‘1’
  3919. Print the sign string before the quantity and currency symbol.
  3920. ‘2’
  3921. Print the sign string after the quantity and currency symbol.
  3922. ‘3’
  3923. Print the sign string right before the currency symbol.
  3924. ‘4’
  3925. Print the sign string right after the currency symbol.
  3926. ‘CHAR_MAX’
  3927. “Unspecified”. Both members have this value in the standard
  3928. ‘C’ locale.
  3929. The ISO standard doesn’t say what you should do when the value is
  3930. ‘CHAR_MAX’. We recommend you print the sign after the currency
  3931. symbol.
  3932. The members with the ‘int_’ prefix apply to the ‘int_curr_symbol’
  3933. while the other two apply to ‘currency_symbol’.
  3934. 
  3935. File: libc.info, Node: The Elegant and Fast Way, Prev: The Lame Way to Locale Data, Up: Locale Information
  3936. 7.7.2 Pinpoint Access to Locale Data
  3937. ------------------------------------
  3938. When writing the X/Open Portability Guide the authors realized that the
  3939. ‘localeconv’ function is not enough to provide reasonable access to
  3940. locale information. The information which was meant to be available in
  3941. the locale (as later specified in the POSIX.1 standard) requires more
  3942. ways to access it. Therefore the ‘nl_langinfo’ function was introduced.
  3943. -- Function: char * nl_langinfo (nl_item ITEM)
  3944. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3945. Safety Concepts::.
  3946. The ‘nl_langinfo’ function can be used to access individual
  3947. elements of the locale categories. Unlike the ‘localeconv’
  3948. function, which returns all the information, ‘nl_langinfo’ lets the
  3949. caller select what information it requires. This is very fast and
  3950. it is not a problem to call this function multiple times.
  3951. A second advantage is that in addition to the numeric and monetary
  3952. formatting information, information from the ‘LC_TIME’ and
  3953. ‘LC_MESSAGES’ categories is available.
  3954. The type ‘nl_type’ is defined in ‘nl_types.h’. The argument ITEM
  3955. is a numeric value defined in the header ‘langinfo.h’. The X/Open
  3956. standard defines the following values:
  3957. ‘CODESET’
  3958. ‘nl_langinfo’ returns a string with the name of the coded
  3959. character set used in the selected locale.
  3960. ‘ABDAY_1’
  3961. ‘ABDAY_2’
  3962. ‘ABDAY_3’
  3963. ‘ABDAY_4’
  3964. ‘ABDAY_5’
  3965. ‘ABDAY_6’
  3966. ‘ABDAY_7’
  3967. ‘nl_langinfo’ returns the abbreviated weekday name. ‘ABDAY_1’
  3968. corresponds to Sunday.
  3969. ‘DAY_1’
  3970. ‘DAY_2’
  3971. ‘DAY_3’
  3972. ‘DAY_4’
  3973. ‘DAY_5’
  3974. ‘DAY_6’
  3975. ‘DAY_7’
  3976. Similar to ‘ABDAY_1’ etc., but here the return value is the
  3977. unabbreviated weekday name.
  3978. ‘ABMON_1’
  3979. ‘ABMON_2’
  3980. ‘ABMON_3’
  3981. ‘ABMON_4’
  3982. ‘ABMON_5’
  3983. ‘ABMON_6’
  3984. ‘ABMON_7’
  3985. ‘ABMON_8’
  3986. ‘ABMON_9’
  3987. ‘ABMON_10’
  3988. ‘ABMON_11’
  3989. ‘ABMON_12’
  3990. The return value is abbreviated name of the month. ‘ABMON_1’
  3991. corresponds to January.
  3992. ‘MON_1’
  3993. ‘MON_2’
  3994. ‘MON_3’
  3995. ‘MON_4’
  3996. ‘MON_5’
  3997. ‘MON_6’
  3998. ‘MON_7’
  3999. ‘MON_8’
  4000. ‘MON_9’
  4001. ‘MON_10’
  4002. ‘MON_11’
  4003. ‘MON_12’
  4004. Similar to ‘ABMON_1’ etc., but here the month names are not
  4005. abbreviated. Here the first value ‘MON_1’ also corresponds to
  4006. January.
  4007. ‘AM_STR’
  4008. ‘PM_STR’
  4009. The return values are strings which can be used in the
  4010. representation of time as an hour from 1 to 12 plus an am/pm
  4011. specifier.
  4012. Note that in locales which do not use this time representation
  4013. these strings might be empty, in which case the am/pm format
  4014. cannot be used at all.
  4015. ‘D_T_FMT’
  4016. The return value can be used as a format string for ‘strftime’
  4017. to represent time and date in a locale-specific way.
  4018. ‘D_FMT’
  4019. The return value can be used as a format string for ‘strftime’
  4020. to represent a date in a locale-specific way.
  4021. ‘T_FMT’
  4022. The return value can be used as a format string for ‘strftime’
  4023. to represent time in a locale-specific way.
  4024. ‘T_FMT_AMPM’
  4025. The return value can be used as a format string for ‘strftime’
  4026. to represent time in the am/pm format.
  4027. Note that if the am/pm format does not make any sense for the
  4028. selected locale, the return value might be the same as the one
  4029. for ‘T_FMT’.
  4030. ‘ERA’
  4031. The return value represents the era used in the current
  4032. locale.
  4033. Most locales do not define this value. An example of a locale
  4034. which does define this value is the Japanese one. In Japan,
  4035. the traditional representation of dates includes the name of
  4036. the era corresponding to the then-emperor’s reign.
  4037. Normally it should not be necessary to use this value
  4038. directly. Specifying the ‘E’ modifier in their format strings
  4039. causes the ‘strftime’ functions to use this information. The
  4040. format of the returned string is not specified, and therefore
  4041. you should not assume knowledge of it on different systems.
  4042. ‘ERA_YEAR’
  4043. The return value gives the year in the relevant era of the
  4044. locale. As for ‘ERA’ it should not be necessary to use this
  4045. value directly.
  4046. ‘ERA_D_T_FMT’
  4047. This return value can be used as a format string for
  4048. ‘strftime’ to represent dates and times in a locale-specific
  4049. era-based way.
  4050. ‘ERA_D_FMT’
  4051. This return value can be used as a format string for
  4052. ‘strftime’ to represent a date in a locale-specific era-based
  4053. way.
  4054. ‘ERA_T_FMT’
  4055. This return value can be used as a format string for
  4056. ‘strftime’ to represent time in a locale-specific era-based
  4057. way.
  4058. ‘ALT_DIGITS’
  4059. The return value is a representation of up to 100 values used
  4060. to represent the values 0 to 99. As for ‘ERA’ this value is
  4061. not intended to be used directly, but instead indirectly
  4062. through the ‘strftime’ function. When the modifier ‘O’ is
  4063. used in a format which would otherwise use numerals to
  4064. represent hours, minutes, seconds, weekdays, months, or weeks,
  4065. the appropriate value for the locale is used instead.
  4066. ‘INT_CURR_SYMBOL’
  4067. The same as the value returned by ‘localeconv’ in the
  4068. ‘int_curr_symbol’ element of the ‘struct lconv’.
  4069. ‘CURRENCY_SYMBOL’
  4070. ‘CRNCYSTR’
  4071. The same as the value returned by ‘localeconv’ in the
  4072. ‘currency_symbol’ element of the ‘struct lconv’.
  4073. ‘CRNCYSTR’ is a deprecated alias still required by Unix98.
  4074. ‘MON_DECIMAL_POINT’
  4075. The same as the value returned by ‘localeconv’ in the
  4076. ‘mon_decimal_point’ element of the ‘struct lconv’.
  4077. ‘MON_THOUSANDS_SEP’
  4078. The same as the value returned by ‘localeconv’ in the
  4079. ‘mon_thousands_sep’ element of the ‘struct lconv’.
  4080. ‘MON_GROUPING’
  4081. The same as the value returned by ‘localeconv’ in the
  4082. ‘mon_grouping’ element of the ‘struct lconv’.
  4083. ‘POSITIVE_SIGN’
  4084. The same as the value returned by ‘localeconv’ in the
  4085. ‘positive_sign’ element of the ‘struct lconv’.
  4086. ‘NEGATIVE_SIGN’
  4087. The same as the value returned by ‘localeconv’ in the
  4088. ‘negative_sign’ element of the ‘struct lconv’.
  4089. ‘INT_FRAC_DIGITS’
  4090. The same as the value returned by ‘localeconv’ in the
  4091. ‘int_frac_digits’ element of the ‘struct lconv’.
  4092. ‘FRAC_DIGITS’
  4093. The same as the value returned by ‘localeconv’ in the
  4094. ‘frac_digits’ element of the ‘struct lconv’.
  4095. ‘P_CS_PRECEDES’
  4096. The same as the value returned by ‘localeconv’ in the
  4097. ‘p_cs_precedes’ element of the ‘struct lconv’.
  4098. ‘P_SEP_BY_SPACE’
  4099. The same as the value returned by ‘localeconv’ in the
  4100. ‘p_sep_by_space’ element of the ‘struct lconv’.
  4101. ‘N_CS_PRECEDES’
  4102. The same as the value returned by ‘localeconv’ in the
  4103. ‘n_cs_precedes’ element of the ‘struct lconv’.
  4104. ‘N_SEP_BY_SPACE’
  4105. The same as the value returned by ‘localeconv’ in the
  4106. ‘n_sep_by_space’ element of the ‘struct lconv’.
  4107. ‘P_SIGN_POSN’
  4108. The same as the value returned by ‘localeconv’ in the
  4109. ‘p_sign_posn’ element of the ‘struct lconv’.
  4110. ‘N_SIGN_POSN’
  4111. The same as the value returned by ‘localeconv’ in the
  4112. ‘n_sign_posn’ element of the ‘struct lconv’.
  4113. ‘INT_P_CS_PRECEDES’
  4114. The same as the value returned by ‘localeconv’ in the
  4115. ‘int_p_cs_precedes’ element of the ‘struct lconv’.
  4116. ‘INT_P_SEP_BY_SPACE’
  4117. The same as the value returned by ‘localeconv’ in the
  4118. ‘int_p_sep_by_space’ element of the ‘struct lconv’.
  4119. ‘INT_N_CS_PRECEDES’
  4120. The same as the value returned by ‘localeconv’ in the
  4121. ‘int_n_cs_precedes’ element of the ‘struct lconv’.
  4122. ‘INT_N_SEP_BY_SPACE’
  4123. The same as the value returned by ‘localeconv’ in the
  4124. ‘int_n_sep_by_space’ element of the ‘struct lconv’.
  4125. ‘INT_P_SIGN_POSN’
  4126. The same as the value returned by ‘localeconv’ in the
  4127. ‘int_p_sign_posn’ element of the ‘struct lconv’.
  4128. ‘INT_N_SIGN_POSN’
  4129. The same as the value returned by ‘localeconv’ in the
  4130. ‘int_n_sign_posn’ element of the ‘struct lconv’.
  4131. ‘DECIMAL_POINT’
  4132. ‘RADIXCHAR’
  4133. The same as the value returned by ‘localeconv’ in the
  4134. ‘decimal_point’ element of the ‘struct lconv’.
  4135. The name ‘RADIXCHAR’ is a deprecated alias still used in
  4136. Unix98.
  4137. ‘THOUSANDS_SEP’
  4138. ‘THOUSEP’
  4139. The same as the value returned by ‘localeconv’ in the
  4140. ‘thousands_sep’ element of the ‘struct lconv’.
  4141. The name ‘THOUSEP’ is a deprecated alias still used in Unix98.
  4142. ‘GROUPING’
  4143. The same as the value returned by ‘localeconv’ in the
  4144. ‘grouping’ element of the ‘struct lconv’.
  4145. ‘YESEXPR’
  4146. The return value is a regular expression which can be used
  4147. with the ‘regex’ function to recognize a positive response to
  4148. a yes/no question. The GNU C Library provides the ‘rpmatch’
  4149. function for easier handling in applications.
  4150. ‘NOEXPR’
  4151. The return value is a regular expression which can be used
  4152. with the ‘regex’ function to recognize a negative response to
  4153. a yes/no question.
  4154. ‘YESSTR’
  4155. The return value is a locale-specific translation of the
  4156. positive response to a yes/no question.
  4157. Using this value is deprecated since it is a very special case
  4158. of message translation, and is better handled by the message
  4159. translation functions (*note Message Translation::).
  4160. The use of this symbol is deprecated. Instead message
  4161. translation should be used.
  4162. ‘NOSTR’
  4163. The return value is a locale-specific translation of the
  4164. negative response to a yes/no question. What is said for
  4165. ‘YESSTR’ is also true here.
  4166. The use of this symbol is deprecated. Instead message
  4167. translation should be used.
  4168. The file ‘langinfo.h’ defines a lot more symbols but none of them
  4169. are official. Using them is not portable, and the format of the
  4170. return values might change. Therefore we recommended you not use
  4171. them.
  4172. Note that the return value for any valid argument can be used in
  4173. all situations (with the possible exception of the am/pm time
  4174. formatting codes). If the user has not selected any locale for the
  4175. appropriate category, ‘nl_langinfo’ returns the information from
  4176. the ‘"C"’ locale. It is therefore possible to use this function as
  4177. shown in the example below.
  4178. If the argument ITEM is not valid, a pointer to an empty string is
  4179. returned.
  4180. An example of ‘nl_langinfo’ usage is a function which has to print a
  4181. given date and time in a locale-specific way. At first one might think
  4182. that, since ‘strftime’ internally uses the locale information, writing
  4183. something like the following is enough:
  4184. size_t
  4185. i18n_time_n_data (char *s, size_t len, const struct tm *tp)
  4186. {
  4187. return strftime (s, len, "%X %D", tp);
  4188. }
  4189. The format contains no weekday or month names and therefore is
  4190. internationally usable. Wrong! The output produced is something like
  4191. ‘"hh:mm:ss MM/DD/YY"’. This format is only recognizable in the USA.
  4192. Other countries use different formats. Therefore the function should be
  4193. rewritten like this:
  4194. size_t
  4195. i18n_time_n_data (char *s, size_t len, const struct tm *tp)
  4196. {
  4197. return strftime (s, len, nl_langinfo (D_T_FMT), tp);
  4198. }
  4199. Now it uses the date and time format of the locale selected when the
  4200. program runs. If the user selects the locale correctly there should
  4201. never be a misunderstanding over the time and date format.
  4202. 
  4203. File: libc.info, Node: Formatting Numbers, Next: Yes-or-No Questions, Prev: Locale Information, Up: Locales
  4204. 7.8 A dedicated function to format numbers
  4205. ==========================================
  4206. We have seen that the structure returned by ‘localeconv’ as well as the
  4207. values given to ‘nl_langinfo’ allow you to retrieve the various pieces
  4208. of locale-specific information to format numbers and monetary amounts.
  4209. We have also seen that the underlying rules are quite complex.
  4210. Therefore the X/Open standards introduce a function which uses such
  4211. locale information, making it easier for the user to format numbers
  4212. according to these rules.
  4213. -- Function: ssize_t strfmon (char *S, size_t MAXSIZE, const char
  4214. *FORMAT, …)
  4215. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  4216. *Note POSIX Safety Concepts::.
  4217. The ‘strfmon’ function is similar to the ‘strftime’ function in
  4218. that it takes a buffer, its size, a format string, and values to
  4219. write into the buffer as text in a form specified by the format
  4220. string. Like ‘strftime’, the function also returns the number of
  4221. bytes written into the buffer.
  4222. There are two differences: ‘strfmon’ can take more than one
  4223. argument, and, of course, the format specification is different.
  4224. Like ‘strftime’, the format string consists of normal text, which
  4225. is output as is, and format specifiers, which are indicated by a
  4226. ‘%’. Immediately after the ‘%’, you can optionally specify various
  4227. flags and formatting information before the main formatting
  4228. character, in a similar way to ‘printf’:
  4229. • Immediately following the ‘%’ there can be one or more of the
  4230. following flags:
  4231. ‘=F’
  4232. The single byte character F is used for this field as the
  4233. numeric fill character. By default this character is a
  4234. space character. Filling with this character is only
  4235. performed if a left precision is specified. It is not
  4236. just to fill to the given field width.
  4237. ‘^’
  4238. The number is printed without grouping the digits
  4239. according to the rules of the current locale. By default
  4240. grouping is enabled.
  4241. ‘+’, ‘(’
  4242. At most one of these flags can be used. They select
  4243. which format to represent the sign of a currency amount.
  4244. By default, and if ‘+’ is given, the locale equivalent of
  4245. +/- is used. If ‘(’ is given, negative amounts are
  4246. enclosed in parentheses. The exact format is determined
  4247. by the values of the ‘LC_MONETARY’ category of the locale
  4248. selected at program runtime.
  4249. ‘!’
  4250. The output will not contain the currency symbol.
  4251. ‘-’
  4252. The output will be formatted left-justified instead of
  4253. right-justified if it does not fill the entire field
  4254. width.
  4255. The next part of the specification is an optional field width. If
  4256. no width is specified 0 is taken. During output, the function
  4257. first determines how much space is required. If it requires at
  4258. least as many characters as given by the field width, it is output
  4259. using as much space as necessary. Otherwise, it is extended to use
  4260. the full width by filling with the space character. The presence
  4261. or absence of the ‘-’ flag determines the side at which such
  4262. padding occurs. If present, the spaces are added at the right
  4263. making the output left-justified, and vice versa.
  4264. So far the format looks familiar, being similar to the ‘printf’ and
  4265. ‘strftime’ formats. However, the next two optional fields
  4266. introduce something new. The first one is a ‘#’ character followed
  4267. by a decimal digit string. The value of the digit string specifies
  4268. the number of _digit_ positions to the left of the decimal point
  4269. (or equivalent). This does _not_ include the grouping character
  4270. when the ‘^’ flag is not given. If the space needed to print the
  4271. number does not fill the whole width, the field is padded at the
  4272. left side with the fill character, which can be selected using the
  4273. ‘=’ flag and by default is a space. For example, if the field
  4274. width is selected as 6 and the number is 123, the fill character is
  4275. ‘*’ the result will be ‘***123’.
  4276. The second optional field starts with a ‘.’ (period) and consists
  4277. of another decimal digit string. Its value describes the number of
  4278. characters printed after the decimal point. The default is
  4279. selected from the current locale (‘frac_digits’, ‘int_frac_digits’,
  4280. see *note General Numeric::). If the exact representation needs
  4281. more digits than given by the field width, the displayed value is
  4282. rounded. If the number of fractional digits is selected to be
  4283. zero, no decimal point is printed.
  4284. As a GNU extension, the ‘strfmon’ implementation in the GNU C
  4285. Library allows an optional ‘L’ next as a format modifier. If this
  4286. modifier is given, the argument is expected to be a ‘long double’
  4287. instead of a ‘double’ value.
  4288. Finally, the last component is a format specifier. There are three
  4289. specifiers defined:
  4290. ‘i’
  4291. Use the locale’s rules for formatting an international
  4292. currency value.
  4293. ‘n’
  4294. Use the locale’s rules for formatting a national currency
  4295. value.
  4296. ‘%’
  4297. Place a ‘%’ in the output. There must be no flag, width
  4298. specifier or modifier given, only ‘%%’ is allowed.
  4299. As for ‘printf’, the function reads the format string from left to
  4300. right and uses the values passed to the function following the
  4301. format string. The values are expected to be either of type
  4302. ‘double’ or ‘long double’, depending on the presence of the
  4303. modifier ‘L’. The result is stored in the buffer pointed to by S.
  4304. At most MAXSIZE characters are stored.
  4305. The return value of the function is the number of characters stored
  4306. in S, including the terminating ‘NULL’ byte. If the number of
  4307. characters stored would exceed MAXSIZE, the function returns -1 and
  4308. the content of the buffer S is unspecified. In this case ‘errno’
  4309. is set to ‘E2BIG’.
  4310. A few examples should make clear how the function works. It is
  4311. assumed that all the following pieces of code are executed in a program
  4312. which uses the USA locale (‘en_US’). The simplest form of the format is
  4313. this:
  4314. strfmon (buf, 100, "@%n@%n@%n@", 123.45, -567.89, 12345.678);
  4315. The output produced is
  4316. "@$123.45@-$567.89@$12,345.68@"
  4317. We can notice several things here. First, the widths of the output
  4318. numbers are different. We have not specified a width in the format
  4319. string, and so this is no wonder. Second, the third number is printed
  4320. using thousands separators. The thousands separator for the ‘en_US’
  4321. locale is a comma. The number is also rounded. .678 is rounded to .68
  4322. since the format does not specify a precision and the default value in
  4323. the locale is 2. Finally, note that the national currency symbol is
  4324. printed since ‘%n’ was used, not ‘i’. The next example shows how we can
  4325. align the output.
  4326. strfmon (buf, 100, "@%=*11n@%=*11n@%=*11n@", 123.45, -567.89, 12345.678);
  4327. The output this time is:
  4328. "@ $123.45@ -$567.89@ $12,345.68@"
  4329. Two things stand out. Firstly, all fields have the same width
  4330. (eleven characters) since this is the width given in the format and
  4331. since no number required more characters to be printed. The second
  4332. important point is that the fill character is not used. This is correct
  4333. since the white space was not used to achieve a precision given by a ‘#’
  4334. modifier, but instead to fill to the given width. The difference
  4335. becomes obvious if we now add a width specification.
  4336. strfmon (buf, 100, "@%=*11#5n@%=*11#5n@%=*11#5n@",
  4337. 123.45, -567.89, 12345.678);
  4338. The output is
  4339. "@ $***123.45@-$***567.89@ $12,456.68@"
  4340. Here we can see that all the currency symbols are now aligned, and
  4341. that the space between the currency sign and the number is filled with
  4342. the selected fill character. Note that although the width is selected
  4343. to be 5 and 123.45 has three digits left of the decimal point, the space
  4344. is filled with three asterisks. This is correct since, as explained
  4345. above, the width does not include the positions used to store thousands
  4346. separators. One last example should explain the remaining
  4347. functionality.
  4348. strfmon (buf, 100, "@%=0(16#5.3i@%=0(16#5.3i@%=0(16#5.3i@",
  4349. 123.45, -567.89, 12345.678);
  4350. This rather complex format string produces the following output:
  4351. "@ USD 000123,450 @(USD 000567.890)@ USD 12,345.678 @"
  4352. The most noticeable change is the alternative way of representing
  4353. negative numbers. In financial circles this is often done using
  4354. parentheses, and this is what the ‘(’ flag selected. The fill character
  4355. is now ‘0’. Note that this ‘0’ character is not regarded as a numeric
  4356. zero, and therefore the first and second numbers are not printed using a
  4357. thousands separator. Since we used the format specifier ‘i’ instead of
  4358. ‘n’, the international form of the currency symbol is used. This is a
  4359. four letter string, in this case ‘"USD "’. The last point is that since
  4360. the precision right of the decimal point is selected to be three, the
  4361. first and second numbers are printed with an extra zero at the end and
  4362. the third number is printed without rounding.
  4363. 
  4364. File: libc.info, Node: Yes-or-No Questions, Prev: Formatting Numbers, Up: Locales
  4365. 7.9 Yes-or-No Questions
  4366. =======================
  4367. Some non GUI programs ask a yes-or-no question. If the messages
  4368. (especially the questions) are translated into foreign languages, be
  4369. sure that you localize the answers too. It would be very bad habit to
  4370. ask a question in one language and request the answer in another, often
  4371. English.
  4372. The GNU C Library contains ‘rpmatch’ to give applications easy access
  4373. to the corresponding locale definitions.
  4374. -- Function: int rpmatch (const char *RESPONSE)
  4375. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
  4376. | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  4377. The function ‘rpmatch’ checks the string in RESPONSE for whether or
  4378. not it is a correct yes-or-no answer and if yes, which one. The
  4379. check uses the ‘YESEXPR’ and ‘NOEXPR’ data in the ‘LC_MESSAGES’
  4380. category of the currently selected locale. The return value is as
  4381. follows:
  4382. ‘1’
  4383. The user entered an affirmative answer.
  4384. ‘0’
  4385. The user entered a negative answer.
  4386. ‘-1’
  4387. The answer matched neither the ‘YESEXPR’ nor the ‘NOEXPR’
  4388. regular expression.
  4389. This function is not standardized but available beside in the GNU C
  4390. Library at least also in the IBM AIX library.
  4391. This function would normally be used like this:
  4392. /* Use a safe default. */
  4393. _Bool doit = false;
  4394. fputs (gettext ("Do you really want to do this? "), stdout);
  4395. fflush (stdout);
  4396. /* Prepare the ‘getline’ call. */
  4397. line = NULL;
  4398. len = 0;
  4399. while (getline (&line, &len, stdin) >= 0)
  4400. {
  4401. /* Check the response. */
  4402. int res = rpmatch (line);
  4403. if (res >= 0)
  4404. {
  4405. /* We got a definitive answer. */
  4406. if (res > 0)
  4407. doit = true;
  4408. break;
  4409. }
  4410. }
  4411. /* Free what ‘getline’ allocated. */
  4412. free (line);
  4413. Note that the loop continues until a read error is detected or until
  4414. a definitive (positive or negative) answer is read.
  4415. 
  4416. File: libc.info, Node: Message Translation, Next: Searching and Sorting, Prev: Locales, Up: Top
  4417. 8 Message Translation
  4418. *********************
  4419. The program’s interface with the user should be designed to ease the
  4420. user’s task. One way to ease the user’s task is to use messages in
  4421. whatever language the user prefers.
  4422. Printing messages in different languages can be implemented in
  4423. different ways. One could add all the different languages in the source
  4424. code and choose among the variants every time a message has to be
  4425. printed. This is certainly not a good solution since extending the set
  4426. of languages is cumbersome (the code must be changed) and the code
  4427. itself can become really big with dozens of message sets.
  4428. A better solution is to keep the message sets for each language in
  4429. separate files which are loaded at runtime depending on the language
  4430. selection of the user.
  4431. The GNU C Library provides two different sets of functions to support
  4432. message translation. The problem is that neither of the interfaces is
  4433. officially defined by the POSIX standard. The ‘catgets’ family of
  4434. functions is defined in the X/Open standard but this is derived from
  4435. industry decisions and therefore not necessarily based on reasonable
  4436. decisions.
  4437. As mentioned above, the message catalog handling provides easy
  4438. extendability by using external data files which contain the message
  4439. translations. I.e., these files contain for each of the messages used
  4440. in the program a translation for the appropriate language. So the tasks
  4441. of the message handling functions are
  4442. • locate the external data file with the appropriate translations
  4443. • load the data and make it possible to address the messages
  4444. • map a given key to the translated message
  4445. The two approaches mainly differ in the implementation of this last
  4446. step. Decisions made in the last step influence the rest of the design.
  4447. * Menu:
  4448. * Message catalogs a la X/Open:: The ‘catgets’ family of functions.
  4449. * The Uniforum approach:: The ‘gettext’ family of functions.
  4450. 
  4451. File: libc.info, Node: Message catalogs a la X/Open, Next: The Uniforum approach, Up: Message Translation
  4452. 8.1 X/Open Message Catalog Handling
  4453. ===================================
  4454. The ‘catgets’ functions are based on the simple scheme:
  4455. Associate every message to translate in the source code with a
  4456. unique identifier. To retrieve a message from a catalog file
  4457. solely the identifier is used.
  4458. This means for the author of the program that s/he will have to make
  4459. sure the meaning of the identifier in the program code and in the
  4460. message catalogs is always the same.
  4461. Before a message can be translated the catalog file must be located.
  4462. The user of the program must be able to guide the responsible function
  4463. to find whatever catalog the user wants. This is separated from what
  4464. the programmer had in mind.
  4465. All the types, constants and functions for the ‘catgets’ functions
  4466. are defined/declared in the ‘nl_types.h’ header file.
  4467. * Menu:
  4468. * The catgets Functions:: The ‘catgets’ function family.
  4469. * The message catalog files:: Format of the message catalog files.
  4470. * The gencat program:: How to generate message catalogs files which
  4471. can be used by the functions.
  4472. * Common Usage:: How to use the ‘catgets’ interface.
  4473. 
  4474. File: libc.info, Node: The catgets Functions, Next: The message catalog files, Up: Message catalogs a la X/Open
  4475. 8.1.1 The ‘catgets’ function family
  4476. -----------------------------------
  4477. -- Function: nl_catd catopen (const char *CAT_NAME, int FLAG)
  4478. Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | *Note
  4479. POSIX Safety Concepts::.
  4480. The ‘catopen’ function tries to locate the message data file named
  4481. CAT_NAME and loads it when found. The return value is of an opaque
  4482. type and can be used in calls to the other functions to refer to
  4483. this loaded catalog.
  4484. The return value is ‘(nl_catd) -1’ in case the function failed and
  4485. no catalog was loaded. The global variable ERRNO contains a code
  4486. for the error causing the failure. But even if the function call
  4487. succeeded this does not mean that all messages can be translated.
  4488. Locating the catalog file must happen in a way which lets the user
  4489. of the program influence the decision. It is up to the user to
  4490. decide about the language to use and sometimes it is useful to use
  4491. alternate catalog files. All this can be specified by the user by
  4492. setting some environment variables.
  4493. The first problem is to find out where all the message catalogs are
  4494. stored. Every program could have its own place to keep all the
  4495. different files but usually the catalog files are grouped by
  4496. languages and the catalogs for all programs are kept in the same
  4497. place.
  4498. To tell the ‘catopen’ function where the catalog for the program
  4499. can be found the user can set the environment variable ‘NLSPATH’ to
  4500. a value which describes her/his choice. Since this value must be
  4501. usable for different languages and locales it cannot be a simple
  4502. string. Instead it is a format string (similar to ‘printf’’s). An
  4503. example is
  4504. /usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N
  4505. First one can see that more than one directory can be specified
  4506. (with the usual syntax of separating them by colons). The next
  4507. things to observe are the format string, ‘%L’ and ‘%N’ in this
  4508. case. The ‘catopen’ function knows about several of them and the
  4509. replacement for all of them is of course different.
  4510. ‘%N’
  4511. This format element is substituted with the name of the
  4512. catalog file. This is the value of the CAT_NAME argument
  4513. given to ‘catgets’.
  4514. ‘%L’
  4515. This format element is substituted with the name of the
  4516. currently selected locale for translating messages. How this
  4517. is determined is explained below.
  4518. ‘%l’
  4519. (This is the lowercase ell.) This format element is
  4520. substituted with the language element of the locale name. The
  4521. string describing the selected locale is expected to have the
  4522. form ‘LANG[_TERR[.CODESET]]’ and this format uses the first
  4523. part LANG.
  4524. ‘%t’
  4525. This format element is substituted by the territory part TERR
  4526. of the name of the currently selected locale. See the
  4527. explanation of the format above.
  4528. ‘%c’
  4529. This format element is substituted by the codeset part CODESET
  4530. of the name of the currently selected locale. See the
  4531. explanation of the format above.
  4532. ‘%%’
  4533. Since ‘%’ is used as a meta character there must be a way to
  4534. express the ‘%’ character in the result itself. Using ‘%%’
  4535. does this just like it works for ‘printf’.
  4536. Using ‘NLSPATH’ allows arbitrary directories to be searched for
  4537. message catalogs while still allowing different languages to be
  4538. used. If the ‘NLSPATH’ environment variable is not set, the
  4539. default value is
  4540. PREFIX/share/locale/%L/%N:PREFIX/share/locale/%L/LC_MESSAGES/%N
  4541. where PREFIX is given to ‘configure’ while installing the GNU C
  4542. Library (this value is in many cases ‘/usr’ or the empty string).
  4543. The remaining problem is to decide which must be used. The value
  4544. decides about the substitution of the format elements mentioned
  4545. above. First of all the user can specify a path in the message
  4546. catalog name (i.e., the name contains a slash character). In this
  4547. situation the ‘NLSPATH’ environment variable is not used. The
  4548. catalog must exist as specified in the program, perhaps relative to
  4549. the current working directory. This situation in not desirable and
  4550. catalogs names never should be written this way. Beside this, this
  4551. behavior is not portable to all other platforms providing the
  4552. ‘catgets’ interface.
  4553. Otherwise the values of environment variables from the standard
  4554. environment are examined (*note Standard Environment::). Which
  4555. variables are examined is decided by the FLAG parameter of
  4556. ‘catopen’. If the value is ‘NL_CAT_LOCALE’ (which is defined in
  4557. ‘nl_types.h’) then the ‘catopen’ function uses the name of the
  4558. locale currently selected for the ‘LC_MESSAGES’ category.
  4559. If FLAG is zero the ‘LANG’ environment variable is examined. This
  4560. is a left-over from the early days when the concept of locales had
  4561. not even reached the level of POSIX locales.
  4562. The environment variable and the locale name should have a value of
  4563. the form ‘LANG[_TERR[.CODESET]]’ as explained above. If no
  4564. environment variable is set the ‘"C"’ locale is used which prevents
  4565. any translation.
  4566. The return value of the function is in any case a valid string.
  4567. Either it is a translation from a message catalog or it is the same
  4568. as the STRING parameter. So a piece of code to decide whether a
  4569. translation actually happened must look like this:
  4570. {
  4571. char *trans = catgets (desc, set, msg, input_string);
  4572. if (trans == input_string)
  4573. {
  4574. /* Something went wrong. */
  4575. }
  4576. }
  4577. When an error occurs the global variable ERRNO is set to
  4578. EBADF
  4579. The catalog does not exist.
  4580. ENOMSG
  4581. The set/message tuple does not name an existing element in the
  4582. message catalog.
  4583. While it sometimes can be useful to test for errors programs
  4584. normally will avoid any test. If the translation is not available
  4585. it is no big problem if the original, untranslated message is
  4586. printed. Either the user understands this as well or s/he will
  4587. look for the reason why the messages are not translated.
  4588. Please note that the currently selected locale does not depend on a
  4589. call to the ‘setlocale’ function. It is not necessary that the locale
  4590. data files for this locale exist and calling ‘setlocale’ succeeds. The
  4591. ‘catopen’ function directly reads the values of the environment
  4592. variables.
  4593. -- Function: char * catgets (nl_catd CATALOG_DESC, int SET, int
  4594. MESSAGE, const char *STRING)
  4595. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4596. Concepts::.
  4597. The function ‘catgets’ has to be used to access the message catalog
  4598. previously opened using the ‘catopen’ function. The CATALOG_DESC
  4599. parameter must be a value previously returned by ‘catopen’.
  4600. The next two parameters, SET and MESSAGE, reflect the internal
  4601. organization of the message catalog files. This will be explained
  4602. in detail below. For now it is interesting to know that a catalog
  4603. can consist of several sets and the messages in each thread are
  4604. individually numbered using numbers. Neither the set number nor
  4605. the message number must be consecutive. They can be arbitrarily
  4606. chosen. But each message (unless equal to another one) must have
  4607. its own unique pair of set and message numbers.
  4608. Since it is not guaranteed that the message catalog for the
  4609. language selected by the user exists the last parameter STRING
  4610. helps to handle this case gracefully. If no matching string can be
  4611. found STRING is returned. This means for the programmer that
  4612. • the STRING parameters should contain reasonable text (this
  4613. also helps to understand the program seems otherwise there
  4614. would be no hint on the string which is expected to be
  4615. returned.
  4616. • all STRING arguments should be written in the same language.
  4617. It is somewhat uncomfortable to write a program using the ‘catgets’
  4618. functions if no supporting functionality is available. Since each
  4619. set/message number tuple must be unique the programmer must keep lists
  4620. of the messages at the same time the code is written. And the work
  4621. between several people working on the same project must be coordinated.
  4622. We will see how some of these problems can be relaxed a bit (*note
  4623. Common Usage::).
  4624. -- Function: int catclose (nl_catd CATALOG_DESC)
  4625. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe corrupt mem |
  4626. *Note POSIX Safety Concepts::.
  4627. The ‘catclose’ function can be used to free the resources
  4628. associated with a message catalog which previously was opened by a
  4629. call to ‘catopen’. If the resources can be successfully freed the
  4630. function returns ‘0’. Otherwise it returns ‘−1’ and the global
  4631. variable ERRNO is set. Errors can occur if the catalog descriptor
  4632. CATALOG_DESC is not valid in which case ERRNO is set to ‘EBADF’.
  4633. 
  4634. File: libc.info, Node: The message catalog files, Next: The gencat program, Prev: The catgets Functions, Up: Message catalogs a la X/Open
  4635. 8.1.2 Format of the message catalog files
  4636. -----------------------------------------
  4637. The only reasonable way to translate all the messages of a function and
  4638. store the result in a message catalog file which can be read by the
  4639. ‘catopen’ function is to write all the message text to the translator
  4640. and let her/him translate them all. I.e., we must have a file with
  4641. entries which associate the set/message tuple with a specific
  4642. translation. This file format is specified in the X/Open standard and
  4643. is as follows:
  4644. • Lines containing only whitespace characters or empty lines are
  4645. ignored.
  4646. • Lines which contain as the first non-whitespace character a ‘$’
  4647. followed by a whitespace character are comment and are also
  4648. ignored.
  4649. • If a line contains as the first non-whitespace characters the
  4650. sequence ‘$set’ followed by a whitespace character an additional
  4651. argument is required to follow. This argument can either be:
  4652. − a number. In this case the value of this number determines
  4653. the set to which the following messages are added.
  4654. − an identifier consisting of alphanumeric characters plus the
  4655. underscore character. In this case the set get automatically
  4656. a number assigned. This value is one added to the largest set
  4657. number which so far appeared.
  4658. How to use the symbolic names is explained in section *note
  4659. Common Usage::.
  4660. It is an error if a symbol name appears more than once. All
  4661. following messages are placed in a set with this number.
  4662. • If a line contains as the first non-whitespace characters the
  4663. sequence ‘$delset’ followed by a whitespace character an additional
  4664. argument is required to follow. This argument can either be:
  4665. − a number. In this case the value of this number determines
  4666. the set which will be deleted.
  4667. − an identifier consisting of alphanumeric characters plus the
  4668. underscore character. This symbolic identifier must match a
  4669. name for a set which previously was defined. It is an error
  4670. if the name is unknown.
  4671. In both cases all messages in the specified set will be removed.
  4672. They will not appear in the output. But if this set is later again
  4673. selected with a ‘$set’ command again messages could be added and
  4674. these messages will appear in the output.
  4675. • If a line contains after leading whitespaces the sequence ‘$quote’,
  4676. the quoting character used for this input file is changed to the
  4677. first non-whitespace character following ‘$quote’. If no
  4678. non-whitespace character is present before the line ends quoting is
  4679. disabled.
  4680. By default no quoting character is used. In this mode strings are
  4681. terminated with the first unescaped line break. If there is a
  4682. ‘$quote’ sequence present newline need not be escaped. Instead a
  4683. string is terminated with the first unescaped appearance of the
  4684. quote character.
  4685. A common usage of this feature would be to set the quote character
  4686. to ‘"’. Then any appearance of the ‘"’ in the strings must be
  4687. escaped using the backslash (i.e., ‘\"’ must be written).
  4688. • Any other line must start with a number or an alphanumeric
  4689. identifier (with the underscore character included). The following
  4690. characters (starting after the first whitespace character) will
  4691. form the string which gets associated with the currently selected
  4692. set and the message number represented by the number and identifier
  4693. respectively.
  4694. If the start of the line is a number the message number is obvious.
  4695. It is an error if the same message number already appeared for this
  4696. set.
  4697. If the leading token was an identifier the message number gets
  4698. automatically assigned. The value is the current maximum message
  4699. number for this set plus one. It is an error if the identifier was
  4700. already used for a message in this set. It is OK to reuse the
  4701. identifier for a message in another thread. How to use the
  4702. symbolic identifiers will be explained below (*note Common
  4703. Usage::). There is one limitation with the identifier: it must not
  4704. be ‘Set’. The reason will be explained below.
  4705. The text of the messages can contain escape characters. The usual
  4706. bunch of characters known from the ISO C language are recognized
  4707. (‘\n’, ‘\t’, ‘\v’, ‘\b’, ‘\r’, ‘\f’, ‘\\’, and ‘\NNN’, where NNN is
  4708. the octal coding of a character code).
  4709. *Important:* The handling of identifiers instead of numbers for the
  4710. set and messages is a GNU extension. Systems strictly following the
  4711. X/Open specification do not have this feature. An example for a message
  4712. catalog file is this:
  4713. $ This is a leading comment.
  4714. $quote "
  4715. $set SetOne
  4716. 1 Message with ID 1.
  4717. two " Message with ID \"two\", which gets the value 2 assigned"
  4718. $set SetTwo
  4719. $ Since the last set got the number 1 assigned this set has number 2.
  4720. 4000 "The numbers can be arbitrary, they need not start at one."
  4721. This small example shows various aspects:
  4722. • Lines 1 and 9 are comments since they start with ‘$’ followed by a
  4723. whitespace.
  4724. • The quoting character is set to ‘"’. Otherwise the quotes in the
  4725. message definition would have to be omitted and in this case the
  4726. message with the identifier ‘two’ would lose its leading
  4727. whitespace.
  4728. • Mixing numbered messages with messages having symbolic names is no
  4729. problem and the numbering happens automatically.
  4730. While this file format is pretty easy it is not the best possible for
  4731. use in a running program. The ‘catopen’ function would have to parse
  4732. the file and handle syntactic errors gracefully. This is not so easy
  4733. and the whole process is pretty slow. Therefore the ‘catgets’ functions
  4734. expect the data in another more compact and ready-to-use file format.
  4735. There is a special program ‘gencat’ which is explained in detail in the
  4736. next section.
  4737. Files in this other format are not human readable. To be easy to use
  4738. by programs it is a binary file. But the format is byte order
  4739. independent so translation files can be shared by systems of arbitrary
  4740. architecture (as long as they use the GNU C Library).
  4741. Details about the binary file format are not important to know since
  4742. these files are always created by the ‘gencat’ program. The sources of
  4743. the GNU C Library also provide the sources for the ‘gencat’ program and
  4744. so the interested reader can look through these source files to learn
  4745. about the file format.
  4746. 
  4747. File: libc.info, Node: The gencat program, Next: Common Usage, Prev: The message catalog files, Up: Message catalogs a la X/Open
  4748. 8.1.3 Generate Message Catalogs files
  4749. -------------------------------------
  4750. The ‘gencat’ program is specified in the X/Open standard and the GNU
  4751. implementation follows this specification and so processes all correctly
  4752. formed input files. Additionally some extension are implemented which
  4753. help to work in a more reasonable way with the ‘catgets’ functions.
  4754. The ‘gencat’ program can be invoked in two ways:
  4755. `gencat [OPTION …] [OUTPUT-FILE [INPUT-FILE …]]`
  4756. This is the interface defined in the X/Open standard. If no
  4757. INPUT-FILE parameter is given, input will be read from standard input.
  4758. Multiple input files will be read as if they were concatenated. If
  4759. OUTPUT-FILE is also missing, the output will be written to standard
  4760. output. To provide the interface one is used to from other programs a
  4761. second interface is provided.
  4762. `gencat [OPTION …] -o OUTPUT-FILE [INPUT-FILE …]`
  4763. The option ‘-o’ is used to specify the output file and all file
  4764. arguments are used as input files.
  4765. Beside this one can use ‘-’ or ‘/dev/stdin’ for INPUT-FILE to denote
  4766. the standard input. Corresponding one can use ‘-’ and ‘/dev/stdout’ for
  4767. OUTPUT-FILE to denote standard output. Using ‘-’ as a file name is
  4768. allowed in X/Open while using the device names is a GNU extension.
  4769. The ‘gencat’ program works by concatenating all input files and then
  4770. *merging* the resulting collection of message sets with a possibly
  4771. existing output file. This is done by removing all messages with
  4772. set/message number tuples matching any of the generated messages from
  4773. the output file and then adding all the new messages. To regenerate a
  4774. catalog file while ignoring the old contents therefore requires removing
  4775. the output file if it exists. If the output is written to standard
  4776. output no merging takes place.
  4777. The following table shows the options understood by the ‘gencat’
  4778. program. The X/Open standard does not specify any options for the
  4779. program so all of these are GNU extensions.
  4780. ‘-V’
  4781. ‘--version’
  4782. Print the version information and exit.
  4783. ‘-h’
  4784. ‘--help’
  4785. Print a usage message listing all available options, then exit
  4786. successfully.
  4787. ‘--new’
  4788. Do not merge the new messages from the input files with the old
  4789. content of the output file. The old content of the output file is
  4790. discarded.
  4791. ‘-H’
  4792. ‘--header=name’
  4793. This option is used to emit the symbolic names given to sets and
  4794. messages in the input files for use in the program. Details about
  4795. how to use this are given in the next section. The NAME parameter
  4796. to this option specifies the name of the output file. It will
  4797. contain a number of C preprocessor ‘#define’s to associate a name
  4798. with a number.
  4799. Please note that the generated file only contains the symbols from
  4800. the input files. If the output is merged with the previous content
  4801. of the output file the possibly existing symbols from the file(s)
  4802. which generated the old output files are not in the generated
  4803. header file.
  4804. 
  4805. File: libc.info, Node: Common Usage, Prev: The gencat program, Up: Message catalogs a la X/Open
  4806. 8.1.4 How to use the ‘catgets’ interface
  4807. ----------------------------------------
  4808. The ‘catgets’ functions can be used in two different ways. By following
  4809. slavishly the X/Open specs and not relying on the extension and by using
  4810. the GNU extensions. We will take a look at the former method first to
  4811. understand the benefits of extensions.
  4812. 8.1.4.1 Not using symbolic names
  4813. ................................
  4814. Since the X/Open format of the message catalog files does not allow
  4815. symbol names we have to work with numbers all the time. When we start
  4816. writing a program we have to replace all appearances of translatable
  4817. strings with something like
  4818. catgets (catdesc, set, msg, "string")
  4819. CATGETS is retrieved from a call to ‘catopen’ which is normally done
  4820. once at the program start. The ‘"string"’ is the string we want to
  4821. translate. The problems start with the set and message numbers.
  4822. In a bigger program several programmers usually work at the same time
  4823. on the program and so coordinating the number allocation is crucial.
  4824. Though no two different strings must be indexed by the same tuple of
  4825. numbers it is highly desirable to reuse the numbers for equal strings
  4826. with equal translations (please note that there might be strings which
  4827. are equal in one language but have different translations due to
  4828. difference contexts).
  4829. The allocation process can be relaxed a bit by different set numbers
  4830. for different parts of the program. So the number of developers who
  4831. have to coordinate the allocation can be reduced. But still lists must
  4832. be keep track of the allocation and errors can easily happen. These
  4833. errors cannot be discovered by the compiler or the ‘catgets’ functions.
  4834. Only the user of the program might see wrong messages printed. In the
  4835. worst cases the messages are so irritating that they cannot be
  4836. recognized as wrong. Think about the translations for ‘"true"’ and
  4837. ‘"false"’ being exchanged. This could result in a disaster.
  4838. 8.1.4.2 Using symbolic names
  4839. ............................
  4840. The problems mentioned in the last section derive from the fact that:
  4841. 1. the numbers are allocated once and due to the possibly frequent use
  4842. of them it is difficult to change a number later.
  4843. 2. the numbers do not allow guessing anything about the string and
  4844. therefore collisions can easily happen.
  4845. By constantly using symbolic names and by providing a method which
  4846. maps the string content to a symbolic name (however this will happen)
  4847. one can prevent both problems above. The cost of this is that the
  4848. programmer has to write a complete message catalog file while s/he is
  4849. writing the program itself.
  4850. This is necessary since the symbolic names must be mapped to numbers
  4851. before the program sources can be compiled. In the last section it was
  4852. described how to generate a header containing the mapping of the names.
  4853. E.g., for the example message file given in the last section we could
  4854. call the ‘gencat’ program as follows (assume ‘ex.msg’ contains the
  4855. sources).
  4856. gencat -H ex.h -o ex.cat ex.msg
  4857. This generates a header file with the following content:
  4858. #define SetTwoSet 0x2 /* ex.msg:8 */
  4859. #define SetOneSet 0x1 /* ex.msg:4 */
  4860. #define SetOnetwo 0x2 /* ex.msg:6 */
  4861. As can be seen the various symbols given in the source file are
  4862. mangled to generate unique identifiers and these identifiers get numbers
  4863. assigned. Reading the source file and knowing about the rules will
  4864. allow to predict the content of the header file (it is deterministic)
  4865. but this is not necessary. The ‘gencat’ program can take care for
  4866. everything. All the programmer has to do is to put the generated header
  4867. file in the dependency list of the source files of her/his project and
  4868. add a rule to regenerate the header if any of the input files change.
  4869. One word about the symbol mangling. Every symbol consists of two
  4870. parts: the name of the message set plus the name of the message or the
  4871. special string ‘Set’. So ‘SetOnetwo’ means this macro can be used to
  4872. access the translation with identifier ‘two’ in the message set
  4873. ‘SetOne’.
  4874. The other names denote the names of the message sets. The special
  4875. string ‘Set’ is used in the place of the message identifier.
  4876. If in the code the second string of the set ‘SetOne’ is used the C
  4877. code should look like this:
  4878. catgets (catdesc, SetOneSet, SetOnetwo,
  4879. " Message with ID \"two\", which gets the value 2 assigned")
  4880. Writing the function this way will allow to change the message number
  4881. and even the set number without requiring any change in the C source
  4882. code. (The text of the string is normally not the same; this is only
  4883. for this example.)
  4884. 8.1.4.3 How does to this allow to develop
  4885. .........................................
  4886. To illustrate the usual way to work with the symbolic version numbers
  4887. here is a little example. Assume we want to write the very complex and
  4888. famous greeting program. We start by writing the code as usual:
  4889. #include <stdio.h>
  4890. int
  4891. main (void)
  4892. {
  4893. printf ("Hello, world!\n");
  4894. return 0;
  4895. }
  4896. Now we want to internationalize the message and therefore replace the
  4897. message with whatever the user wants.
  4898. #include <nl_types.h>
  4899. #include <stdio.h>
  4900. #include "msgnrs.h"
  4901. int
  4902. main (void)
  4903. {
  4904. nl_catd catdesc = catopen ("hello.cat", NL_CAT_LOCALE);
  4905. printf (catgets (catdesc, SetMainSet, SetMainHello,
  4906. "Hello, world!\n"));
  4907. catclose (catdesc);
  4908. return 0;
  4909. }
  4910. We see how the catalog object is opened and the returned descriptor
  4911. used in the other function calls. It is not really necessary to check
  4912. for failure of any of the functions since even in these situations the
  4913. functions will behave reasonable. They simply will be return a
  4914. translation.
  4915. What remains unspecified here are the constants ‘SetMainSet’ and
  4916. ‘SetMainHello’. These are the symbolic names describing the message.
  4917. To get the actual definitions which match the information in the catalog
  4918. file we have to create the message catalog source file and process it
  4919. using the ‘gencat’ program.
  4920. $ Messages for the famous greeting program.
  4921. $quote "
  4922. $set Main
  4923. Hello "Hallo, Welt!\n"
  4924. Now we can start building the program (assume the message catalog
  4925. source file is named ‘hello.msg’ and the program source file ‘hello.c’):
  4926. % gencat -H msgnrs.h -o hello.cat hello.msg
  4927. % cat msgnrs.h
  4928. #define MainSet 0x1 /* hello.msg:4 */
  4929. #define MainHello 0x1 /* hello.msg:5 */
  4930. % gcc -o hello hello.c -I.
  4931. % cp hello.cat /usr/share/locale/de/LC_MESSAGES
  4932. % echo $LC_ALL
  4933. de
  4934. % ./hello
  4935. Hallo, Welt!
  4936. %
  4937. The call of the ‘gencat’ program creates the missing header file
  4938. ‘msgnrs.h’ as well as the message catalog binary. The former is used in
  4939. the compilation of ‘hello.c’ while the later is placed in a directory in
  4940. which the ‘catopen’ function will try to locate it. Please check the
  4941. ‘LC_ALL’ environment variable and the default path for ‘catopen’
  4942. presented in the description above.
  4943. 
  4944. File: libc.info, Node: The Uniforum approach, Prev: Message catalogs a la X/Open, Up: Message Translation
  4945. 8.2 The Uniforum approach to Message Translation
  4946. ================================================
  4947. Sun Microsystems tried to standardize a different approach to message
  4948. translation in the Uniforum group. There never was a real standard
  4949. defined but still the interface was used in Sun’s operating systems.
  4950. Since this approach fits better in the development process of free
  4951. software it is also used throughout the GNU project and the GNU
  4952. ‘gettext’ package provides support for this outside the GNU C Library.
  4953. The code of the ‘libintl’ from GNU ‘gettext’ is the same as the code
  4954. in the GNU C Library. So the documentation in the GNU ‘gettext’ manual
  4955. is also valid for the functionality here. The following text will
  4956. describe the library functions in detail. But the numerous helper
  4957. programs are not described in this manual. Instead people should read
  4958. the GNU ‘gettext’ manual (*note GNU gettext utilities: (gettext)Top.).
  4959. We will only give a short overview.
  4960. Though the ‘catgets’ functions are available by default on more
  4961. systems the ‘gettext’ interface is at least as portable as the former.
  4962. The GNU ‘gettext’ package can be used wherever the functions are not
  4963. available.
  4964. * Menu:
  4965. * Message catalogs with gettext:: The ‘gettext’ family of functions.
  4966. * Helper programs for gettext:: Programs to handle message catalogs
  4967. for ‘gettext’.
  4968. 
  4969. File: libc.info, Node: Message catalogs with gettext, Next: Helper programs for gettext, Up: The Uniforum approach
  4970. 8.2.1 The ‘gettext’ family of functions
  4971. ---------------------------------------
  4972. The paradigms underlying the ‘gettext’ approach to message translations
  4973. is different from that of the ‘catgets’ functions the basic functionally
  4974. is equivalent. There are functions of the following categories:
  4975. * Menu:
  4976. * Translation with gettext:: What has to be done to translate a message.
  4977. * Locating gettext catalog:: How to determine which catalog to be used.
  4978. * Advanced gettext functions:: Additional functions for more complicated
  4979. situations.
  4980. * Charset conversion in gettext:: How to specify the output character set
  4981. ‘gettext’ uses.
  4982. * GUI program problems:: How to use ‘gettext’ in GUI programs.
  4983. * Using gettextized software:: The possibilities of the user to influence
  4984. the way ‘gettext’ works.
  4985. 
  4986. File: libc.info, Node: Translation with gettext, Next: Locating gettext catalog, Up: Message catalogs with gettext
  4987. 8.2.1.1 What has to be done to translate a message?
  4988. ...................................................
  4989. The ‘gettext’ functions have a very simple interface. The most basic
  4990. function just takes the string which shall be translated as the argument
  4991. and it returns the translation. This is fundamentally different from
  4992. the ‘catgets’ approach where an extra key is necessary and the original
  4993. string is only used for the error case.
  4994. If the string which has to be translated is the only argument this of
  4995. course means the string itself is the key. I.e., the translation will
  4996. be selected based on the original string. The message catalogs must
  4997. therefore contain the original strings plus one translation for any such
  4998. string. The task of the ‘gettext’ function is to compare the argument
  4999. string with the available strings in the catalog and return the
  5000. appropriate translation. Of course this process is optimized so that
  5001. this process is not more expensive than an access using an atomic key
  5002. like in ‘catgets’.
  5003. The ‘gettext’ approach has some advantages but also some
  5004. disadvantages. Please see the GNU ‘gettext’ manual for a detailed
  5005. discussion of the pros and cons.
  5006. All the definitions and declarations for ‘gettext’ can be found in
  5007. the ‘libintl.h’ header file. On systems where these functions are not
  5008. part of the C library they can be found in a separate library named
  5009. ‘libintl.a’ (or accordingly different for shared libraries).
  5010. -- Function: char * gettext (const char *MSGID)
  5011. Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
  5012. AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
  5013. The ‘gettext’ function searches the currently selected message
  5014. catalogs for a string which is equal to MSGID. If there is such a
  5015. string available it is returned. Otherwise the argument string
  5016. MSGID is returned.
  5017. Please note that although the return value is ‘char *’ the returned
  5018. string must not be changed. This broken type results from the
  5019. history of the function and does not reflect the way the function
  5020. should be used.
  5021. Please note that above we wrote “message catalogs” (plural). This
  5022. is a specialty of the GNU implementation of these functions and we
  5023. will say more about this when we talk about the ways message
  5024. catalogs are selected (*note Locating gettext catalog::).
  5025. The ‘gettext’ function does not modify the value of the global
  5026. ERRNO variable. This is necessary to make it possible to write
  5027. something like
  5028. printf (gettext ("Operation failed: %m\n"));
  5029. Here the ERRNO value is used in the ‘printf’ function while
  5030. processing the ‘%m’ format element and if the ‘gettext’ function
  5031. would change this value (it is called before ‘printf’ is called) we
  5032. would get a wrong message.
  5033. So there is no easy way to detect a missing message catalog besides
  5034. comparing the argument string with the result. But it is normally
  5035. the task of the user to react on missing catalogs. The program
  5036. cannot guess when a message catalog is really necessary since for a
  5037. user who speaks the language the program was developed in, the
  5038. message does not need any translation.
  5039. The remaining two functions to access the message catalog add some
  5040. functionality to select a message catalog which is not the default one.
  5041. This is important if parts of the program are developed independently.
  5042. Every part can have its own message catalog and all of them can be used
  5043. at the same time. The C library itself is an example: internally it
  5044. uses the ‘gettext’ functions but since it must not depend on a currently
  5045. selected default message catalog it must specify all ambiguous
  5046. information.
  5047. -- Function: char * dgettext (const char *DOMAINNAME, const char
  5048. *MSGID)
  5049. Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
  5050. AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
  5051. The ‘dgettext’ function acts just like the ‘gettext’ function. It
  5052. only takes an additional first argument DOMAINNAME which guides the
  5053. selection of the message catalogs which are searched for the
  5054. translation. If the DOMAINNAME parameter is the null pointer the
  5055. ‘dgettext’ function is exactly equivalent to ‘gettext’ since the
  5056. default value for the domain name is used.
  5057. As for ‘gettext’ the return value type is ‘char *’ which is an
  5058. anachronism. The returned string must never be modified.
  5059. -- Function: char * dcgettext (const char *DOMAINNAME, const char
  5060. *MSGID, int CATEGORY)
  5061. Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
  5062. AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
  5063. The ‘dcgettext’ adds another argument to those which ‘dgettext’
  5064. takes. This argument CATEGORY specifies the last piece of
  5065. information needed to localize the message catalog. I.e., the
  5066. domain name and the locale category exactly specify which message
  5067. catalog has to be used (relative to a given directory, see below).
  5068. The ‘dgettext’ function can be expressed in terms of ‘dcgettext’ by
  5069. using
  5070. dcgettext (domain, string, LC_MESSAGES)
  5071. instead of
  5072. dgettext (domain, string)
  5073. This also shows which values are expected for the third parameter.
  5074. One has to use the available selectors for the categories available
  5075. in ‘locale.h’. Normally the available values are ‘LC_CTYPE’,
  5076. ‘LC_COLLATE’, ‘LC_MESSAGES’, ‘LC_MONETARY’, ‘LC_NUMERIC’, and
  5077. ‘LC_TIME’. Please note that ‘LC_ALL’ must not be used and even
  5078. though the names might suggest this, there is no relation to the
  5079. environment variable of this name.
  5080. The ‘dcgettext’ function is only implemented for compatibility with
  5081. other systems which have ‘gettext’ functions. There is not really
  5082. any situation where it is necessary (or useful) to use a different
  5083. value than ‘LC_MESSAGES’ for the CATEGORY parameter. We are
  5084. dealing with messages here and any other choice can only be
  5085. irritating.
  5086. As for ‘gettext’ the return value type is ‘char *’ which is an
  5087. anachronism. The returned string must never be modified.
  5088. When using the three functions above in a program it is a frequent
  5089. case that the MSGID argument is a constant string. So it is worthwhile
  5090. to optimize this case. Thinking shortly about this one will realize
  5091. that as long as no new message catalog is loaded the translation of a
  5092. message will not change. This optimization is actually implemented by
  5093. the ‘gettext’, ‘dgettext’ and ‘dcgettext’ functions.
  5094. 
  5095. File: libc.info, Node: Locating gettext catalog, Next: Advanced gettext functions, Prev: Translation with gettext, Up: Message catalogs with gettext
  5096. 8.2.1.2 How to determine which catalog to be used
  5097. .................................................
  5098. The functions to retrieve the translations for a given message have a
  5099. remarkable simple interface. But to provide the user of the program
  5100. still the opportunity to select exactly the translation s/he wants and
  5101. also to provide the programmer the possibility to influence the way to
  5102. locate the search for catalogs files there is a quite complicated
  5103. underlying mechanism which controls all this. The code is complicated
  5104. the use is easy.
  5105. Basically we have two different tasks to perform which can also be
  5106. performed by the ‘catgets’ functions:
  5107. 1. Locate the set of message catalogs. There are a number of files
  5108. for different languages which all belong to the package. Usually
  5109. they are all stored in the filesystem below a certain directory.
  5110. There can be arbitrarily many packages installed and they can
  5111. follow different guidelines for the placement of their files.
  5112. 2. Relative to the location specified by the package the actual
  5113. translation files must be searched, based on the wishes of the
  5114. user. I.e., for each language the user selects the program should
  5115. be able to locate the appropriate file.
  5116. This is the functionality required by the specifications for
  5117. ‘gettext’ and this is also what the ‘catgets’ functions are able to do.
  5118. But there are some problems unresolved:
  5119. • The language to be used can be specified in several different ways.
  5120. There is no generally accepted standard for this and the user
  5121. always expects the program to understand what s/he means. E.g., to
  5122. select the German translation one could write ‘de’, ‘german’, or
  5123. ‘deutsch’ and the program should always react the same.
  5124. • Sometimes the specification of the user is too detailed. If s/he,
  5125. e.g., specifies ‘de_DE.ISO-8859-1’ which means German, spoken in
  5126. Germany, coded using the ISO 8859-1 character set there is the
  5127. possibility that a message catalog matching this exactly is not
  5128. available. But there could be a catalog matching ‘de’ and if the
  5129. character set used on the machine is always ISO 8859-1 there is no
  5130. reason why this later message catalog should not be used. (We call
  5131. this "message inheritance".)
  5132. • If a catalog for a wanted language is not available it is not
  5133. always the second best choice to fall back on the language of the
  5134. developer and simply not translate any message. Instead a user
  5135. might be better able to read the messages in another language and
  5136. so the user of the program should be able to define a precedence
  5137. order of languages.
  5138. We can divide the configuration actions in two parts: the one is
  5139. performed by the programmer, the other by the user. We will start with
  5140. the functions the programmer can use since the user configuration will
  5141. be based on this.
  5142. As the functions described in the last sections already mention
  5143. separate sets of messages can be selected by a "domain name". This is a
  5144. simple string which should be unique for each program part that uses a
  5145. separate domain. It is possible to use in one program arbitrarily many
  5146. domains at the same time. E.g., the GNU C Library itself uses a domain
  5147. named ‘libc’ while the program using the C Library could use a domain
  5148. named ‘foo’. The important point is that at any time exactly one domain
  5149. is active. This is controlled with the following function.
  5150. -- Function: char * textdomain (const char *DOMAINNAME)
  5151. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5152. *Note POSIX Safety Concepts::.
  5153. The ‘textdomain’ function sets the default domain, which is used in
  5154. all future ‘gettext’ calls, to DOMAINNAME. Please note that
  5155. ‘dgettext’ and ‘dcgettext’ calls are not influenced if the
  5156. DOMAINNAME parameter of these functions is not the null pointer.
  5157. Before the first call to ‘textdomain’ the default domain is
  5158. ‘messages’. This is the name specified in the specification of the
  5159. ‘gettext’ API. This name is as good as any other name. No program
  5160. should ever really use a domain with this name since this can only
  5161. lead to problems.
  5162. The function returns the value which is from now on taken as the
  5163. default domain. If the system went out of memory the returned
  5164. value is ‘NULL’ and the global variable ERRNO is set to ‘ENOMEM’.
  5165. Despite the return value type being ‘char *’ the return string must
  5166. not be changed. It is allocated internally by the ‘textdomain’
  5167. function.
  5168. If the DOMAINNAME parameter is the null pointer no new default
  5169. domain is set. Instead the currently selected default domain is
  5170. returned.
  5171. If the DOMAINNAME parameter is the empty string the default domain
  5172. is reset to its initial value, the domain with the name ‘messages’.
  5173. This possibility is questionable to use since the domain ‘messages’
  5174. really never should be used.
  5175. -- Function: char * bindtextdomain (const char *DOMAINNAME, const char
  5176. *DIRNAME)
  5177. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5178. POSIX Safety Concepts::.
  5179. The ‘bindtextdomain’ function can be used to specify the directory
  5180. which contains the message catalogs for domain DOMAINNAME for the
  5181. different languages. To be correct, this is the directory where
  5182. the hierarchy of directories is expected. Details are explained
  5183. below.
  5184. For the programmer it is important to note that the translations
  5185. which come with the program have to be placed in a directory
  5186. hierarchy starting at, say, ‘/foo/bar’. Then the program should
  5187. make a ‘bindtextdomain’ call to bind the domain for the current
  5188. program to this directory. So it is made sure the catalogs are
  5189. found. A correctly running program does not depend on the user
  5190. setting an environment variable.
  5191. The ‘bindtextdomain’ function can be used several times and if the
  5192. DOMAINNAME argument is different the previously bound domains will
  5193. not be overwritten.
  5194. If the program which wish to use ‘bindtextdomain’ at some point of
  5195. time use the ‘chdir’ function to change the current working
  5196. directory it is important that the DIRNAME strings ought to be an
  5197. absolute pathname. Otherwise the addressed directory might vary
  5198. with the time.
  5199. If the DIRNAME parameter is the null pointer ‘bindtextdomain’
  5200. returns the currently selected directory for the domain with the
  5201. name DOMAINNAME.
  5202. The ‘bindtextdomain’ function returns a pointer to a string
  5203. containing the name of the selected directory name. The string is
  5204. allocated internally in the function and must not be changed by the
  5205. user. If the system went out of core during the execution of
  5206. ‘bindtextdomain’ the return value is ‘NULL’ and the global variable
  5207. ERRNO is set accordingly.
  5208. 
  5209. File: libc.info, Node: Advanced gettext functions, Next: Charset conversion in gettext, Prev: Locating gettext catalog, Up: Message catalogs with gettext
  5210. 8.2.1.3 Additional functions for more complicated situations
  5211. ............................................................
  5212. The functions of the ‘gettext’ family described so far (and all the
  5213. ‘catgets’ functions as well) have one problem in the real world which
  5214. has been neglected completely in all existing approaches. What is meant
  5215. here is the handling of plural forms.
  5216. Looking through Unix source code before the time anybody thought
  5217. about internationalization (and, sadly, even afterwards) one can often
  5218. find code similar to the following:
  5219. printf ("%d file%s deleted", n, n == 1 ? "" : "s");
  5220. After the first complaints from people internationalizing the code
  5221. people either completely avoided formulations like this or used strings
  5222. like ‘"file(s)"’. Both look unnatural and should be avoided. First
  5223. tries to solve the problem correctly looked like this:
  5224. if (n == 1)
  5225. printf ("%d file deleted", n);
  5226. else
  5227. printf ("%d files deleted", n);
  5228. But this does not solve the problem. It helps languages where the
  5229. plural form of a noun is not simply constructed by adding an ‘s’ but
  5230. that is all. Once again people fell into the trap of believing the
  5231. rules their language uses are universal. But the handling of plural
  5232. forms differs widely between the language families. There are two
  5233. things we can differ between (and even inside language families);
  5234. • The form how plural forms are build differs. This is a problem
  5235. with language which have many irregularities. German, for
  5236. instance, is a drastic case. Though English and German are part of
  5237. the same language family (Germanic), the almost regular forming of
  5238. plural noun forms (appending an ‘s’) is hardly found in German.
  5239. • The number of plural forms differ. This is somewhat surprising for
  5240. those who only have experiences with Romanic and Germanic languages
  5241. since here the number is the same (there are two).
  5242. But other language families have only one form or many forms. More
  5243. information on this in an extra section.
  5244. The consequence of this is that application writers should not try to
  5245. solve the problem in their code. This would be localization since it is
  5246. only usable for certain, hardcoded language environments. Instead the
  5247. extended ‘gettext’ interface should be used.
  5248. These extra functions are taking instead of the one key string two
  5249. strings and a numerical argument. The idea behind this is that using
  5250. the numerical argument and the first string as a key, the implementation
  5251. can select using rules specified by the translator the right plural
  5252. form. The two string arguments then will be used to provide a return
  5253. value in case no message catalog is found (similar to the normal
  5254. ‘gettext’ behavior). In this case the rules for Germanic language are
  5255. used and it is assumed that the first string argument is the singular
  5256. form, the second the plural form.
  5257. This has the consequence that programs without language catalogs can
  5258. display the correct strings only if the program itself is written using
  5259. a Germanic language. This is a limitation but since the GNU C Library
  5260. (as well as the GNU ‘gettext’ package) is written as part of the GNU
  5261. package and the coding standards for the GNU project require programs to
  5262. be written in English, this solution nevertheless fulfills its purpose.
  5263. -- Function: char * ngettext (const char *MSGID1, const char *MSGID2,
  5264. unsigned long int N)
  5265. Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
  5266. AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
  5267. The ‘ngettext’ function is similar to the ‘gettext’ function as it
  5268. finds the message catalogs in the same way. But it takes two extra
  5269. arguments. The MSGID1 parameter must contain the singular form of
  5270. the string to be converted. It is also used as the key for the
  5271. search in the catalog. The MSGID2 parameter is the plural form.
  5272. The parameter N is used to determine the plural form. If no
  5273. message catalog is found MSGID1 is returned if ‘n == 1’, otherwise
  5274. ‘msgid2’.
  5275. An example for the use of this function is:
  5276. printf (ngettext ("%d file removed", "%d files removed", n), n);
  5277. Please note that the numeric value N has to be passed to the
  5278. ‘printf’ function as well. It is not sufficient to pass it only to
  5279. ‘ngettext’.
  5280. -- Function: char * dngettext (const char *DOMAIN, const char *MSGID1,
  5281. const char *MSGID2, unsigned long int N)
  5282. Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
  5283. AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
  5284. The ‘dngettext’ is similar to the ‘dgettext’ function in the way
  5285. the message catalog is selected. The difference is that it takes
  5286. two extra parameters to provide the correct plural form. These two
  5287. parameters are handled in the same way ‘ngettext’ handles them.
  5288. -- Function: char * dcngettext (const char *DOMAIN, const char *MSGID1,
  5289. const char *MSGID2, unsigned long int N, int CATEGORY)
  5290. Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
  5291. AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
  5292. The ‘dcngettext’ is similar to the ‘dcgettext’ function in the way
  5293. the message catalog is selected. The difference is that it takes
  5294. two extra parameters to provide the correct plural form. These two
  5295. parameters are handled in the same way ‘ngettext’ handles them.
  5296. The problem of plural forms
  5297. ...........................
  5298. A description of the problem can be found at the beginning of the last
  5299. section. Now there is the question how to solve it. Without the input
  5300. of linguists (which was not available) it was not possible to determine
  5301. whether there are only a few different forms in which plural forms are
  5302. formed or whether the number can increase with every new supported
  5303. language.
  5304. Therefore the solution implemented is to allow the translator to
  5305. specify the rules of how to select the plural form. Since the formula
  5306. varies with every language this is the only viable solution except for
  5307. hardcoding the information in the code (which still would require the
  5308. possibility of extensions to not prevent the use of new languages). The
  5309. details are explained in the GNU ‘gettext’ manual. Here only a bit of
  5310. information is provided.
  5311. The information about the plural form selection has to be stored in
  5312. the header entry (the one with the empty ‘msgid’ string). It looks like
  5313. this:
  5314. Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
  5315. The ‘nplurals’ value must be a decimal number which specifies how
  5316. many different plural forms exist for this language. The string
  5317. following ‘plural’ is an expression using the C language syntax.
  5318. Exceptions are that no negative numbers are allowed, numbers must be
  5319. decimal, and the only variable allowed is ‘n’. This expression will be
  5320. evaluated whenever one of the functions ‘ngettext’, ‘dngettext’, or
  5321. ‘dcngettext’ is called. The numeric value passed to these functions is
  5322. then substituted for all uses of the variable ‘n’ in the expression.
  5323. The resulting value then must be greater or equal to zero and smaller
  5324. than the value given as the value of ‘nplurals’.
  5325. The following rules are known at this point. The language with families
  5326. are listed. But this does not necessarily mean the information can be
  5327. generalized for the whole family (as can be easily seen in the table
  5328. below).(1)
  5329. Only one form:
  5330. Some languages only require one single form. There is no
  5331. distinction between the singular and plural form. An appropriate
  5332. header entry would look like this:
  5333. Plural-Forms: nplurals=1; plural=0;
  5334. Languages with this property include:
  5335. Finno-Ugric family
  5336. Hungarian
  5337. Asian family
  5338. Japanese, Korean
  5339. Turkic/Altaic family
  5340. Turkish
  5341. Two forms, singular used for one only
  5342. This is the form used in most existing programs since it is what
  5343. English uses. A header entry would look like this:
  5344. Plural-Forms: nplurals=2; plural=n != 1;
  5345. (Note: this uses the feature of C expressions that boolean
  5346. expressions have to value zero or one.)
  5347. Languages with this property include:
  5348. Germanic family
  5349. Danish, Dutch, English, German, Norwegian, Swedish
  5350. Finno-Ugric family
  5351. Estonian, Finnish
  5352. Latin/Greek family
  5353. Greek
  5354. Semitic family
  5355. Hebrew
  5356. Romance family
  5357. Italian, Portuguese, Spanish
  5358. Artificial
  5359. Esperanto
  5360. Two forms, singular used for zero and one
  5361. Exceptional case in the language family. The header entry would
  5362. be:
  5363. Plural-Forms: nplurals=2; plural=n>1;
  5364. Languages with this property include:
  5365. Romanic family
  5366. French, Brazilian Portuguese
  5367. Three forms, special case for zero
  5368. The header entry would be:
  5369. Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
  5370. Languages with this property include:
  5371. Baltic family
  5372. Latvian
  5373. Three forms, special cases for one and two
  5374. The header entry would be:
  5375. Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
  5376. Languages with this property include:
  5377. Celtic
  5378. Gaeilge (Irish)
  5379. Three forms, special case for numbers ending in 1[2-9]
  5380. The header entry would look like this:
  5381. Plural-Forms: nplurals=3; \
  5382. plural=n%10==1 && n%100!=11 ? 0 : \
  5383. n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
  5384. Languages with this property include:
  5385. Baltic family
  5386. Lithuanian
  5387. Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
  5388. The header entry would look like this:
  5389. Plural-Forms: nplurals=3; \
  5390. plural=n%100/10==1 ? 2 : n%10==1 ? 0 : (n+9)%10>3 ? 2 : 1;
  5391. Languages with this property include:
  5392. Slavic family
  5393. Croatian, Czech, Russian, Ukrainian
  5394. Three forms, special cases for 1 and 2, 3, 4
  5395. The header entry would look like this:
  5396. Plural-Forms: nplurals=3; \
  5397. plural=(n==1) ? 1 : (n>=2 && n<=4) ? 2 : 0;
  5398. Languages with this property include:
  5399. Slavic family
  5400. Slovak
  5401. Three forms, special case for one and some numbers ending in 2, 3, or 4
  5402. The header entry would look like this:
  5403. Plural-Forms: nplurals=3; \
  5404. plural=n==1 ? 0 : \
  5405. n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
  5406. Languages with this property include:
  5407. Slavic family
  5408. Polish
  5409. Four forms, special case for one and all numbers ending in 02, 03, or 04
  5410. The header entry would look like this:
  5411. Plural-Forms: nplurals=4; \
  5412. plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
  5413. Languages with this property include:
  5414. Slavic family
  5415. Slovenian
  5416. ---------- Footnotes ----------
  5417. (1) Additions are welcome. Send appropriate information to
  5418. <bug-glibc-manual@gnu.org>.
  5419. 
  5420. File: libc.info, Node: Charset conversion in gettext, Next: GUI program problems, Prev: Advanced gettext functions, Up: Message catalogs with gettext
  5421. 8.2.1.4 How to specify the output character set ‘gettext’ uses
  5422. ..............................................................
  5423. ‘gettext’ not only looks up a translation in a message catalog, it also
  5424. converts the translation on the fly to the desired output character set.
  5425. This is useful if the user is working in a different character set than
  5426. the translator who created the message catalog, because it avoids
  5427. distributing variants of message catalogs which differ only in the
  5428. character set.
  5429. The output character set is, by default, the value of ‘nl_langinfo
  5430. (CODESET)’, which depends on the ‘LC_CTYPE’ part of the current locale.
  5431. But programs which store strings in a locale independent way (e.g.
  5432. UTF-8) can request that ‘gettext’ and related functions return the
  5433. translations in that encoding, by use of the ‘bind_textdomain_codeset’
  5434. function.
  5435. Note that the MSGID argument to ‘gettext’ is not subject to character
  5436. set conversion. Also, when ‘gettext’ does not find a translation for
  5437. MSGID, it returns MSGID unchanged – independently of the current output
  5438. character set. It is therefore recommended that all MSGIDs be US-ASCII
  5439. strings.
  5440. -- Function: char * bind_textdomain_codeset (const char *DOMAINNAME,
  5441. const char *CODESET)
  5442. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5443. POSIX Safety Concepts::.
  5444. The ‘bind_textdomain_codeset’ function can be used to specify the
  5445. output character set for message catalogs for domain DOMAINNAME.
  5446. The CODESET argument must be a valid codeset name which can be used
  5447. for the ‘iconv_open’ function, or a null pointer.
  5448. If the CODESET parameter is the null pointer,
  5449. ‘bind_textdomain_codeset’ returns the currently selected codeset
  5450. for the domain with the name DOMAINNAME. It returns ‘NULL’ if no
  5451. codeset has yet been selected.
  5452. The ‘bind_textdomain_codeset’ function can be used several times.
  5453. If used multiple times with the same DOMAINNAME argument, the later
  5454. call overrides the settings made by the earlier one.
  5455. The ‘bind_textdomain_codeset’ function returns a pointer to a
  5456. string containing the name of the selected codeset. The string is
  5457. allocated internally in the function and must not be changed by the
  5458. user. If the system went out of core during the execution of
  5459. ‘bind_textdomain_codeset’, the return value is ‘NULL’ and the
  5460. global variable ERRNO is set accordingly.
  5461. 
  5462. File: libc.info, Node: GUI program problems, Next: Using gettextized software, Prev: Charset conversion in gettext, Up: Message catalogs with gettext
  5463. 8.2.1.5 How to use ‘gettext’ in GUI programs
  5464. ............................................
  5465. One place where the ‘gettext’ functions, if used normally, have big
  5466. problems is within programs with graphical user interfaces (GUIs). The
  5467. problem is that many of the strings which have to be translated are very
  5468. short. They have to appear in pull-down menus which restricts the
  5469. length. But strings which are not containing entire sentences or at
  5470. least large fragments of a sentence may appear in more than one
  5471. situation in the program but might have different translations. This is
  5472. especially true for the one-word strings which are frequently used in
  5473. GUI programs.
  5474. As a consequence many people say that the ‘gettext’ approach is wrong
  5475. and instead ‘catgets’ should be used which indeed does not have this
  5476. problem. But there is a very simple and powerful method to handle these
  5477. kind of problems with the ‘gettext’ functions.
  5478. As an example consider the following fictional situation. A GUI program
  5479. has a menu bar with the following entries:
  5480. +------------+------------+--------------------------------------+
  5481. | File | Printer | |
  5482. +------------+------------+--------------------------------------+
  5483. | Open | | Select |
  5484. | New | | Open |
  5485. +----------+ | Connect |
  5486. +----------+
  5487. To have the strings ‘File’, ‘Printer’, ‘Open’, ‘New’, ‘Select’, and
  5488. ‘Connect’ translated there has to be at some point in the code a call to
  5489. a function of the ‘gettext’ family. But in two places the string passed
  5490. into the function would be ‘Open’. The translations might not be the
  5491. same and therefore we are in the dilemma described above.
  5492. One solution to this problem is to artificially extend the strings to
  5493. make them unambiguous. But what would the program do if no translation
  5494. is available? The extended string is not what should be printed. So we
  5495. should use a slightly modified version of the functions.
  5496. To extend the strings a uniform method should be used. E.g., in the
  5497. example above, the strings could be chosen as
  5498. Menu|File
  5499. Menu|Printer
  5500. Menu|File|Open
  5501. Menu|File|New
  5502. Menu|Printer|Select
  5503. Menu|Printer|Open
  5504. Menu|Printer|Connect
  5505. Now all the strings are different and if now instead of ‘gettext’ the
  5506. following little wrapper function is used, everything works just fine:
  5507. char *
  5508. sgettext (const char *msgid)
  5509. {
  5510. char *msgval = gettext (msgid);
  5511. if (msgval == msgid)
  5512. msgval = strrchr (msgid, '|') + 1;
  5513. return msgval;
  5514. }
  5515. What this little function does is to recognize the case when no
  5516. translation is available. This can be done very efficiently by a
  5517. pointer comparison since the return value is the input value. If there
  5518. is no translation we know that the input string is in the format we used
  5519. for the Menu entries and therefore contains a ‘|’ character. We simply
  5520. search for the last occurrence of this character and return a pointer to
  5521. the character following it. That’s it!
  5522. If one now consistently uses the extended string form and replaces
  5523. the ‘gettext’ calls with calls to ‘sgettext’ (this is normally limited
  5524. to very few places in the GUI implementation) then it is possible to
  5525. produce a program which can be internationalized.
  5526. With advanced compilers (such as GNU C) one can write the ‘sgettext’
  5527. functions as an inline function or as a macro like this:
  5528. #define sgettext(msgid) \
  5529. ({ const char *__msgid = (msgid); \
  5530. char *__msgstr = gettext (__msgid); \
  5531. if (__msgval == __msgid) \
  5532. __msgval = strrchr (__msgid, '|') + 1; \
  5533. __msgval; })
  5534. The other ‘gettext’ functions (‘dgettext’, ‘dcgettext’ and the
  5535. ‘ngettext’ equivalents) can and should have corresponding functions as
  5536. well which look almost identical, except for the parameters and the call
  5537. to the underlying function.
  5538. Now there is of course the question why such functions do not exist
  5539. in the GNU C Library? There are two parts of the answer to this
  5540. question.
  5541. • They are easy to write and therefore can be provided by the project
  5542. they are used in. This is not an answer by itself and must be seen
  5543. together with the second part which is:
  5544. • There is no way the C library can contain a version which can work
  5545. everywhere. The problem is the selection of the character to
  5546. separate the prefix from the actual string in the extended string.
  5547. The examples above used ‘|’ which is a quite good choice because it
  5548. resembles a notation frequently used in this context and it also is
  5549. a character not often used in message strings.
  5550. But what if the character is used in message strings. Or if the
  5551. chose character is not available in the character set on the
  5552. machine one compiles (e.g., ‘|’ is not required to exist for ISO C;
  5553. this is why the ‘iso646.h’ file exists in ISO C programming
  5554. environments).
  5555. There is only one more comment to make left. The wrapper function
  5556. above requires that the translations strings are not extended
  5557. themselves. This is only logical. There is no need to disambiguate the
  5558. strings (since they are never used as keys for a search) and one also
  5559. saves quite some memory and disk space by doing this.
  5560. 
  5561. File: libc.info, Node: Using gettextized software, Prev: GUI program problems, Up: Message catalogs with gettext
  5562. 8.2.1.6 User influence on ‘gettext’
  5563. ...................................
  5564. The last sections described what the programmer can do to
  5565. internationalize the messages of the program. But it is finally up to
  5566. the user to select the message s/he wants to see. S/He must understand
  5567. them.
  5568. The POSIX locale model uses the environment variables ‘LC_COLLATE’,
  5569. ‘LC_CTYPE’, ‘LC_MESSAGES’, ‘LC_MONETARY’, ‘LC_NUMERIC’, and ‘LC_TIME’ to
  5570. select the locale which is to be used. This way the user can influence
  5571. lots of functions. As we mentioned above, the ‘gettext’ functions also
  5572. take advantage of this.
  5573. To understand how this happens it is necessary to take a look at the
  5574. various components of the filename which gets computed to locate a
  5575. message catalog. It is composed as follows:
  5576. DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
  5577. The default value for DIR_NAME is system specific. It is computed
  5578. from the value given as the prefix while configuring the C library.
  5579. This value normally is ‘/usr’ or ‘/’. For the former the complete
  5580. DIR_NAME is:
  5581. /usr/share/locale
  5582. We can use ‘/usr/share’ since the ‘.mo’ files containing the message
  5583. catalogs are system independent, so all systems can use the same files.
  5584. If the program executed the ‘bindtextdomain’ function for the message
  5585. domain that is currently handled, the ‘dir_name’ component is exactly
  5586. the value which was given to the function as the second parameter.
  5587. I.e., ‘bindtextdomain’ allows overwriting the only system dependent and
  5588. fixed value to make it possible to address files anywhere in the
  5589. filesystem.
  5590. The CATEGORY is the name of the locale category which was selected in
  5591. the program code. For ‘gettext’ and ‘dgettext’ this is always
  5592. ‘LC_MESSAGES’, for ‘dcgettext’ this is selected by the value of the
  5593. third parameter. As said above it should be avoided to ever use a
  5594. category other than ‘LC_MESSAGES’.
  5595. The LOCALE component is computed based on the category used. Just
  5596. like for the ‘setlocale’ function here comes the user selection into the
  5597. play. Some environment variables are examined in a fixed order and the
  5598. first environment variable set determines the return value of the lookup
  5599. process. In detail, for the category ‘LC_xxx’ the following variables
  5600. in this order are examined:
  5601. ‘LANGUAGE’
  5602. ‘LC_ALL’
  5603. ‘LC_xxx’
  5604. ‘LANG’
  5605. This looks very familiar. With the exception of the ‘LANGUAGE’
  5606. environment variable this is exactly the lookup order the ‘setlocale’
  5607. function uses. But why introduce the ‘LANGUAGE’ variable?
  5608. The reason is that the syntax of the values these variables can have
  5609. is different to what is expected by the ‘setlocale’ function. If we
  5610. would set ‘LC_ALL’ to a value following the extended syntax that would
  5611. mean the ‘setlocale’ function will never be able to use the value of
  5612. this variable as well. An additional variable removes this problem plus
  5613. we can select the language independently of the locale setting which
  5614. sometimes is useful.
  5615. While for the ‘LC_xxx’ variables the value should consist of exactly
  5616. one specification of a locale the ‘LANGUAGE’ variable’s value can
  5617. consist of a colon separated list of locale names. The attentive reader
  5618. will realize that this is the way we manage to implement one of our
  5619. additional demands above: we want to be able to specify an ordered list
  5620. of languages.
  5621. Back to the constructed filename we have only one component missing.
  5622. The DOMAIN_NAME part is the name which was either registered using the
  5623. ‘textdomain’ function or which was given to ‘dgettext’ or ‘dcgettext’ as
  5624. the first parameter. Now it becomes obvious that a good choice for the
  5625. domain name in the program code is a string which is closely related to
  5626. the program/package name. E.g., for the GNU C Library the domain name
  5627. is ‘libc’.
  5628. A limited piece of example code should show how the program is supposed
  5629. to work:
  5630. {
  5631. setlocale (LC_ALL, "");
  5632. textdomain ("test-package");
  5633. bindtextdomain ("test-package", "/usr/local/share/locale");
  5634. puts (gettext ("Hello, world!"));
  5635. }
  5636. At the program start the default domain is ‘messages’, and the
  5637. default locale is "C". The ‘setlocale’ call sets the locale according to
  5638. the user’s environment variables; remember that correct functioning of
  5639. ‘gettext’ relies on the correct setting of the ‘LC_MESSAGES’ locale (for
  5640. looking up the message catalog) and of the ‘LC_CTYPE’ locale (for the
  5641. character set conversion). The ‘textdomain’ call changes the default
  5642. domain to ‘test-package’. The ‘bindtextdomain’ call specifies that the
  5643. message catalogs for the domain ‘test-package’ can be found below the
  5644. directory ‘/usr/local/share/locale’.
  5645. If the user sets in her/his environment the variable ‘LANGUAGE’ to
  5646. ‘de’ the ‘gettext’ function will try to use the translations from the
  5647. file
  5648. /usr/local/share/locale/de/LC_MESSAGES/test-package.mo
  5649. From the above descriptions it should be clear which component of
  5650. this filename is determined by which source.
  5651. In the above example we assumed the ‘LANGUAGE’ environment variable
  5652. to be ‘de’. This might be an appropriate selection but what happens if
  5653. the user wants to use ‘LC_ALL’ because of the wider usability and here
  5654. the required value is ‘de_DE.ISO-8859-1’? We already mentioned above
  5655. that a situation like this is not infrequent. E.g., a person might
  5656. prefer reading a dialect and if this is not available fall back on the
  5657. standard language.
  5658. The ‘gettext’ functions know about situations like this and can
  5659. handle them gracefully. The functions recognize the format of the value
  5660. of the environment variable. It can split the value is different pieces
  5661. and by leaving out the only or the other part it can construct new
  5662. values. This happens of course in a predictable way. To understand
  5663. this one must know the format of the environment variable value. There
  5664. is one more or less standardized form, originally from the X/Open
  5665. specification:
  5666. ‘language[_territory[.codeset]][@modifier]’
  5667. Less specific locale names will be stripped in the order of the
  5668. following list:
  5669. 1. ‘codeset’
  5670. 2. ‘normalized codeset’
  5671. 3. ‘territory’
  5672. 4. ‘modifier’
  5673. The ‘language’ field will never be dropped for obvious reasons.
  5674. The only new thing is the ‘normalized codeset’ entry. This is
  5675. another goodie which is introduced to help reduce the chaos which
  5676. derives from the inability of people to standardize the names of
  5677. character sets. Instead of ISO-8859-1 one can often see 8859-1, 88591,
  5678. iso8859-1, or iso_8859-1. The ‘normalized codeset’ value is generated
  5679. from the user-provided character set name by applying the following
  5680. rules:
  5681. 1. Remove all characters besides numbers and letters.
  5682. 2. Fold letters to lowercase.
  5683. 3. If the same only contains digits prepend the string ‘"iso"’.
  5684. So all of the above names will be normalized to ‘iso88591’. This allows
  5685. the program user much more freedom in choosing the locale name.
  5686. Even this extended functionality still does not help to solve the
  5687. problem that completely different names can be used to denote the same
  5688. locale (e.g., ‘de’ and ‘german’). To be of help in this situation the
  5689. locale implementation and also the ‘gettext’ functions know about
  5690. aliases.
  5691. The file ‘/usr/share/locale/locale.alias’ (replace ‘/usr’ with
  5692. whatever prefix you used for configuring the C library) contains a
  5693. mapping of alternative names to more regular names. The system manager
  5694. is free to add new entries to fill her/his own needs. The selected
  5695. locale from the environment is compared with the entries in the first
  5696. column of this file ignoring the case. If they match, the value of the
  5697. second column is used instead for the further handling.
  5698. In the description of the format of the environment variables we
  5699. already mentioned the character set as a factor in the selection of the
  5700. message catalog. In fact, only catalogs which contain text written
  5701. using the character set of the system/program can be used (directly;
  5702. there will come a solution for this some day). This means for the user
  5703. that s/he will always have to take care of this. If in the collection
  5704. of the message catalogs there are files for the same language but coded
  5705. using different character sets the user has to be careful.
  5706. 
  5707. File: libc.info, Node: Helper programs for gettext, Prev: Message catalogs with gettext, Up: The Uniforum approach
  5708. 8.2.2 Programs to handle message catalogs for ‘gettext’
  5709. -------------------------------------------------------
  5710. The GNU C Library does not contain the source code for the programs to
  5711. handle message catalogs for the ‘gettext’ functions. As part of the GNU
  5712. project the GNU gettext package contains everything the developer needs.
  5713. The functionality provided by the tools in this package by far exceeds
  5714. the abilities of the ‘gencat’ program described above for the ‘catgets’
  5715. functions.
  5716. There is a program ‘msgfmt’ which is the equivalent program to the
  5717. ‘gencat’ program. It generates from the human-readable and -editable
  5718. form of the message catalog a binary file which can be used by the
  5719. ‘gettext’ functions. But there are several more programs available.
  5720. The ‘xgettext’ program can be used to automatically extract the
  5721. translatable messages from a source file. I.e., the programmer need not
  5722. take care of the translations and the list of messages which have to be
  5723. translated. S/He will simply wrap the translatable string in calls to
  5724. ‘gettext’ et.al and the rest will be done by ‘xgettext’. This program
  5725. has a lot of options which help to customize the output or help to
  5726. understand the input better.
  5727. Other programs help to manage the development cycle when new messages
  5728. appear in the source files or when a new translation of the messages
  5729. appears. Here it should only be noted that using all the tools in GNU
  5730. gettext it is possible to _completely_ automate the handling of message
  5731. catalogs. Besides marking the translatable strings in the source code
  5732. and generating the translations the developers do not have anything to
  5733. do themselves.