12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638 |
- This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
- This file documents the GNU C Library.
- This is ‘The GNU C Library Reference Manual’, for version 2.25.
- Copyright © 1993–2017 Free Software Foundation, Inc.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with the
- Invariant Sections being “Free Software Needs Free Documentation” and
- “GNU Lesser General Public License”, the Front-Cover texts being “A GNU
- Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
- license is included in the section entitled "GNU Free Documentation
- License".
- (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
- modify this GNU manual. Buying copies from the FSF supports it in
- developing GNU and promoting software freedom.”
- INFO-DIR-SECTION Software libraries
- START-INFO-DIR-ENTRY
- * Libc: (libc). C library.
- END-INFO-DIR-ENTRY
- INFO-DIR-SECTION GNU C library functions and macros
- START-INFO-DIR-ENTRY
- * a64l: (libc)Encode Binary Data.
- * abort: (libc)Aborting a Program.
- * abs: (libc)Absolute Value.
- * accept: (libc)Accepting Connections.
- * access: (libc)Testing File Access.
- * acosf: (libc)Inverse Trig Functions.
- * acoshf: (libc)Hyperbolic Functions.
- * acosh: (libc)Hyperbolic Functions.
- * acoshl: (libc)Hyperbolic Functions.
- * acos: (libc)Inverse Trig Functions.
- * acosl: (libc)Inverse Trig Functions.
- * addmntent: (libc)mtab.
- * addseverity: (libc)Adding Severity Classes.
- * adjtime: (libc)High-Resolution Calendar.
- * adjtimex: (libc)High-Resolution Calendar.
- * aio_cancel64: (libc)Cancel AIO Operations.
- * aio_cancel: (libc)Cancel AIO Operations.
- * aio_error64: (libc)Status of AIO Operations.
- * aio_error: (libc)Status of AIO Operations.
- * aio_fsync64: (libc)Synchronizing AIO Operations.
- * aio_fsync: (libc)Synchronizing AIO Operations.
- * aio_init: (libc)Configuration of AIO.
- * aio_read64: (libc)Asynchronous Reads/Writes.
- * aio_read: (libc)Asynchronous Reads/Writes.
- * aio_return64: (libc)Status of AIO Operations.
- * aio_return: (libc)Status of AIO Operations.
- * aio_suspend64: (libc)Synchronizing AIO Operations.
- * aio_suspend: (libc)Synchronizing AIO Operations.
- * aio_write64: (libc)Asynchronous Reads/Writes.
- * aio_write: (libc)Asynchronous Reads/Writes.
- * alarm: (libc)Setting an Alarm.
- * aligned_alloc: (libc)Aligned Memory Blocks.
- * alloca: (libc)Variable Size Automatic.
- * alphasort64: (libc)Scanning Directory Content.
- * alphasort: (libc)Scanning Directory Content.
- * ALTWERASE: (libc)Local Modes.
- * ARG_MAX: (libc)General Limits.
- * argp_error: (libc)Argp Helper Functions.
- * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
- * argp_failure: (libc)Argp Helper Functions.
- * argp_help: (libc)Argp Help.
- * argp_parse: (libc)Argp.
- * argp_state_help: (libc)Argp Helper Functions.
- * argp_usage: (libc)Argp Helper Functions.
- * argz_add: (libc)Argz Functions.
- * argz_add_sep: (libc)Argz Functions.
- * argz_append: (libc)Argz Functions.
- * argz_count: (libc)Argz Functions.
- * argz_create: (libc)Argz Functions.
- * argz_create_sep: (libc)Argz Functions.
- * argz_delete: (libc)Argz Functions.
- * argz_extract: (libc)Argz Functions.
- * argz_insert: (libc)Argz Functions.
- * argz_next: (libc)Argz Functions.
- * argz_replace: (libc)Argz Functions.
- * argz_stringify: (libc)Argz Functions.
- * asctime: (libc)Formatting Calendar Time.
- * asctime_r: (libc)Formatting Calendar Time.
- * asinf: (libc)Inverse Trig Functions.
- * asinhf: (libc)Hyperbolic Functions.
- * asinh: (libc)Hyperbolic Functions.
- * asinhl: (libc)Hyperbolic Functions.
- * asin: (libc)Inverse Trig Functions.
- * asinl: (libc)Inverse Trig Functions.
- * asprintf: (libc)Dynamic Output.
- * assert: (libc)Consistency Checking.
- * assert_perror: (libc)Consistency Checking.
- * atan2f: (libc)Inverse Trig Functions.
- * atan2: (libc)Inverse Trig Functions.
- * atan2l: (libc)Inverse Trig Functions.
- * atanf: (libc)Inverse Trig Functions.
- * atanhf: (libc)Hyperbolic Functions.
- * atanh: (libc)Hyperbolic Functions.
- * atanhl: (libc)Hyperbolic Functions.
- * atan: (libc)Inverse Trig Functions.
- * atanl: (libc)Inverse Trig Functions.
- * atexit: (libc)Cleanups on Exit.
- * atof: (libc)Parsing of Floats.
- * atoi: (libc)Parsing of Integers.
- * atol: (libc)Parsing of Integers.
- * atoll: (libc)Parsing of Integers.
- * backtrace: (libc)Backtraces.
- * backtrace_symbols_fd: (libc)Backtraces.
- * backtrace_symbols: (libc)Backtraces.
- * basename: (libc)Finding Tokens in a String.
- * basename: (libc)Finding Tokens in a String.
- * BC_BASE_MAX: (libc)Utility Limits.
- * BC_DIM_MAX: (libc)Utility Limits.
- * bcmp: (libc)String/Array Comparison.
- * bcopy: (libc)Copying Strings and Arrays.
- * BC_SCALE_MAX: (libc)Utility Limits.
- * BC_STRING_MAX: (libc)Utility Limits.
- * bind: (libc)Setting Address.
- * bind_textdomain_codeset: (libc)Charset conversion in gettext.
- * bindtextdomain: (libc)Locating gettext catalog.
- * BRKINT: (libc)Input Modes.
- * brk: (libc)Resizing the Data Segment.
- * bsearch: (libc)Array Search Function.
- * btowc: (libc)Converting a Character.
- * BUFSIZ: (libc)Controlling Buffering.
- * bzero: (libc)Copying Strings and Arrays.
- * cabsf: (libc)Absolute Value.
- * cabs: (libc)Absolute Value.
- * cabsl: (libc)Absolute Value.
- * cacosf: (libc)Inverse Trig Functions.
- * cacoshf: (libc)Hyperbolic Functions.
- * cacosh: (libc)Hyperbolic Functions.
- * cacoshl: (libc)Hyperbolic Functions.
- * cacos: (libc)Inverse Trig Functions.
- * cacosl: (libc)Inverse Trig Functions.
- * calloc: (libc)Allocating Cleared Space.
- * canonicalize_file_name: (libc)Symbolic Links.
- * canonicalizef: (libc)FP Bit Twiddling.
- * canonicalize: (libc)FP Bit Twiddling.
- * canonicalizel: (libc)FP Bit Twiddling.
- * cargf: (libc)Operations on Complex.
- * carg: (libc)Operations on Complex.
- * cargl: (libc)Operations on Complex.
- * casinf: (libc)Inverse Trig Functions.
- * casinhf: (libc)Hyperbolic Functions.
- * casinh: (libc)Hyperbolic Functions.
- * casinhl: (libc)Hyperbolic Functions.
- * casin: (libc)Inverse Trig Functions.
- * casinl: (libc)Inverse Trig Functions.
- * catanf: (libc)Inverse Trig Functions.
- * catanhf: (libc)Hyperbolic Functions.
- * catanh: (libc)Hyperbolic Functions.
- * catanhl: (libc)Hyperbolic Functions.
- * catan: (libc)Inverse Trig Functions.
- * catanl: (libc)Inverse Trig Functions.
- * catclose: (libc)The catgets Functions.
- * catgets: (libc)The catgets Functions.
- * catopen: (libc)The catgets Functions.
- * cbc_crypt: (libc)DES Encryption.
- * cbrtf: (libc)Exponents and Logarithms.
- * cbrt: (libc)Exponents and Logarithms.
- * cbrtl: (libc)Exponents and Logarithms.
- * ccosf: (libc)Trig Functions.
- * ccoshf: (libc)Hyperbolic Functions.
- * ccosh: (libc)Hyperbolic Functions.
- * ccoshl: (libc)Hyperbolic Functions.
- * ccos: (libc)Trig Functions.
- * ccosl: (libc)Trig Functions.
- * CCTS_OFLOW: (libc)Control Modes.
- * ceilf: (libc)Rounding Functions.
- * ceil: (libc)Rounding Functions.
- * ceill: (libc)Rounding Functions.
- * cexpf: (libc)Exponents and Logarithms.
- * cexp: (libc)Exponents and Logarithms.
- * cexpl: (libc)Exponents and Logarithms.
- * cfgetispeed: (libc)Line Speed.
- * cfgetospeed: (libc)Line Speed.
- * cfmakeraw: (libc)Noncanonical Input.
- * cfree: (libc)Freeing after Malloc.
- * cfsetispeed: (libc)Line Speed.
- * cfsetospeed: (libc)Line Speed.
- * cfsetspeed: (libc)Line Speed.
- * chdir: (libc)Working Directory.
- * CHILD_MAX: (libc)General Limits.
- * chmod: (libc)Setting Permissions.
- * chown: (libc)File Owner.
- * CIGNORE: (libc)Control Modes.
- * cimagf: (libc)Operations on Complex.
- * cimag: (libc)Operations on Complex.
- * cimagl: (libc)Operations on Complex.
- * clearenv: (libc)Environment Access.
- * clearerr: (libc)Error Recovery.
- * clearerr_unlocked: (libc)Error Recovery.
- * CLK_TCK: (libc)Processor Time.
- * CLOCAL: (libc)Control Modes.
- * clock: (libc)CPU Time.
- * CLOCKS_PER_SEC: (libc)CPU Time.
- * clog10f: (libc)Exponents and Logarithms.
- * clog10: (libc)Exponents and Logarithms.
- * clog10l: (libc)Exponents and Logarithms.
- * clogf: (libc)Exponents and Logarithms.
- * clog: (libc)Exponents and Logarithms.
- * clogl: (libc)Exponents and Logarithms.
- * closedir: (libc)Reading/Closing Directory.
- * close: (libc)Opening and Closing Files.
- * closelog: (libc)closelog.
- * COLL_WEIGHTS_MAX: (libc)Utility Limits.
- * _Complex_I: (libc)Complex Numbers.
- * confstr: (libc)String Parameters.
- * conjf: (libc)Operations on Complex.
- * conj: (libc)Operations on Complex.
- * conjl: (libc)Operations on Complex.
- * connect: (libc)Connecting.
- * copysignf: (libc)FP Bit Twiddling.
- * copysign: (libc)FP Bit Twiddling.
- * copysignl: (libc)FP Bit Twiddling.
- * cosf: (libc)Trig Functions.
- * coshf: (libc)Hyperbolic Functions.
- * cosh: (libc)Hyperbolic Functions.
- * coshl: (libc)Hyperbolic Functions.
- * cos: (libc)Trig Functions.
- * cosl: (libc)Trig Functions.
- * cpowf: (libc)Exponents and Logarithms.
- * cpow: (libc)Exponents and Logarithms.
- * cpowl: (libc)Exponents and Logarithms.
- * cprojf: (libc)Operations on Complex.
- * cproj: (libc)Operations on Complex.
- * cprojl: (libc)Operations on Complex.
- * CPU_CLR: (libc)CPU Affinity.
- * CPU_ISSET: (libc)CPU Affinity.
- * CPU_SET: (libc)CPU Affinity.
- * CPU_SETSIZE: (libc)CPU Affinity.
- * CPU_ZERO: (libc)CPU Affinity.
- * CREAD: (libc)Control Modes.
- * crealf: (libc)Operations on Complex.
- * creal: (libc)Operations on Complex.
- * creall: (libc)Operations on Complex.
- * creat64: (libc)Opening and Closing Files.
- * creat: (libc)Opening and Closing Files.
- * CRTS_IFLOW: (libc)Control Modes.
- * crypt: (libc)crypt.
- * crypt_r: (libc)crypt.
- * CS5: (libc)Control Modes.
- * CS6: (libc)Control Modes.
- * CS7: (libc)Control Modes.
- * CS8: (libc)Control Modes.
- * csinf: (libc)Trig Functions.
- * csinhf: (libc)Hyperbolic Functions.
- * csinh: (libc)Hyperbolic Functions.
- * csinhl: (libc)Hyperbolic Functions.
- * csin: (libc)Trig Functions.
- * csinl: (libc)Trig Functions.
- * CSIZE: (libc)Control Modes.
- * csqrtf: (libc)Exponents and Logarithms.
- * csqrt: (libc)Exponents and Logarithms.
- * csqrtl: (libc)Exponents and Logarithms.
- * CSTOPB: (libc)Control Modes.
- * ctanf: (libc)Trig Functions.
- * ctanhf: (libc)Hyperbolic Functions.
- * ctanh: (libc)Hyperbolic Functions.
- * ctanhl: (libc)Hyperbolic Functions.
- * ctan: (libc)Trig Functions.
- * ctanl: (libc)Trig Functions.
- * ctermid: (libc)Identifying the Terminal.
- * ctime: (libc)Formatting Calendar Time.
- * ctime_r: (libc)Formatting Calendar Time.
- * cuserid: (libc)Who Logged In.
- * dcgettext: (libc)Translation with gettext.
- * dcngettext: (libc)Advanced gettext functions.
- * DES_FAILED: (libc)DES Encryption.
- * des_setparity: (libc)DES Encryption.
- * dgettext: (libc)Translation with gettext.
- * difftime: (libc)Elapsed Time.
- * dirfd: (libc)Opening a Directory.
- * dirname: (libc)Finding Tokens in a String.
- * div: (libc)Integer Division.
- * dngettext: (libc)Advanced gettext functions.
- * drand48: (libc)SVID Random.
- * drand48_r: (libc)SVID Random.
- * dremf: (libc)Remainder Functions.
- * drem: (libc)Remainder Functions.
- * dreml: (libc)Remainder Functions.
- * DTTOIF: (libc)Directory Entries.
- * dup2: (libc)Duplicating Descriptors.
- * dup: (libc)Duplicating Descriptors.
- * E2BIG: (libc)Error Codes.
- * EACCES: (libc)Error Codes.
- * EADDRINUSE: (libc)Error Codes.
- * EADDRNOTAVAIL: (libc)Error Codes.
- * EADV: (libc)Error Codes.
- * EAFNOSUPPORT: (libc)Error Codes.
- * EAGAIN: (libc)Error Codes.
- * EALREADY: (libc)Error Codes.
- * EAUTH: (libc)Error Codes.
- * EBACKGROUND: (libc)Error Codes.
- * EBADE: (libc)Error Codes.
- * EBADFD: (libc)Error Codes.
- * EBADF: (libc)Error Codes.
- * EBADMSG: (libc)Error Codes.
- * EBADR: (libc)Error Codes.
- * EBADRPC: (libc)Error Codes.
- * EBADRQC: (libc)Error Codes.
- * EBADSLT: (libc)Error Codes.
- * EBFONT: (libc)Error Codes.
- * EBUSY: (libc)Error Codes.
- * ECANCELED: (libc)Error Codes.
- * ecb_crypt: (libc)DES Encryption.
- * ECHILD: (libc)Error Codes.
- * ECHOCTL: (libc)Local Modes.
- * ECHOE: (libc)Local Modes.
- * ECHOKE: (libc)Local Modes.
- * ECHOK: (libc)Local Modes.
- * ECHO: (libc)Local Modes.
- * ECHONL: (libc)Local Modes.
- * ECHOPRT: (libc)Local Modes.
- * ECHRNG: (libc)Error Codes.
- * ECOMM: (libc)Error Codes.
- * ECONNABORTED: (libc)Error Codes.
- * ECONNREFUSED: (libc)Error Codes.
- * ECONNRESET: (libc)Error Codes.
- * ecvt: (libc)System V Number Conversion.
- * ecvt_r: (libc)System V Number Conversion.
- * EDEADLK: (libc)Error Codes.
- * EDEADLOCK: (libc)Error Codes.
- * EDESTADDRREQ: (libc)Error Codes.
- * EDIED: (libc)Error Codes.
- * ED: (libc)Error Codes.
- * EDOM: (libc)Error Codes.
- * EDOTDOT: (libc)Error Codes.
- * EDQUOT: (libc)Error Codes.
- * EEXIST: (libc)Error Codes.
- * EFAULT: (libc)Error Codes.
- * EFBIG: (libc)Error Codes.
- * EFTYPE: (libc)Error Codes.
- * EGRATUITOUS: (libc)Error Codes.
- * EGREGIOUS: (libc)Error Codes.
- * EHOSTDOWN: (libc)Error Codes.
- * EHOSTUNREACH: (libc)Error Codes.
- * EHWPOISON: (libc)Error Codes.
- * EIDRM: (libc)Error Codes.
- * EIEIO: (libc)Error Codes.
- * EILSEQ: (libc)Error Codes.
- * EINPROGRESS: (libc)Error Codes.
- * EINTR: (libc)Error Codes.
- * EINVAL: (libc)Error Codes.
- * EIO: (libc)Error Codes.
- * EISCONN: (libc)Error Codes.
- * EISDIR: (libc)Error Codes.
- * EISNAM: (libc)Error Codes.
- * EKEYEXPIRED: (libc)Error Codes.
- * EKEYREJECTED: (libc)Error Codes.
- * EKEYREVOKED: (libc)Error Codes.
- * EL2HLT: (libc)Error Codes.
- * EL2NSYNC: (libc)Error Codes.
- * EL3HLT: (libc)Error Codes.
- * EL3RST: (libc)Error Codes.
- * ELIBACC: (libc)Error Codes.
- * ELIBBAD: (libc)Error Codes.
- * ELIBEXEC: (libc)Error Codes.
- * ELIBMAX: (libc)Error Codes.
- * ELIBSCN: (libc)Error Codes.
- * ELNRNG: (libc)Error Codes.
- * ELOOP: (libc)Error Codes.
- * EMEDIUMTYPE: (libc)Error Codes.
- * EMFILE: (libc)Error Codes.
- * EMLINK: (libc)Error Codes.
- * EMSGSIZE: (libc)Error Codes.
- * EMULTIHOP: (libc)Error Codes.
- * ENAMETOOLONG: (libc)Error Codes.
- * ENAVAIL: (libc)Error Codes.
- * encrypt: (libc)DES Encryption.
- * encrypt_r: (libc)DES Encryption.
- * endfsent: (libc)fstab.
- * endgrent: (libc)Scanning All Groups.
- * endhostent: (libc)Host Names.
- * endmntent: (libc)mtab.
- * endnetent: (libc)Networks Database.
- * endnetgrent: (libc)Lookup Netgroup.
- * endprotoent: (libc)Protocols Database.
- * endpwent: (libc)Scanning All Users.
- * endservent: (libc)Services Database.
- * endutent: (libc)Manipulating the Database.
- * endutxent: (libc)XPG Functions.
- * ENEEDAUTH: (libc)Error Codes.
- * ENETDOWN: (libc)Error Codes.
- * ENETRESET: (libc)Error Codes.
- * ENETUNREACH: (libc)Error Codes.
- * ENFILE: (libc)Error Codes.
- * ENOANO: (libc)Error Codes.
- * ENOBUFS: (libc)Error Codes.
- * ENOCSI: (libc)Error Codes.
- * ENODATA: (libc)Error Codes.
- * ENODEV: (libc)Error Codes.
- * ENOENT: (libc)Error Codes.
- * ENOEXEC: (libc)Error Codes.
- * ENOKEY: (libc)Error Codes.
- * ENOLCK: (libc)Error Codes.
- * ENOLINK: (libc)Error Codes.
- * ENOMEDIUM: (libc)Error Codes.
- * ENOMEM: (libc)Error Codes.
- * ENOMSG: (libc)Error Codes.
- * ENONET: (libc)Error Codes.
- * ENOPKG: (libc)Error Codes.
- * ENOPROTOOPT: (libc)Error Codes.
- * ENOSPC: (libc)Error Codes.
- * ENOSR: (libc)Error Codes.
- * ENOSTR: (libc)Error Codes.
- * ENOSYS: (libc)Error Codes.
- * ENOTBLK: (libc)Error Codes.
- * ENOTCONN: (libc)Error Codes.
- * ENOTDIR: (libc)Error Codes.
- * ENOTEMPTY: (libc)Error Codes.
- * ENOTNAM: (libc)Error Codes.
- * ENOTRECOVERABLE: (libc)Error Codes.
- * ENOTSOCK: (libc)Error Codes.
- * ENOTSUP: (libc)Error Codes.
- * ENOTTY: (libc)Error Codes.
- * ENOTUNIQ: (libc)Error Codes.
- * envz_add: (libc)Envz Functions.
- * envz_entry: (libc)Envz Functions.
- * envz_get: (libc)Envz Functions.
- * envz_merge: (libc)Envz Functions.
- * envz_remove: (libc)Envz Functions.
- * envz_strip: (libc)Envz Functions.
- * ENXIO: (libc)Error Codes.
- * EOF: (libc)EOF and Errors.
- * EOPNOTSUPP: (libc)Error Codes.
- * EOVERFLOW: (libc)Error Codes.
- * EOWNERDEAD: (libc)Error Codes.
- * EPERM: (libc)Error Codes.
- * EPFNOSUPPORT: (libc)Error Codes.
- * EPIPE: (libc)Error Codes.
- * EPROCLIM: (libc)Error Codes.
- * EPROCUNAVAIL: (libc)Error Codes.
- * EPROGMISMATCH: (libc)Error Codes.
- * EPROGUNAVAIL: (libc)Error Codes.
- * EPROTO: (libc)Error Codes.
- * EPROTONOSUPPORT: (libc)Error Codes.
- * EPROTOTYPE: (libc)Error Codes.
- * EQUIV_CLASS_MAX: (libc)Utility Limits.
- * erand48: (libc)SVID Random.
- * erand48_r: (libc)SVID Random.
- * ERANGE: (libc)Error Codes.
- * EREMCHG: (libc)Error Codes.
- * EREMOTEIO: (libc)Error Codes.
- * EREMOTE: (libc)Error Codes.
- * ERESTART: (libc)Error Codes.
- * erfcf: (libc)Special Functions.
- * erfc: (libc)Special Functions.
- * erfcl: (libc)Special Functions.
- * erff: (libc)Special Functions.
- * ERFKILL: (libc)Error Codes.
- * erf: (libc)Special Functions.
- * erfl: (libc)Special Functions.
- * EROFS: (libc)Error Codes.
- * ERPCMISMATCH: (libc)Error Codes.
- * err: (libc)Error Messages.
- * errno: (libc)Checking for Errors.
- * error_at_line: (libc)Error Messages.
- * error: (libc)Error Messages.
- * errx: (libc)Error Messages.
- * ESHUTDOWN: (libc)Error Codes.
- * ESOCKTNOSUPPORT: (libc)Error Codes.
- * ESPIPE: (libc)Error Codes.
- * ESRCH: (libc)Error Codes.
- * ESRMNT: (libc)Error Codes.
- * ESTALE: (libc)Error Codes.
- * ESTRPIPE: (libc)Error Codes.
- * ETIMEDOUT: (libc)Error Codes.
- * ETIME: (libc)Error Codes.
- * ETOOMANYREFS: (libc)Error Codes.
- * ETXTBSY: (libc)Error Codes.
- * EUCLEAN: (libc)Error Codes.
- * EUNATCH: (libc)Error Codes.
- * EUSERS: (libc)Error Codes.
- * EWOULDBLOCK: (libc)Error Codes.
- * EXDEV: (libc)Error Codes.
- * execle: (libc)Executing a File.
- * execl: (libc)Executing a File.
- * execlp: (libc)Executing a File.
- * execve: (libc)Executing a File.
- * execv: (libc)Executing a File.
- * execvp: (libc)Executing a File.
- * EXFULL: (libc)Error Codes.
- * EXIT_FAILURE: (libc)Exit Status.
- * exit: (libc)Normal Termination.
- * _exit: (libc)Termination Internals.
- * _Exit: (libc)Termination Internals.
- * EXIT_SUCCESS: (libc)Exit Status.
- * exp10f: (libc)Exponents and Logarithms.
- * exp10: (libc)Exponents and Logarithms.
- * exp10l: (libc)Exponents and Logarithms.
- * exp2f: (libc)Exponents and Logarithms.
- * exp2: (libc)Exponents and Logarithms.
- * exp2l: (libc)Exponents and Logarithms.
- * expf: (libc)Exponents and Logarithms.
- * exp: (libc)Exponents and Logarithms.
- * explicit_bzero: (libc)Erasing Sensitive Data.
- * expl: (libc)Exponents and Logarithms.
- * expm1f: (libc)Exponents and Logarithms.
- * expm1: (libc)Exponents and Logarithms.
- * expm1l: (libc)Exponents and Logarithms.
- * EXPR_NEST_MAX: (libc)Utility Limits.
- * fabsf: (libc)Absolute Value.
- * fabs: (libc)Absolute Value.
- * fabsl: (libc)Absolute Value.
- * __fbufsize: (libc)Controlling Buffering.
- * fchdir: (libc)Working Directory.
- * fchmod: (libc)Setting Permissions.
- * fchown: (libc)File Owner.
- * fcloseall: (libc)Closing Streams.
- * fclose: (libc)Closing Streams.
- * fcntl: (libc)Control Operations.
- * fcvt: (libc)System V Number Conversion.
- * fcvt_r: (libc)System V Number Conversion.
- * fdatasync: (libc)Synchronizing I/O.
- * FD_CLOEXEC: (libc)Descriptor Flags.
- * FD_CLR: (libc)Waiting for I/O.
- * fdimf: (libc)Misc FP Arithmetic.
- * fdim: (libc)Misc FP Arithmetic.
- * fdiml: (libc)Misc FP Arithmetic.
- * FD_ISSET: (libc)Waiting for I/O.
- * fdopendir: (libc)Opening a Directory.
- * fdopen: (libc)Descriptors and Streams.
- * FD_SET: (libc)Waiting for I/O.
- * FD_SETSIZE: (libc)Waiting for I/O.
- * F_DUPFD: (libc)Duplicating Descriptors.
- * FD_ZERO: (libc)Waiting for I/O.
- * feclearexcept: (libc)Status bit operations.
- * fedisableexcept: (libc)Control Functions.
- * feenableexcept: (libc)Control Functions.
- * fegetenv: (libc)Control Functions.
- * fegetexceptflag: (libc)Status bit operations.
- * fegetexcept: (libc)Control Functions.
- * fegetmode: (libc)Control Functions.
- * fegetround: (libc)Rounding.
- * feholdexcept: (libc)Control Functions.
- * feof: (libc)EOF and Errors.
- * feof_unlocked: (libc)EOF and Errors.
- * feraiseexcept: (libc)Status bit operations.
- * ferror: (libc)EOF and Errors.
- * ferror_unlocked: (libc)EOF and Errors.
- * fesetenv: (libc)Control Functions.
- * fesetexceptflag: (libc)Status bit operations.
- * fesetexcept: (libc)Status bit operations.
- * fesetmode: (libc)Control Functions.
- * fesetround: (libc)Rounding.
- * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
- * fetestexceptflag: (libc)Status bit operations.
- * fetestexcept: (libc)Status bit operations.
- * feupdateenv: (libc)Control Functions.
- * fflush: (libc)Flushing Buffers.
- * fflush_unlocked: (libc)Flushing Buffers.
- * fgetc: (libc)Character Input.
- * fgetc_unlocked: (libc)Character Input.
- * F_GETFD: (libc)Descriptor Flags.
- * F_GETFL: (libc)Getting File Status Flags.
- * fgetgrent: (libc)Scanning All Groups.
- * fgetgrent_r: (libc)Scanning All Groups.
- * F_GETLK: (libc)File Locks.
- * F_GETOWN: (libc)Interrupt Input.
- * fgetpos64: (libc)Portable Positioning.
- * fgetpos: (libc)Portable Positioning.
- * fgetpwent: (libc)Scanning All Users.
- * fgetpwent_r: (libc)Scanning All Users.
- * fgets: (libc)Line Input.
- * fgets_unlocked: (libc)Line Input.
- * fgetwc: (libc)Character Input.
- * fgetwc_unlocked: (libc)Character Input.
- * fgetws: (libc)Line Input.
- * fgetws_unlocked: (libc)Line Input.
- * FILENAME_MAX: (libc)Limits for Files.
- * fileno: (libc)Descriptors and Streams.
- * fileno_unlocked: (libc)Descriptors and Streams.
- * finitef: (libc)Floating Point Classes.
- * finite: (libc)Floating Point Classes.
- * finitel: (libc)Floating Point Classes.
- * __flbf: (libc)Controlling Buffering.
- * flockfile: (libc)Streams and Threads.
- * floorf: (libc)Rounding Functions.
- * floor: (libc)Rounding Functions.
- * floorl: (libc)Rounding Functions.
- * _flushlbf: (libc)Flushing Buffers.
- * FLUSHO: (libc)Local Modes.
- * fmaf: (libc)Misc FP Arithmetic.
- * fma: (libc)Misc FP Arithmetic.
- * fmal: (libc)Misc FP Arithmetic.
- * fmaxf: (libc)Misc FP Arithmetic.
- * fmax: (libc)Misc FP Arithmetic.
- * fmaxl: (libc)Misc FP Arithmetic.
- * fmaxmagf: (libc)Misc FP Arithmetic.
- * fmaxmag: (libc)Misc FP Arithmetic.
- * fmaxmagl: (libc)Misc FP Arithmetic.
- * fmemopen: (libc)String Streams.
- * fminf: (libc)Misc FP Arithmetic.
- * fmin: (libc)Misc FP Arithmetic.
- * fminl: (libc)Misc FP Arithmetic.
- * fminmagf: (libc)Misc FP Arithmetic.
- * fminmag: (libc)Misc FP Arithmetic.
- * fminmagl: (libc)Misc FP Arithmetic.
- * fmodf: (libc)Remainder Functions.
- * fmod: (libc)Remainder Functions.
- * fmodl: (libc)Remainder Functions.
- * fmtmsg: (libc)Printing Formatted Messages.
- * fnmatch: (libc)Wildcard Matching.
- * F_OFD_GETLK: (libc)Open File Description Locks.
- * F_OFD_SETLK: (libc)Open File Description Locks.
- * F_OFD_SETLKW: (libc)Open File Description Locks.
- * F_OK: (libc)Testing File Access.
- * fopen64: (libc)Opening Streams.
- * fopencookie: (libc)Streams and Cookies.
- * fopen: (libc)Opening Streams.
- * FOPEN_MAX: (libc)Opening Streams.
- * fork: (libc)Creating a Process.
- * forkpty: (libc)Pseudo-Terminal Pairs.
- * fpathconf: (libc)Pathconf.
- * fpclassify: (libc)Floating Point Classes.
- * __fpending: (libc)Controlling Buffering.
- * FP_ILOGB0: (libc)Exponents and Logarithms.
- * FP_ILOGBNAN: (libc)Exponents and Logarithms.
- * FP_LLOGB0: (libc)Exponents and Logarithms.
- * FP_LLOGBNAN: (libc)Exponents and Logarithms.
- * fprintf: (libc)Formatted Output Functions.
- * __fpurge: (libc)Flushing Buffers.
- * fputc: (libc)Simple Output.
- * fputc_unlocked: (libc)Simple Output.
- * fputs: (libc)Simple Output.
- * fputs_unlocked: (libc)Simple Output.
- * fputwc: (libc)Simple Output.
- * fputwc_unlocked: (libc)Simple Output.
- * fputws: (libc)Simple Output.
- * fputws_unlocked: (libc)Simple Output.
- * __freadable: (libc)Opening Streams.
- * __freading: (libc)Opening Streams.
- * fread: (libc)Block Input/Output.
- * fread_unlocked: (libc)Block Input/Output.
- * free: (libc)Freeing after Malloc.
- * freopen64: (libc)Opening Streams.
- * freopen: (libc)Opening Streams.
- * frexpf: (libc)Normalization Functions.
- * frexp: (libc)Normalization Functions.
- * frexpl: (libc)Normalization Functions.
- * fromfpf: (libc)Rounding Functions.
- * fromfp: (libc)Rounding Functions.
- * fromfpl: (libc)Rounding Functions.
- * fromfpxf: (libc)Rounding Functions.
- * fromfpx: (libc)Rounding Functions.
- * fromfpxl: (libc)Rounding Functions.
- * fscanf: (libc)Formatted Input Functions.
- * fseek: (libc)File Positioning.
- * fseeko64: (libc)File Positioning.
- * fseeko: (libc)File Positioning.
- * F_SETFD: (libc)Descriptor Flags.
- * F_SETFL: (libc)Getting File Status Flags.
- * F_SETLK: (libc)File Locks.
- * F_SETLKW: (libc)File Locks.
- * __fsetlocking: (libc)Streams and Threads.
- * F_SETOWN: (libc)Interrupt Input.
- * fsetpos64: (libc)Portable Positioning.
- * fsetpos: (libc)Portable Positioning.
- * fstat64: (libc)Reading Attributes.
- * fstat: (libc)Reading Attributes.
- * fsync: (libc)Synchronizing I/O.
- * ftell: (libc)File Positioning.
- * ftello64: (libc)File Positioning.
- * ftello: (libc)File Positioning.
- * ftruncate64: (libc)File Size.
- * ftruncate: (libc)File Size.
- * ftrylockfile: (libc)Streams and Threads.
- * ftw64: (libc)Working with Directory Trees.
- * ftw: (libc)Working with Directory Trees.
- * funlockfile: (libc)Streams and Threads.
- * futimes: (libc)File Times.
- * fwide: (libc)Streams and I18N.
- * fwprintf: (libc)Formatted Output Functions.
- * __fwritable: (libc)Opening Streams.
- * fwrite: (libc)Block Input/Output.
- * fwrite_unlocked: (libc)Block Input/Output.
- * __fwriting: (libc)Opening Streams.
- * fwscanf: (libc)Formatted Input Functions.
- * gammaf: (libc)Special Functions.
- * gamma: (libc)Special Functions.
- * gammal: (libc)Special Functions.
- * __gconv_end_fct: (libc)glibc iconv Implementation.
- * __gconv_fct: (libc)glibc iconv Implementation.
- * __gconv_init_fct: (libc)glibc iconv Implementation.
- * gcvt: (libc)System V Number Conversion.
- * getauxval: (libc)Auxiliary Vector.
- * get_avphys_pages: (libc)Query Memory Parameters.
- * getchar: (libc)Character Input.
- * getchar_unlocked: (libc)Character Input.
- * getc: (libc)Character Input.
- * getcontext: (libc)System V contexts.
- * getc_unlocked: (libc)Character Input.
- * get_current_dir_name: (libc)Working Directory.
- * getcwd: (libc)Working Directory.
- * getdate: (libc)General Time String Parsing.
- * getdate_r: (libc)General Time String Parsing.
- * getdelim: (libc)Line Input.
- * getdomainnname: (libc)Host Identification.
- * getegid: (libc)Reading Persona.
- * getentropy: (libc)Unpredictable Bytes.
- * getenv: (libc)Environment Access.
- * geteuid: (libc)Reading Persona.
- * getfsent: (libc)fstab.
- * getfsfile: (libc)fstab.
- * getfsspec: (libc)fstab.
- * getgid: (libc)Reading Persona.
- * getgrent: (libc)Scanning All Groups.
- * getgrent_r: (libc)Scanning All Groups.
- * getgrgid: (libc)Lookup Group.
- * getgrgid_r: (libc)Lookup Group.
- * getgrnam: (libc)Lookup Group.
- * getgrnam_r: (libc)Lookup Group.
- * getgrouplist: (libc)Setting Groups.
- * getgroups: (libc)Reading Persona.
- * gethostbyaddr: (libc)Host Names.
- * gethostbyaddr_r: (libc)Host Names.
- * gethostbyname2: (libc)Host Names.
- * gethostbyname2_r: (libc)Host Names.
- * gethostbyname: (libc)Host Names.
- * gethostbyname_r: (libc)Host Names.
- * gethostent: (libc)Host Names.
- * gethostid: (libc)Host Identification.
- * gethostname: (libc)Host Identification.
- * getitimer: (libc)Setting an Alarm.
- * getline: (libc)Line Input.
- * getloadavg: (libc)Processor Resources.
- * getlogin: (libc)Who Logged In.
- * getmntent: (libc)mtab.
- * getmntent_r: (libc)mtab.
- * getnetbyaddr: (libc)Networks Database.
- * getnetbyname: (libc)Networks Database.
- * getnetent: (libc)Networks Database.
- * getnetgrent: (libc)Lookup Netgroup.
- * getnetgrent_r: (libc)Lookup Netgroup.
- * get_nprocs_conf: (libc)Processor Resources.
- * get_nprocs: (libc)Processor Resources.
- * getopt: (libc)Using Getopt.
- * getopt_long: (libc)Getopt Long Options.
- * getopt_long_only: (libc)Getopt Long Options.
- * getpagesize: (libc)Query Memory Parameters.
- * getpass: (libc)getpass.
- * getpayloadf: (libc)FP Bit Twiddling.
- * getpayload: (libc)FP Bit Twiddling.
- * getpayloadl: (libc)FP Bit Twiddling.
- * getpeername: (libc)Who is Connected.
- * getpgid: (libc)Process Group Functions.
- * getpgrp: (libc)Process Group Functions.
- * get_phys_pages: (libc)Query Memory Parameters.
- * getpid: (libc)Process Identification.
- * getppid: (libc)Process Identification.
- * getpriority: (libc)Traditional Scheduling Functions.
- * getprotobyname: (libc)Protocols Database.
- * getprotobynumber: (libc)Protocols Database.
- * getprotoent: (libc)Protocols Database.
- * getpt: (libc)Allocation.
- * getpwent: (libc)Scanning All Users.
- * getpwent_r: (libc)Scanning All Users.
- * getpwnam: (libc)Lookup User.
- * getpwnam_r: (libc)Lookup User.
- * getpwuid: (libc)Lookup User.
- * getpwuid_r: (libc)Lookup User.
- * getrandom: (libc)Unpredictable Bytes.
- * getrlimit64: (libc)Limits on Resources.
- * getrlimit: (libc)Limits on Resources.
- * getrusage: (libc)Resource Usage.
- * getservbyname: (libc)Services Database.
- * getservbyport: (libc)Services Database.
- * getservent: (libc)Services Database.
- * getsid: (libc)Process Group Functions.
- * gets: (libc)Line Input.
- * getsockname: (libc)Reading Address.
- * getsockopt: (libc)Socket Option Functions.
- * getsubopt: (libc)Suboptions.
- * gettext: (libc)Translation with gettext.
- * gettimeofday: (libc)High-Resolution Calendar.
- * getuid: (libc)Reading Persona.
- * getumask: (libc)Setting Permissions.
- * getutent: (libc)Manipulating the Database.
- * getutent_r: (libc)Manipulating the Database.
- * getutid: (libc)Manipulating the Database.
- * getutid_r: (libc)Manipulating the Database.
- * getutline: (libc)Manipulating the Database.
- * getutline_r: (libc)Manipulating the Database.
- * getutmp: (libc)XPG Functions.
- * getutmpx: (libc)XPG Functions.
- * getutxent: (libc)XPG Functions.
- * getutxid: (libc)XPG Functions.
- * getutxline: (libc)XPG Functions.
- * getwchar: (libc)Character Input.
- * getwchar_unlocked: (libc)Character Input.
- * getwc: (libc)Character Input.
- * getwc_unlocked: (libc)Character Input.
- * getwd: (libc)Working Directory.
- * getw: (libc)Character Input.
- * glob64: (libc)Calling Glob.
- * globfree64: (libc)More Flags for Globbing.
- * globfree: (libc)More Flags for Globbing.
- * glob: (libc)Calling Glob.
- * gmtime: (libc)Broken-down Time.
- * gmtime_r: (libc)Broken-down Time.
- * grantpt: (libc)Allocation.
- * gsignal: (libc)Signaling Yourself.
- * gtty: (libc)BSD Terminal Modes.
- * hasmntopt: (libc)mtab.
- * hcreate: (libc)Hash Search Function.
- * hcreate_r: (libc)Hash Search Function.
- * hdestroy: (libc)Hash Search Function.
- * hdestroy_r: (libc)Hash Search Function.
- * hsearch: (libc)Hash Search Function.
- * hsearch_r: (libc)Hash Search Function.
- * htonl: (libc)Byte Order.
- * htons: (libc)Byte Order.
- * HUGE_VALF: (libc)Math Error Reporting.
- * HUGE_VAL: (libc)Math Error Reporting.
- * HUGE_VALL: (libc)Math Error Reporting.
- * HUPCL: (libc)Control Modes.
- * hypotf: (libc)Exponents and Logarithms.
- * hypot: (libc)Exponents and Logarithms.
- * hypotl: (libc)Exponents and Logarithms.
- * ICANON: (libc)Local Modes.
- * iconv_close: (libc)Generic Conversion Interface.
- * iconv: (libc)Generic Conversion Interface.
- * iconv_open: (libc)Generic Conversion Interface.
- * ICRNL: (libc)Input Modes.
- * IEXTEN: (libc)Local Modes.
- * if_freenameindex: (libc)Interface Naming.
- * if_indextoname: (libc)Interface Naming.
- * if_nameindex: (libc)Interface Naming.
- * if_nametoindex: (libc)Interface Naming.
- * IFNAMSIZ: (libc)Interface Naming.
- * IFTODT: (libc)Directory Entries.
- * IGNBRK: (libc)Input Modes.
- * IGNCR: (libc)Input Modes.
- * IGNPAR: (libc)Input Modes.
- * I: (libc)Complex Numbers.
- * ilogbf: (libc)Exponents and Logarithms.
- * ilogb: (libc)Exponents and Logarithms.
- * ilogbl: (libc)Exponents and Logarithms.
- * _Imaginary_I: (libc)Complex Numbers.
- * imaxabs: (libc)Absolute Value.
- * IMAXBEL: (libc)Input Modes.
- * imaxdiv: (libc)Integer Division.
- * in6addr_any: (libc)Host Address Data Type.
- * in6addr_loopback: (libc)Host Address Data Type.
- * INADDR_ANY: (libc)Host Address Data Type.
- * INADDR_BROADCAST: (libc)Host Address Data Type.
- * INADDR_LOOPBACK: (libc)Host Address Data Type.
- * INADDR_NONE: (libc)Host Address Data Type.
- * index: (libc)Search Functions.
- * inet_addr: (libc)Host Address Functions.
- * inet_aton: (libc)Host Address Functions.
- * inet_lnaof: (libc)Host Address Functions.
- * inet_makeaddr: (libc)Host Address Functions.
- * inet_netof: (libc)Host Address Functions.
- * inet_network: (libc)Host Address Functions.
- * inet_ntoa: (libc)Host Address Functions.
- * inet_ntop: (libc)Host Address Functions.
- * inet_pton: (libc)Host Address Functions.
- * INFINITY: (libc)Infinity and NaN.
- * initgroups: (libc)Setting Groups.
- * initstate: (libc)BSD Random.
- * initstate_r: (libc)BSD Random.
- * INLCR: (libc)Input Modes.
- * innetgr: (libc)Netgroup Membership.
- * INPCK: (libc)Input Modes.
- * ioctl: (libc)IOCTLs.
- * _IOFBF: (libc)Controlling Buffering.
- * _IOLBF: (libc)Controlling Buffering.
- * _IONBF: (libc)Controlling Buffering.
- * IPPORT_RESERVED: (libc)Ports.
- * IPPORT_USERRESERVED: (libc)Ports.
- * isalnum: (libc)Classification of Characters.
- * isalpha: (libc)Classification of Characters.
- * isascii: (libc)Classification of Characters.
- * isatty: (libc)Is It a Terminal.
- * isblank: (libc)Classification of Characters.
- * iscanonical: (libc)Floating Point Classes.
- * iscntrl: (libc)Classification of Characters.
- * isdigit: (libc)Classification of Characters.
- * iseqsig: (libc)FP Comparison Functions.
- * isfinite: (libc)Floating Point Classes.
- * isgraph: (libc)Classification of Characters.
- * isgreaterequal: (libc)FP Comparison Functions.
- * isgreater: (libc)FP Comparison Functions.
- * ISIG: (libc)Local Modes.
- * isinff: (libc)Floating Point Classes.
- * isinf: (libc)Floating Point Classes.
- * isinfl: (libc)Floating Point Classes.
- * islessequal: (libc)FP Comparison Functions.
- * islessgreater: (libc)FP Comparison Functions.
- * isless: (libc)FP Comparison Functions.
- * islower: (libc)Classification of Characters.
- * isnanf: (libc)Floating Point Classes.
- * isnan: (libc)Floating Point Classes.
- * isnan: (libc)Floating Point Classes.
- * isnanl: (libc)Floating Point Classes.
- * isnormal: (libc)Floating Point Classes.
- * isprint: (libc)Classification of Characters.
- * ispunct: (libc)Classification of Characters.
- * issignaling: (libc)Floating Point Classes.
- * isspace: (libc)Classification of Characters.
- * issubnormal: (libc)Floating Point Classes.
- * ISTRIP: (libc)Input Modes.
- * isunordered: (libc)FP Comparison Functions.
- * isupper: (libc)Classification of Characters.
- * iswalnum: (libc)Classification of Wide Characters.
- * iswalpha: (libc)Classification of Wide Characters.
- * iswblank: (libc)Classification of Wide Characters.
- * iswcntrl: (libc)Classification of Wide Characters.
- * iswctype: (libc)Classification of Wide Characters.
- * iswdigit: (libc)Classification of Wide Characters.
- * iswgraph: (libc)Classification of Wide Characters.
- * iswlower: (libc)Classification of Wide Characters.
- * iswprint: (libc)Classification of Wide Characters.
- * iswpunct: (libc)Classification of Wide Characters.
- * iswspace: (libc)Classification of Wide Characters.
- * iswupper: (libc)Classification of Wide Characters.
- * iswxdigit: (libc)Classification of Wide Characters.
- * isxdigit: (libc)Classification of Characters.
- * iszero: (libc)Floating Point Classes.
- * IXANY: (libc)Input Modes.
- * IXOFF: (libc)Input Modes.
- * IXON: (libc)Input Modes.
- * j0f: (libc)Special Functions.
- * j0: (libc)Special Functions.
- * j0l: (libc)Special Functions.
- * j1f: (libc)Special Functions.
- * j1: (libc)Special Functions.
- * j1l: (libc)Special Functions.
- * jnf: (libc)Special Functions.
- * jn: (libc)Special Functions.
- * jnl: (libc)Special Functions.
- * jrand48: (libc)SVID Random.
- * jrand48_r: (libc)SVID Random.
- * kill: (libc)Signaling Another Process.
- * killpg: (libc)Signaling Another Process.
- * l64a: (libc)Encode Binary Data.
- * labs: (libc)Absolute Value.
- * lcong48: (libc)SVID Random.
- * lcong48_r: (libc)SVID Random.
- * L_ctermid: (libc)Identifying the Terminal.
- * L_cuserid: (libc)Who Logged In.
- * ldexpf: (libc)Normalization Functions.
- * ldexp: (libc)Normalization Functions.
- * ldexpl: (libc)Normalization Functions.
- * ldiv: (libc)Integer Division.
- * lfind: (libc)Array Search Function.
- * lgammaf: (libc)Special Functions.
- * lgammaf_r: (libc)Special Functions.
- * lgamma: (libc)Special Functions.
- * lgammal: (libc)Special Functions.
- * lgammal_r: (libc)Special Functions.
- * lgamma_r: (libc)Special Functions.
- * LINE_MAX: (libc)Utility Limits.
- * link: (libc)Hard Links.
- * LINK_MAX: (libc)Limits for Files.
- * lio_listio64: (libc)Asynchronous Reads/Writes.
- * lio_listio: (libc)Asynchronous Reads/Writes.
- * listen: (libc)Listening.
- * llabs: (libc)Absolute Value.
- * lldiv: (libc)Integer Division.
- * llogbf: (libc)Exponents and Logarithms.
- * llogb: (libc)Exponents and Logarithms.
- * llogbl: (libc)Exponents and Logarithms.
- * llrintf: (libc)Rounding Functions.
- * llrint: (libc)Rounding Functions.
- * llrintl: (libc)Rounding Functions.
- * llroundf: (libc)Rounding Functions.
- * llround: (libc)Rounding Functions.
- * llroundl: (libc)Rounding Functions.
- * localeconv: (libc)The Lame Way to Locale Data.
- * localtime: (libc)Broken-down Time.
- * localtime_r: (libc)Broken-down Time.
- * log10f: (libc)Exponents and Logarithms.
- * log10: (libc)Exponents and Logarithms.
- * log10l: (libc)Exponents and Logarithms.
- * log1pf: (libc)Exponents and Logarithms.
- * log1p: (libc)Exponents and Logarithms.
- * log1pl: (libc)Exponents and Logarithms.
- * log2f: (libc)Exponents and Logarithms.
- * log2: (libc)Exponents and Logarithms.
- * log2l: (libc)Exponents and Logarithms.
- * logbf: (libc)Exponents and Logarithms.
- * logb: (libc)Exponents and Logarithms.
- * logbl: (libc)Exponents and Logarithms.
- * logf: (libc)Exponents and Logarithms.
- * login: (libc)Logging In and Out.
- * login_tty: (libc)Logging In and Out.
- * log: (libc)Exponents and Logarithms.
- * logl: (libc)Exponents and Logarithms.
- * logout: (libc)Logging In and Out.
- * logwtmp: (libc)Logging In and Out.
- * longjmp: (libc)Non-Local Details.
- * lrand48: (libc)SVID Random.
- * lrand48_r: (libc)SVID Random.
- * lrintf: (libc)Rounding Functions.
- * lrint: (libc)Rounding Functions.
- * lrintl: (libc)Rounding Functions.
- * lroundf: (libc)Rounding Functions.
- * lround: (libc)Rounding Functions.
- * lroundl: (libc)Rounding Functions.
- * lsearch: (libc)Array Search Function.
- * lseek64: (libc)File Position Primitive.
- * lseek: (libc)File Position Primitive.
- * lstat64: (libc)Reading Attributes.
- * lstat: (libc)Reading Attributes.
- * L_tmpnam: (libc)Temporary Files.
- * lutimes: (libc)File Times.
- * madvise: (libc)Memory-mapped I/O.
- * makecontext: (libc)System V contexts.
- * mallinfo: (libc)Statistics of Malloc.
- * malloc: (libc)Basic Allocation.
- * mallopt: (libc)Malloc Tunable Parameters.
- * MAX_CANON: (libc)Limits for Files.
- * MAX_INPUT: (libc)Limits for Files.
- * MAXNAMLEN: (libc)Limits for Files.
- * MAXSYMLINKS: (libc)Symbolic Links.
- * MB_CUR_MAX: (libc)Selecting the Conversion.
- * mblen: (libc)Non-reentrant Character Conversion.
- * MB_LEN_MAX: (libc)Selecting the Conversion.
- * mbrlen: (libc)Converting a Character.
- * mbrtowc: (libc)Converting a Character.
- * mbsinit: (libc)Keeping the state.
- * mbsnrtowcs: (libc)Converting Strings.
- * mbsrtowcs: (libc)Converting Strings.
- * mbstowcs: (libc)Non-reentrant String Conversion.
- * mbtowc: (libc)Non-reentrant Character Conversion.
- * mcheck: (libc)Heap Consistency Checking.
- * MDMBUF: (libc)Control Modes.
- * memalign: (libc)Aligned Memory Blocks.
- * memccpy: (libc)Copying Strings and Arrays.
- * memchr: (libc)Search Functions.
- * memcmp: (libc)String/Array Comparison.
- * memcpy: (libc)Copying Strings and Arrays.
- * memfrob: (libc)Trivial Encryption.
- * memmem: (libc)Search Functions.
- * memmove: (libc)Copying Strings and Arrays.
- * mempcpy: (libc)Copying Strings and Arrays.
- * memrchr: (libc)Search Functions.
- * memset: (libc)Copying Strings and Arrays.
- * mkdir: (libc)Creating Directories.
- * mkdtemp: (libc)Temporary Files.
- * mkfifo: (libc)FIFO Special Files.
- * mknod: (libc)Making Special Files.
- * mkstemp: (libc)Temporary Files.
- * mktemp: (libc)Temporary Files.
- * mktime: (libc)Broken-down Time.
- * mlockall: (libc)Page Lock Functions.
- * mlock: (libc)Page Lock Functions.
- * mmap64: (libc)Memory-mapped I/O.
- * mmap: (libc)Memory-mapped I/O.
- * modff: (libc)Rounding Functions.
- * modf: (libc)Rounding Functions.
- * modfl: (libc)Rounding Functions.
- * mount: (libc)Mount-Unmount-Remount.
- * mprobe: (libc)Heap Consistency Checking.
- * mrand48: (libc)SVID Random.
- * mrand48_r: (libc)SVID Random.
- * mremap: (libc)Memory-mapped I/O.
- * MSG_DONTROUTE: (libc)Socket Data Options.
- * MSG_OOB: (libc)Socket Data Options.
- * MSG_PEEK: (libc)Socket Data Options.
- * msync: (libc)Memory-mapped I/O.
- * mtrace: (libc)Tracing malloc.
- * munlockall: (libc)Page Lock Functions.
- * munlock: (libc)Page Lock Functions.
- * munmap: (libc)Memory-mapped I/O.
- * muntrace: (libc)Tracing malloc.
- * NAME_MAX: (libc)Limits for Files.
- * nanf: (libc)FP Bit Twiddling.
- * nan: (libc)FP Bit Twiddling.
- * NAN: (libc)Infinity and NaN.
- * nanl: (libc)FP Bit Twiddling.
- * nanosleep: (libc)Sleeping.
- * NCCS: (libc)Mode Data Types.
- * nearbyintf: (libc)Rounding Functions.
- * nearbyint: (libc)Rounding Functions.
- * nearbyintl: (libc)Rounding Functions.
- * nextafterf: (libc)FP Bit Twiddling.
- * nextafter: (libc)FP Bit Twiddling.
- * nextafterl: (libc)FP Bit Twiddling.
- * nextdownf: (libc)FP Bit Twiddling.
- * nextdown: (libc)FP Bit Twiddling.
- * nextdownl: (libc)FP Bit Twiddling.
- * nexttowardf: (libc)FP Bit Twiddling.
- * nexttoward: (libc)FP Bit Twiddling.
- * nexttowardl: (libc)FP Bit Twiddling.
- * nextupf: (libc)FP Bit Twiddling.
- * nextup: (libc)FP Bit Twiddling.
- * nextupl: (libc)FP Bit Twiddling.
- * nftw64: (libc)Working with Directory Trees.
- * nftw: (libc)Working with Directory Trees.
- * ngettext: (libc)Advanced gettext functions.
- * NGROUPS_MAX: (libc)General Limits.
- * nice: (libc)Traditional Scheduling Functions.
- * nl_langinfo: (libc)The Elegant and Fast Way.
- * NOFLSH: (libc)Local Modes.
- * NOKERNINFO: (libc)Local Modes.
- * nrand48: (libc)SVID Random.
- * nrand48_r: (libc)SVID Random.
- * NSIG: (libc)Standard Signals.
- * ntohl: (libc)Byte Order.
- * ntohs: (libc)Byte Order.
- * ntp_adjtime: (libc)High Accuracy Clock.
- * ntp_gettime: (libc)High Accuracy Clock.
- * NULL: (libc)Null Pointer Constant.
- * O_ACCMODE: (libc)Access Modes.
- * O_APPEND: (libc)Operating Modes.
- * O_ASYNC: (libc)Operating Modes.
- * obstack_1grow_fast: (libc)Extra Fast Growing.
- * obstack_1grow: (libc)Growing Objects.
- * obstack_alignment_mask: (libc)Obstacks Data Alignment.
- * obstack_alloc: (libc)Allocation in an Obstack.
- * obstack_base: (libc)Status of an Obstack.
- * obstack_blank_fast: (libc)Extra Fast Growing.
- * obstack_blank: (libc)Growing Objects.
- * obstack_chunk_size: (libc)Obstack Chunks.
- * obstack_copy0: (libc)Allocation in an Obstack.
- * obstack_copy: (libc)Allocation in an Obstack.
- * obstack_finish: (libc)Growing Objects.
- * obstack_free: (libc)Freeing Obstack Objects.
- * obstack_grow0: (libc)Growing Objects.
- * obstack_grow: (libc)Growing Objects.
- * obstack_init: (libc)Preparing for Obstacks.
- * obstack_int_grow_fast: (libc)Extra Fast Growing.
- * obstack_int_grow: (libc)Growing Objects.
- * obstack_next_free: (libc)Status of an Obstack.
- * obstack_object_size: (libc)Growing Objects.
- * obstack_object_size: (libc)Status of an Obstack.
- * obstack_printf: (libc)Dynamic Output.
- * obstack_ptr_grow_fast: (libc)Extra Fast Growing.
- * obstack_ptr_grow: (libc)Growing Objects.
- * obstack_room: (libc)Extra Fast Growing.
- * obstack_vprintf: (libc)Variable Arguments Output.
- * O_CREAT: (libc)Open-time Flags.
- * O_EXCL: (libc)Open-time Flags.
- * O_EXEC: (libc)Access Modes.
- * O_EXLOCK: (libc)Open-time Flags.
- * offsetof: (libc)Structure Measurement.
- * O_FSYNC: (libc)Operating Modes.
- * O_IGNORE_CTTY: (libc)Open-time Flags.
- * O_NDELAY: (libc)Operating Modes.
- * on_exit: (libc)Cleanups on Exit.
- * ONLCR: (libc)Output Modes.
- * O_NOATIME: (libc)Operating Modes.
- * O_NOCTTY: (libc)Open-time Flags.
- * ONOEOT: (libc)Output Modes.
- * O_NOLINK: (libc)Open-time Flags.
- * O_NONBLOCK: (libc)Open-time Flags.
- * O_NONBLOCK: (libc)Operating Modes.
- * O_NOTRANS: (libc)Open-time Flags.
- * open64: (libc)Opening and Closing Files.
- * opendir: (libc)Opening a Directory.
- * open: (libc)Opening and Closing Files.
- * openlog: (libc)openlog.
- * OPEN_MAX: (libc)General Limits.
- * open_memstream: (libc)String Streams.
- * openpty: (libc)Pseudo-Terminal Pairs.
- * OPOST: (libc)Output Modes.
- * O_RDONLY: (libc)Access Modes.
- * O_RDWR: (libc)Access Modes.
- * O_READ: (libc)Access Modes.
- * O_SHLOCK: (libc)Open-time Flags.
- * O_SYNC: (libc)Operating Modes.
- * O_TRUNC: (libc)Open-time Flags.
- * O_WRITE: (libc)Access Modes.
- * O_WRONLY: (libc)Access Modes.
- * OXTABS: (libc)Output Modes.
- * PA_FLAG_MASK: (libc)Parsing a Template String.
- * PARENB: (libc)Control Modes.
- * PARMRK: (libc)Input Modes.
- * PARODD: (libc)Control Modes.
- * parse_printf_format: (libc)Parsing a Template String.
- * pathconf: (libc)Pathconf.
- * PATH_MAX: (libc)Limits for Files.
- * _PATH_UTMP: (libc)Manipulating the Database.
- * _PATH_WTMP: (libc)Manipulating the Database.
- * pause: (libc)Using Pause.
- * pclose: (libc)Pipe to a Subprocess.
- * PENDIN: (libc)Local Modes.
- * perror: (libc)Error Messages.
- * PF_FILE: (libc)Local Namespace Details.
- * PF_INET6: (libc)Internet Namespace.
- * PF_INET: (libc)Internet Namespace.
- * PF_LOCAL: (libc)Local Namespace Details.
- * PF_UNIX: (libc)Local Namespace Details.
- * PIPE_BUF: (libc)Limits for Files.
- * pipe: (libc)Creating a Pipe.
- * popen: (libc)Pipe to a Subprocess.
- * _POSIX2_C_DEV: (libc)System Options.
- * _POSIX2_C_VERSION: (libc)Version Supported.
- * _POSIX2_FORT_DEV: (libc)System Options.
- * _POSIX2_FORT_RUN: (libc)System Options.
- * _POSIX2_LOCALEDEF: (libc)System Options.
- * _POSIX2_SW_DEV: (libc)System Options.
- * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
- * posix_fallocate64: (libc)Storage Allocation.
- * posix_fallocate: (libc)Storage Allocation.
- * _POSIX_JOB_CONTROL: (libc)System Options.
- * posix_memalign: (libc)Aligned Memory Blocks.
- * _POSIX_NO_TRUNC: (libc)Options for Files.
- * _POSIX_SAVED_IDS: (libc)System Options.
- * _POSIX_VDISABLE: (libc)Options for Files.
- * _POSIX_VERSION: (libc)Version Supported.
- * pow10f: (libc)Exponents and Logarithms.
- * pow10: (libc)Exponents and Logarithms.
- * pow10l: (libc)Exponents and Logarithms.
- * powf: (libc)Exponents and Logarithms.
- * pow: (libc)Exponents and Logarithms.
- * powl: (libc)Exponents and Logarithms.
- * __ppc_get_timebase_freq: (libc)PowerPC.
- * __ppc_get_timebase: (libc)PowerPC.
- * __ppc_mdoio: (libc)PowerPC.
- * __ppc_mdoom: (libc)PowerPC.
- * __ppc_set_ppr_low: (libc)PowerPC.
- * __ppc_set_ppr_med_high: (libc)PowerPC.
- * __ppc_set_ppr_med: (libc)PowerPC.
- * __ppc_set_ppr_med_low: (libc)PowerPC.
- * __ppc_set_ppr_very_low: (libc)PowerPC.
- * __ppc_yield: (libc)PowerPC.
- * pread64: (libc)I/O Primitives.
- * pread: (libc)I/O Primitives.
- * printf: (libc)Formatted Output Functions.
- * printf_size_info: (libc)Predefined Printf Handlers.
- * printf_size: (libc)Predefined Printf Handlers.
- * psignal: (libc)Signal Messages.
- * pthread_getattr_default_np: (libc)Default Thread Attributes.
- * pthread_getspecific: (libc)Thread-specific Data.
- * pthread_key_create: (libc)Thread-specific Data.
- * pthread_key_delete: (libc)Thread-specific Data.
- * pthread_setattr_default_np: (libc)Default Thread Attributes.
- * pthread_setspecific: (libc)Thread-specific Data.
- * P_tmpdir: (libc)Temporary Files.
- * ptsname: (libc)Allocation.
- * ptsname_r: (libc)Allocation.
- * putchar: (libc)Simple Output.
- * putchar_unlocked: (libc)Simple Output.
- * putc: (libc)Simple Output.
- * putc_unlocked: (libc)Simple Output.
- * putenv: (libc)Environment Access.
- * putpwent: (libc)Writing a User Entry.
- * puts: (libc)Simple Output.
- * pututline: (libc)Manipulating the Database.
- * pututxline: (libc)XPG Functions.
- * putwchar: (libc)Simple Output.
- * putwchar_unlocked: (libc)Simple Output.
- * putwc: (libc)Simple Output.
- * putwc_unlocked: (libc)Simple Output.
- * putw: (libc)Simple Output.
- * pwrite64: (libc)I/O Primitives.
- * pwrite: (libc)I/O Primitives.
- * qecvt: (libc)System V Number Conversion.
- * qecvt_r: (libc)System V Number Conversion.
- * qfcvt: (libc)System V Number Conversion.
- * qfcvt_r: (libc)System V Number Conversion.
- * qgcvt: (libc)System V Number Conversion.
- * qsort: (libc)Array Sort Function.
- * raise: (libc)Signaling Yourself.
- * rand: (libc)ISO Random.
- * RAND_MAX: (libc)ISO Random.
- * random: (libc)BSD Random.
- * random_r: (libc)BSD Random.
- * rand_r: (libc)ISO Random.
- * rawmemchr: (libc)Search Functions.
- * readdir64: (libc)Reading/Closing Directory.
- * readdir64_r: (libc)Reading/Closing Directory.
- * readdir: (libc)Reading/Closing Directory.
- * readdir_r: (libc)Reading/Closing Directory.
- * read: (libc)I/O Primitives.
- * readlink: (libc)Symbolic Links.
- * readv: (libc)Scatter-Gather.
- * realloc: (libc)Changing Block Size.
- * realpath: (libc)Symbolic Links.
- * recvfrom: (libc)Receiving Datagrams.
- * recv: (libc)Receiving Data.
- * recvmsg: (libc)Receiving Datagrams.
- * RE_DUP_MAX: (libc)General Limits.
- * regcomp: (libc)POSIX Regexp Compilation.
- * regerror: (libc)Regexp Cleanup.
- * regexec: (libc)Matching POSIX Regexps.
- * regfree: (libc)Regexp Cleanup.
- * register_printf_function: (libc)Registering New Conversions.
- * remainderf: (libc)Remainder Functions.
- * remainder: (libc)Remainder Functions.
- * remainderl: (libc)Remainder Functions.
- * remove: (libc)Deleting Files.
- * rename: (libc)Renaming Files.
- * rewinddir: (libc)Random Access Directory.
- * rewind: (libc)File Positioning.
- * rindex: (libc)Search Functions.
- * rintf: (libc)Rounding Functions.
- * rint: (libc)Rounding Functions.
- * rintl: (libc)Rounding Functions.
- * RLIM_INFINITY: (libc)Limits on Resources.
- * rmdir: (libc)Deleting Files.
- * R_OK: (libc)Testing File Access.
- * roundevenf: (libc)Rounding Functions.
- * roundeven: (libc)Rounding Functions.
- * roundevenl: (libc)Rounding Functions.
- * roundf: (libc)Rounding Functions.
- * round: (libc)Rounding Functions.
- * roundl: (libc)Rounding Functions.
- * rpmatch: (libc)Yes-or-No Questions.
- * SA_NOCLDSTOP: (libc)Flags for Sigaction.
- * SA_ONSTACK: (libc)Flags for Sigaction.
- * SA_RESTART: (libc)Flags for Sigaction.
- * sbrk: (libc)Resizing the Data Segment.
- * scalbf: (libc)Normalization Functions.
- * scalb: (libc)Normalization Functions.
- * scalbl: (libc)Normalization Functions.
- * scalblnf: (libc)Normalization Functions.
- * scalbln: (libc)Normalization Functions.
- * scalblnl: (libc)Normalization Functions.
- * scalbnf: (libc)Normalization Functions.
- * scalbn: (libc)Normalization Functions.
- * scalbnl: (libc)Normalization Functions.
- * scandir64: (libc)Scanning Directory Content.
- * scandir: (libc)Scanning Directory Content.
- * scanf: (libc)Formatted Input Functions.
- * sched_getaffinity: (libc)CPU Affinity.
- * sched_getparam: (libc)Basic Scheduling Functions.
- * sched_get_priority_max: (libc)Basic Scheduling Functions.
- * sched_get_priority_min: (libc)Basic Scheduling Functions.
- * sched_getscheduler: (libc)Basic Scheduling Functions.
- * sched_rr_get_interval: (libc)Basic Scheduling Functions.
- * sched_setaffinity: (libc)CPU Affinity.
- * sched_setparam: (libc)Basic Scheduling Functions.
- * sched_setscheduler: (libc)Basic Scheduling Functions.
- * sched_yield: (libc)Basic Scheduling Functions.
- * secure_getenv: (libc)Environment Access.
- * seed48: (libc)SVID Random.
- * seed48_r: (libc)SVID Random.
- * SEEK_CUR: (libc)File Positioning.
- * seekdir: (libc)Random Access Directory.
- * SEEK_END: (libc)File Positioning.
- * SEEK_SET: (libc)File Positioning.
- * select: (libc)Waiting for I/O.
- * sem_close: (libc)Semaphores.
- * semctl: (libc)Semaphores.
- * sem_destroy: (libc)Semaphores.
- * semget: (libc)Semaphores.
- * sem_getvalue: (libc)Semaphores.
- * sem_init: (libc)Semaphores.
- * sem_open: (libc)Semaphores.
- * semop: (libc)Semaphores.
- * sem_post: (libc)Semaphores.
- * semtimedop: (libc)Semaphores.
- * sem_timedwait: (libc)Semaphores.
- * sem_trywait: (libc)Semaphores.
- * sem_unlink: (libc)Semaphores.
- * sem_wait: (libc)Semaphores.
- * send: (libc)Sending Data.
- * sendmsg: (libc)Receiving Datagrams.
- * sendto: (libc)Sending Datagrams.
- * setbuffer: (libc)Controlling Buffering.
- * setbuf: (libc)Controlling Buffering.
- * setcontext: (libc)System V contexts.
- * setdomainname: (libc)Host Identification.
- * setegid: (libc)Setting Groups.
- * setenv: (libc)Environment Access.
- * seteuid: (libc)Setting User ID.
- * setfsent: (libc)fstab.
- * setgid: (libc)Setting Groups.
- * setgrent: (libc)Scanning All Groups.
- * setgroups: (libc)Setting Groups.
- * sethostent: (libc)Host Names.
- * sethostid: (libc)Host Identification.
- * sethostname: (libc)Host Identification.
- * setitimer: (libc)Setting an Alarm.
- * setjmp: (libc)Non-Local Details.
- * setkey: (libc)DES Encryption.
- * setkey_r: (libc)DES Encryption.
- * setlinebuf: (libc)Controlling Buffering.
- * setlocale: (libc)Setting the Locale.
- * setlogmask: (libc)setlogmask.
- * setmntent: (libc)mtab.
- * setnetent: (libc)Networks Database.
- * setnetgrent: (libc)Lookup Netgroup.
- * setpayloadf: (libc)FP Bit Twiddling.
- * setpayload: (libc)FP Bit Twiddling.
- * setpayloadl: (libc)FP Bit Twiddling.
- * setpayloadsigf: (libc)FP Bit Twiddling.
- * setpayloadsig: (libc)FP Bit Twiddling.
- * setpayloadsigl: (libc)FP Bit Twiddling.
- * setpgid: (libc)Process Group Functions.
- * setpgrp: (libc)Process Group Functions.
- * setpriority: (libc)Traditional Scheduling Functions.
- * setprotoent: (libc)Protocols Database.
- * setpwent: (libc)Scanning All Users.
- * setregid: (libc)Setting Groups.
- * setreuid: (libc)Setting User ID.
- * setrlimit64: (libc)Limits on Resources.
- * setrlimit: (libc)Limits on Resources.
- * setservent: (libc)Services Database.
- * setsid: (libc)Process Group Functions.
- * setsockopt: (libc)Socket Option Functions.
- * setstate: (libc)BSD Random.
- * setstate_r: (libc)BSD Random.
- * settimeofday: (libc)High-Resolution Calendar.
- * setuid: (libc)Setting User ID.
- * setutent: (libc)Manipulating the Database.
- * setutxent: (libc)XPG Functions.
- * setvbuf: (libc)Controlling Buffering.
- * shm_open: (libc)Memory-mapped I/O.
- * shm_unlink: (libc)Memory-mapped I/O.
- * shutdown: (libc)Closing a Socket.
- * S_IFMT: (libc)Testing File Type.
- * SIGABRT: (libc)Program Error Signals.
- * sigaction: (libc)Advanced Signal Handling.
- * sigaddset: (libc)Signal Sets.
- * SIGALRM: (libc)Alarm Signals.
- * sigaltstack: (libc)Signal Stack.
- * sigblock: (libc)BSD Signal Handling.
- * SIGBUS: (libc)Program Error Signals.
- * SIGCHLD: (libc)Job Control Signals.
- * SIGCLD: (libc)Job Control Signals.
- * SIGCONT: (libc)Job Control Signals.
- * sigdelset: (libc)Signal Sets.
- * sigemptyset: (libc)Signal Sets.
- * SIGEMT: (libc)Program Error Signals.
- * SIG_ERR: (libc)Basic Signal Handling.
- * sigfillset: (libc)Signal Sets.
- * SIGFPE: (libc)Program Error Signals.
- * SIGHUP: (libc)Termination Signals.
- * SIGILL: (libc)Program Error Signals.
- * SIGINFO: (libc)Miscellaneous Signals.
- * siginterrupt: (libc)BSD Signal Handling.
- * SIGINT: (libc)Termination Signals.
- * SIGIO: (libc)Asynchronous I/O Signals.
- * SIGIOT: (libc)Program Error Signals.
- * sigismember: (libc)Signal Sets.
- * SIGKILL: (libc)Termination Signals.
- * siglongjmp: (libc)Non-Local Exits and Signals.
- * SIGLOST: (libc)Operation Error Signals.
- * sigmask: (libc)BSD Signal Handling.
- * signal: (libc)Basic Signal Handling.
- * signbit: (libc)FP Bit Twiddling.
- * significandf: (libc)Normalization Functions.
- * significand: (libc)Normalization Functions.
- * significandl: (libc)Normalization Functions.
- * sigpause: (libc)BSD Signal Handling.
- * sigpending: (libc)Checking for Pending Signals.
- * SIGPIPE: (libc)Operation Error Signals.
- * SIGPOLL: (libc)Asynchronous I/O Signals.
- * sigprocmask: (libc)Process Signal Mask.
- * SIGPROF: (libc)Alarm Signals.
- * SIGQUIT: (libc)Termination Signals.
- * SIGSEGV: (libc)Program Error Signals.
- * sigsetjmp: (libc)Non-Local Exits and Signals.
- * sigsetmask: (libc)BSD Signal Handling.
- * sigstack: (libc)Signal Stack.
- * SIGSTOP: (libc)Job Control Signals.
- * sigsuspend: (libc)Sigsuspend.
- * SIGSYS: (libc)Program Error Signals.
- * SIGTERM: (libc)Termination Signals.
- * SIGTRAP: (libc)Program Error Signals.
- * SIGTSTP: (libc)Job Control Signals.
- * SIGTTIN: (libc)Job Control Signals.
- * SIGTTOU: (libc)Job Control Signals.
- * SIGURG: (libc)Asynchronous I/O Signals.
- * SIGUSR1: (libc)Miscellaneous Signals.
- * SIGUSR2: (libc)Miscellaneous Signals.
- * SIGVTALRM: (libc)Alarm Signals.
- * SIGWINCH: (libc)Miscellaneous Signals.
- * SIGXCPU: (libc)Operation Error Signals.
- * SIGXFSZ: (libc)Operation Error Signals.
- * sincosf: (libc)Trig Functions.
- * sincos: (libc)Trig Functions.
- * sincosl: (libc)Trig Functions.
- * sinf: (libc)Trig Functions.
- * sinhf: (libc)Hyperbolic Functions.
- * sinh: (libc)Hyperbolic Functions.
- * sinhl: (libc)Hyperbolic Functions.
- * sin: (libc)Trig Functions.
- * sinl: (libc)Trig Functions.
- * S_ISBLK: (libc)Testing File Type.
- * S_ISCHR: (libc)Testing File Type.
- * S_ISDIR: (libc)Testing File Type.
- * S_ISFIFO: (libc)Testing File Type.
- * S_ISLNK: (libc)Testing File Type.
- * S_ISREG: (libc)Testing File Type.
- * S_ISSOCK: (libc)Testing File Type.
- * sleep: (libc)Sleeping.
- * SNANF: (libc)Infinity and NaN.
- * SNAN: (libc)Infinity and NaN.
- * SNANL: (libc)Infinity and NaN.
- * snprintf: (libc)Formatted Output Functions.
- * SOCK_DGRAM: (libc)Communication Styles.
- * socket: (libc)Creating a Socket.
- * socketpair: (libc)Socket Pairs.
- * SOCK_RAW: (libc)Communication Styles.
- * SOCK_RDM: (libc)Communication Styles.
- * SOCK_SEQPACKET: (libc)Communication Styles.
- * SOCK_STREAM: (libc)Communication Styles.
- * SOL_SOCKET: (libc)Socket-Level Options.
- * sprintf: (libc)Formatted Output Functions.
- * sqrtf: (libc)Exponents and Logarithms.
- * sqrt: (libc)Exponents and Logarithms.
- * sqrtl: (libc)Exponents and Logarithms.
- * srand48: (libc)SVID Random.
- * srand48_r: (libc)SVID Random.
- * srand: (libc)ISO Random.
- * srandom: (libc)BSD Random.
- * srandom_r: (libc)BSD Random.
- * sscanf: (libc)Formatted Input Functions.
- * ssignal: (libc)Basic Signal Handling.
- * SSIZE_MAX: (libc)General Limits.
- * stat64: (libc)Reading Attributes.
- * stat: (libc)Reading Attributes.
- * stime: (libc)Simple Calendar Time.
- * stpcpy: (libc)Copying Strings and Arrays.
- * stpncpy: (libc)Truncating Strings.
- * strcasecmp: (libc)String/Array Comparison.
- * strcasestr: (libc)Search Functions.
- * strcat: (libc)Concatenating Strings.
- * strchr: (libc)Search Functions.
- * strchrnul: (libc)Search Functions.
- * strcmp: (libc)String/Array Comparison.
- * strcoll: (libc)Collation Functions.
- * strcpy: (libc)Copying Strings and Arrays.
- * strcspn: (libc)Search Functions.
- * strdupa: (libc)Copying Strings and Arrays.
- * strdup: (libc)Copying Strings and Arrays.
- * STREAM_MAX: (libc)General Limits.
- * strerror: (libc)Error Messages.
- * strerror_r: (libc)Error Messages.
- * strfmon: (libc)Formatting Numbers.
- * strfromd: (libc)Printing of Floats.
- * strfromf: (libc)Printing of Floats.
- * strfroml: (libc)Printing of Floats.
- * strfry: (libc)strfry.
- * strftime: (libc)Formatting Calendar Time.
- * strlen: (libc)String Length.
- * strncasecmp: (libc)String/Array Comparison.
- * strncat: (libc)Truncating Strings.
- * strncmp: (libc)String/Array Comparison.
- * strncpy: (libc)Truncating Strings.
- * strndupa: (libc)Truncating Strings.
- * strndup: (libc)Truncating Strings.
- * strnlen: (libc)String Length.
- * strpbrk: (libc)Search Functions.
- * strptime: (libc)Low-Level Time String Parsing.
- * strrchr: (libc)Search Functions.
- * strsep: (libc)Finding Tokens in a String.
- * strsignal: (libc)Signal Messages.
- * strspn: (libc)Search Functions.
- * strstr: (libc)Search Functions.
- * strtod: (libc)Parsing of Floats.
- * strtof: (libc)Parsing of Floats.
- * strtoimax: (libc)Parsing of Integers.
- * strtok: (libc)Finding Tokens in a String.
- * strtok_r: (libc)Finding Tokens in a String.
- * strtold: (libc)Parsing of Floats.
- * strtol: (libc)Parsing of Integers.
- * strtoll: (libc)Parsing of Integers.
- * strtoq: (libc)Parsing of Integers.
- * strtoul: (libc)Parsing of Integers.
- * strtoull: (libc)Parsing of Integers.
- * strtoumax: (libc)Parsing of Integers.
- * strtouq: (libc)Parsing of Integers.
- * strverscmp: (libc)String/Array Comparison.
- * strxfrm: (libc)Collation Functions.
- * stty: (libc)BSD Terminal Modes.
- * S_TYPEISMQ: (libc)Testing File Type.
- * S_TYPEISSEM: (libc)Testing File Type.
- * S_TYPEISSHM: (libc)Testing File Type.
- * SUN_LEN: (libc)Local Namespace Details.
- * swapcontext: (libc)System V contexts.
- * swprintf: (libc)Formatted Output Functions.
- * swscanf: (libc)Formatted Input Functions.
- * symlink: (libc)Symbolic Links.
- * sync: (libc)Synchronizing I/O.
- * syscall: (libc)System Calls.
- * sysconf: (libc)Sysconf Definition.
- * sysctl: (libc)System Parameters.
- * syslog: (libc)syslog; vsyslog.
- * system: (libc)Running a Command.
- * sysv_signal: (libc)Basic Signal Handling.
- * tanf: (libc)Trig Functions.
- * tanhf: (libc)Hyperbolic Functions.
- * tanh: (libc)Hyperbolic Functions.
- * tanhl: (libc)Hyperbolic Functions.
- * tan: (libc)Trig Functions.
- * tanl: (libc)Trig Functions.
- * tcdrain: (libc)Line Control.
- * tcflow: (libc)Line Control.
- * tcflush: (libc)Line Control.
- * tcgetattr: (libc)Mode Functions.
- * tcgetpgrp: (libc)Terminal Access Functions.
- * tcgetsid: (libc)Terminal Access Functions.
- * tcsendbreak: (libc)Line Control.
- * tcsetattr: (libc)Mode Functions.
- * tcsetpgrp: (libc)Terminal Access Functions.
- * tdelete: (libc)Tree Search Function.
- * tdestroy: (libc)Tree Search Function.
- * telldir: (libc)Random Access Directory.
- * tempnam: (libc)Temporary Files.
- * textdomain: (libc)Locating gettext catalog.
- * tfind: (libc)Tree Search Function.
- * tgammaf: (libc)Special Functions.
- * tgamma: (libc)Special Functions.
- * tgammal: (libc)Special Functions.
- * timegm: (libc)Broken-down Time.
- * time: (libc)Simple Calendar Time.
- * timelocal: (libc)Broken-down Time.
- * times: (libc)Processor Time.
- * tmpfile64: (libc)Temporary Files.
- * tmpfile: (libc)Temporary Files.
- * TMP_MAX: (libc)Temporary Files.
- * tmpnam: (libc)Temporary Files.
- * tmpnam_r: (libc)Temporary Files.
- * toascii: (libc)Case Conversion.
- * _tolower: (libc)Case Conversion.
- * tolower: (libc)Case Conversion.
- * TOSTOP: (libc)Local Modes.
- * totalorderf: (libc)FP Comparison Functions.
- * totalorder: (libc)FP Comparison Functions.
- * totalorderl: (libc)FP Comparison Functions.
- * totalordermagf: (libc)FP Comparison Functions.
- * totalordermag: (libc)FP Comparison Functions.
- * totalordermagl: (libc)FP Comparison Functions.
- * _toupper: (libc)Case Conversion.
- * toupper: (libc)Case Conversion.
- * towctrans: (libc)Wide Character Case Conversion.
- * towlower: (libc)Wide Character Case Conversion.
- * towupper: (libc)Wide Character Case Conversion.
- * truncate64: (libc)File Size.
- * truncate: (libc)File Size.
- * truncf: (libc)Rounding Functions.
- * trunc: (libc)Rounding Functions.
- * truncl: (libc)Rounding Functions.
- * tsearch: (libc)Tree Search Function.
- * ttyname: (libc)Is It a Terminal.
- * ttyname_r: (libc)Is It a Terminal.
- * twalk: (libc)Tree Search Function.
- * TZNAME_MAX: (libc)General Limits.
- * tzset: (libc)Time Zone Functions.
- * ufromfpf: (libc)Rounding Functions.
- * ufromfp: (libc)Rounding Functions.
- * ufromfpl: (libc)Rounding Functions.
- * ufromfpxf: (libc)Rounding Functions.
- * ufromfpx: (libc)Rounding Functions.
- * ufromfpxl: (libc)Rounding Functions.
- * ulimit: (libc)Limits on Resources.
- * umask: (libc)Setting Permissions.
- * umount2: (libc)Mount-Unmount-Remount.
- * umount: (libc)Mount-Unmount-Remount.
- * uname: (libc)Platform Type.
- * ungetc: (libc)How Unread.
- * ungetwc: (libc)How Unread.
- * unlink: (libc)Deleting Files.
- * unlockpt: (libc)Allocation.
- * unsetenv: (libc)Environment Access.
- * updwtmp: (libc)Manipulating the Database.
- * utime: (libc)File Times.
- * utimes: (libc)File Times.
- * utmpname: (libc)Manipulating the Database.
- * utmpxname: (libc)XPG Functions.
- * va_arg: (libc)Argument Macros.
- * __va_copy: (libc)Argument Macros.
- * va_copy: (libc)Argument Macros.
- * va_end: (libc)Argument Macros.
- * valloc: (libc)Aligned Memory Blocks.
- * vasprintf: (libc)Variable Arguments Output.
- * va_start: (libc)Argument Macros.
- * VDISCARD: (libc)Other Special.
- * VDSUSP: (libc)Signal Characters.
- * VEOF: (libc)Editing Characters.
- * VEOL2: (libc)Editing Characters.
- * VEOL: (libc)Editing Characters.
- * VERASE: (libc)Editing Characters.
- * verr: (libc)Error Messages.
- * verrx: (libc)Error Messages.
- * versionsort64: (libc)Scanning Directory Content.
- * versionsort: (libc)Scanning Directory Content.
- * vfork: (libc)Creating a Process.
- * vfprintf: (libc)Variable Arguments Output.
- * vfscanf: (libc)Variable Arguments Input.
- * vfwprintf: (libc)Variable Arguments Output.
- * vfwscanf: (libc)Variable Arguments Input.
- * VINTR: (libc)Signal Characters.
- * VKILL: (libc)Editing Characters.
- * vlimit: (libc)Limits on Resources.
- * VLNEXT: (libc)Other Special.
- * VMIN: (libc)Noncanonical Input.
- * vprintf: (libc)Variable Arguments Output.
- * VQUIT: (libc)Signal Characters.
- * VREPRINT: (libc)Editing Characters.
- * vscanf: (libc)Variable Arguments Input.
- * vsnprintf: (libc)Variable Arguments Output.
- * vsprintf: (libc)Variable Arguments Output.
- * vsscanf: (libc)Variable Arguments Input.
- * VSTART: (libc)Start/Stop Characters.
- * VSTATUS: (libc)Other Special.
- * VSTOP: (libc)Start/Stop Characters.
- * VSUSP: (libc)Signal Characters.
- * vswprintf: (libc)Variable Arguments Output.
- * vswscanf: (libc)Variable Arguments Input.
- * vsyslog: (libc)syslog; vsyslog.
- * VTIME: (libc)Noncanonical Input.
- * vtimes: (libc)Resource Usage.
- * vwarn: (libc)Error Messages.
- * vwarnx: (libc)Error Messages.
- * VWERASE: (libc)Editing Characters.
- * vwprintf: (libc)Variable Arguments Output.
- * vwscanf: (libc)Variable Arguments Input.
- * wait3: (libc)BSD Wait Functions.
- * wait4: (libc)Process Completion.
- * wait: (libc)Process Completion.
- * waitpid: (libc)Process Completion.
- * warn: (libc)Error Messages.
- * warnx: (libc)Error Messages.
- * WCHAR_MAX: (libc)Extended Char Intro.
- * WCHAR_MIN: (libc)Extended Char Intro.
- * WCOREDUMP: (libc)Process Completion Status.
- * wcpcpy: (libc)Copying Strings and Arrays.
- * wcpncpy: (libc)Truncating Strings.
- * wcrtomb: (libc)Converting a Character.
- * wcscasecmp: (libc)String/Array Comparison.
- * wcscat: (libc)Concatenating Strings.
- * wcschr: (libc)Search Functions.
- * wcschrnul: (libc)Search Functions.
- * wcscmp: (libc)String/Array Comparison.
- * wcscoll: (libc)Collation Functions.
- * wcscpy: (libc)Copying Strings and Arrays.
- * wcscspn: (libc)Search Functions.
- * wcsdup: (libc)Copying Strings and Arrays.
- * wcsftime: (libc)Formatting Calendar Time.
- * wcslen: (libc)String Length.
- * wcsncasecmp: (libc)String/Array Comparison.
- * wcsncat: (libc)Truncating Strings.
- * wcsncmp: (libc)String/Array Comparison.
- * wcsncpy: (libc)Truncating Strings.
- * wcsnlen: (libc)String Length.
- * wcsnrtombs: (libc)Converting Strings.
- * wcspbrk: (libc)Search Functions.
- * wcsrchr: (libc)Search Functions.
- * wcsrtombs: (libc)Converting Strings.
- * wcsspn: (libc)Search Functions.
- * wcsstr: (libc)Search Functions.
- * wcstod: (libc)Parsing of Floats.
- * wcstof: (libc)Parsing of Floats.
- * wcstoimax: (libc)Parsing of Integers.
- * wcstok: (libc)Finding Tokens in a String.
- * wcstold: (libc)Parsing of Floats.
- * wcstol: (libc)Parsing of Integers.
- * wcstoll: (libc)Parsing of Integers.
- * wcstombs: (libc)Non-reentrant String Conversion.
- * wcstoq: (libc)Parsing of Integers.
- * wcstoul: (libc)Parsing of Integers.
- * wcstoull: (libc)Parsing of Integers.
- * wcstoumax: (libc)Parsing of Integers.
- * wcstouq: (libc)Parsing of Integers.
- * wcswcs: (libc)Search Functions.
- * wcsxfrm: (libc)Collation Functions.
- * wctob: (libc)Converting a Character.
- * wctomb: (libc)Non-reentrant Character Conversion.
- * wctrans: (libc)Wide Character Case Conversion.
- * wctype: (libc)Classification of Wide Characters.
- * WEOF: (libc)EOF and Errors.
- * WEOF: (libc)Extended Char Intro.
- * WEXITSTATUS: (libc)Process Completion Status.
- * WIFEXITED: (libc)Process Completion Status.
- * WIFSIGNALED: (libc)Process Completion Status.
- * WIFSTOPPED: (libc)Process Completion Status.
- * wmemchr: (libc)Search Functions.
- * wmemcmp: (libc)String/Array Comparison.
- * wmemcpy: (libc)Copying Strings and Arrays.
- * wmemmove: (libc)Copying Strings and Arrays.
- * wmempcpy: (libc)Copying Strings and Arrays.
- * wmemset: (libc)Copying Strings and Arrays.
- * W_OK: (libc)Testing File Access.
- * wordexp: (libc)Calling Wordexp.
- * wordfree: (libc)Calling Wordexp.
- * wprintf: (libc)Formatted Output Functions.
- * write: (libc)I/O Primitives.
- * writev: (libc)Scatter-Gather.
- * wscanf: (libc)Formatted Input Functions.
- * WSTOPSIG: (libc)Process Completion Status.
- * WTERMSIG: (libc)Process Completion Status.
- * X_OK: (libc)Testing File Access.
- * y0f: (libc)Special Functions.
- * y0: (libc)Special Functions.
- * y0l: (libc)Special Functions.
- * y1f: (libc)Special Functions.
- * y1: (libc)Special Functions.
- * y1l: (libc)Special Functions.
- * ynf: (libc)Special Functions.
- * yn: (libc)Special Functions.
- * ynl: (libc)Special Functions.
- END-INFO-DIR-ENTRY
- File: libc.info, Node: Converting Strings, Next: Multibyte Conversion Example, Prev: Converting a Character, Up: Restartable multibyte conversion
- 6.3.4 Converting Multibyte and Wide Character Strings
- -----------------------------------------------------
- The functions described in the previous section only convert a single
- character at a time. Most operations to be performed in real-world
- programs include strings and therefore the ISO C standard also defines
- conversions on entire strings. However, the defined set of functions is
- quite limited; therefore, the GNU C Library contains a few extensions
- that can help in some important situations.
- -- Function: size_t mbsrtowcs (wchar_t *restrict DST, const char
- **restrict SRC, size_t LEN, mbstate_t *restrict PS)
- Preliminary: | MT-Unsafe race:mbsrtowcs/!ps | AS-Unsafe corrupt
- heap lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX
- Safety Concepts::.
- The ‘mbsrtowcs’ function (“multibyte string restartable to wide
- character string”) converts the NUL-terminated multibyte character
- string at ‘*SRC’ into an equivalent wide character string,
- including the NUL wide character at the end. The conversion is
- started using the state information from the object pointed to by
- PS or from an internal object of ‘mbsrtowcs’ if PS is a null
- pointer. Before returning, the state object is updated to match
- the state after the last converted character. The state is the
- initial state if the terminating NUL byte is reached and converted.
- If DST is not a null pointer, the result is stored in the array
- pointed to by DST; otherwise, the conversion result is not
- available since it is stored in an internal buffer.
- If LEN wide characters are stored in the array DST before reaching
- the end of the input string, the conversion stops and LEN is
- returned. If DST is a null pointer, LEN is never checked.
- Another reason for a premature return from the function call is if
- the input string contains an invalid multibyte sequence. In this
- case the global variable ‘errno’ is set to ‘EILSEQ’ and the
- function returns ‘(size_t) -1’.
- In all other cases the function returns the number of wide
- characters converted during this call. If DST is not null,
- ‘mbsrtowcs’ stores in the pointer pointed to by SRC either a null
- pointer (if the NUL byte in the input string was reached) or the
- address of the byte following the last converted multibyte
- character.
- ‘mbsrtowcs’ was introduced in Amendment 1 to ISO C90 and is
- declared in ‘wchar.h’.
- The definition of the ‘mbsrtowcs’ function has one important
- limitation. The requirement that DST has to be a NUL-terminated string
- provides problems if one wants to convert buffers with text. A buffer
- is not normally a collection of NUL-terminated strings but instead a
- continuous collection of lines, separated by newline characters. Now
- assume that a function to convert one line from a buffer is needed.
- Since the line is not NUL-terminated, the source pointer cannot directly
- point into the unmodified text buffer. This means, either one inserts
- the NUL byte at the appropriate place for the time of the ‘mbsrtowcs’
- function call (which is not doable for a read-only buffer or in a
- multi-threaded application) or one copies the line in an extra buffer
- where it can be terminated by a NUL byte. Note that it is not in
- general possible to limit the number of characters to convert by setting
- the parameter LEN to any specific value. Since it is not known how many
- bytes each multibyte character sequence is in length, one can only
- guess.
- There is still a problem with the method of NUL-terminating a line
- right after the newline character, which could lead to very strange
- results. As said in the description of the ‘mbsrtowcs’ function above,
- the conversion state is guaranteed to be in the initial shift state
- after processing the NUL byte at the end of the input string. But this
- NUL byte is not really part of the text (i.e., the conversion state
- after the newline in the original text could be something different than
- the initial shift state and therefore the first character of the next
- line is encoded using this state). But the state in question is never
- accessible to the user since the conversion stops after the NUL byte
- (which resets the state). Most stateful character sets in use today
- require that the shift state after a newline be the initial state–but
- this is not a strict guarantee. Therefore, simply NUL-terminating a
- piece of a running text is not always an adequate solution and,
- therefore, should never be used in generally used code.
- The generic conversion interface (*note Generic Charset Conversion::)
- does not have this limitation (it simply works on buffers, not strings),
- and the GNU C Library contains a set of functions that take additional
- parameters specifying the maximal number of bytes that are consumed from
- the input string. This way the problem of ‘mbsrtowcs’’s example above
- could be solved by determining the line length and passing this length
- to the function.
- -- Function: size_t wcsrtombs (char *restrict DST, const wchar_t
- **restrict SRC, size_t LEN, mbstate_t *restrict PS)
- Preliminary: | MT-Unsafe race:wcsrtombs/!ps | AS-Unsafe corrupt
- heap lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX
- Safety Concepts::.
- The ‘wcsrtombs’ function (“wide character string restartable to
- multibyte string”) converts the NUL-terminated wide character
- string at ‘*SRC’ into an equivalent multibyte character string and
- stores the result in the array pointed to by DST. The NUL wide
- character is also converted. The conversion starts in the state
- described in the object pointed to by PS or by a state object local
- to ‘wcsrtombs’ in case PS is a null pointer. If DST is a null
- pointer, the conversion is performed as usual but the result is not
- available. If all characters of the input string were successfully
- converted and if DST is not a null pointer, the pointer pointed to
- by SRC gets assigned a null pointer.
- If one of the wide characters in the input string has no valid
- multibyte character equivalent, the conversion stops early, sets
- the global variable ‘errno’ to ‘EILSEQ’, and returns ‘(size_t) -1’.
- Another reason for a premature stop is if DST is not a null pointer
- and the next converted character would require more than LEN bytes
- in total to the array DST. In this case (and if DST is not a null
- pointer) the pointer pointed to by SRC is assigned a value pointing
- to the wide character right after the last one successfully
- converted.
- Except in the case of an encoding error the return value of the
- ‘wcsrtombs’ function is the number of bytes in all the multibyte
- character sequences stored in DST. Before returning, the state in
- the object pointed to by PS (or the internal object in case PS is a
- null pointer) is updated to reflect the state after the last
- conversion. The state is the initial shift state in case the
- terminating NUL wide character was converted.
- The ‘wcsrtombs’ function was introduced in Amendment 1 to ISO C90
- and is declared in ‘wchar.h’.
- The restriction mentioned above for the ‘mbsrtowcs’ function applies
- here also. There is no possibility of directly controlling the number
- of input characters. One has to place the NUL wide character at the
- correct place or control the consumed input indirectly via the available
- output array size (the LEN parameter).
- -- Function: size_t mbsnrtowcs (wchar_t *restrict DST, const char
- **restrict SRC, size_t NMC, size_t LEN, mbstate_t *restrict
- PS)
- Preliminary: | MT-Unsafe race:mbsnrtowcs/!ps | AS-Unsafe corrupt
- heap lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX
- Safety Concepts::.
- The ‘mbsnrtowcs’ function is very similar to the ‘mbsrtowcs’
- function. All the parameters are the same except for NMC, which is
- new. The return value is the same as for ‘mbsrtowcs’.
- This new parameter specifies how many bytes at most can be used
- from the multibyte character string. In other words, the multibyte
- character string ‘*SRC’ need not be NUL-terminated. But if a NUL
- byte is found within the NMC first bytes of the string, the
- conversion stops there.
- This function is a GNU extension. It is meant to work around the
- problems mentioned above. Now it is possible to convert a buffer
- with multibyte character text piece by piece without having to care
- about inserting NUL bytes and the effect of NUL bytes on the
- conversion state.
- A function to convert a multibyte string into a wide character string
- and display it could be written like this (this is not a really useful
- example):
- void
- showmbs (const char *src, FILE *fp)
- {
- mbstate_t state;
- int cnt = 0;
- memset (&state, '\0', sizeof (state));
- while (1)
- {
- wchar_t linebuf[100];
- const char *endp = strchr (src, '\n');
- size_t n;
- /* Exit if there is no more line. */
- if (endp == NULL)
- break;
- n = mbsnrtowcs (linebuf, &src, endp - src, 99, &state);
- linebuf[n] = L'\0';
- fprintf (fp, "line %d: \"%S\"\n", linebuf);
- }
- }
- There is no problem with the state after a call to ‘mbsnrtowcs’.
- Since we don’t insert characters in the strings that were not in there
- right from the beginning and we use STATE only for the conversion of the
- given buffer, there is no problem with altering the state.
- -- Function: size_t wcsnrtombs (char *restrict DST, const wchar_t
- **restrict SRC, size_t NWC, size_t LEN, mbstate_t *restrict
- PS)
- Preliminary: | MT-Unsafe race:wcsnrtombs/!ps | AS-Unsafe corrupt
- heap lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX
- Safety Concepts::.
- The ‘wcsnrtombs’ function implements the conversion from wide
- character strings to multibyte character strings. It is similar to
- ‘wcsrtombs’ but, just like ‘mbsnrtowcs’, it takes an extra
- parameter, which specifies the length of the input string.
- No more than NWC wide characters from the input string ‘*SRC’ are
- converted. If the input string contains a NUL wide character in
- the first NWC characters, the conversion stops at this place.
- The ‘wcsnrtombs’ function is a GNU extension and just like
- ‘mbsnrtowcs’ helps in situations where no NUL-terminated input
- strings are available.
- File: libc.info, Node: Multibyte Conversion Example, Prev: Converting Strings, Up: Restartable multibyte conversion
- 6.3.5 A Complete Multibyte Conversion Example
- ---------------------------------------------
- The example programs given in the last sections are only brief and do
- not contain all the error checking, etc. Presented here is a complete
- and documented example. It features the ‘mbrtowc’ function but it
- should be easy to derive versions using the other functions.
- int
- file_mbsrtowcs (int input, int output)
- {
- /* Note the use of ‘MB_LEN_MAX’.
- ‘MB_CUR_MAX’ cannot portably be used here. */
- char buffer[BUFSIZ + MB_LEN_MAX];
- mbstate_t state;
- int filled = 0;
- int eof = 0;
- /* Initialize the state. */
- memset (&state, '\0', sizeof (state));
- while (!eof)
- {
- ssize_t nread;
- ssize_t nwrite;
- char *inp = buffer;
- wchar_t outbuf[BUFSIZ];
- wchar_t *outp = outbuf;
- /* Fill up the buffer from the input file. */
- nread = read (input, buffer + filled, BUFSIZ);
- if (nread < 0)
- {
- perror ("read");
- return 0;
- }
- /* If we reach end of file, make a note to read no more. */
- if (nread == 0)
- eof = 1;
- /* ‘filled’ is now the number of bytes in ‘buffer’. */
- filled += nread;
- /* Convert those bytes to wide characters–as many as we can. */
- while (1)
- {
- size_t thislen = mbrtowc (outp, inp, filled, &state);
- /* Stop converting at invalid character;
- this can mean we have read just the first part
- of a valid character. */
- if (thislen == (size_t) -1)
- break;
- /* We want to handle embedded NUL bytes
- but the return value is 0. Correct this. */
- if (thislen == 0)
- thislen = 1;
- /* Advance past this character. */
- inp += thislen;
- filled -= thislen;
- ++outp;
- }
- /* Write the wide characters we just made. */
- nwrite = write (output, outbuf,
- (outp - outbuf) * sizeof (wchar_t));
- if (nwrite < 0)
- {
- perror ("write");
- return 0;
- }
- /* See if we have a _real_ invalid character. */
- if ((eof && filled > 0) || filled >= MB_CUR_MAX)
- {
- error (0, 0, "invalid multibyte character");
- return 0;
- }
- /* If any characters must be carried forward,
- put them at the beginning of ‘buffer’. */
- if (filled > 0)
- memmove (buffer, inp, filled);
- }
- return 1;
- }
- File: libc.info, Node: Non-reentrant Conversion, Next: Generic Charset Conversion, Prev: Restartable multibyte conversion, Up: Character Set Handling
- 6.4 Non-reentrant Conversion Function
- =====================================
- The functions described in the previous chapter are defined in Amendment 1
- to ISO C90, but the original ISO C90 standard also contained functions
- for character set conversion. The reason that these original functions
- are not described first is that they are almost entirely useless.
- The problem is that all the conversion functions described in the
- original ISO C90 use a local state. Using a local state implies that
- multiple conversions at the same time (not only when using threads)
- cannot be done, and that you cannot first convert single characters and
- then strings since you cannot tell the conversion functions which state
- to use.
- These original functions are therefore usable only in a very limited
- set of situations. One must complete converting the entire string
- before starting a new one, and each string/text must be converted with
- the same function (there is no problem with the library itself; it is
- guaranteed that no library function changes the state of any of these
- functions). *For the above reasons it is highly requested that the
- functions described in the previous section be used in place of
- non-reentrant conversion functions.*
- * Menu:
- * Non-reentrant Character Conversion:: Non-reentrant Conversion of Single
- Characters.
- * Non-reentrant String Conversion:: Non-reentrant Conversion of Strings.
- * Shift State:: States in Non-reentrant Functions.
- File: libc.info, Node: Non-reentrant Character Conversion, Next: Non-reentrant String Conversion, Up: Non-reentrant Conversion
- 6.4.1 Non-reentrant Conversion of Single Characters
- ---------------------------------------------------
- -- Function: int mbtowc (wchar_t *restrict RESULT, const char *restrict
- STRING, size_t SIZE)
- Preliminary: | MT-Unsafe race | AS-Unsafe corrupt heap lock dlopen
- | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
- The ‘mbtowc’ (“multibyte to wide character”) function when called
- with non-null STRING converts the first multibyte character
- beginning at STRING to its corresponding wide character code. It
- stores the result in ‘*RESULT’.
- ‘mbtowc’ never examines more than SIZE bytes. (The idea is to
- supply for SIZE the number of bytes of data you have in hand.)
- ‘mbtowc’ with non-null STRING distinguishes three possibilities:
- the first SIZE bytes at STRING start with valid multibyte
- characters, they start with an invalid byte sequence or just part
- of a character, or STRING points to an empty string (a null
- character).
- For a valid multibyte character, ‘mbtowc’ converts it to a wide
- character and stores that in ‘*RESULT’, and returns the number of
- bytes in that character (always at least 1 and never more than
- SIZE).
- For an invalid byte sequence, ‘mbtowc’ returns -1. For an empty
- string, it returns 0, also storing ‘'\0'’ in ‘*RESULT’.
- If the multibyte character code uses shift characters, then
- ‘mbtowc’ maintains and updates a shift state as it scans. If you
- call ‘mbtowc’ with a null pointer for STRING, that initializes the
- shift state to its standard initial value. It also returns nonzero
- if the multibyte character code in use actually has a shift state.
- *Note Shift State::.
- -- Function: int wctomb (char *STRING, wchar_t WCHAR)
- Preliminary: | MT-Unsafe race | AS-Unsafe corrupt heap lock dlopen
- | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
- The ‘wctomb’ (“wide character to multibyte”) function converts the
- wide character code WCHAR to its corresponding multibyte character
- sequence, and stores the result in bytes starting at STRING. At
- most ‘MB_CUR_MAX’ characters are stored.
- ‘wctomb’ with non-null STRING distinguishes three possibilities for
- WCHAR: a valid wide character code (one that can be translated to a
- multibyte character), an invalid code, and ‘L'\0'’.
- Given a valid code, ‘wctomb’ converts it to a multibyte character,
- storing the bytes starting at STRING. Then it returns the number
- of bytes in that character (always at least 1 and never more than
- ‘MB_CUR_MAX’).
- If WCHAR is an invalid wide character code, ‘wctomb’ returns -1.
- If WCHAR is ‘L'\0'’, it returns ‘0’, also storing ‘'\0'’ in
- ‘*STRING’.
- If the multibyte character code uses shift characters, then
- ‘wctomb’ maintains and updates a shift state as it scans. If you
- call ‘wctomb’ with a null pointer for STRING, that initializes the
- shift state to its standard initial value. It also returns nonzero
- if the multibyte character code in use actually has a shift state.
- *Note Shift State::.
- Calling this function with a WCHAR argument of zero when STRING is
- not null has the side-effect of reinitializing the stored shift
- state _as well as_ storing the multibyte character ‘'\0'’ and
- returning 0.
- Similar to ‘mbrlen’ there is also a non-reentrant function that
- computes the length of a multibyte character. It can be defined in
- terms of ‘mbtowc’.
- -- Function: int mblen (const char *STRING, size_t SIZE)
- Preliminary: | MT-Unsafe race | AS-Unsafe corrupt heap lock dlopen
- | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
- The ‘mblen’ function with a non-null STRING argument returns the
- number of bytes that make up the multibyte character beginning at
- STRING, never examining more than SIZE bytes. (The idea is to
- supply for SIZE the number of bytes of data you have in hand.)
- The return value of ‘mblen’ distinguishes three possibilities: the
- first SIZE bytes at STRING start with valid multibyte characters,
- they start with an invalid byte sequence or just part of a
- character, or STRING points to an empty string (a null character).
- For a valid multibyte character, ‘mblen’ returns the number of
- bytes in that character (always at least ‘1’ and never more than
- SIZE). For an invalid byte sequence, ‘mblen’ returns -1. For an
- empty string, it returns 0.
- If the multibyte character code uses shift characters, then ‘mblen’
- maintains and updates a shift state as it scans. If you call
- ‘mblen’ with a null pointer for STRING, that initializes the shift
- state to its standard initial value. It also returns a nonzero
- value if the multibyte character code in use actually has a shift
- state. *Note Shift State::.
- The function ‘mblen’ is declared in ‘stdlib.h’.
- File: libc.info, Node: Non-reentrant String Conversion, Next: Shift State, Prev: Non-reentrant Character Conversion, Up: Non-reentrant Conversion
- 6.4.2 Non-reentrant Conversion of Strings
- -----------------------------------------
- For convenience the ISO C90 standard also defines functions to convert
- entire strings instead of single characters. These functions suffer
- from the same problems as their reentrant counterparts from Amendment 1
- to ISO C90; see *note Converting Strings::.
- -- Function: size_t mbstowcs (wchar_t *WSTRING, const char *STRING,
- size_t SIZE)
- Preliminary: | MT-Safe | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
- The ‘mbstowcs’ (“multibyte string to wide character string”)
- function converts the null-terminated string of multibyte
- characters STRING to an array of wide character codes, storing not
- more than SIZE wide characters into the array beginning at WSTRING.
- The terminating null character counts towards the size, so if SIZE
- is less than the actual number of wide characters resulting from
- STRING, no terminating null character is stored.
- The conversion of characters from STRING begins in the initial
- shift state.
- If an invalid multibyte character sequence is found, the ‘mbstowcs’
- function returns a value of -1. Otherwise, it returns the number
- of wide characters stored in the array WSTRING. This number does
- not include the terminating null character, which is present if the
- number is less than SIZE.
- Here is an example showing how to convert a string of multibyte
- characters, allocating enough space for the result.
- wchar_t *
- mbstowcs_alloc (const char *string)
- {
- size_t size = strlen (string) + 1;
- wchar_t *buf = xmalloc (size * sizeof (wchar_t));
- size = mbstowcs (buf, string, size);
- if (size == (size_t) -1)
- return NULL;
- buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
- return buf;
- }
- -- Function: size_t wcstombs (char *STRING, const wchar_t *WSTRING,
- size_t SIZE)
- Preliminary: | MT-Safe | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
- The ‘wcstombs’ (“wide character string to multibyte string”)
- function converts the null-terminated wide character array WSTRING
- into a string containing multibyte characters, storing not more
- than SIZE bytes starting at STRING, followed by a terminating null
- character if there is room. The conversion of characters begins in
- the initial shift state.
- The terminating null character counts towards the size, so if SIZE
- is less than or equal to the number of bytes needed in WSTRING, no
- terminating null character is stored.
- If a code that does not correspond to a valid multibyte character
- is found, the ‘wcstombs’ function returns a value of -1.
- Otherwise, the return value is the number of bytes stored in the
- array STRING. This number does not include the terminating null
- character, which is present if the number is less than SIZE.
- File: libc.info, Node: Shift State, Prev: Non-reentrant String Conversion, Up: Non-reentrant Conversion
- 6.4.3 States in Non-reentrant Functions
- ---------------------------------------
- In some multibyte character codes, the _meaning_ of any particular byte
- sequence is not fixed; it depends on what other sequences have come
- earlier in the same string. Typically there are just a few sequences
- that can change the meaning of other sequences; these few are called
- "shift sequences" and we say that they set the "shift state" for other
- sequences that follow.
- To illustrate shift state and shift sequences, suppose we decide that
- the sequence ‘0200’ (just one byte) enters Japanese mode, in which pairs
- of bytes in the range from ‘0240’ to ‘0377’ are single characters, while
- ‘0201’ enters Latin-1 mode, in which single bytes in the range from
- ‘0240’ to ‘0377’ are characters, and interpreted according to the ISO
- Latin-1 character set. This is a multibyte code that has two
- alternative shift states (“Japanese mode” and “Latin-1 mode”), and two
- shift sequences that specify particular shift states.
- When the multibyte character code in use has shift states, then
- ‘mblen’, ‘mbtowc’, and ‘wctomb’ must maintain and update the current
- shift state as they scan the string. To make this work properly, you
- must follow these rules:
- • Before starting to scan a string, call the function with a null
- pointer for the multibyte character address—for example, ‘mblen
- (NULL, 0)’. This initializes the shift state to its standard
- initial value.
- • Scan the string one character at a time, in order. Do not “back
- up” and rescan characters already scanned, and do not intersperse
- the processing of different strings.
- Here is an example of using ‘mblen’ following these rules:
- void
- scan_string (char *s)
- {
- int length = strlen (s);
- /* Initialize shift state. */
- mblen (NULL, 0);
- while (1)
- {
- int thischar = mblen (s, length);
- /* Deal with end of string and invalid characters. */
- if (thischar == 0)
- break;
- if (thischar == -1)
- {
- error ("invalid multibyte character");
- break;
- }
- /* Advance past this character. */
- s += thischar;
- length -= thischar;
- }
- }
- The functions ‘mblen’, ‘mbtowc’ and ‘wctomb’ are not reentrant when
- using a multibyte code that uses a shift state. However, no other
- library functions call these functions, so you don’t have to worry that
- the shift state will be changed mysteriously.
- File: libc.info, Node: Generic Charset Conversion, Prev: Non-reentrant Conversion, Up: Character Set Handling
- 6.5 Generic Charset Conversion
- ==============================
- The conversion functions mentioned so far in this chapter all had in
- common that they operate on character sets that are not directly
- specified by the functions. The multibyte encoding used is specified by
- the currently selected locale for the ‘LC_CTYPE’ category. The wide
- character set is fixed by the implementation (in the case of the GNU C
- Library it is always UCS-4 encoded ISO 10646).
- This has of course several problems when it comes to general
- character conversion:
- • For every conversion where neither the source nor the destination
- character set is the character set of the locale for the ‘LC_CTYPE’
- category, one has to change the ‘LC_CTYPE’ locale using
- ‘setlocale’.
- Changing the ‘LC_CTYPE’ locale introduces major problems for the
- rest of the programs since several more functions (e.g., the
- character classification functions, *note Classification of
- Characters::) use the ‘LC_CTYPE’ category.
- • Parallel conversions to and from different character sets are not
- possible since the ‘LC_CTYPE’ selection is global and shared by all
- threads.
- • If neither the source nor the destination character set is the
- character set used for ‘wchar_t’ representation, there is at least
- a two-step process necessary to convert a text using the functions
- above. One would have to select the source character set as the
- multibyte encoding, convert the text into a ‘wchar_t’ text, select
- the destination character set as the multibyte encoding, and
- convert the wide character text to the multibyte (= destination)
- character set.
- Even if this is possible (which is not guaranteed) it is a very
- tiring work. Plus it suffers from the other two raised points even
- more due to the steady changing of the locale.
- The XPG2 standard defines a completely new set of functions, which
- has none of these limitations. They are not at all coupled to the
- selected locales, and they have no constraints on the character sets
- selected for source and destination. Only the set of available
- conversions limits them. The standard does not specify that any
- conversion at all must be available. Such availability is a measure of
- the quality of the implementation.
- In the following text first the interface to ‘iconv’ and then the
- conversion function, will be described. Comparisons with other
- implementations will show what obstacles stand in the way of portable
- applications. Finally, the implementation is described in so far as
- might interest the advanced user who wants to extend conversion
- capabilities.
- * Menu:
- * Generic Conversion Interface:: Generic Character Set Conversion Interface.
- * iconv Examples:: A complete ‘iconv’ example.
- * Other iconv Implementations:: Some Details about other ‘iconv’
- Implementations.
- * glibc iconv Implementation:: The ‘iconv’ Implementation in the GNU C
- library.
- File: libc.info, Node: Generic Conversion Interface, Next: iconv Examples, Up: Generic Charset Conversion
- 6.5.1 Generic Character Set Conversion Interface
- ------------------------------------------------
- This set of functions follows the traditional cycle of using a resource:
- open–use–close. The interface consists of three functions, each of
- which implements one step.
- Before the interfaces are described it is necessary to introduce a
- data type. Just like other open–use–close interfaces the functions
- introduced here work using handles and the ‘iconv.h’ header defines a
- special type for the handles used.
- -- Data Type: iconv_t
- This data type is an abstract type defined in ‘iconv.h’. The user
- must not assume anything about the definition of this type; it must
- be completely opaque.
- Objects of this type can be assigned handles for the conversions
- using the ‘iconv’ functions. The objects themselves need not be
- freed, but the conversions for which the handles stand for have to.
- The first step is the function to create a handle.
- -- Function: iconv_t iconv_open (const char *TOCODE, const char
- *FROMCODE)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
- | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
- The ‘iconv_open’ function has to be used before starting a
- conversion. The two parameters this function takes determine the
- source and destination character set for the conversion, and if the
- implementation has the possibility to perform such a conversion,
- the function returns a handle.
- If the wanted conversion is not available, the ‘iconv_open’
- function returns ‘(iconv_t) -1’. In this case the global variable
- ‘errno’ can have the following values:
- ‘EMFILE’
- The process already has ‘OPEN_MAX’ file descriptors open.
- ‘ENFILE’
- The system limit of open files is reached.
- ‘ENOMEM’
- Not enough memory to carry out the operation.
- ‘EINVAL’
- The conversion from FROMCODE to TOCODE is not supported.
- It is not possible to use the same descriptor in different threads
- to perform independent conversions. The data structures associated
- with the descriptor include information about the conversion state.
- This must not be messed up by using it in different conversions.
- An ‘iconv’ descriptor is like a file descriptor as for every use a
- new descriptor must be created. The descriptor does not stand for
- all of the conversions from FROMSET to TOSET.
- The GNU C Library implementation of ‘iconv_open’ has one
- significant extension to other implementations. To ease the
- extension of the set of available conversions, the implementation
- allows storing the necessary files with data and code in an
- arbitrary number of directories. How this extension must be
- written will be explained below (*note glibc iconv
- Implementation::). Here it is only important to say that all
- directories mentioned in the ‘GCONV_PATH’ environment variable are
- considered only if they contain a file ‘gconv-modules’. These
- directories need not necessarily be created by the system
- administrator. In fact, this extension is introduced to help users
- writing and using their own, new conversions. Of course, this does
- not work for security reasons in SUID binaries; in this case only
- the system directory is considered and this normally is
- ‘PREFIX/lib/gconv’. The ‘GCONV_PATH’ environment variable is
- examined exactly once at the first call of the ‘iconv_open’
- function. Later modifications of the variable have no effect.
- The ‘iconv_open’ function was introduced early in the X/Open
- Portability Guide, version 2. It is supported by all commercial
- Unices as it is required for the Unix branding. However, the
- quality and completeness of the implementation varies widely. The
- ‘iconv_open’ function is declared in ‘iconv.h’.
- The ‘iconv’ implementation can associate large data structure with
- the handle returned by ‘iconv_open’. Therefore, it is crucial to free
- all the resources once all conversions are carried out and the
- conversion is not needed anymore.
- -- Function: int iconv_close (iconv_t CD)
- Preliminary: | MT-Safe | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
- The ‘iconv_close’ function frees all resources associated with the
- handle CD, which must have been returned by a successful call to
- the ‘iconv_open’ function.
- If the function call was successful the return value is 0.
- Otherwise it is -1 and ‘errno’ is set appropriately. Defined
- errors are:
- ‘EBADF’
- The conversion descriptor is invalid.
- The ‘iconv_close’ function was introduced together with the rest of
- the ‘iconv’ functions in XPG2 and is declared in ‘iconv.h’.
- The standard defines only one actual conversion function. This has,
- therefore, the most general interface: it allows conversion from one
- buffer to another. Conversion from a file to a buffer, vice versa, or
- even file to file can be implemented on top of it.
- -- Function: size_t iconv (iconv_t CD, char **INBUF, size_t
- *INBYTESLEFT, char **OUTBUF, size_t *OUTBYTESLEFT)
- Preliminary: | MT-Safe race:cd | AS-Safe | AC-Unsafe corrupt |
- *Note POSIX Safety Concepts::.
- The ‘iconv’ function converts the text in the input buffer
- according to the rules associated with the descriptor CD and stores
- the result in the output buffer. It is possible to call the
- function for the same text several times in a row since for
- stateful character sets the necessary state information is kept in
- the data structures associated with the descriptor.
- The input buffer is specified by ‘*INBUF’ and it contains
- ‘*INBYTESLEFT’ bytes. The extra indirection is necessary for
- communicating the used input back to the caller (see below). It is
- important to note that the buffer pointer is of type ‘char’ and the
- length is measured in bytes even if the input text is encoded in
- wide characters.
- The output buffer is specified in a similar way. ‘*OUTBUF’ points
- to the beginning of the buffer with at least ‘*OUTBYTESLEFT’ bytes
- room for the result. The buffer pointer again is of type ‘char’
- and the length is measured in bytes. If OUTBUF or ‘*OUTBUF’ is a
- null pointer, the conversion is performed but no output is
- available.
- If INBUF is a null pointer, the ‘iconv’ function performs the
- necessary action to put the state of the conversion into the
- initial state. This is obviously a no-op for non-stateful
- encodings, but if the encoding has a state, such a function call
- might put some byte sequences in the output buffer, which perform
- the necessary state changes. The next call with INBUF not being a
- null pointer then simply goes on from the initial state. It is
- important that the programmer never makes any assumption as to
- whether the conversion has to deal with states. Even if the input
- and output character sets are not stateful, the implementation
- might still have to keep states. This is due to the implementation
- chosen for the GNU C Library as it is described below. Therefore
- an ‘iconv’ call to reset the state should always be performed if
- some protocol requires this for the output text.
- The conversion stops for one of three reasons. The first is that
- all characters from the input buffer are converted. This actually
- can mean two things: either all bytes from the input buffer are
- consumed or there are some bytes at the end of the buffer that
- possibly can form a complete character but the input is incomplete.
- The second reason for a stop is that the output buffer is full.
- And the third reason is that the input contains invalid characters.
- In all of these cases the buffer pointers after the last successful
- conversion, for the input and output buffers, are stored in INBUF
- and OUTBUF, and the available room in each buffer is stored in
- INBYTESLEFT and OUTBYTESLEFT.
- Since the character sets selected in the ‘iconv_open’ call can be
- almost arbitrary, there can be situations where the input buffer
- contains valid characters, which have no identical representation
- in the output character set. The behavior in this situation is
- undefined. The _current_ behavior of the GNU C Library in this
- situation is to return with an error immediately. This certainly
- is not the most desirable solution; therefore, future versions will
- provide better ones, but they are not yet finished.
- If all input from the input buffer is successfully converted and
- stored in the output buffer, the function returns the number of
- non-reversible conversions performed. In all other cases the
- return value is ‘(size_t) -1’ and ‘errno’ is set appropriately. In
- such cases the value pointed to by INBYTESLEFT is nonzero.
- ‘EILSEQ’
- The conversion stopped because of an invalid byte sequence in
- the input. After the call, ‘*INBUF’ points at the first byte
- of the invalid byte sequence.
- ‘E2BIG’
- The conversion stopped because it ran out of space in the
- output buffer.
- ‘EINVAL’
- The conversion stopped because of an incomplete byte sequence
- at the end of the input buffer.
- ‘EBADF’
- The CD argument is invalid.
- The ‘iconv’ function was introduced in the XPG2 standard and is
- declared in the ‘iconv.h’ header.
- The definition of the ‘iconv’ function is quite good overall. It
- provides quite flexible functionality. The only problems lie in the
- boundary cases, which are incomplete byte sequences at the end of the
- input buffer and invalid input. A third problem, which is not really a
- design problem, is the way conversions are selected. The standard does
- not say anything about the legitimate names, a minimal set of available
- conversions. We will see how this negatively impacts other
- implementations, as demonstrated below.
- File: libc.info, Node: iconv Examples, Next: Other iconv Implementations, Prev: Generic Conversion Interface, Up: Generic Charset Conversion
- 6.5.2 A complete ‘iconv’ example
- --------------------------------
- The example below features a solution for a common problem. Given that
- one knows the internal encoding used by the system for ‘wchar_t’
- strings, one often is in the position to read text from a file and store
- it in wide character buffers. One can do this using ‘mbsrtowcs’, but
- then we run into the problems discussed above.
- int
- file2wcs (int fd, const char *charset, wchar_t *outbuf, size_t avail)
- {
- char inbuf[BUFSIZ];
- size_t insize = 0;
- char *wrptr = (char *) outbuf;
- int result = 0;
- iconv_t cd;
- cd = iconv_open ("WCHAR_T", charset);
- if (cd == (iconv_t) -1)
- {
- /* Something went wrong. */
- if (errno == EINVAL)
- error (0, 0, "conversion from '%s' to wchar_t not available",
- charset);
- else
- perror ("iconv_open");
- /* Terminate the output string. */
- *outbuf = L'\0';
- return -1;
- }
- while (avail > 0)
- {
- size_t nread;
- size_t nconv;
- char *inptr = inbuf;
- /* Read more input. */
- nread = read (fd, inbuf + insize, sizeof (inbuf) - insize);
- if (nread == 0)
- {
- /* When we come here the file is completely read.
- This still could mean there are some unused
- characters in the ‘inbuf’. Put them back. */
- if (lseek (fd, -insize, SEEK_CUR) == -1)
- result = -1;
- /* Now write out the byte sequence to get into the
- initial state if this is necessary. */
- iconv (cd, NULL, NULL, &wrptr, &avail);
- break;
- }
- insize += nread;
- /* Do the conversion. */
- nconv = iconv (cd, &inptr, &insize, &wrptr, &avail);
- if (nconv == (size_t) -1)
- {
- /* Not everything went right. It might only be
- an unfinished byte sequence at the end of the
- buffer. Or it is a real problem. */
- if (errno == EINVAL)
- /* This is harmless. Simply move the unused
- bytes to the beginning of the buffer so that
- they can be used in the next round. */
- memmove (inbuf, inptr, insize);
- else
- {
- /* It is a real problem. Maybe we ran out of
- space in the output buffer or we have invalid
- input. In any case back the file pointer to
- the position of the last processed byte. */
- lseek (fd, -insize, SEEK_CUR);
- result = -1;
- break;
- }
- }
- }
- /* Terminate the output string. */
- if (avail >= sizeof (wchar_t))
- *((wchar_t *) wrptr) = L'\0';
- if (iconv_close (cd) != 0)
- perror ("iconv_close");
- return (wchar_t *) wrptr - outbuf;
- }
- This example shows the most important aspects of using the ‘iconv’
- functions. It shows how successive calls to ‘iconv’ can be used to
- convert large amounts of text. The user does not have to care about
- stateful encodings as the functions take care of everything.
- An interesting point is the case where ‘iconv’ returns an error and
- ‘errno’ is set to ‘EINVAL’. This is not really an error in the
- transformation. It can happen whenever the input character set contains
- byte sequences of more than one byte for some character and texts are
- not processed in one piece. In this case there is a chance that a
- multibyte sequence is cut. The caller can then simply read the
- remainder of the takes and feed the offending bytes together with new
- character from the input to ‘iconv’ and continue the work. The internal
- state kept in the descriptor is _not_ unspecified after such an event as
- is the case with the conversion functions from the ISO C standard.
- The example also shows the problem of using wide character strings
- with ‘iconv’. As explained in the description of the ‘iconv’ function
- above, the function always takes a pointer to a ‘char’ array and the
- available space is measured in bytes. In the example, the output buffer
- is a wide character buffer; therefore, we use a local variable WRPTR of
- type ‘char *’, which is used in the ‘iconv’ calls.
- This looks rather innocent but can lead to problems on platforms that
- have tight restriction on alignment. Therefore the caller of ‘iconv’
- has to make sure that the pointers passed are suitable for access of
- characters from the appropriate character set. Since, in the above
- case, the input parameter to the function is a ‘wchar_t’ pointer, this
- is the case (unless the user violates alignment when computing the
- parameter). But in other situations, especially when writing generic
- functions where one does not know what type of character set one uses
- and, therefore, treats text as a sequence of bytes, it might become
- tricky.
- File: libc.info, Node: Other iconv Implementations, Next: glibc iconv Implementation, Prev: iconv Examples, Up: Generic Charset Conversion
- 6.5.3 Some Details about other ‘iconv’ Implementations
- ------------------------------------------------------
- This is not really the place to discuss the ‘iconv’ implementation of
- other systems but it is necessary to know a bit about them to write
- portable programs. The above mentioned problems with the specification
- of the ‘iconv’ functions can lead to portability issues.
- The first thing to notice is that, due to the large number of
- character sets in use, it is certainly not practical to encode the
- conversions directly in the C library. Therefore, the conversion
- information must come from files outside the C library. This is usually
- done in one or both of the following ways:
- • The C library contains a set of generic conversion functions that
- can read the needed conversion tables and other information from
- data files. These files get loaded when necessary.
- This solution is problematic as it requires a great deal of effort
- to apply to all character sets (potentially an infinite set). The
- differences in the structure of the different character sets is so
- large that many different variants of the table-processing
- functions must be developed. In addition, the generic nature of
- these functions make them slower than specifically implemented
- functions.
- • The C library only contains a framework that can dynamically load
- object files and execute the conversion functions contained
- therein.
- This solution provides much more flexibility. The C library itself
- contains only very little code and therefore reduces the general
- memory footprint. Also, with a documented interface between the C
- library and the loadable modules it is possible for third parties
- to extend the set of available conversion modules. A drawback of
- this solution is that dynamic loading must be available.
- Some implementations in commercial Unices implement a mixture of
- these possibilities; the majority implement only the second solution.
- Using loadable modules moves the code out of the library itself and
- keeps the door open for extensions and improvements, but this design is
- also limiting on some platforms since not many platforms support dynamic
- loading in statically linked programs. On platforms without this
- capability it is therefore not possible to use this interface in
- statically linked programs. The GNU C Library has, on ELF platforms, no
- problems with dynamic loading in these situations; therefore, this point
- is moot. The danger is that one gets acquainted with this situation and
- forgets about the restrictions on other systems.
- A second thing to know about other ‘iconv’ implementations is that
- the number of available conversions is often very limited. Some
- implementations provide, in the standard release (not special
- international or developer releases), at most 100 to 200 conversion
- possibilities. This does not mean 200 different character sets are
- supported; for example, conversions from one character set to a set of
- 10 others might count as 10 conversions. Together with the other
- direction this makes 20 conversion possibilities used up by one
- character set. One can imagine the thin coverage these platforms
- provide. Some Unix vendors even provide only a handful of conversions,
- which renders them useless for almost all uses.
- This directly leads to a third and probably the most problematic
- point. The way the ‘iconv’ conversion functions are implemented on all
- known Unix systems and the availability of the conversion functions from
- character set A to B and the conversion from B to C does _not_ imply
- that the conversion from A to C is available.
- This might not seem unreasonable and problematic at first, but it is
- a quite big problem as one will notice shortly after hitting it. To
- show the problem we assume to write a program that has to convert from A
- to C. A call like
- cd = iconv_open ("C", "A");
- fails according to the assumption above. But what does the program do
- now? The conversion is necessary; therefore, simply giving up is not an
- option.
- This is a nuisance. The ‘iconv’ function should take care of this.
- But how should the program proceed from here on? If it tries to convert
- to character set B, first the two ‘iconv_open’ calls
- cd1 = iconv_open ("B", "A");
- and
- cd2 = iconv_open ("C", "B");
- will succeed, but how to find B?
- Unfortunately, the answer is: there is no general solution. On some
- systems guessing might help. On those systems most character sets can
- convert to and from UTF-8 encoded ISO 10646 or Unicode text. Besides
- this only some very system-specific methods can help. Since the
- conversion functions come from loadable modules and these modules must
- be stored somewhere in the filesystem, one _could_ try to find them and
- determine from the available file which conversions are available and
- whether there is an indirect route from A to C.
- This example shows one of the design errors of ‘iconv’ mentioned
- above. It should at least be possible to determine the list of
- available conversions programmatically so that if ‘iconv_open’ says
- there is no such conversion, one could make sure this also is true for
- indirect routes.
- File: libc.info, Node: glibc iconv Implementation, Prev: Other iconv Implementations, Up: Generic Charset Conversion
- 6.5.4 The ‘iconv’ Implementation in the GNU C Library
- -----------------------------------------------------
- After reading about the problems of ‘iconv’ implementations in the last
- section it is certainly good to note that the implementation in the GNU
- C Library has none of the problems mentioned above. What follows is a
- step-by-step analysis of the points raised above. The evaluation is
- based on the current state of the development (as of January 1999). The
- development of the ‘iconv’ functions is not complete, but basic
- functionality has solidified.
- The GNU C Library’s ‘iconv’ implementation uses shared loadable
- modules to implement the conversions. A very small number of
- conversions are built into the library itself but these are only rather
- trivial conversions.
- All the benefits of loadable modules are available in the GNU C
- Library implementation. This is especially appealing since the
- interface is well documented (see below), and it, therefore, is easy to
- write new conversion modules. The drawback of using loadable objects is
- not a problem in the GNU C Library, at least on ELF systems. Since the
- library is able to load shared objects even in statically linked
- binaries, static linking need not be forbidden in case one wants to use
- ‘iconv’.
- The second mentioned problem is the number of supported conversions.
- Currently, the GNU C Library supports more than 150 character sets. The
- way the implementation is designed the number of supported conversions
- is greater than 22350 (150 times 149). If any conversion from or to a
- character set is missing, it can be added easily.
- Particularly impressive as it may be, this high number is due to the
- fact that the GNU C Library implementation of ‘iconv’ does not have the
- third problem mentioned above (i.e., whenever there is a conversion from
- a character set A to B and from B to C it is always possible to convert
- from A to C directly). If the ‘iconv_open’ returns an error and sets
- ‘errno’ to ‘EINVAL’, there is no known way, directly or indirectly, to
- perform the wanted conversion.
- Triangulation is achieved by providing for each character set a
- conversion from and to UCS-4 encoded ISO 10646. Using ISO 10646 as an
- intermediate representation it is possible to "triangulate" (i.e.,
- convert with an intermediate representation).
- There is no inherent requirement to provide a conversion to ISO 10646
- for a new character set, and it is also possible to provide other
- conversions where neither source nor destination character set is
- ISO 10646. The existing set of conversions is simply meant to cover all
- conversions that might be of interest.
- All currently available conversions use the triangulation method
- above, making conversion run unnecessarily slow. If, for example,
- somebody often needs the conversion from ISO-2022-JP to EUC-JP, a
- quicker solution would involve direct conversion between the two
- character sets, skipping the input to ISO 10646 first. The two
- character sets of interest are much more similar to each other than to
- ISO 10646.
- In such a situation one easily can write a new conversion and provide
- it as a better alternative. The GNU C Library ‘iconv’ implementation
- would automatically use the module implementing the conversion if it is
- specified to be more efficient.
- 6.5.4.1 Format of ‘gconv-modules’ files
- .......................................
- All information about the available conversions comes from a file named
- ‘gconv-modules’, which can be found in any of the directories along the
- ‘GCONV_PATH’. The ‘gconv-modules’ files are line-oriented text files,
- where each of the lines has one of the following formats:
- • If the first non-whitespace character is a ‘#’ the line contains
- only comments and is ignored.
- • Lines starting with ‘alias’ define an alias name for a character
- set. Two more words are expected on the line. The first word
- defines the alias name, and the second defines the original name of
- the character set. The effect is that it is possible to use the
- alias name in the FROMSET or TOSET parameters of ‘iconv_open’ and
- achieve the same result as when using the real character set name.
- This is quite important as a character set has often many different
- names. There is normally an official name but this need not
- correspond to the most popular name. Besides this many character
- sets have special names that are somehow constructed. For example,
- all character sets specified by the ISO have an alias of the form
- ‘ISO-IR-NNN’ where NNN is the registration number. This allows
- programs that know about the registration number to construct
- character set names and use them in ‘iconv_open’ calls. More on
- the available names and aliases follows below.
- • Lines starting with ‘module’ introduce an available conversion
- module. These lines must contain three or four more words.
- The first word specifies the source character set, the second word
- the destination character set of conversion implemented in this
- module, and the third word is the name of the loadable module. The
- filename is constructed by appending the usual shared object suffix
- (normally ‘.so’) and this file is then supposed to be found in the
- same directory the ‘gconv-modules’ file is in. The last word on
- the line, which is optional, is a numeric value representing the
- cost of the conversion. If this word is missing, a cost of 1 is
- assumed. The numeric value itself does not matter that much; what
- counts are the relative values of the sums of costs for all
- possible conversion paths. Below is a more precise description of
- the use of the cost value.
- Returning to the example above where one has written a module to
- directly convert from ISO-2022-JP to EUC-JP and back. All that has to
- be done is to put the new module, let its name be ISO2022JP-EUCJP.so, in
- a directory and add a file ‘gconv-modules’ with the following content in
- the same directory:
- module ISO-2022-JP// EUC-JP// ISO2022JP-EUCJP 1
- module EUC-JP// ISO-2022-JP// ISO2022JP-EUCJP 1
- To see why this is sufficient, it is necessary to understand how the
- conversion used by ‘iconv’ (and described in the descriptor) is
- selected. The approach to this problem is quite simple.
- At the first call of the ‘iconv_open’ function the program reads all
- available ‘gconv-modules’ files and builds up two tables: one containing
- all the known aliases and another that contains the information about
- the conversions and which shared object implements them.
- 6.5.4.2 Finding the conversion path in ‘iconv’
- ..............................................
- The set of available conversions form a directed graph with weighted
- edges. The weights on the edges are the costs specified in the
- ‘gconv-modules’ files. The ‘iconv_open’ function uses an algorithm
- suitable for search for the best path in such a graph and so constructs
- a list of conversions that must be performed in succession to get the
- transformation from the source to the destination character set.
- Explaining why the above ‘gconv-modules’ files allows the ‘iconv’
- implementation to resolve the specific ISO-2022-JP to EUC-JP conversion
- module instead of the conversion coming with the library itself is
- straightforward. Since the latter conversion takes two steps (from
- ISO-2022-JP to ISO 10646 and then from ISO 10646 to EUC-JP), the cost is
- 1+1 = 2. The above ‘gconv-modules’ file, however, specifies that the
- new conversion modules can perform this conversion with only the cost of
- 1.
- A mysterious item about the ‘gconv-modules’ file above (and also the
- file coming with the GNU C Library) are the names of the character sets
- specified in the ‘module’ lines. Why do almost all the names end in
- ‘//’? And this is not all: the names can actually be regular
- expressions. At this point in time this mystery should not be revealed,
- unless you have the relevant spell-casting materials: ashes from an
- original DOS 6.2 boot disk burnt in effigy, a crucifix blessed by St.
- Emacs, assorted herbal roots from Central America, sand from Cebu, etc.
- Sorry! *The part of the implementation where this is used is not yet
- finished. For now please simply follow the existing examples. It’ll
- become clearer once it is. –drepper*
- A last remark about the ‘gconv-modules’ is about the names not ending
- with ‘//’. A character set named ‘INTERNAL’ is often mentioned. From
- the discussion above and the chosen name it should have become clear
- that this is the name for the representation used in the intermediate
- step of the triangulation. We have said that this is UCS-4 but actually
- that is not quite right. The UCS-4 specification also includes the
- specification of the byte ordering used. Since a UCS-4 value consists
- of four bytes, a stored value is affected by byte ordering. The
- internal representation is _not_ the same as UCS-4 in case the byte
- ordering of the processor (or at least the running process) is not the
- same as the one required for UCS-4. This is done for performance
- reasons as one does not want to perform unnecessary byte-swapping
- operations if one is not interested in actually seeing the result in
- UCS-4. To avoid trouble with endianness, the internal representation
- consistently is named ‘INTERNAL’ even on big-endian systems where the
- representations are identical.
- 6.5.4.3 ‘iconv’ module data structures
- ......................................
- So far this section has described how modules are located and considered
- to be used. What remains to be described is the interface of the
- modules so that one can write new ones. This section describes the
- interface as it is in use in January 1999. The interface will change a
- bit in the future but, with luck, only in an upwardly compatible way.
- The definitions necessary to write new modules are publicly available
- in the non-standard header ‘gconv.h’. The following text, therefore,
- describes the definitions from this header file. First, however, it is
- necessary to get an overview.
- From the perspective of the user of ‘iconv’ the interface is quite
- simple: the ‘iconv_open’ function returns a handle that can be used in
- calls to ‘iconv’, and finally the handle is freed with a call to
- ‘iconv_close’. The problem is that the handle has to be able to
- represent the possibly long sequences of conversion steps and also the
- state of each conversion since the handle is all that is passed to the
- ‘iconv’ function. Therefore, the data structures are really the
- elements necessary to understanding the implementation.
- We need two different kinds of data structures. The first describes
- the conversion and the second describes the state etc. There are really
- two type definitions like this in ‘gconv.h’.
- -- Data type: struct __gconv_step
- This data structure describes one conversion a module can perform.
- For each function in a loaded module with conversion functions
- there is exactly one object of this type. This object is shared by
- all users of the conversion (i.e., this object does not contain any
- information corresponding to an actual conversion; it only
- describes the conversion itself).
- ‘struct __gconv_loaded_object *__shlib_handle’
- ‘const char *__modname’
- ‘int __counter’
- All these elements of the structure are used internally in the
- C library to coordinate loading and unloading the shared
- object. One must not expect any of the other elements to be
- available or initialized.
- ‘const char *__from_name’
- ‘const char *__to_name’
- ‘__from_name’ and ‘__to_name’ contain the names of the source
- and destination character sets. They can be used to identify
- the actual conversion to be carried out since one module might
- implement conversions for more than one character set and/or
- direction.
- ‘gconv_fct __fct’
- ‘gconv_init_fct __init_fct’
- ‘gconv_end_fct __end_fct’
- These elements contain pointers to the functions in the
- loadable module. The interface will be explained below.
- ‘int __min_needed_from’
- ‘int __max_needed_from’
- ‘int __min_needed_to’
- ‘int __max_needed_to;’
- These values have to be supplied in the init function of the
- module. The ‘__min_needed_from’ value specifies how many
- bytes a character of the source character set at least needs.
- The ‘__max_needed_from’ specifies the maximum value that also
- includes possible shift sequences.
- The ‘__min_needed_to’ and ‘__max_needed_to’ values serve the
- same purpose as ‘__min_needed_from’ and ‘__max_needed_from’
- but this time for the destination character set.
- It is crucial that these values be accurate since otherwise
- the conversion functions will have problems or not work at
- all.
- ‘int __stateful’
- This element must also be initialized by the init function.
- ‘int __stateful’ is nonzero if the source character set is
- stateful. Otherwise it is zero.
- ‘void *__data’
- This element can be used freely by the conversion functions in
- the module. ‘void *__data’ can be used to communicate extra
- information from one call to another. ‘void *__data’ need not
- be initialized if not needed at all. If ‘void *__data’
- element is assigned a pointer to dynamically allocated memory
- (presumably in the init function) it has to be made sure that
- the end function deallocates the memory. Otherwise the
- application will leak memory.
- It is important to be aware that this data structure is shared
- by all users of this specification conversion and therefore
- the ‘__data’ element must not contain data specific to one
- specific use of the conversion function.
- -- Data type: struct __gconv_step_data
- This is the data structure that contains the information specific
- to each use of the conversion functions.
- ‘char *__outbuf’
- ‘char *__outbufend’
- These elements specify the output buffer for the conversion
- step. The ‘__outbuf’ element points to the beginning of the
- buffer, and ‘__outbufend’ points to the byte following the
- last byte in the buffer. The conversion function must not
- assume anything about the size of the buffer but it can be
- safely assumed there is room for at least one complete
- character in the output buffer.
- Once the conversion is finished, if the conversion is the last
- step, the ‘__outbuf’ element must be modified to point after
- the last byte written into the buffer to signal how much
- output is available. If this conversion step is not the last
- one, the element must not be modified. The ‘__outbufend’
- element must not be modified.
- ‘int __is_last’
- This element is nonzero if this conversion step is the last
- one. This information is necessary for the recursion. See
- the description of the conversion function internals below.
- This element must never be modified.
- ‘int __invocation_counter’
- The conversion function can use this element to see how many
- calls of the conversion function already happened. Some
- character sets require a certain prolog when generating
- output, and by comparing this value with zero, one can find
- out whether it is the first call and whether, therefore, the
- prolog should be emitted. This element must never be
- modified.
- ‘int __internal_use’
- This element is another one rarely used but needed in certain
- situations. It is assigned a nonzero value in case the
- conversion functions are used to implement ‘mbsrtowcs’ et.al.
- (i.e., the function is not used directly through the ‘iconv’
- interface).
- This sometimes makes a difference as it is expected that the
- ‘iconv’ functions are used to translate entire texts while the
- ‘mbsrtowcs’ functions are normally used only to convert single
- strings and might be used multiple times to convert entire
- texts.
- But in this situation we would have problem complying with
- some rules of the character set specification. Some character
- sets require a prolog, which must appear exactly once for an
- entire text. If a number of ‘mbsrtowcs’ calls are used to
- convert the text, only the first call must add the prolog.
- However, because there is no communication between the
- different calls of ‘mbsrtowcs’, the conversion functions have
- no possibility to find this out. The situation is different
- for sequences of ‘iconv’ calls since the handle allows access
- to the needed information.
- The ‘int __internal_use’ element is mostly used together with
- ‘__invocation_counter’ as follows:
- if (!data->__internal_use
- && data->__invocation_counter == 0)
- /* Emit prolog. */
- …
- This element must never be modified.
- ‘mbstate_t *__statep’
- The ‘__statep’ element points to an object of type ‘mbstate_t’
- (*note Keeping the state::). The conversion of a stateful
- character set must use the object pointed to by ‘__statep’ to
- store information about the conversion state. The ‘__statep’
- element itself must never be modified.
- ‘mbstate_t __state’
- This element must _never_ be used directly. It is only part
- of this structure to have the needed space allocated.
- 6.5.4.4 ‘iconv’ module interfaces
- .................................
- With the knowledge about the data structures we now can describe the
- conversion function itself. To understand the interface a bit of
- knowledge is necessary about the functionality in the C library that
- loads the objects with the conversions.
- It is often the case that one conversion is used more than once
- (i.e., there are several ‘iconv_open’ calls for the same set of
- character sets during one program run). The ‘mbsrtowcs’ et.al.
- functions in the GNU C Library also use the ‘iconv’ functionality, which
- increases the number of uses of the same functions even more.
- Because of this multiple use of conversions, the modules do not get
- loaded exclusively for one conversion. Instead a module once loaded can
- be used by an arbitrary number of ‘iconv’ or ‘mbsrtowcs’ calls at the
- same time. The splitting of the information between conversion-
- function-specific information and conversion data makes this possible.
- The last section showed the two data structures used to do this.
- This is of course also reflected in the interface and semantics of
- the functions that the modules must provide. There are three functions
- that must have the following names:
- ‘gconv_init’
- The ‘gconv_init’ function initializes the conversion function
- specific data structure. This very same object is shared by all
- conversions that use this conversion and, therefore, no state
- information about the conversion itself must be stored in here. If
- a module implements more than one conversion, the ‘gconv_init’
- function will be called multiple times.
- ‘gconv_end’
- The ‘gconv_end’ function is responsible for freeing all resources
- allocated by the ‘gconv_init’ function. If there is nothing to do,
- this function can be missing. Special care must be taken if the
- module implements more than one conversion and the ‘gconv_init’
- function does not allocate the same resources for all conversions.
- ‘gconv’
- This is the actual conversion function. It is called to convert
- one block of text. It gets passed the conversion step information
- initialized by ‘gconv_init’ and the conversion data, specific to
- this use of the conversion functions.
- There are three data types defined for the three module interface
- functions and these define the interface.
- -- Data type: int (*__gconv_init_fct) (struct __gconv_step *)
- This specifies the interface of the initialization function of the
- module. It is called exactly once for each conversion the module
- implements.
- As explained in the description of the ‘struct __gconv_step’ data
- structure above the initialization function has to initialize parts
- of it.
- ‘__min_needed_from’
- ‘__max_needed_from’
- ‘__min_needed_to’
- ‘__max_needed_to’
- These elements must be initialized to the exact numbers of the
- minimum and maximum number of bytes used by one character in
- the source and destination character sets, respectively. If
- the characters all have the same size, the minimum and maximum
- values are the same.
- ‘__stateful’
- This element must be initialized to a nonzero value if the
- source character set is stateful. Otherwise it must be zero.
- If the initialization function needs to communicate some
- information to the conversion function, this communication can
- happen using the ‘__data’ element of the ‘__gconv_step’ structure.
- But since this data is shared by all the conversions, it must not
- be modified by the conversion function. The example below shows
- how this can be used.
- #define MIN_NEEDED_FROM 1
- #define MAX_NEEDED_FROM 4
- #define MIN_NEEDED_TO 4
- #define MAX_NEEDED_TO 4
- int
- gconv_init (struct __gconv_step *step)
- {
- /* Determine which direction. */
- struct iso2022jp_data *new_data;
- enum direction dir = illegal_dir;
- enum variant var = illegal_var;
- int result;
- if (__strcasecmp (step->__from_name, "ISO-2022-JP//") == 0)
- {
- dir = from_iso2022jp;
- var = iso2022jp;
- }
- else if (__strcasecmp (step->__to_name, "ISO-2022-JP//") == 0)
- {
- dir = to_iso2022jp;
- var = iso2022jp;
- }
- else if (__strcasecmp (step->__from_name, "ISO-2022-JP-2//") == 0)
- {
- dir = from_iso2022jp;
- var = iso2022jp2;
- }
- else if (__strcasecmp (step->__to_name, "ISO-2022-JP-2//") == 0)
- {
- dir = to_iso2022jp;
- var = iso2022jp2;
- }
- result = __GCONV_NOCONV;
- if (dir != illegal_dir)
- {
- new_data = (struct iso2022jp_data *)
- malloc (sizeof (struct iso2022jp_data));
- result = __GCONV_NOMEM;
- if (new_data != NULL)
- {
- new_data->dir = dir;
- new_data->var = var;
- step->__data = new_data;
- if (dir == from_iso2022jp)
- {
- step->__min_needed_from = MIN_NEEDED_FROM;
- step->__max_needed_from = MAX_NEEDED_FROM;
- step->__min_needed_to = MIN_NEEDED_TO;
- step->__max_needed_to = MAX_NEEDED_TO;
- }
- else
- {
- step->__min_needed_from = MIN_NEEDED_TO;
- step->__max_needed_from = MAX_NEEDED_TO;
- step->__min_needed_to = MIN_NEEDED_FROM;
- step->__max_needed_to = MAX_NEEDED_FROM + 2;
- }
- /* Yes, this is a stateful encoding. */
- step->__stateful = 1;
- result = __GCONV_OK;
- }
- }
- return result;
- }
- The function first checks which conversion is wanted. The module
- from which this function is taken implements four different
- conversions; which one is selected can be determined by comparing
- the names. The comparison should always be done without paying
- attention to the case.
- Next, a data structure, which contains the necessary information
- about which conversion is selected, is allocated. The data
- structure ‘struct iso2022jp_data’ is locally defined since, outside
- the module, this data is not used at all. Please note that if all
- four conversions this module supports are requested there are four
- data blocks.
- One interesting thing is the initialization of the ‘__min_’ and
- ‘__max_’ elements of the step data object. A single ISO-2022-JP
- character can consist of one to four bytes. Therefore the
- ‘MIN_NEEDED_FROM’ and ‘MAX_NEEDED_FROM’ macros are defined this
- way. The output is always the ‘INTERNAL’ character set (aka UCS-4)
- and therefore each character consists of exactly four bytes. For
- the conversion from ‘INTERNAL’ to ISO-2022-JP we have to take into
- account that escape sequences might be necessary to switch the
- character sets. Therefore the ‘__max_needed_to’ element for this
- direction gets assigned ‘MAX_NEEDED_FROM + 2’. This takes into
- account the two bytes needed for the escape sequences to signal the
- switching. The asymmetry in the maximum values for the two
- directions can be explained easily: when reading ISO-2022-JP text,
- escape sequences can be handled alone (i.e., it is not necessary to
- process a real character since the effect of the escape sequence
- can be recorded in the state information). The situation is
- different for the other direction. Since it is in general not
- known which character comes next, one cannot emit escape sequences
- to change the state in advance. This means the escape sequences
- have to be emitted together with the next character. Therefore one
- needs more room than only for the character itself.
- The possible return values of the initialization function are:
- ‘__GCONV_OK’
- The initialization succeeded
- ‘__GCONV_NOCONV’
- The requested conversion is not supported in the module. This
- can happen if the ‘gconv-modules’ file has errors.
- ‘__GCONV_NOMEM’
- Memory required to store additional information could not be
- allocated.
- The function called before the module is unloaded is significantly
- easier. It often has nothing at all to do; in which case it can be left
- out completely.
- -- Data type: void (*__gconv_end_fct) (struct gconv_step *)
- The task of this function is to free all resources allocated in the
- initialization function. Therefore only the ‘__data’ element of
- the object pointed to by the argument is of interest. Continuing
- the example from the initialization function, the finalization
- function looks like this:
- void
- gconv_end (struct __gconv_step *data)
- {
- free (data->__data);
- }
- The most important function is the conversion function itself, which
- can get quite complicated for complex character sets. But since this is
- not of interest here, we will only describe a possible skeleton for the
- conversion function.
- -- Data type: int (*__gconv_fct) (struct __gconv_step *, struct
- __gconv_step_data *, const char **, const char *, size_t *,
- int)
- The conversion function can be called for two basic reasons: to
- convert text or to reset the state. From the description of the
- ‘iconv’ function it can be seen why the flushing mode is necessary.
- What mode is selected is determined by the sixth argument, an
- integer. This argument being nonzero means that flushing is
- selected.
- Common to both modes is where the output buffer can be found. The
- information about this buffer is stored in the conversion step
- data. A pointer to this information is passed as the second
- argument to this function. The description of the ‘struct
- __gconv_step_data’ structure has more information on the conversion
- step data.
- What has to be done for flushing depends on the source character
- set. If the source character set is not stateful, nothing has to
- be done. Otherwise the function has to emit a byte sequence to
- bring the state object into the initial state. Once this all
- happened the other conversion modules in the chain of conversions
- have to get the same chance. Whether another step follows can be
- determined from the ‘__is_last’ element of the step data structure
- to which the first parameter points.
- The more interesting mode is when actual text has to be converted.
- The first step in this case is to convert as much text as possible
- from the input buffer and store the result in the output buffer.
- The start of the input buffer is determined by the third argument,
- which is a pointer to a pointer variable referencing the beginning
- of the buffer. The fourth argument is a pointer to the byte right
- after the last byte in the buffer.
- The conversion has to be performed according to the current state
- if the character set is stateful. The state is stored in an object
- pointed to by the ‘__statep’ element of the step data (second
- argument). Once either the input buffer is empty or the output
- buffer is full the conversion stops. At this point, the pointer
- variable referenced by the third parameter must point to the byte
- following the last processed byte (i.e., if all of the input is
- consumed, this pointer and the fourth parameter have the same
- value).
- What now happens depends on whether this step is the last one. If
- it is the last step, the only thing that has to be done is to
- update the ‘__outbuf’ element of the step data structure to point
- after the last written byte. This update gives the caller the
- information on how much text is available in the output buffer. In
- addition, the variable pointed to by the fifth parameter, which is
- of type ‘size_t’, must be incremented by the number of characters
- (_not bytes_) that were converted in a non-reversible way. Then,
- the function can return.
- In case the step is not the last one, the later conversion
- functions have to get a chance to do their work. Therefore, the
- appropriate conversion function has to be called. The information
- about the functions is stored in the conversion data structures,
- passed as the first parameter. This information and the step data
- are stored in arrays, so the next element in both cases can be
- found by simple pointer arithmetic:
- int
- gconv (struct __gconv_step *step, struct __gconv_step_data *data,
- const char **inbuf, const char *inbufend, size_t *written,
- int do_flush)
- {
- struct __gconv_step *next_step = step + 1;
- struct __gconv_step_data *next_data = data + 1;
- …
- The ‘next_step’ pointer references the next step information and
- ‘next_data’ the next data record. The call of the next function
- therefore will look similar to this:
- next_step->__fct (next_step, next_data, &outerr, outbuf,
- written, 0)
- But this is not yet all. Once the function call returns the
- conversion function might have some more to do. If the return
- value of the function is ‘__GCONV_EMPTY_INPUT’, more room is
- available in the output buffer. Unless the input buffer is empty,
- the conversion functions start all over again and process the rest
- of the input buffer. If the return value is not
- ‘__GCONV_EMPTY_INPUT’, something went wrong and we have to recover
- from this.
- A requirement for the conversion function is that the input buffer
- pointer (the third argument) always point to the last character
- that was put in converted form into the output buffer. This is
- trivially true after the conversion performed in the current step,
- but if the conversion functions deeper downstream stop prematurely,
- not all characters from the output buffer are consumed and,
- therefore, the input buffer pointers must be backed off to the
- right position.
- Correcting the input buffers is easy to do if the input and output
- character sets have a fixed width for all characters. In this
- situation we can compute how many characters are left in the output
- buffer and, therefore, can correct the input buffer pointer
- appropriately with a similar computation. Things are getting
- tricky if either character set has characters represented with
- variable length byte sequences, and it gets even more complicated
- if the conversion has to take care of the state. In these cases
- the conversion has to be performed once again, from the known state
- before the initial conversion (i.e., if necessary the state of the
- conversion has to be reset and the conversion loop has to be
- executed again). The difference now is that it is known how much
- input must be created, and the conversion can stop before
- converting the first unused character. Once this is done the input
- buffer pointers must be updated again and the function can return.
- One final thing should be mentioned. If it is necessary for the
- conversion to know whether it is the first invocation (in case a
- prolog has to be emitted), the conversion function should increment
- the ‘__invocation_counter’ element of the step data structure just
- before returning to the caller. See the description of the ‘struct
- __gconv_step_data’ structure above for more information on how this
- can be used.
- The return value must be one of the following values:
- ‘__GCONV_EMPTY_INPUT’
- All input was consumed and there is room left in the output
- buffer.
- ‘__GCONV_FULL_OUTPUT’
- No more room in the output buffer. In case this is not the
- last step this value is propagated down from the call of the
- next conversion function in the chain.
- ‘__GCONV_INCOMPLETE_INPUT’
- The input buffer is not entirely empty since it contains an
- incomplete character sequence.
- The following example provides a framework for a conversion
- function. In case a new conversion has to be written the holes in
- this implementation have to be filled and that is it.
- int
- gconv (struct __gconv_step *step, struct __gconv_step_data *data,
- const char **inbuf, const char *inbufend, size_t *written,
- int do_flush)
- {
- struct __gconv_step *next_step = step + 1;
- struct __gconv_step_data *next_data = data + 1;
- gconv_fct fct = next_step->__fct;
- int status;
- /* If the function is called with no input this means we have
- to reset to the initial state. The possibly partly
- converted input is dropped. */
- if (do_flush)
- {
- status = __GCONV_OK;
- /* Possible emit a byte sequence which put the state object
- into the initial state. */
- /* Call the steps down the chain if there are any but only
- if we successfully emitted the escape sequence. */
- if (status == __GCONV_OK && ! data->__is_last)
- status = fct (next_step, next_data, NULL, NULL,
- written, 1);
- }
- else
- {
- /* We preserve the initial values of the pointer variables. */
- const char *inptr = *inbuf;
- char *outbuf = data->__outbuf;
- char *outend = data->__outbufend;
- char *outptr;
- do
- {
- /* Remember the start value for this round. */
- inptr = *inbuf;
- /* The outbuf buffer is empty. */
- outptr = outbuf;
- /* For stateful encodings the state must be safe here. */
- /* Run the conversion loop. ‘status’ is set
- appropriately afterwards. */
- /* If this is the last step, leave the loop. There is
- nothing we can do. */
- if (data->__is_last)
- {
- /* Store information about how many bytes are
- available. */
- data->__outbuf = outbuf;
- /* If any non-reversible conversions were performed,
- add the number to ‘*written’. */
- break;
- }
- /* Write out all output that was produced. */
- if (outbuf > outptr)
- {
- const char *outerr = data->__outbuf;
- int result;
- result = fct (next_step, next_data, &outerr,
- outbuf, written, 0);
- if (result != __GCONV_EMPTY_INPUT)
- {
- if (outerr != outbuf)
- {
- /* Reset the input buffer pointer. We
- document here the complex case. */
- size_t nstatus;
- /* Reload the pointers. */
- *inbuf = inptr;
- outbuf = outptr;
- /* Possibly reset the state. */
- /* Redo the conversion, but this time
- the end of the output buffer is at
- ‘outerr’. */
- }
- /* Change the status. */
- status = result;
- }
- else
- /* All the output is consumed, we can make
- another run if everything was ok. */
- if (status == __GCONV_FULL_OUTPUT)
- status = __GCONV_OK;
- }
- }
- while (status == __GCONV_OK);
- /* We finished one use of this step. */
- ++data->__invocation_counter;
- }
- return status;
- }
- This information should be sufficient to write new modules. Anybody
- doing so should also take a look at the available source code in the GNU
- C Library sources. It contains many examples of working and optimized
- modules.
- File: libc.info, Node: Locales, Next: Message Translation, Prev: Character Set Handling, Up: Top
- 7 Locales and Internationalization
- **********************************
- Different countries and cultures have varying conventions for how to
- communicate. These conventions range from very simple ones, such as the
- format for representing dates and times, to very complex ones, such as
- the language spoken.
- "Internationalization" of software means programming it to be able to
- adapt to the user’s favorite conventions. In ISO C,
- internationalization works by means of "locales". Each locale specifies
- a collection of conventions, one convention for each purpose. The user
- chooses a set of conventions by specifying a locale (via environment
- variables).
- All programs inherit the chosen locale as part of their environment.
- Provided the programs are written to obey the choice of locale, they
- will follow the conventions preferred by the user.
- * Menu:
- * Effects of Locale:: Actions affected by the choice of
- locale.
- * Choosing Locale:: How the user specifies a locale.
- * Locale Categories:: Different purposes for which you can
- select a locale.
- * Setting the Locale:: How a program specifies the locale
- with library functions.
- * Standard Locales:: Locale names available on all systems.
- * Locale Names:: Format of system-specific locale names.
- * Locale Information:: How to access the information for the locale.
- * Formatting Numbers:: A dedicated function to format numbers.
- * Yes-or-No Questions:: Check a Response against the locale.
- File: libc.info, Node: Effects of Locale, Next: Choosing Locale, Up: Locales
- 7.1 What Effects a Locale Has
- =============================
- Each locale specifies conventions for several purposes, including the
- following:
- • What multibyte character sequences are valid, and how they are
- interpreted (*note Character Set Handling::).
- • Classification of which characters in the local character set are
- considered alphabetic, and upper- and lower-case conversion
- conventions (*note Character Handling::).
- • The collating sequence for the local language and character set
- (*note Collation Functions::).
- • Formatting of numbers and currency amounts (*note General
- Numeric::).
- • Formatting of dates and times (*note Formatting Calendar Time::).
- • What language to use for output, including error messages (*note
- Message Translation::).
- • What language to use for user answers to yes-or-no questions (*note
- Yes-or-No Questions::).
- • What language to use for more complex user input. (The C library
- doesn’t yet help you implement this.)
- Some aspects of adapting to the specified locale are handled
- automatically by the library subroutines. For example, all your program
- needs to do in order to use the collating sequence of the chosen locale
- is to use ‘strcoll’ or ‘strxfrm’ to compare strings.
- Other aspects of locales are beyond the comprehension of the library.
- For example, the library can’t automatically translate your program’s
- output messages into other languages. The only way you can support
- output in the user’s favorite language is to program this more or less
- by hand. The C library provides functions to handle translations for
- multiple languages easily.
- This chapter discusses the mechanism by which you can modify the
- current locale. The effects of the current locale on specific library
- functions are discussed in more detail in the descriptions of those
- functions.
- File: libc.info, Node: Choosing Locale, Next: Locale Categories, Prev: Effects of Locale, Up: Locales
- 7.2 Choosing a Locale
- =====================
- The simplest way for the user to choose a locale is to set the
- environment variable ‘LANG’. This specifies a single locale to use for
- all purposes. For example, a user could specify a hypothetical locale
- named ‘espana-castellano’ to use the standard conventions of most of
- Spain.
- The set of locales supported depends on the operating system you are
- using, and so do their names, except that the standard locale called ‘C’
- or ‘POSIX’ always exist. *Note Locale Names::.
- In order to force the system to always use the default locale, the
- user can set the ‘LC_ALL’ environment variable to ‘C’.
- A user also has the option of specifying different locales for
- different purposes—in effect, choosing a mixture of multiple locales.
- *Note Locale Categories::.
- For example, the user might specify the locale ‘espana-castellano’
- for most purposes, but specify the locale ‘usa-english’ for currency
- formatting. This might make sense if the user is a Spanish-speaking
- American, working in Spanish, but representing monetary amounts in US
- dollars.
- Note that both locales ‘espana-castellano’ and ‘usa-english’, like
- all locales, would include conventions for all of the purposes to which
- locales apply. However, the user can choose to use each locale for a
- particular subset of those purposes.
- File: libc.info, Node: Locale Categories, Next: Setting the Locale, Prev: Choosing Locale, Up: Locales
- 7.3 Locale Categories
- =====================
- The purposes that locales serve are grouped into "categories", so that a
- user or a program can choose the locale for each category independently.
- Here is a table of categories; each name is both an environment variable
- that a user can set, and a macro name that you can use as the first
- argument to ‘setlocale’.
- The contents of the environment variable (or the string in the second
- argument to ‘setlocale’) has to be a valid locale name. *Note Locale
- Names::.
- ‘LC_COLLATE’
- This category applies to collation of strings (functions ‘strcoll’
- and ‘strxfrm’); see *note Collation Functions::.
- ‘LC_CTYPE’
- This category applies to classification and conversion of
- characters, and to multibyte and wide characters; see *note
- Character Handling::, and *note Character Set Handling::.
- ‘LC_MONETARY’
- This category applies to formatting monetary values; see *note
- General Numeric::.
- ‘LC_NUMERIC’
- This category applies to formatting numeric values that are not
- monetary; see *note General Numeric::.
- ‘LC_TIME’
- This category applies to formatting date and time values; see *note
- Formatting Calendar Time::.
- ‘LC_MESSAGES’
- This category applies to selecting the language used in the user
- interface for message translation (*note The Uniforum approach::;
- *note Message catalogs a la X/Open::) and contains regular
- expressions for affirmative and negative responses.
- ‘LC_ALL’
- This is not a category; it is only a macro that you can use with
- ‘setlocale’ to set a single locale for all purposes. Setting this
- environment variable overwrites all selections by the other ‘LC_*’
- variables or ‘LANG’.
- ‘LANG’
- If this environment variable is defined, its value specifies the
- locale to use for all purposes except as overridden by the
- variables above.
- When developing the message translation functions it was felt that
- the functionality provided by the variables above is not sufficient.
- For example, it should be possible to specify more than one locale name.
- Take a Swedish user who better speaks German than English, and a program
- whose messages are output in English by default. It should be possible
- to specify that the first choice of language is Swedish, the second
- German, and if this also fails to use English. This is possible with
- the variable ‘LANGUAGE’. For further description of this GNU extension
- see *note Using gettextized software::.
- File: libc.info, Node: Setting the Locale, Next: Standard Locales, Prev: Locale Categories, Up: Locales
- 7.4 How Programs Set the Locale
- ===============================
- A C program inherits its locale environment variables when it starts up.
- This happens automatically. However, these variables do not
- automatically control the locale used by the library functions, because ISO C
- says that all programs start by default in the standard ‘C’ locale. To
- use the locales specified by the environment, you must call ‘setlocale’.
- Call it as follows:
- setlocale (LC_ALL, "");
- to select a locale based on the user choice of the appropriate
- environment variables.
- You can also use ‘setlocale’ to specify a particular locale, for
- general use or for a specific category.
- The symbols in this section are defined in the header file
- ‘locale.h’.
- -- Function: char * setlocale (int CATEGORY, const char *LOCALE)
- Preliminary: | MT-Unsafe const:locale env | AS-Unsafe init lock
- heap corrupt | AC-Unsafe init corrupt lock mem fd | *Note POSIX
- Safety Concepts::.
- The function ‘setlocale’ sets the current locale for category
- CATEGORY to LOCALE.
- If CATEGORY is ‘LC_ALL’, this specifies the locale for all
- purposes. The other possible values of CATEGORY specify a single
- purpose (*note Locale Categories::).
- You can also use this function to find out the current locale by
- passing a null pointer as the LOCALE argument. In this case,
- ‘setlocale’ returns a string that is the name of the locale
- currently selected for category CATEGORY.
- The string returned by ‘setlocale’ can be overwritten by subsequent
- calls, so you should make a copy of the string (*note Copying
- Strings and Arrays::) if you want to save it past any further calls
- to ‘setlocale’. (The standard library is guaranteed never to call
- ‘setlocale’ itself.)
- You should not modify the string returned by ‘setlocale’. It might
- be the same string that was passed as an argument in a previous
- call to ‘setlocale’. One requirement is that the CATEGORY must be
- the same in the call the string was returned and the one when the
- string is passed in as LOCALE parameter.
- When you read the current locale for category ‘LC_ALL’, the value
- encodes the entire combination of selected locales for all
- categories. If you specify the same “locale name” with ‘LC_ALL’ in
- a subsequent call to ‘setlocale’, it restores the same combination
- of locale selections.
- To be sure you can use the returned string encoding the currently
- selected locale at a later time, you must make a copy of the
- string. It is not guaranteed that the returned pointer remains
- valid over time.
- When the LOCALE argument is not a null pointer, the string returned
- by ‘setlocale’ reflects the newly-modified locale.
- If you specify an empty string for LOCALE, this means to read the
- appropriate environment variable and use its value to select the
- locale for CATEGORY.
- If a nonempty string is given for LOCALE, then the locale of that
- name is used if possible.
- The effective locale name (either the second argument to
- ‘setlocale’, or if the argument is an empty string, the name
- obtained from the process environment) must be a valid locale name.
- *Note Locale Names::.
- If you specify an invalid locale name, ‘setlocale’ returns a null
- pointer and leaves the current locale unchanged.
- Here is an example showing how you might use ‘setlocale’ to
- temporarily switch to a new locale.
- #include <stddef.h>
- #include <locale.h>
- #include <stdlib.h>
- #include <string.h>
- void
- with_other_locale (char *new_locale,
- void (*subroutine) (int),
- int argument)
- {
- char *old_locale, *saved_locale;
- /* Get the name of the current locale. */
- old_locale = setlocale (LC_ALL, NULL);
- /* Copy the name so it won’t be clobbered by ‘setlocale’. */
- saved_locale = strdup (old_locale);
- if (saved_locale == NULL)
- fatal ("Out of memory");
- /* Now change the locale and do some stuff with it. */
- setlocale (LC_ALL, new_locale);
- (*subroutine) (argument);
- /* Restore the original locale. */
- setlocale (LC_ALL, saved_locale);
- free (saved_locale);
- }
- *Portability Note:* Some ISO C systems may define additional locale
- categories, and future versions of the library will do so. For
- portability, assume that any symbol beginning with ‘LC_’ might be
- defined in ‘locale.h’.
- File: libc.info, Node: Standard Locales, Next: Locale Names, Prev: Setting the Locale, Up: Locales
- 7.5 Standard Locales
- ====================
- The only locale names you can count on finding on all operating systems
- are these three standard ones:
- ‘"C"’
- This is the standard C locale. The attributes and behavior it
- provides are specified in the ISO C standard. When your program
- starts up, it initially uses this locale by default.
- ‘"POSIX"’
- This is the standard POSIX locale. Currently, it is an alias for
- the standard C locale.
- ‘""’
- The empty name says to select a locale based on environment
- variables. *Note Locale Categories::.
- Defining and installing named locales is normally a responsibility of
- the system administrator at your site (or the person who installed the
- GNU C Library). It is also possible for the user to create private
- locales. All this will be discussed later when describing the tool to
- do so.
- If your program needs to use something other than the ‘C’ locale, it
- will be more portable if you use whatever locale the user specifies with
- the environment, rather than trying to specify some non-standard locale
- explicitly by name. Remember, different machines might have different
- sets of locales installed.
- File: libc.info, Node: Locale Names, Next: Locale Information, Prev: Standard Locales, Up: Locales
- 7.6 Locale Names
- ================
- The following command prints a list of locales supported by the system:
- locale -a
- *Portability Note:* With the notable exception of the standard locale
- names ‘C’ and ‘POSIX’, locale names are system-specific.
- Most locale names follow XPG syntax and consist of up to four parts:
- LANGUAGE[_TERRITORY[.CODESET]][@MODIFIER]
- Beside the first part, all of them are allowed to be missing. If the
- full specified locale is not found, less specific ones are looked for.
- The various parts will be stripped off, in the following order:
- 1. codeset
- 2. normalized codeset
- 3. territory
- 4. modifier
- For example, the locale name ‘de_AT.iso885915@euro’ denotes a
- German-language locale for use in Austria, using the ISO-8859-15
- (Latin-9) character set, and with the Euro as the currency symbol.
- In addition to locale names which follow XPG syntax, systems may
- provide aliases such as ‘german’. Both categories of names must not
- contain the slash character ‘/’.
- If the locale name starts with a slash ‘/’, it is treated as a path
- relative to the configured locale directories; see ‘LOCPATH’ below. The
- specified path must not contain a component ‘..’, or the name is
- invalid, and ‘setlocale’ will fail.
- *Portability Note:* POSIX suggests that if a locale name starts with
- a slash ‘/’, it is resolved as an absolute path. However, the GNU C
- Library treats it as a relative path under the directories listed in
- ‘LOCPATH’ (or the default locale directory if ‘LOCPATH’ is unset).
- Locale names which are longer than an implementation-defined limit
- are invalid and cause ‘setlocale’ to fail.
- As a special case, locale names used with ‘LC_ALL’ can combine
- several locales, reflecting different locale settings for different
- categories. For example, you might want to use a U.S. locale with ISO
- A4 paper format, so you set ‘LANG’ to ‘en_US.UTF-8’, and ‘LC_PAPER’ to
- ‘de_DE.UTF-8’. In this case, the ‘LC_ALL’-style combined locale name is
- LC_CTYPE=en_US.UTF-8;LC_TIME=en_US.UTF-8;LC_PAPER=de_DE.UTF-8;…
- followed by other category settings not shown here.
- The path used for finding locale data can be set using the ‘LOCPATH’
- environment variable. This variable lists the directories in which to
- search for locale definitions, separated by a colon ‘:’.
- The default path for finding locale data is system specific. A
- typical value for the ‘LOCPATH’ default is:
- /usr/share/locale
- The value of ‘LOCPATH’ is ignored by privileged programs for security
- reasons, and only the default directory is used.
- File: libc.info, Node: Locale Information, Next: Formatting Numbers, Prev: Locale Names, Up: Locales
- 7.7 Accessing Locale Information
- ================================
- There are several ways to access locale information. The simplest way
- is to let the C library itself do the work. Several of the functions in
- this library implicitly access the locale data, and use what information
- is provided by the currently selected locale. This is how the locale
- model is meant to work normally.
- As an example take the ‘strftime’ function, which is meant to nicely
- format date and time information (*note Formatting Calendar Time::).
- Part of the standard information contained in the ‘LC_TIME’ category is
- the names of the months. Instead of requiring the programmer to take
- care of providing the translations the ‘strftime’ function does this all
- by itself. ‘%A’ in the format string is replaced by the appropriate
- weekday name of the locale currently selected by ‘LC_TIME’. This is an
- easy example, and wherever possible functions do things automatically in
- this way.
- But there are quite often situations when there is simply no function
- to perform the task, or it is simply not possible to do the work
- automatically. For these cases it is necessary to access the
- information in the locale directly. To do this the C library provides
- two functions: ‘localeconv’ and ‘nl_langinfo’. The former is part of ISO C
- and therefore portable, but has a brain-damaged interface. The second
- is part of the Unix interface and is portable in as far as the system
- follows the Unix standards.
- * Menu:
- * The Lame Way to Locale Data:: ISO C’s ‘localeconv’.
- * The Elegant and Fast Way:: X/Open’s ‘nl_langinfo’.
- File: libc.info, Node: The Lame Way to Locale Data, Next: The Elegant and Fast Way, Up: Locale Information
- 7.7.1 ‘localeconv’: It is portable but …
- ----------------------------------------
- Together with the ‘setlocale’ function the ISO C people invented the
- ‘localeconv’ function. It is a masterpiece of poor design. It is
- expensive to use, not extensible, and not generally usable as it
- provides access to only ‘LC_MONETARY’ and ‘LC_NUMERIC’ related
- information. Nevertheless, if it is applicable to a given situation it
- should be used since it is very portable. The function ‘strfmon’
- formats monetary amounts according to the selected locale using this
- information.
- -- Function: struct lconv * localeconv (void)
- Preliminary: | MT-Unsafe race:localeconv locale | AS-Unsafe |
- AC-Safe | *Note POSIX Safety Concepts::.
- The ‘localeconv’ function returns a pointer to a structure whose
- components contain information about how numeric and monetary
- values should be formatted in the current locale.
- You should not modify the structure or its contents. The structure
- might be overwritten by subsequent calls to ‘localeconv’, or by
- calls to ‘setlocale’, but no other function in the library
- overwrites this value.
- -- Data Type: struct lconv
- ‘localeconv’’s return value is of this data type. Its elements are
- described in the following subsections.
- If a member of the structure ‘struct lconv’ has type ‘char’, and the
- value is ‘CHAR_MAX’, it means that the current locale has no value for
- that parameter.
- * Menu:
- * General Numeric:: Parameters for formatting numbers and
- currency amounts.
- * Currency Symbol:: How to print the symbol that identifies an
- amount of money (e.g. ‘$’).
- * Sign of Money Amount:: How to print the (positive or negative) sign
- for a monetary amount, if one exists.
- File: libc.info, Node: General Numeric, Next: Currency Symbol, Up: The Lame Way to Locale Data
- 7.7.1.1 Generic Numeric Formatting Parameters
- .............................................
- These are the standard members of ‘struct lconv’; there may be others.
- ‘char *decimal_point’
- ‘char *mon_decimal_point’
- These are the decimal-point separators used in formatting
- non-monetary and monetary quantities, respectively. In the ‘C’
- locale, the value of ‘decimal_point’ is ‘"."’, and the value of
- ‘mon_decimal_point’ is ‘""’.
- ‘char *thousands_sep’
- ‘char *mon_thousands_sep’
- These are the separators used to delimit groups of digits to the
- left of the decimal point in formatting non-monetary and monetary
- quantities, respectively. In the ‘C’ locale, both members have a
- value of ‘""’ (the empty string).
- ‘char *grouping’
- ‘char *mon_grouping’
- These are strings that specify how to group the digits to the left
- of the decimal point. ‘grouping’ applies to non-monetary
- quantities and ‘mon_grouping’ applies to monetary quantities. Use
- either ‘thousands_sep’ or ‘mon_thousands_sep’ to separate the digit
- groups.
- Each member of these strings is to be interpreted as an integer
- value of type ‘char’. Successive numbers (from left to right) give
- the sizes of successive groups (from right to left, starting at the
- decimal point.) The last member is either ‘0’, in which case the
- previous member is used over and over again for all the remaining
- groups, or ‘CHAR_MAX’, in which case there is no more grouping—or,
- put another way, any remaining digits form one large group without
- separators.
- For example, if ‘grouping’ is ‘"\04\03\02"’, the correct grouping
- for the number ‘123456787654321’ is ‘12’, ‘34’, ‘56’, ‘78’, ‘765’,
- ‘4321’. This uses a group of 4 digits at the end, preceded by a
- group of 3 digits, preceded by groups of 2 digits (as many as
- needed). With a separator of ‘,’, the number would be printed as
- ‘12,34,56,78,765,4321’.
- A value of ‘"\03"’ indicates repeated groups of three digits, as
- normally used in the U.S.
- In the standard ‘C’ locale, both ‘grouping’ and ‘mon_grouping’ have
- a value of ‘""’. This value specifies no grouping at all.
- ‘char int_frac_digits’
- ‘char frac_digits’
- These are small integers indicating how many fractional digits (to
- the right of the decimal point) should be displayed in a monetary
- value in international and local formats, respectively. (Most
- often, both members have the same value.)
- In the standard ‘C’ locale, both of these members have the value
- ‘CHAR_MAX’, meaning “unspecified”. The ISO standard doesn’t say
- what to do when you find this value; we recommend printing no
- fractional digits. (This locale also specifies the empty string
- for ‘mon_decimal_point’, so printing any fractional digits would be
- confusing!)
- File: libc.info, Node: Currency Symbol, Next: Sign of Money Amount, Prev: General Numeric, Up: The Lame Way to Locale Data
- 7.7.1.2 Printing the Currency Symbol
- ....................................
- These members of the ‘struct lconv’ structure specify how to print the
- symbol to identify a monetary value—the international analog of ‘$’ for
- US dollars.
- Each country has two standard currency symbols. The "local currency
- symbol" is used commonly within the country, while the "international
- currency symbol" is used internationally to refer to that country’s
- currency when it is necessary to indicate the country unambiguously.
- For example, many countries use the dollar as their monetary unit,
- and when dealing with international currencies it’s important to specify
- that one is dealing with (say) Canadian dollars instead of U.S. dollars
- or Australian dollars. But when the context is known to be Canada,
- there is no need to make this explicit—dollar amounts are implicitly
- assumed to be in Canadian dollars.
- ‘char *currency_symbol’
- The local currency symbol for the selected locale.
- In the standard ‘C’ locale, this member has a value of ‘""’ (the
- empty string), meaning “unspecified”. The ISO standard doesn’t say
- what to do when you find this value; we recommend you simply print
- the empty string as you would print any other string pointed to by
- this variable.
- ‘char *int_curr_symbol’
- The international currency symbol for the selected locale.
- The value of ‘int_curr_symbol’ should normally consist of a
- three-letter abbreviation determined by the international standard
- ‘ISO 4217 Codes for the Representation of Currency and Funds’,
- followed by a one-character separator (often a space).
- In the standard ‘C’ locale, this member has a value of ‘""’ (the
- empty string), meaning “unspecified”. We recommend you simply
- print the empty string as you would print any other string pointed
- to by this variable.
- ‘char p_cs_precedes’
- ‘char n_cs_precedes’
- ‘char int_p_cs_precedes’
- ‘char int_n_cs_precedes’
- These members are ‘1’ if the ‘currency_symbol’ or ‘int_curr_symbol’
- strings should precede the value of a monetary amount, or ‘0’ if
- the strings should follow the value. The ‘p_cs_precedes’ and
- ‘int_p_cs_precedes’ members apply to positive amounts (or zero),
- and the ‘n_cs_precedes’ and ‘int_n_cs_precedes’ members apply to
- negative amounts.
- In the standard ‘C’ locale, all of these members have a value of
- ‘CHAR_MAX’, meaning “unspecified”. The ISO standard doesn’t say
- what to do when you find this value. We recommend printing the
- currency symbol before the amount, which is right for most
- countries. In other words, treat all nonzero values alike in these
- members.
- The members with the ‘int_’ prefix apply to the ‘int_curr_symbol’
- while the other two apply to ‘currency_symbol’.
- ‘char p_sep_by_space’
- ‘char n_sep_by_space’
- ‘char int_p_sep_by_space’
- ‘char int_n_sep_by_space’
- These members are ‘1’ if a space should appear between the
- ‘currency_symbol’ or ‘int_curr_symbol’ strings and the amount, or
- ‘0’ if no space should appear. The ‘p_sep_by_space’ and
- ‘int_p_sep_by_space’ members apply to positive amounts (or zero),
- and the ‘n_sep_by_space’ and ‘int_n_sep_by_space’ members apply to
- negative amounts.
- In the standard ‘C’ locale, all of these members have a value of
- ‘CHAR_MAX’, meaning “unspecified”. The ISO standard doesn’t say
- what you should do when you find this value; we suggest you treat
- it as 1 (print a space). In other words, treat all nonzero values
- alike in these members.
- The members with the ‘int_’ prefix apply to the ‘int_curr_symbol’
- while the other two apply to ‘currency_symbol’. There is one
- specialty with the ‘int_curr_symbol’, though. Since all legal
- values contain a space at the end of the string one either prints
- this space (if the currency symbol must appear in front and must be
- separated) or one has to avoid printing this character at all
- (especially when at the end of the string).
- File: libc.info, Node: Sign of Money Amount, Prev: Currency Symbol, Up: The Lame Way to Locale Data
- 7.7.1.3 Printing the Sign of a Monetary Amount
- ..............................................
- These members of the ‘struct lconv’ structure specify how to print the
- sign (if any) of a monetary value.
- ‘char *positive_sign’
- ‘char *negative_sign’
- These are strings used to indicate positive (or zero) and negative
- monetary quantities, respectively.
- In the standard ‘C’ locale, both of these members have a value of
- ‘""’ (the empty string), meaning “unspecified”.
- The ISO standard doesn’t say what to do when you find this value;
- we recommend printing ‘positive_sign’ as you find it, even if it is
- empty. For a negative value, print ‘negative_sign’ as you find it
- unless both it and ‘positive_sign’ are empty, in which case print
- ‘-’ instead. (Failing to indicate the sign at all seems rather
- unreasonable.)
- ‘char p_sign_posn’
- ‘char n_sign_posn’
- ‘char int_p_sign_posn’
- ‘char int_n_sign_posn’
- These members are small integers that indicate how to position the
- sign for nonnegative and negative monetary quantities,
- respectively. (The string used for the sign is what was specified
- with ‘positive_sign’ or ‘negative_sign’.) The possible values are
- as follows:
- ‘0’
- The currency symbol and quantity should be surrounded by
- parentheses.
- ‘1’
- Print the sign string before the quantity and currency symbol.
- ‘2’
- Print the sign string after the quantity and currency symbol.
- ‘3’
- Print the sign string right before the currency symbol.
- ‘4’
- Print the sign string right after the currency symbol.
- ‘CHAR_MAX’
- “Unspecified”. Both members have this value in the standard
- ‘C’ locale.
- The ISO standard doesn’t say what you should do when the value is
- ‘CHAR_MAX’. We recommend you print the sign after the currency
- symbol.
- The members with the ‘int_’ prefix apply to the ‘int_curr_symbol’
- while the other two apply to ‘currency_symbol’.
- File: libc.info, Node: The Elegant and Fast Way, Prev: The Lame Way to Locale Data, Up: Locale Information
- 7.7.2 Pinpoint Access to Locale Data
- ------------------------------------
- When writing the X/Open Portability Guide the authors realized that the
- ‘localeconv’ function is not enough to provide reasonable access to
- locale information. The information which was meant to be available in
- the locale (as later specified in the POSIX.1 standard) requires more
- ways to access it. Therefore the ‘nl_langinfo’ function was introduced.
- -- Function: char * nl_langinfo (nl_item ITEM)
- Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- The ‘nl_langinfo’ function can be used to access individual
- elements of the locale categories. Unlike the ‘localeconv’
- function, which returns all the information, ‘nl_langinfo’ lets the
- caller select what information it requires. This is very fast and
- it is not a problem to call this function multiple times.
- A second advantage is that in addition to the numeric and monetary
- formatting information, information from the ‘LC_TIME’ and
- ‘LC_MESSAGES’ categories is available.
- The type ‘nl_type’ is defined in ‘nl_types.h’. The argument ITEM
- is a numeric value defined in the header ‘langinfo.h’. The X/Open
- standard defines the following values:
- ‘CODESET’
- ‘nl_langinfo’ returns a string with the name of the coded
- character set used in the selected locale.
- ‘ABDAY_1’
- ‘ABDAY_2’
- ‘ABDAY_3’
- ‘ABDAY_4’
- ‘ABDAY_5’
- ‘ABDAY_6’
- ‘ABDAY_7’
- ‘nl_langinfo’ returns the abbreviated weekday name. ‘ABDAY_1’
- corresponds to Sunday.
- ‘DAY_1’
- ‘DAY_2’
- ‘DAY_3’
- ‘DAY_4’
- ‘DAY_5’
- ‘DAY_6’
- ‘DAY_7’
- Similar to ‘ABDAY_1’ etc., but here the return value is the
- unabbreviated weekday name.
- ‘ABMON_1’
- ‘ABMON_2’
- ‘ABMON_3’
- ‘ABMON_4’
- ‘ABMON_5’
- ‘ABMON_6’
- ‘ABMON_7’
- ‘ABMON_8’
- ‘ABMON_9’
- ‘ABMON_10’
- ‘ABMON_11’
- ‘ABMON_12’
- The return value is abbreviated name of the month. ‘ABMON_1’
- corresponds to January.
- ‘MON_1’
- ‘MON_2’
- ‘MON_3’
- ‘MON_4’
- ‘MON_5’
- ‘MON_6’
- ‘MON_7’
- ‘MON_8’
- ‘MON_9’
- ‘MON_10’
- ‘MON_11’
- ‘MON_12’
- Similar to ‘ABMON_1’ etc., but here the month names are not
- abbreviated. Here the first value ‘MON_1’ also corresponds to
- January.
- ‘AM_STR’
- ‘PM_STR’
- The return values are strings which can be used in the
- representation of time as an hour from 1 to 12 plus an am/pm
- specifier.
- Note that in locales which do not use this time representation
- these strings might be empty, in which case the am/pm format
- cannot be used at all.
- ‘D_T_FMT’
- The return value can be used as a format string for ‘strftime’
- to represent time and date in a locale-specific way.
- ‘D_FMT’
- The return value can be used as a format string for ‘strftime’
- to represent a date in a locale-specific way.
- ‘T_FMT’
- The return value can be used as a format string for ‘strftime’
- to represent time in a locale-specific way.
- ‘T_FMT_AMPM’
- The return value can be used as a format string for ‘strftime’
- to represent time in the am/pm format.
- Note that if the am/pm format does not make any sense for the
- selected locale, the return value might be the same as the one
- for ‘T_FMT’.
- ‘ERA’
- The return value represents the era used in the current
- locale.
- Most locales do not define this value. An example of a locale
- which does define this value is the Japanese one. In Japan,
- the traditional representation of dates includes the name of
- the era corresponding to the then-emperor’s reign.
- Normally it should not be necessary to use this value
- directly. Specifying the ‘E’ modifier in their format strings
- causes the ‘strftime’ functions to use this information. The
- format of the returned string is not specified, and therefore
- you should not assume knowledge of it on different systems.
- ‘ERA_YEAR’
- The return value gives the year in the relevant era of the
- locale. As for ‘ERA’ it should not be necessary to use this
- value directly.
- ‘ERA_D_T_FMT’
- This return value can be used as a format string for
- ‘strftime’ to represent dates and times in a locale-specific
- era-based way.
- ‘ERA_D_FMT’
- This return value can be used as a format string for
- ‘strftime’ to represent a date in a locale-specific era-based
- way.
- ‘ERA_T_FMT’
- This return value can be used as a format string for
- ‘strftime’ to represent time in a locale-specific era-based
- way.
- ‘ALT_DIGITS’
- The return value is a representation of up to 100 values used
- to represent the values 0 to 99. As for ‘ERA’ this value is
- not intended to be used directly, but instead indirectly
- through the ‘strftime’ function. When the modifier ‘O’ is
- used in a format which would otherwise use numerals to
- represent hours, minutes, seconds, weekdays, months, or weeks,
- the appropriate value for the locale is used instead.
- ‘INT_CURR_SYMBOL’
- The same as the value returned by ‘localeconv’ in the
- ‘int_curr_symbol’ element of the ‘struct lconv’.
- ‘CURRENCY_SYMBOL’
- ‘CRNCYSTR’
- The same as the value returned by ‘localeconv’ in the
- ‘currency_symbol’ element of the ‘struct lconv’.
- ‘CRNCYSTR’ is a deprecated alias still required by Unix98.
- ‘MON_DECIMAL_POINT’
- The same as the value returned by ‘localeconv’ in the
- ‘mon_decimal_point’ element of the ‘struct lconv’.
- ‘MON_THOUSANDS_SEP’
- The same as the value returned by ‘localeconv’ in the
- ‘mon_thousands_sep’ element of the ‘struct lconv’.
- ‘MON_GROUPING’
- The same as the value returned by ‘localeconv’ in the
- ‘mon_grouping’ element of the ‘struct lconv’.
- ‘POSITIVE_SIGN’
- The same as the value returned by ‘localeconv’ in the
- ‘positive_sign’ element of the ‘struct lconv’.
- ‘NEGATIVE_SIGN’
- The same as the value returned by ‘localeconv’ in the
- ‘negative_sign’ element of the ‘struct lconv’.
- ‘INT_FRAC_DIGITS’
- The same as the value returned by ‘localeconv’ in the
- ‘int_frac_digits’ element of the ‘struct lconv’.
- ‘FRAC_DIGITS’
- The same as the value returned by ‘localeconv’ in the
- ‘frac_digits’ element of the ‘struct lconv’.
- ‘P_CS_PRECEDES’
- The same as the value returned by ‘localeconv’ in the
- ‘p_cs_precedes’ element of the ‘struct lconv’.
- ‘P_SEP_BY_SPACE’
- The same as the value returned by ‘localeconv’ in the
- ‘p_sep_by_space’ element of the ‘struct lconv’.
- ‘N_CS_PRECEDES’
- The same as the value returned by ‘localeconv’ in the
- ‘n_cs_precedes’ element of the ‘struct lconv’.
- ‘N_SEP_BY_SPACE’
- The same as the value returned by ‘localeconv’ in the
- ‘n_sep_by_space’ element of the ‘struct lconv’.
- ‘P_SIGN_POSN’
- The same as the value returned by ‘localeconv’ in the
- ‘p_sign_posn’ element of the ‘struct lconv’.
- ‘N_SIGN_POSN’
- The same as the value returned by ‘localeconv’ in the
- ‘n_sign_posn’ element of the ‘struct lconv’.
- ‘INT_P_CS_PRECEDES’
- The same as the value returned by ‘localeconv’ in the
- ‘int_p_cs_precedes’ element of the ‘struct lconv’.
- ‘INT_P_SEP_BY_SPACE’
- The same as the value returned by ‘localeconv’ in the
- ‘int_p_sep_by_space’ element of the ‘struct lconv’.
- ‘INT_N_CS_PRECEDES’
- The same as the value returned by ‘localeconv’ in the
- ‘int_n_cs_precedes’ element of the ‘struct lconv’.
- ‘INT_N_SEP_BY_SPACE’
- The same as the value returned by ‘localeconv’ in the
- ‘int_n_sep_by_space’ element of the ‘struct lconv’.
- ‘INT_P_SIGN_POSN’
- The same as the value returned by ‘localeconv’ in the
- ‘int_p_sign_posn’ element of the ‘struct lconv’.
- ‘INT_N_SIGN_POSN’
- The same as the value returned by ‘localeconv’ in the
- ‘int_n_sign_posn’ element of the ‘struct lconv’.
- ‘DECIMAL_POINT’
- ‘RADIXCHAR’
- The same as the value returned by ‘localeconv’ in the
- ‘decimal_point’ element of the ‘struct lconv’.
- The name ‘RADIXCHAR’ is a deprecated alias still used in
- Unix98.
- ‘THOUSANDS_SEP’
- ‘THOUSEP’
- The same as the value returned by ‘localeconv’ in the
- ‘thousands_sep’ element of the ‘struct lconv’.
- The name ‘THOUSEP’ is a deprecated alias still used in Unix98.
- ‘GROUPING’
- The same as the value returned by ‘localeconv’ in the
- ‘grouping’ element of the ‘struct lconv’.
- ‘YESEXPR’
- The return value is a regular expression which can be used
- with the ‘regex’ function to recognize a positive response to
- a yes/no question. The GNU C Library provides the ‘rpmatch’
- function for easier handling in applications.
- ‘NOEXPR’
- The return value is a regular expression which can be used
- with the ‘regex’ function to recognize a negative response to
- a yes/no question.
- ‘YESSTR’
- The return value is a locale-specific translation of the
- positive response to a yes/no question.
- Using this value is deprecated since it is a very special case
- of message translation, and is better handled by the message
- translation functions (*note Message Translation::).
- The use of this symbol is deprecated. Instead message
- translation should be used.
- ‘NOSTR’
- The return value is a locale-specific translation of the
- negative response to a yes/no question. What is said for
- ‘YESSTR’ is also true here.
- The use of this symbol is deprecated. Instead message
- translation should be used.
- The file ‘langinfo.h’ defines a lot more symbols but none of them
- are official. Using them is not portable, and the format of the
- return values might change. Therefore we recommended you not use
- them.
- Note that the return value for any valid argument can be used in
- all situations (with the possible exception of the am/pm time
- formatting codes). If the user has not selected any locale for the
- appropriate category, ‘nl_langinfo’ returns the information from
- the ‘"C"’ locale. It is therefore possible to use this function as
- shown in the example below.
- If the argument ITEM is not valid, a pointer to an empty string is
- returned.
- An example of ‘nl_langinfo’ usage is a function which has to print a
- given date and time in a locale-specific way. At first one might think
- that, since ‘strftime’ internally uses the locale information, writing
- something like the following is enough:
- size_t
- i18n_time_n_data (char *s, size_t len, const struct tm *tp)
- {
- return strftime (s, len, "%X %D", tp);
- }
- The format contains no weekday or month names and therefore is
- internationally usable. Wrong! The output produced is something like
- ‘"hh:mm:ss MM/DD/YY"’. This format is only recognizable in the USA.
- Other countries use different formats. Therefore the function should be
- rewritten like this:
- size_t
- i18n_time_n_data (char *s, size_t len, const struct tm *tp)
- {
- return strftime (s, len, nl_langinfo (D_T_FMT), tp);
- }
- Now it uses the date and time format of the locale selected when the
- program runs. If the user selects the locale correctly there should
- never be a misunderstanding over the time and date format.
- File: libc.info, Node: Formatting Numbers, Next: Yes-or-No Questions, Prev: Locale Information, Up: Locales
- 7.8 A dedicated function to format numbers
- ==========================================
- We have seen that the structure returned by ‘localeconv’ as well as the
- values given to ‘nl_langinfo’ allow you to retrieve the various pieces
- of locale-specific information to format numbers and monetary amounts.
- We have also seen that the underlying rules are quite complex.
- Therefore the X/Open standards introduce a function which uses such
- locale information, making it easier for the user to format numbers
- according to these rules.
- -- Function: ssize_t strfmon (char *S, size_t MAXSIZE, const char
- *FORMAT, …)
- Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
- *Note POSIX Safety Concepts::.
- The ‘strfmon’ function is similar to the ‘strftime’ function in
- that it takes a buffer, its size, a format string, and values to
- write into the buffer as text in a form specified by the format
- string. Like ‘strftime’, the function also returns the number of
- bytes written into the buffer.
- There are two differences: ‘strfmon’ can take more than one
- argument, and, of course, the format specification is different.
- Like ‘strftime’, the format string consists of normal text, which
- is output as is, and format specifiers, which are indicated by a
- ‘%’. Immediately after the ‘%’, you can optionally specify various
- flags and formatting information before the main formatting
- character, in a similar way to ‘printf’:
- • Immediately following the ‘%’ there can be one or more of the
- following flags:
- ‘=F’
- The single byte character F is used for this field as the
- numeric fill character. By default this character is a
- space character. Filling with this character is only
- performed if a left precision is specified. It is not
- just to fill to the given field width.
- ‘^’
- The number is printed without grouping the digits
- according to the rules of the current locale. By default
- grouping is enabled.
- ‘+’, ‘(’
- At most one of these flags can be used. They select
- which format to represent the sign of a currency amount.
- By default, and if ‘+’ is given, the locale equivalent of
- +/- is used. If ‘(’ is given, negative amounts are
- enclosed in parentheses. The exact format is determined
- by the values of the ‘LC_MONETARY’ category of the locale
- selected at program runtime.
- ‘!’
- The output will not contain the currency symbol.
- ‘-’
- The output will be formatted left-justified instead of
- right-justified if it does not fill the entire field
- width.
- The next part of the specification is an optional field width. If
- no width is specified 0 is taken. During output, the function
- first determines how much space is required. If it requires at
- least as many characters as given by the field width, it is output
- using as much space as necessary. Otherwise, it is extended to use
- the full width by filling with the space character. The presence
- or absence of the ‘-’ flag determines the side at which such
- padding occurs. If present, the spaces are added at the right
- making the output left-justified, and vice versa.
- So far the format looks familiar, being similar to the ‘printf’ and
- ‘strftime’ formats. However, the next two optional fields
- introduce something new. The first one is a ‘#’ character followed
- by a decimal digit string. The value of the digit string specifies
- the number of _digit_ positions to the left of the decimal point
- (or equivalent). This does _not_ include the grouping character
- when the ‘^’ flag is not given. If the space needed to print the
- number does not fill the whole width, the field is padded at the
- left side with the fill character, which can be selected using the
- ‘=’ flag and by default is a space. For example, if the field
- width is selected as 6 and the number is 123, the fill character is
- ‘*’ the result will be ‘***123’.
- The second optional field starts with a ‘.’ (period) and consists
- of another decimal digit string. Its value describes the number of
- characters printed after the decimal point. The default is
- selected from the current locale (‘frac_digits’, ‘int_frac_digits’,
- see *note General Numeric::). If the exact representation needs
- more digits than given by the field width, the displayed value is
- rounded. If the number of fractional digits is selected to be
- zero, no decimal point is printed.
- As a GNU extension, the ‘strfmon’ implementation in the GNU C
- Library allows an optional ‘L’ next as a format modifier. If this
- modifier is given, the argument is expected to be a ‘long double’
- instead of a ‘double’ value.
- Finally, the last component is a format specifier. There are three
- specifiers defined:
- ‘i’
- Use the locale’s rules for formatting an international
- currency value.
- ‘n’
- Use the locale’s rules for formatting a national currency
- value.
- ‘%’
- Place a ‘%’ in the output. There must be no flag, width
- specifier or modifier given, only ‘%%’ is allowed.
- As for ‘printf’, the function reads the format string from left to
- right and uses the values passed to the function following the
- format string. The values are expected to be either of type
- ‘double’ or ‘long double’, depending on the presence of the
- modifier ‘L’. The result is stored in the buffer pointed to by S.
- At most MAXSIZE characters are stored.
- The return value of the function is the number of characters stored
- in S, including the terminating ‘NULL’ byte. If the number of
- characters stored would exceed MAXSIZE, the function returns -1 and
- the content of the buffer S is unspecified. In this case ‘errno’
- is set to ‘E2BIG’.
- A few examples should make clear how the function works. It is
- assumed that all the following pieces of code are executed in a program
- which uses the USA locale (‘en_US’). The simplest form of the format is
- this:
- strfmon (buf, 100, "@%n@%n@%n@", 123.45, -567.89, 12345.678);
- The output produced is
- "@$123.45@-$567.89@$12,345.68@"
- We can notice several things here. First, the widths of the output
- numbers are different. We have not specified a width in the format
- string, and so this is no wonder. Second, the third number is printed
- using thousands separators. The thousands separator for the ‘en_US’
- locale is a comma. The number is also rounded. .678 is rounded to .68
- since the format does not specify a precision and the default value in
- the locale is 2. Finally, note that the national currency symbol is
- printed since ‘%n’ was used, not ‘i’. The next example shows how we can
- align the output.
- strfmon (buf, 100, "@%=*11n@%=*11n@%=*11n@", 123.45, -567.89, 12345.678);
- The output this time is:
- "@ $123.45@ -$567.89@ $12,345.68@"
- Two things stand out. Firstly, all fields have the same width
- (eleven characters) since this is the width given in the format and
- since no number required more characters to be printed. The second
- important point is that the fill character is not used. This is correct
- since the white space was not used to achieve a precision given by a ‘#’
- modifier, but instead to fill to the given width. The difference
- becomes obvious if we now add a width specification.
- strfmon (buf, 100, "@%=*11#5n@%=*11#5n@%=*11#5n@",
- 123.45, -567.89, 12345.678);
- The output is
- "@ $***123.45@-$***567.89@ $12,456.68@"
- Here we can see that all the currency symbols are now aligned, and
- that the space between the currency sign and the number is filled with
- the selected fill character. Note that although the width is selected
- to be 5 and 123.45 has three digits left of the decimal point, the space
- is filled with three asterisks. This is correct since, as explained
- above, the width does not include the positions used to store thousands
- separators. One last example should explain the remaining
- functionality.
- strfmon (buf, 100, "@%=0(16#5.3i@%=0(16#5.3i@%=0(16#5.3i@",
- 123.45, -567.89, 12345.678);
- This rather complex format string produces the following output:
- "@ USD 000123,450 @(USD 000567.890)@ USD 12,345.678 @"
- The most noticeable change is the alternative way of representing
- negative numbers. In financial circles this is often done using
- parentheses, and this is what the ‘(’ flag selected. The fill character
- is now ‘0’. Note that this ‘0’ character is not regarded as a numeric
- zero, and therefore the first and second numbers are not printed using a
- thousands separator. Since we used the format specifier ‘i’ instead of
- ‘n’, the international form of the currency symbol is used. This is a
- four letter string, in this case ‘"USD "’. The last point is that since
- the precision right of the decimal point is selected to be three, the
- first and second numbers are printed with an extra zero at the end and
- the third number is printed without rounding.
- File: libc.info, Node: Yes-or-No Questions, Prev: Formatting Numbers, Up: Locales
- 7.9 Yes-or-No Questions
- =======================
- Some non GUI programs ask a yes-or-no question. If the messages
- (especially the questions) are translated into foreign languages, be
- sure that you localize the answers too. It would be very bad habit to
- ask a question in one language and request the answer in another, often
- English.
- The GNU C Library contains ‘rpmatch’ to give applications easy access
- to the corresponding locale definitions.
- -- Function: int rpmatch (const char *RESPONSE)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
- | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
- The function ‘rpmatch’ checks the string in RESPONSE for whether or
- not it is a correct yes-or-no answer and if yes, which one. The
- check uses the ‘YESEXPR’ and ‘NOEXPR’ data in the ‘LC_MESSAGES’
- category of the currently selected locale. The return value is as
- follows:
- ‘1’
- The user entered an affirmative answer.
- ‘0’
- The user entered a negative answer.
- ‘-1’
- The answer matched neither the ‘YESEXPR’ nor the ‘NOEXPR’
- regular expression.
- This function is not standardized but available beside in the GNU C
- Library at least also in the IBM AIX library.
- This function would normally be used like this:
- …
- /* Use a safe default. */
- _Bool doit = false;
- fputs (gettext ("Do you really want to do this? "), stdout);
- fflush (stdout);
- /* Prepare the ‘getline’ call. */
- line = NULL;
- len = 0;
- while (getline (&line, &len, stdin) >= 0)
- {
- /* Check the response. */
- int res = rpmatch (line);
- if (res >= 0)
- {
- /* We got a definitive answer. */
- if (res > 0)
- doit = true;
- break;
- }
- }
- /* Free what ‘getline’ allocated. */
- free (line);
- Note that the loop continues until a read error is detected or until
- a definitive (positive or negative) answer is read.
- File: libc.info, Node: Message Translation, Next: Searching and Sorting, Prev: Locales, Up: Top
- 8 Message Translation
- *********************
- The program’s interface with the user should be designed to ease the
- user’s task. One way to ease the user’s task is to use messages in
- whatever language the user prefers.
- Printing messages in different languages can be implemented in
- different ways. One could add all the different languages in the source
- code and choose among the variants every time a message has to be
- printed. This is certainly not a good solution since extending the set
- of languages is cumbersome (the code must be changed) and the code
- itself can become really big with dozens of message sets.
- A better solution is to keep the message sets for each language in
- separate files which are loaded at runtime depending on the language
- selection of the user.
- The GNU C Library provides two different sets of functions to support
- message translation. The problem is that neither of the interfaces is
- officially defined by the POSIX standard. The ‘catgets’ family of
- functions is defined in the X/Open standard but this is derived from
- industry decisions and therefore not necessarily based on reasonable
- decisions.
- As mentioned above, the message catalog handling provides easy
- extendability by using external data files which contain the message
- translations. I.e., these files contain for each of the messages used
- in the program a translation for the appropriate language. So the tasks
- of the message handling functions are
- • locate the external data file with the appropriate translations
- • load the data and make it possible to address the messages
- • map a given key to the translated message
- The two approaches mainly differ in the implementation of this last
- step. Decisions made in the last step influence the rest of the design.
- * Menu:
- * Message catalogs a la X/Open:: The ‘catgets’ family of functions.
- * The Uniforum approach:: The ‘gettext’ family of functions.
- File: libc.info, Node: Message catalogs a la X/Open, Next: The Uniforum approach, Up: Message Translation
- 8.1 X/Open Message Catalog Handling
- ===================================
- The ‘catgets’ functions are based on the simple scheme:
- Associate every message to translate in the source code with a
- unique identifier. To retrieve a message from a catalog file
- solely the identifier is used.
- This means for the author of the program that s/he will have to make
- sure the meaning of the identifier in the program code and in the
- message catalogs is always the same.
- Before a message can be translated the catalog file must be located.
- The user of the program must be able to guide the responsible function
- to find whatever catalog the user wants. This is separated from what
- the programmer had in mind.
- All the types, constants and functions for the ‘catgets’ functions
- are defined/declared in the ‘nl_types.h’ header file.
- * Menu:
- * The catgets Functions:: The ‘catgets’ function family.
- * The message catalog files:: Format of the message catalog files.
- * The gencat program:: How to generate message catalogs files which
- can be used by the functions.
- * Common Usage:: How to use the ‘catgets’ interface.
- File: libc.info, Node: The catgets Functions, Next: The message catalog files, Up: Message catalogs a la X/Open
- 8.1.1 The ‘catgets’ function family
- -----------------------------------
- -- Function: nl_catd catopen (const char *CAT_NAME, int FLAG)
- Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- The ‘catopen’ function tries to locate the message data file named
- CAT_NAME and loads it when found. The return value is of an opaque
- type and can be used in calls to the other functions to refer to
- this loaded catalog.
- The return value is ‘(nl_catd) -1’ in case the function failed and
- no catalog was loaded. The global variable ERRNO contains a code
- for the error causing the failure. But even if the function call
- succeeded this does not mean that all messages can be translated.
- Locating the catalog file must happen in a way which lets the user
- of the program influence the decision. It is up to the user to
- decide about the language to use and sometimes it is useful to use
- alternate catalog files. All this can be specified by the user by
- setting some environment variables.
- The first problem is to find out where all the message catalogs are
- stored. Every program could have its own place to keep all the
- different files but usually the catalog files are grouped by
- languages and the catalogs for all programs are kept in the same
- place.
- To tell the ‘catopen’ function where the catalog for the program
- can be found the user can set the environment variable ‘NLSPATH’ to
- a value which describes her/his choice. Since this value must be
- usable for different languages and locales it cannot be a simple
- string. Instead it is a format string (similar to ‘printf’’s). An
- example is
- /usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N
- First one can see that more than one directory can be specified
- (with the usual syntax of separating them by colons). The next
- things to observe are the format string, ‘%L’ and ‘%N’ in this
- case. The ‘catopen’ function knows about several of them and the
- replacement for all of them is of course different.
- ‘%N’
- This format element is substituted with the name of the
- catalog file. This is the value of the CAT_NAME argument
- given to ‘catgets’.
- ‘%L’
- This format element is substituted with the name of the
- currently selected locale for translating messages. How this
- is determined is explained below.
- ‘%l’
- (This is the lowercase ell.) This format element is
- substituted with the language element of the locale name. The
- string describing the selected locale is expected to have the
- form ‘LANG[_TERR[.CODESET]]’ and this format uses the first
- part LANG.
- ‘%t’
- This format element is substituted by the territory part TERR
- of the name of the currently selected locale. See the
- explanation of the format above.
- ‘%c’
- This format element is substituted by the codeset part CODESET
- of the name of the currently selected locale. See the
- explanation of the format above.
- ‘%%’
- Since ‘%’ is used as a meta character there must be a way to
- express the ‘%’ character in the result itself. Using ‘%%’
- does this just like it works for ‘printf’.
- Using ‘NLSPATH’ allows arbitrary directories to be searched for
- message catalogs while still allowing different languages to be
- used. If the ‘NLSPATH’ environment variable is not set, the
- default value is
- PREFIX/share/locale/%L/%N:PREFIX/share/locale/%L/LC_MESSAGES/%N
- where PREFIX is given to ‘configure’ while installing the GNU C
- Library (this value is in many cases ‘/usr’ or the empty string).
- The remaining problem is to decide which must be used. The value
- decides about the substitution of the format elements mentioned
- above. First of all the user can specify a path in the message
- catalog name (i.e., the name contains a slash character). In this
- situation the ‘NLSPATH’ environment variable is not used. The
- catalog must exist as specified in the program, perhaps relative to
- the current working directory. This situation in not desirable and
- catalogs names never should be written this way. Beside this, this
- behavior is not portable to all other platforms providing the
- ‘catgets’ interface.
- Otherwise the values of environment variables from the standard
- environment are examined (*note Standard Environment::). Which
- variables are examined is decided by the FLAG parameter of
- ‘catopen’. If the value is ‘NL_CAT_LOCALE’ (which is defined in
- ‘nl_types.h’) then the ‘catopen’ function uses the name of the
- locale currently selected for the ‘LC_MESSAGES’ category.
- If FLAG is zero the ‘LANG’ environment variable is examined. This
- is a left-over from the early days when the concept of locales had
- not even reached the level of POSIX locales.
- The environment variable and the locale name should have a value of
- the form ‘LANG[_TERR[.CODESET]]’ as explained above. If no
- environment variable is set the ‘"C"’ locale is used which prevents
- any translation.
- The return value of the function is in any case a valid string.
- Either it is a translation from a message catalog or it is the same
- as the STRING parameter. So a piece of code to decide whether a
- translation actually happened must look like this:
- {
- char *trans = catgets (desc, set, msg, input_string);
- if (trans == input_string)
- {
- /* Something went wrong. */
- }
- }
- When an error occurs the global variable ERRNO is set to
- EBADF
- The catalog does not exist.
- ENOMSG
- The set/message tuple does not name an existing element in the
- message catalog.
- While it sometimes can be useful to test for errors programs
- normally will avoid any test. If the translation is not available
- it is no big problem if the original, untranslated message is
- printed. Either the user understands this as well or s/he will
- look for the reason why the messages are not translated.
- Please note that the currently selected locale does not depend on a
- call to the ‘setlocale’ function. It is not necessary that the locale
- data files for this locale exist and calling ‘setlocale’ succeeds. The
- ‘catopen’ function directly reads the values of the environment
- variables.
- -- Function: char * catgets (nl_catd CATALOG_DESC, int SET, int
- MESSAGE, const char *STRING)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The function ‘catgets’ has to be used to access the message catalog
- previously opened using the ‘catopen’ function. The CATALOG_DESC
- parameter must be a value previously returned by ‘catopen’.
- The next two parameters, SET and MESSAGE, reflect the internal
- organization of the message catalog files. This will be explained
- in detail below. For now it is interesting to know that a catalog
- can consist of several sets and the messages in each thread are
- individually numbered using numbers. Neither the set number nor
- the message number must be consecutive. They can be arbitrarily
- chosen. But each message (unless equal to another one) must have
- its own unique pair of set and message numbers.
- Since it is not guaranteed that the message catalog for the
- language selected by the user exists the last parameter STRING
- helps to handle this case gracefully. If no matching string can be
- found STRING is returned. This means for the programmer that
- • the STRING parameters should contain reasonable text (this
- also helps to understand the program seems otherwise there
- would be no hint on the string which is expected to be
- returned.
- • all STRING arguments should be written in the same language.
- It is somewhat uncomfortable to write a program using the ‘catgets’
- functions if no supporting functionality is available. Since each
- set/message number tuple must be unique the programmer must keep lists
- of the messages at the same time the code is written. And the work
- between several people working on the same project must be coordinated.
- We will see how some of these problems can be relaxed a bit (*note
- Common Usage::).
- -- Function: int catclose (nl_catd CATALOG_DESC)
- Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe corrupt mem |
- *Note POSIX Safety Concepts::.
- The ‘catclose’ function can be used to free the resources
- associated with a message catalog which previously was opened by a
- call to ‘catopen’. If the resources can be successfully freed the
- function returns ‘0’. Otherwise it returns ‘−1’ and the global
- variable ERRNO is set. Errors can occur if the catalog descriptor
- CATALOG_DESC is not valid in which case ERRNO is set to ‘EBADF’.
- File: libc.info, Node: The message catalog files, Next: The gencat program, Prev: The catgets Functions, Up: Message catalogs a la X/Open
- 8.1.2 Format of the message catalog files
- -----------------------------------------
- The only reasonable way to translate all the messages of a function and
- store the result in a message catalog file which can be read by the
- ‘catopen’ function is to write all the message text to the translator
- and let her/him translate them all. I.e., we must have a file with
- entries which associate the set/message tuple with a specific
- translation. This file format is specified in the X/Open standard and
- is as follows:
- • Lines containing only whitespace characters or empty lines are
- ignored.
- • Lines which contain as the first non-whitespace character a ‘$’
- followed by a whitespace character are comment and are also
- ignored.
- • If a line contains as the first non-whitespace characters the
- sequence ‘$set’ followed by a whitespace character an additional
- argument is required to follow. This argument can either be:
- − a number. In this case the value of this number determines
- the set to which the following messages are added.
- − an identifier consisting of alphanumeric characters plus the
- underscore character. In this case the set get automatically
- a number assigned. This value is one added to the largest set
- number which so far appeared.
- How to use the symbolic names is explained in section *note
- Common Usage::.
- It is an error if a symbol name appears more than once. All
- following messages are placed in a set with this number.
- • If a line contains as the first non-whitespace characters the
- sequence ‘$delset’ followed by a whitespace character an additional
- argument is required to follow. This argument can either be:
- − a number. In this case the value of this number determines
- the set which will be deleted.
- − an identifier consisting of alphanumeric characters plus the
- underscore character. This symbolic identifier must match a
- name for a set which previously was defined. It is an error
- if the name is unknown.
- In both cases all messages in the specified set will be removed.
- They will not appear in the output. But if this set is later again
- selected with a ‘$set’ command again messages could be added and
- these messages will appear in the output.
- • If a line contains after leading whitespaces the sequence ‘$quote’,
- the quoting character used for this input file is changed to the
- first non-whitespace character following ‘$quote’. If no
- non-whitespace character is present before the line ends quoting is
- disabled.
- By default no quoting character is used. In this mode strings are
- terminated with the first unescaped line break. If there is a
- ‘$quote’ sequence present newline need not be escaped. Instead a
- string is terminated with the first unescaped appearance of the
- quote character.
- A common usage of this feature would be to set the quote character
- to ‘"’. Then any appearance of the ‘"’ in the strings must be
- escaped using the backslash (i.e., ‘\"’ must be written).
- • Any other line must start with a number or an alphanumeric
- identifier (with the underscore character included). The following
- characters (starting after the first whitespace character) will
- form the string which gets associated with the currently selected
- set and the message number represented by the number and identifier
- respectively.
- If the start of the line is a number the message number is obvious.
- It is an error if the same message number already appeared for this
- set.
- If the leading token was an identifier the message number gets
- automatically assigned. The value is the current maximum message
- number for this set plus one. It is an error if the identifier was
- already used for a message in this set. It is OK to reuse the
- identifier for a message in another thread. How to use the
- symbolic identifiers will be explained below (*note Common
- Usage::). There is one limitation with the identifier: it must not
- be ‘Set’. The reason will be explained below.
- The text of the messages can contain escape characters. The usual
- bunch of characters known from the ISO C language are recognized
- (‘\n’, ‘\t’, ‘\v’, ‘\b’, ‘\r’, ‘\f’, ‘\\’, and ‘\NNN’, where NNN is
- the octal coding of a character code).
- *Important:* The handling of identifiers instead of numbers for the
- set and messages is a GNU extension. Systems strictly following the
- X/Open specification do not have this feature. An example for a message
- catalog file is this:
- $ This is a leading comment.
- $quote "
- $set SetOne
- 1 Message with ID 1.
- two " Message with ID \"two\", which gets the value 2 assigned"
- $set SetTwo
- $ Since the last set got the number 1 assigned this set has number 2.
- 4000 "The numbers can be arbitrary, they need not start at one."
- This small example shows various aspects:
- • Lines 1 and 9 are comments since they start with ‘$’ followed by a
- whitespace.
- • The quoting character is set to ‘"’. Otherwise the quotes in the
- message definition would have to be omitted and in this case the
- message with the identifier ‘two’ would lose its leading
- whitespace.
- • Mixing numbered messages with messages having symbolic names is no
- problem and the numbering happens automatically.
- While this file format is pretty easy it is not the best possible for
- use in a running program. The ‘catopen’ function would have to parse
- the file and handle syntactic errors gracefully. This is not so easy
- and the whole process is pretty slow. Therefore the ‘catgets’ functions
- expect the data in another more compact and ready-to-use file format.
- There is a special program ‘gencat’ which is explained in detail in the
- next section.
- Files in this other format are not human readable. To be easy to use
- by programs it is a binary file. But the format is byte order
- independent so translation files can be shared by systems of arbitrary
- architecture (as long as they use the GNU C Library).
- Details about the binary file format are not important to know since
- these files are always created by the ‘gencat’ program. The sources of
- the GNU C Library also provide the sources for the ‘gencat’ program and
- so the interested reader can look through these source files to learn
- about the file format.
- File: libc.info, Node: The gencat program, Next: Common Usage, Prev: The message catalog files, Up: Message catalogs a la X/Open
- 8.1.3 Generate Message Catalogs files
- -------------------------------------
- The ‘gencat’ program is specified in the X/Open standard and the GNU
- implementation follows this specification and so processes all correctly
- formed input files. Additionally some extension are implemented which
- help to work in a more reasonable way with the ‘catgets’ functions.
- The ‘gencat’ program can be invoked in two ways:
- `gencat [OPTION …] [OUTPUT-FILE [INPUT-FILE …]]`
- This is the interface defined in the X/Open standard. If no
- INPUT-FILE parameter is given, input will be read from standard input.
- Multiple input files will be read as if they were concatenated. If
- OUTPUT-FILE is also missing, the output will be written to standard
- output. To provide the interface one is used to from other programs a
- second interface is provided.
- `gencat [OPTION …] -o OUTPUT-FILE [INPUT-FILE …]`
- The option ‘-o’ is used to specify the output file and all file
- arguments are used as input files.
- Beside this one can use ‘-’ or ‘/dev/stdin’ for INPUT-FILE to denote
- the standard input. Corresponding one can use ‘-’ and ‘/dev/stdout’ for
- OUTPUT-FILE to denote standard output. Using ‘-’ as a file name is
- allowed in X/Open while using the device names is a GNU extension.
- The ‘gencat’ program works by concatenating all input files and then
- *merging* the resulting collection of message sets with a possibly
- existing output file. This is done by removing all messages with
- set/message number tuples matching any of the generated messages from
- the output file and then adding all the new messages. To regenerate a
- catalog file while ignoring the old contents therefore requires removing
- the output file if it exists. If the output is written to standard
- output no merging takes place.
- The following table shows the options understood by the ‘gencat’
- program. The X/Open standard does not specify any options for the
- program so all of these are GNU extensions.
- ‘-V’
- ‘--version’
- Print the version information and exit.
- ‘-h’
- ‘--help’
- Print a usage message listing all available options, then exit
- successfully.
- ‘--new’
- Do not merge the new messages from the input files with the old
- content of the output file. The old content of the output file is
- discarded.
- ‘-H’
- ‘--header=name’
- This option is used to emit the symbolic names given to sets and
- messages in the input files for use in the program. Details about
- how to use this are given in the next section. The NAME parameter
- to this option specifies the name of the output file. It will
- contain a number of C preprocessor ‘#define’s to associate a name
- with a number.
- Please note that the generated file only contains the symbols from
- the input files. If the output is merged with the previous content
- of the output file the possibly existing symbols from the file(s)
- which generated the old output files are not in the generated
- header file.
- File: libc.info, Node: Common Usage, Prev: The gencat program, Up: Message catalogs a la X/Open
- 8.1.4 How to use the ‘catgets’ interface
- ----------------------------------------
- The ‘catgets’ functions can be used in two different ways. By following
- slavishly the X/Open specs and not relying on the extension and by using
- the GNU extensions. We will take a look at the former method first to
- understand the benefits of extensions.
- 8.1.4.1 Not using symbolic names
- ................................
- Since the X/Open format of the message catalog files does not allow
- symbol names we have to work with numbers all the time. When we start
- writing a program we have to replace all appearances of translatable
- strings with something like
- catgets (catdesc, set, msg, "string")
- CATGETS is retrieved from a call to ‘catopen’ which is normally done
- once at the program start. The ‘"string"’ is the string we want to
- translate. The problems start with the set and message numbers.
- In a bigger program several programmers usually work at the same time
- on the program and so coordinating the number allocation is crucial.
- Though no two different strings must be indexed by the same tuple of
- numbers it is highly desirable to reuse the numbers for equal strings
- with equal translations (please note that there might be strings which
- are equal in one language but have different translations due to
- difference contexts).
- The allocation process can be relaxed a bit by different set numbers
- for different parts of the program. So the number of developers who
- have to coordinate the allocation can be reduced. But still lists must
- be keep track of the allocation and errors can easily happen. These
- errors cannot be discovered by the compiler or the ‘catgets’ functions.
- Only the user of the program might see wrong messages printed. In the
- worst cases the messages are so irritating that they cannot be
- recognized as wrong. Think about the translations for ‘"true"’ and
- ‘"false"’ being exchanged. This could result in a disaster.
- 8.1.4.2 Using symbolic names
- ............................
- The problems mentioned in the last section derive from the fact that:
- 1. the numbers are allocated once and due to the possibly frequent use
- of them it is difficult to change a number later.
- 2. the numbers do not allow guessing anything about the string and
- therefore collisions can easily happen.
- By constantly using symbolic names and by providing a method which
- maps the string content to a symbolic name (however this will happen)
- one can prevent both problems above. The cost of this is that the
- programmer has to write a complete message catalog file while s/he is
- writing the program itself.
- This is necessary since the symbolic names must be mapped to numbers
- before the program sources can be compiled. In the last section it was
- described how to generate a header containing the mapping of the names.
- E.g., for the example message file given in the last section we could
- call the ‘gencat’ program as follows (assume ‘ex.msg’ contains the
- sources).
- gencat -H ex.h -o ex.cat ex.msg
- This generates a header file with the following content:
- #define SetTwoSet 0x2 /* ex.msg:8 */
- #define SetOneSet 0x1 /* ex.msg:4 */
- #define SetOnetwo 0x2 /* ex.msg:6 */
- As can be seen the various symbols given in the source file are
- mangled to generate unique identifiers and these identifiers get numbers
- assigned. Reading the source file and knowing about the rules will
- allow to predict the content of the header file (it is deterministic)
- but this is not necessary. The ‘gencat’ program can take care for
- everything. All the programmer has to do is to put the generated header
- file in the dependency list of the source files of her/his project and
- add a rule to regenerate the header if any of the input files change.
- One word about the symbol mangling. Every symbol consists of two
- parts: the name of the message set plus the name of the message or the
- special string ‘Set’. So ‘SetOnetwo’ means this macro can be used to
- access the translation with identifier ‘two’ in the message set
- ‘SetOne’.
- The other names denote the names of the message sets. The special
- string ‘Set’ is used in the place of the message identifier.
- If in the code the second string of the set ‘SetOne’ is used the C
- code should look like this:
- catgets (catdesc, SetOneSet, SetOnetwo,
- " Message with ID \"two\", which gets the value 2 assigned")
- Writing the function this way will allow to change the message number
- and even the set number without requiring any change in the C source
- code. (The text of the string is normally not the same; this is only
- for this example.)
- 8.1.4.3 How does to this allow to develop
- .........................................
- To illustrate the usual way to work with the symbolic version numbers
- here is a little example. Assume we want to write the very complex and
- famous greeting program. We start by writing the code as usual:
- #include <stdio.h>
- int
- main (void)
- {
- printf ("Hello, world!\n");
- return 0;
- }
- Now we want to internationalize the message and therefore replace the
- message with whatever the user wants.
- #include <nl_types.h>
- #include <stdio.h>
- #include "msgnrs.h"
- int
- main (void)
- {
- nl_catd catdesc = catopen ("hello.cat", NL_CAT_LOCALE);
- printf (catgets (catdesc, SetMainSet, SetMainHello,
- "Hello, world!\n"));
- catclose (catdesc);
- return 0;
- }
- We see how the catalog object is opened and the returned descriptor
- used in the other function calls. It is not really necessary to check
- for failure of any of the functions since even in these situations the
- functions will behave reasonable. They simply will be return a
- translation.
- What remains unspecified here are the constants ‘SetMainSet’ and
- ‘SetMainHello’. These are the symbolic names describing the message.
- To get the actual definitions which match the information in the catalog
- file we have to create the message catalog source file and process it
- using the ‘gencat’ program.
- $ Messages for the famous greeting program.
- $quote "
- $set Main
- Hello "Hallo, Welt!\n"
- Now we can start building the program (assume the message catalog
- source file is named ‘hello.msg’ and the program source file ‘hello.c’):
- % gencat -H msgnrs.h -o hello.cat hello.msg
- % cat msgnrs.h
- #define MainSet 0x1 /* hello.msg:4 */
- #define MainHello 0x1 /* hello.msg:5 */
- % gcc -o hello hello.c -I.
- % cp hello.cat /usr/share/locale/de/LC_MESSAGES
- % echo $LC_ALL
- de
- % ./hello
- Hallo, Welt!
- %
- The call of the ‘gencat’ program creates the missing header file
- ‘msgnrs.h’ as well as the message catalog binary. The former is used in
- the compilation of ‘hello.c’ while the later is placed in a directory in
- which the ‘catopen’ function will try to locate it. Please check the
- ‘LC_ALL’ environment variable and the default path for ‘catopen’
- presented in the description above.
- File: libc.info, Node: The Uniforum approach, Prev: Message catalogs a la X/Open, Up: Message Translation
- 8.2 The Uniforum approach to Message Translation
- ================================================
- Sun Microsystems tried to standardize a different approach to message
- translation in the Uniforum group. There never was a real standard
- defined but still the interface was used in Sun’s operating systems.
- Since this approach fits better in the development process of free
- software it is also used throughout the GNU project and the GNU
- ‘gettext’ package provides support for this outside the GNU C Library.
- The code of the ‘libintl’ from GNU ‘gettext’ is the same as the code
- in the GNU C Library. So the documentation in the GNU ‘gettext’ manual
- is also valid for the functionality here. The following text will
- describe the library functions in detail. But the numerous helper
- programs are not described in this manual. Instead people should read
- the GNU ‘gettext’ manual (*note GNU gettext utilities: (gettext)Top.).
- We will only give a short overview.
- Though the ‘catgets’ functions are available by default on more
- systems the ‘gettext’ interface is at least as portable as the former.
- The GNU ‘gettext’ package can be used wherever the functions are not
- available.
- * Menu:
- * Message catalogs with gettext:: The ‘gettext’ family of functions.
- * Helper programs for gettext:: Programs to handle message catalogs
- for ‘gettext’.
- File: libc.info, Node: Message catalogs with gettext, Next: Helper programs for gettext, Up: The Uniforum approach
- 8.2.1 The ‘gettext’ family of functions
- ---------------------------------------
- The paradigms underlying the ‘gettext’ approach to message translations
- is different from that of the ‘catgets’ functions the basic functionally
- is equivalent. There are functions of the following categories:
- * Menu:
- * Translation with gettext:: What has to be done to translate a message.
- * Locating gettext catalog:: How to determine which catalog to be used.
- * Advanced gettext functions:: Additional functions for more complicated
- situations.
- * Charset conversion in gettext:: How to specify the output character set
- ‘gettext’ uses.
- * GUI program problems:: How to use ‘gettext’ in GUI programs.
- * Using gettextized software:: The possibilities of the user to influence
- the way ‘gettext’ works.
- File: libc.info, Node: Translation with gettext, Next: Locating gettext catalog, Up: Message catalogs with gettext
- 8.2.1.1 What has to be done to translate a message?
- ...................................................
- The ‘gettext’ functions have a very simple interface. The most basic
- function just takes the string which shall be translated as the argument
- and it returns the translation. This is fundamentally different from
- the ‘catgets’ approach where an extra key is necessary and the original
- string is only used for the error case.
- If the string which has to be translated is the only argument this of
- course means the string itself is the key. I.e., the translation will
- be selected based on the original string. The message catalogs must
- therefore contain the original strings plus one translation for any such
- string. The task of the ‘gettext’ function is to compare the argument
- string with the available strings in the catalog and return the
- appropriate translation. Of course this process is optimized so that
- this process is not more expensive than an access using an atomic key
- like in ‘catgets’.
- The ‘gettext’ approach has some advantages but also some
- disadvantages. Please see the GNU ‘gettext’ manual for a detailed
- discussion of the pros and cons.
- All the definitions and declarations for ‘gettext’ can be found in
- the ‘libintl.h’ header file. On systems where these functions are not
- part of the C library they can be found in a separate library named
- ‘libintl.a’ (or accordingly different for shared libraries).
- -- Function: char * gettext (const char *MSGID)
- Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
- The ‘gettext’ function searches the currently selected message
- catalogs for a string which is equal to MSGID. If there is such a
- string available it is returned. Otherwise the argument string
- MSGID is returned.
- Please note that although the return value is ‘char *’ the returned
- string must not be changed. This broken type results from the
- history of the function and does not reflect the way the function
- should be used.
- Please note that above we wrote “message catalogs” (plural). This
- is a specialty of the GNU implementation of these functions and we
- will say more about this when we talk about the ways message
- catalogs are selected (*note Locating gettext catalog::).
- The ‘gettext’ function does not modify the value of the global
- ERRNO variable. This is necessary to make it possible to write
- something like
- printf (gettext ("Operation failed: %m\n"));
- Here the ERRNO value is used in the ‘printf’ function while
- processing the ‘%m’ format element and if the ‘gettext’ function
- would change this value (it is called before ‘printf’ is called) we
- would get a wrong message.
- So there is no easy way to detect a missing message catalog besides
- comparing the argument string with the result. But it is normally
- the task of the user to react on missing catalogs. The program
- cannot guess when a message catalog is really necessary since for a
- user who speaks the language the program was developed in, the
- message does not need any translation.
- The remaining two functions to access the message catalog add some
- functionality to select a message catalog which is not the default one.
- This is important if parts of the program are developed independently.
- Every part can have its own message catalog and all of them can be used
- at the same time. The C library itself is an example: internally it
- uses the ‘gettext’ functions but since it must not depend on a currently
- selected default message catalog it must specify all ambiguous
- information.
- -- Function: char * dgettext (const char *DOMAINNAME, const char
- *MSGID)
- Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
- The ‘dgettext’ function acts just like the ‘gettext’ function. It
- only takes an additional first argument DOMAINNAME which guides the
- selection of the message catalogs which are searched for the
- translation. If the DOMAINNAME parameter is the null pointer the
- ‘dgettext’ function is exactly equivalent to ‘gettext’ since the
- default value for the domain name is used.
- As for ‘gettext’ the return value type is ‘char *’ which is an
- anachronism. The returned string must never be modified.
- -- Function: char * dcgettext (const char *DOMAINNAME, const char
- *MSGID, int CATEGORY)
- Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
- The ‘dcgettext’ adds another argument to those which ‘dgettext’
- takes. This argument CATEGORY specifies the last piece of
- information needed to localize the message catalog. I.e., the
- domain name and the locale category exactly specify which message
- catalog has to be used (relative to a given directory, see below).
- The ‘dgettext’ function can be expressed in terms of ‘dcgettext’ by
- using
- dcgettext (domain, string, LC_MESSAGES)
- instead of
- dgettext (domain, string)
- This also shows which values are expected for the third parameter.
- One has to use the available selectors for the categories available
- in ‘locale.h’. Normally the available values are ‘LC_CTYPE’,
- ‘LC_COLLATE’, ‘LC_MESSAGES’, ‘LC_MONETARY’, ‘LC_NUMERIC’, and
- ‘LC_TIME’. Please note that ‘LC_ALL’ must not be used and even
- though the names might suggest this, there is no relation to the
- environment variable of this name.
- The ‘dcgettext’ function is only implemented for compatibility with
- other systems which have ‘gettext’ functions. There is not really
- any situation where it is necessary (or useful) to use a different
- value than ‘LC_MESSAGES’ for the CATEGORY parameter. We are
- dealing with messages here and any other choice can only be
- irritating.
- As for ‘gettext’ the return value type is ‘char *’ which is an
- anachronism. The returned string must never be modified.
- When using the three functions above in a program it is a frequent
- case that the MSGID argument is a constant string. So it is worthwhile
- to optimize this case. Thinking shortly about this one will realize
- that as long as no new message catalog is loaded the translation of a
- message will not change. This optimization is actually implemented by
- the ‘gettext’, ‘dgettext’ and ‘dcgettext’ functions.
- File: libc.info, Node: Locating gettext catalog, Next: Advanced gettext functions, Prev: Translation with gettext, Up: Message catalogs with gettext
- 8.2.1.2 How to determine which catalog to be used
- .................................................
- The functions to retrieve the translations for a given message have a
- remarkable simple interface. But to provide the user of the program
- still the opportunity to select exactly the translation s/he wants and
- also to provide the programmer the possibility to influence the way to
- locate the search for catalogs files there is a quite complicated
- underlying mechanism which controls all this. The code is complicated
- the use is easy.
- Basically we have two different tasks to perform which can also be
- performed by the ‘catgets’ functions:
- 1. Locate the set of message catalogs. There are a number of files
- for different languages which all belong to the package. Usually
- they are all stored in the filesystem below a certain directory.
- There can be arbitrarily many packages installed and they can
- follow different guidelines for the placement of their files.
- 2. Relative to the location specified by the package the actual
- translation files must be searched, based on the wishes of the
- user. I.e., for each language the user selects the program should
- be able to locate the appropriate file.
- This is the functionality required by the specifications for
- ‘gettext’ and this is also what the ‘catgets’ functions are able to do.
- But there are some problems unresolved:
- • The language to be used can be specified in several different ways.
- There is no generally accepted standard for this and the user
- always expects the program to understand what s/he means. E.g., to
- select the German translation one could write ‘de’, ‘german’, or
- ‘deutsch’ and the program should always react the same.
- • Sometimes the specification of the user is too detailed. If s/he,
- e.g., specifies ‘de_DE.ISO-8859-1’ which means German, spoken in
- Germany, coded using the ISO 8859-1 character set there is the
- possibility that a message catalog matching this exactly is not
- available. But there could be a catalog matching ‘de’ and if the
- character set used on the machine is always ISO 8859-1 there is no
- reason why this later message catalog should not be used. (We call
- this "message inheritance".)
- • If a catalog for a wanted language is not available it is not
- always the second best choice to fall back on the language of the
- developer and simply not translate any message. Instead a user
- might be better able to read the messages in another language and
- so the user of the program should be able to define a precedence
- order of languages.
- We can divide the configuration actions in two parts: the one is
- performed by the programmer, the other by the user. We will start with
- the functions the programmer can use since the user configuration will
- be based on this.
- As the functions described in the last sections already mention
- separate sets of messages can be selected by a "domain name". This is a
- simple string which should be unique for each program part that uses a
- separate domain. It is possible to use in one program arbitrarily many
- domains at the same time. E.g., the GNU C Library itself uses a domain
- named ‘libc’ while the program using the C Library could use a domain
- named ‘foo’. The important point is that at any time exactly one domain
- is active. This is controlled with the following function.
- -- Function: char * textdomain (const char *DOMAINNAME)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- The ‘textdomain’ function sets the default domain, which is used in
- all future ‘gettext’ calls, to DOMAINNAME. Please note that
- ‘dgettext’ and ‘dcgettext’ calls are not influenced if the
- DOMAINNAME parameter of these functions is not the null pointer.
- Before the first call to ‘textdomain’ the default domain is
- ‘messages’. This is the name specified in the specification of the
- ‘gettext’ API. This name is as good as any other name. No program
- should ever really use a domain with this name since this can only
- lead to problems.
- The function returns the value which is from now on taken as the
- default domain. If the system went out of memory the returned
- value is ‘NULL’ and the global variable ERRNO is set to ‘ENOMEM’.
- Despite the return value type being ‘char *’ the return string must
- not be changed. It is allocated internally by the ‘textdomain’
- function.
- If the DOMAINNAME parameter is the null pointer no new default
- domain is set. Instead the currently selected default domain is
- returned.
- If the DOMAINNAME parameter is the empty string the default domain
- is reset to its initial value, the domain with the name ‘messages’.
- This possibility is questionable to use since the domain ‘messages’
- really never should be used.
- -- Function: char * bindtextdomain (const char *DOMAINNAME, const char
- *DIRNAME)
- Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- The ‘bindtextdomain’ function can be used to specify the directory
- which contains the message catalogs for domain DOMAINNAME for the
- different languages. To be correct, this is the directory where
- the hierarchy of directories is expected. Details are explained
- below.
- For the programmer it is important to note that the translations
- which come with the program have to be placed in a directory
- hierarchy starting at, say, ‘/foo/bar’. Then the program should
- make a ‘bindtextdomain’ call to bind the domain for the current
- program to this directory. So it is made sure the catalogs are
- found. A correctly running program does not depend on the user
- setting an environment variable.
- The ‘bindtextdomain’ function can be used several times and if the
- DOMAINNAME argument is different the previously bound domains will
- not be overwritten.
- If the program which wish to use ‘bindtextdomain’ at some point of
- time use the ‘chdir’ function to change the current working
- directory it is important that the DIRNAME strings ought to be an
- absolute pathname. Otherwise the addressed directory might vary
- with the time.
- If the DIRNAME parameter is the null pointer ‘bindtextdomain’
- returns the currently selected directory for the domain with the
- name DOMAINNAME.
- The ‘bindtextdomain’ function returns a pointer to a string
- containing the name of the selected directory name. The string is
- allocated internally in the function and must not be changed by the
- user. If the system went out of core during the execution of
- ‘bindtextdomain’ the return value is ‘NULL’ and the global variable
- ERRNO is set accordingly.
- File: libc.info, Node: Advanced gettext functions, Next: Charset conversion in gettext, Prev: Locating gettext catalog, Up: Message catalogs with gettext
- 8.2.1.3 Additional functions for more complicated situations
- ............................................................
- The functions of the ‘gettext’ family described so far (and all the
- ‘catgets’ functions as well) have one problem in the real world which
- has been neglected completely in all existing approaches. What is meant
- here is the handling of plural forms.
- Looking through Unix source code before the time anybody thought
- about internationalization (and, sadly, even afterwards) one can often
- find code similar to the following:
- printf ("%d file%s deleted", n, n == 1 ? "" : "s");
- After the first complaints from people internationalizing the code
- people either completely avoided formulations like this or used strings
- like ‘"file(s)"’. Both look unnatural and should be avoided. First
- tries to solve the problem correctly looked like this:
- if (n == 1)
- printf ("%d file deleted", n);
- else
- printf ("%d files deleted", n);
- But this does not solve the problem. It helps languages where the
- plural form of a noun is not simply constructed by adding an ‘s’ but
- that is all. Once again people fell into the trap of believing the
- rules their language uses are universal. But the handling of plural
- forms differs widely between the language families. There are two
- things we can differ between (and even inside language families);
- • The form how plural forms are build differs. This is a problem
- with language which have many irregularities. German, for
- instance, is a drastic case. Though English and German are part of
- the same language family (Germanic), the almost regular forming of
- plural noun forms (appending an ‘s’) is hardly found in German.
- • The number of plural forms differ. This is somewhat surprising for
- those who only have experiences with Romanic and Germanic languages
- since here the number is the same (there are two).
- But other language families have only one form or many forms. More
- information on this in an extra section.
- The consequence of this is that application writers should not try to
- solve the problem in their code. This would be localization since it is
- only usable for certain, hardcoded language environments. Instead the
- extended ‘gettext’ interface should be used.
- These extra functions are taking instead of the one key string two
- strings and a numerical argument. The idea behind this is that using
- the numerical argument and the first string as a key, the implementation
- can select using rules specified by the translator the right plural
- form. The two string arguments then will be used to provide a return
- value in case no message catalog is found (similar to the normal
- ‘gettext’ behavior). In this case the rules for Germanic language are
- used and it is assumed that the first string argument is the singular
- form, the second the plural form.
- This has the consequence that programs without language catalogs can
- display the correct strings only if the program itself is written using
- a Germanic language. This is a limitation but since the GNU C Library
- (as well as the GNU ‘gettext’ package) is written as part of the GNU
- package and the coding standards for the GNU project require programs to
- be written in English, this solution nevertheless fulfills its purpose.
- -- Function: char * ngettext (const char *MSGID1, const char *MSGID2,
- unsigned long int N)
- Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
- The ‘ngettext’ function is similar to the ‘gettext’ function as it
- finds the message catalogs in the same way. But it takes two extra
- arguments. The MSGID1 parameter must contain the singular form of
- the string to be converted. It is also used as the key for the
- search in the catalog. The MSGID2 parameter is the plural form.
- The parameter N is used to determine the plural form. If no
- message catalog is found MSGID1 is returned if ‘n == 1’, otherwise
- ‘msgid2’.
- An example for the use of this function is:
- printf (ngettext ("%d file removed", "%d files removed", n), n);
- Please note that the numeric value N has to be passed to the
- ‘printf’ function as well. It is not sufficient to pass it only to
- ‘ngettext’.
- -- Function: char * dngettext (const char *DOMAIN, const char *MSGID1,
- const char *MSGID2, unsigned long int N)
- Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
- The ‘dngettext’ is similar to the ‘dgettext’ function in the way
- the message catalog is selected. The difference is that it takes
- two extra parameters to provide the correct plural form. These two
- parameters are handled in the same way ‘ngettext’ handles them.
- -- Function: char * dcngettext (const char *DOMAIN, const char *MSGID1,
- const char *MSGID2, unsigned long int N, int CATEGORY)
- Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
- AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
- The ‘dcngettext’ is similar to the ‘dcgettext’ function in the way
- the message catalog is selected. The difference is that it takes
- two extra parameters to provide the correct plural form. These two
- parameters are handled in the same way ‘ngettext’ handles them.
- The problem of plural forms
- ...........................
- A description of the problem can be found at the beginning of the last
- section. Now there is the question how to solve it. Without the input
- of linguists (which was not available) it was not possible to determine
- whether there are only a few different forms in which plural forms are
- formed or whether the number can increase with every new supported
- language.
- Therefore the solution implemented is to allow the translator to
- specify the rules of how to select the plural form. Since the formula
- varies with every language this is the only viable solution except for
- hardcoding the information in the code (which still would require the
- possibility of extensions to not prevent the use of new languages). The
- details are explained in the GNU ‘gettext’ manual. Here only a bit of
- information is provided.
- The information about the plural form selection has to be stored in
- the header entry (the one with the empty ‘msgid’ string). It looks like
- this:
- Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
- The ‘nplurals’ value must be a decimal number which specifies how
- many different plural forms exist for this language. The string
- following ‘plural’ is an expression using the C language syntax.
- Exceptions are that no negative numbers are allowed, numbers must be
- decimal, and the only variable allowed is ‘n’. This expression will be
- evaluated whenever one of the functions ‘ngettext’, ‘dngettext’, or
- ‘dcngettext’ is called. The numeric value passed to these functions is
- then substituted for all uses of the variable ‘n’ in the expression.
- The resulting value then must be greater or equal to zero and smaller
- than the value given as the value of ‘nplurals’.
- The following rules are known at this point. The language with families
- are listed. But this does not necessarily mean the information can be
- generalized for the whole family (as can be easily seen in the table
- below).(1)
- Only one form:
- Some languages only require one single form. There is no
- distinction between the singular and plural form. An appropriate
- header entry would look like this:
- Plural-Forms: nplurals=1; plural=0;
- Languages with this property include:
- Finno-Ugric family
- Hungarian
- Asian family
- Japanese, Korean
- Turkic/Altaic family
- Turkish
- Two forms, singular used for one only
- This is the form used in most existing programs since it is what
- English uses. A header entry would look like this:
- Plural-Forms: nplurals=2; plural=n != 1;
- (Note: this uses the feature of C expressions that boolean
- expressions have to value zero or one.)
- Languages with this property include:
- Germanic family
- Danish, Dutch, English, German, Norwegian, Swedish
- Finno-Ugric family
- Estonian, Finnish
- Latin/Greek family
- Greek
- Semitic family
- Hebrew
- Romance family
- Italian, Portuguese, Spanish
- Artificial
- Esperanto
- Two forms, singular used for zero and one
- Exceptional case in the language family. The header entry would
- be:
- Plural-Forms: nplurals=2; plural=n>1;
- Languages with this property include:
- Romanic family
- French, Brazilian Portuguese
- Three forms, special case for zero
- The header entry would be:
- Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
- Languages with this property include:
- Baltic family
- Latvian
- Three forms, special cases for one and two
- The header entry would be:
- Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
- Languages with this property include:
- Celtic
- Gaeilge (Irish)
- Three forms, special case for numbers ending in 1[2-9]
- The header entry would look like this:
- Plural-Forms: nplurals=3; \
- plural=n%10==1 && n%100!=11 ? 0 : \
- n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
- Languages with this property include:
- Baltic family
- Lithuanian
- Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
- The header entry would look like this:
- Plural-Forms: nplurals=3; \
- plural=n%100/10==1 ? 2 : n%10==1 ? 0 : (n+9)%10>3 ? 2 : 1;
- Languages with this property include:
- Slavic family
- Croatian, Czech, Russian, Ukrainian
- Three forms, special cases for 1 and 2, 3, 4
- The header entry would look like this:
- Plural-Forms: nplurals=3; \
- plural=(n==1) ? 1 : (n>=2 && n<=4) ? 2 : 0;
- Languages with this property include:
- Slavic family
- Slovak
- Three forms, special case for one and some numbers ending in 2, 3, or 4
- The header entry would look like this:
- Plural-Forms: nplurals=3; \
- plural=n==1 ? 0 : \
- n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
- Languages with this property include:
- Slavic family
- Polish
- Four forms, special case for one and all numbers ending in 02, 03, or 04
- The header entry would look like this:
- Plural-Forms: nplurals=4; \
- plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
- Languages with this property include:
- Slavic family
- Slovenian
- ---------- Footnotes ----------
- (1) Additions are welcome. Send appropriate information to
- <bug-glibc-manual@gnu.org>.
- File: libc.info, Node: Charset conversion in gettext, Next: GUI program problems, Prev: Advanced gettext functions, Up: Message catalogs with gettext
- 8.2.1.4 How to specify the output character set ‘gettext’ uses
- ..............................................................
- ‘gettext’ not only looks up a translation in a message catalog, it also
- converts the translation on the fly to the desired output character set.
- This is useful if the user is working in a different character set than
- the translator who created the message catalog, because it avoids
- distributing variants of message catalogs which differ only in the
- character set.
- The output character set is, by default, the value of ‘nl_langinfo
- (CODESET)’, which depends on the ‘LC_CTYPE’ part of the current locale.
- But programs which store strings in a locale independent way (e.g.
- UTF-8) can request that ‘gettext’ and related functions return the
- translations in that encoding, by use of the ‘bind_textdomain_codeset’
- function.
- Note that the MSGID argument to ‘gettext’ is not subject to character
- set conversion. Also, when ‘gettext’ does not find a translation for
- MSGID, it returns MSGID unchanged – independently of the current output
- character set. It is therefore recommended that all MSGIDs be US-ASCII
- strings.
- -- Function: char * bind_textdomain_codeset (const char *DOMAINNAME,
- const char *CODESET)
- Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- The ‘bind_textdomain_codeset’ function can be used to specify the
- output character set for message catalogs for domain DOMAINNAME.
- The CODESET argument must be a valid codeset name which can be used
- for the ‘iconv_open’ function, or a null pointer.
- If the CODESET parameter is the null pointer,
- ‘bind_textdomain_codeset’ returns the currently selected codeset
- for the domain with the name DOMAINNAME. It returns ‘NULL’ if no
- codeset has yet been selected.
- The ‘bind_textdomain_codeset’ function can be used several times.
- If used multiple times with the same DOMAINNAME argument, the later
- call overrides the settings made by the earlier one.
- The ‘bind_textdomain_codeset’ function returns a pointer to a
- string containing the name of the selected codeset. The string is
- allocated internally in the function and must not be changed by the
- user. If the system went out of core during the execution of
- ‘bind_textdomain_codeset’, the return value is ‘NULL’ and the
- global variable ERRNO is set accordingly.
- File: libc.info, Node: GUI program problems, Next: Using gettextized software, Prev: Charset conversion in gettext, Up: Message catalogs with gettext
- 8.2.1.5 How to use ‘gettext’ in GUI programs
- ............................................
- One place where the ‘gettext’ functions, if used normally, have big
- problems is within programs with graphical user interfaces (GUIs). The
- problem is that many of the strings which have to be translated are very
- short. They have to appear in pull-down menus which restricts the
- length. But strings which are not containing entire sentences or at
- least large fragments of a sentence may appear in more than one
- situation in the program but might have different translations. This is
- especially true for the one-word strings which are frequently used in
- GUI programs.
- As a consequence many people say that the ‘gettext’ approach is wrong
- and instead ‘catgets’ should be used which indeed does not have this
- problem. But there is a very simple and powerful method to handle these
- kind of problems with the ‘gettext’ functions.
- As an example consider the following fictional situation. A GUI program
- has a menu bar with the following entries:
- +------------+------------+--------------------------------------+
- | File | Printer | |
- +------------+------------+--------------------------------------+
- | Open | | Select |
- | New | | Open |
- +----------+ | Connect |
- +----------+
- To have the strings ‘File’, ‘Printer’, ‘Open’, ‘New’, ‘Select’, and
- ‘Connect’ translated there has to be at some point in the code a call to
- a function of the ‘gettext’ family. But in two places the string passed
- into the function would be ‘Open’. The translations might not be the
- same and therefore we are in the dilemma described above.
- One solution to this problem is to artificially extend the strings to
- make them unambiguous. But what would the program do if no translation
- is available? The extended string is not what should be printed. So we
- should use a slightly modified version of the functions.
- To extend the strings a uniform method should be used. E.g., in the
- example above, the strings could be chosen as
- Menu|File
- Menu|Printer
- Menu|File|Open
- Menu|File|New
- Menu|Printer|Select
- Menu|Printer|Open
- Menu|Printer|Connect
- Now all the strings are different and if now instead of ‘gettext’ the
- following little wrapper function is used, everything works just fine:
- char *
- sgettext (const char *msgid)
- {
- char *msgval = gettext (msgid);
- if (msgval == msgid)
- msgval = strrchr (msgid, '|') + 1;
- return msgval;
- }
- What this little function does is to recognize the case when no
- translation is available. This can be done very efficiently by a
- pointer comparison since the return value is the input value. If there
- is no translation we know that the input string is in the format we used
- for the Menu entries and therefore contains a ‘|’ character. We simply
- search for the last occurrence of this character and return a pointer to
- the character following it. That’s it!
- If one now consistently uses the extended string form and replaces
- the ‘gettext’ calls with calls to ‘sgettext’ (this is normally limited
- to very few places in the GUI implementation) then it is possible to
- produce a program which can be internationalized.
- With advanced compilers (such as GNU C) one can write the ‘sgettext’
- functions as an inline function or as a macro like this:
- #define sgettext(msgid) \
- ({ const char *__msgid = (msgid); \
- char *__msgstr = gettext (__msgid); \
- if (__msgval == __msgid) \
- __msgval = strrchr (__msgid, '|') + 1; \
- __msgval; })
- The other ‘gettext’ functions (‘dgettext’, ‘dcgettext’ and the
- ‘ngettext’ equivalents) can and should have corresponding functions as
- well which look almost identical, except for the parameters and the call
- to the underlying function.
- Now there is of course the question why such functions do not exist
- in the GNU C Library? There are two parts of the answer to this
- question.
- • They are easy to write and therefore can be provided by the project
- they are used in. This is not an answer by itself and must be seen
- together with the second part which is:
- • There is no way the C library can contain a version which can work
- everywhere. The problem is the selection of the character to
- separate the prefix from the actual string in the extended string.
- The examples above used ‘|’ which is a quite good choice because it
- resembles a notation frequently used in this context and it also is
- a character not often used in message strings.
- But what if the character is used in message strings. Or if the
- chose character is not available in the character set on the
- machine one compiles (e.g., ‘|’ is not required to exist for ISO C;
- this is why the ‘iso646.h’ file exists in ISO C programming
- environments).
- There is only one more comment to make left. The wrapper function
- above requires that the translations strings are not extended
- themselves. This is only logical. There is no need to disambiguate the
- strings (since they are never used as keys for a search) and one also
- saves quite some memory and disk space by doing this.
- File: libc.info, Node: Using gettextized software, Prev: GUI program problems, Up: Message catalogs with gettext
- 8.2.1.6 User influence on ‘gettext’
- ...................................
- The last sections described what the programmer can do to
- internationalize the messages of the program. But it is finally up to
- the user to select the message s/he wants to see. S/He must understand
- them.
- The POSIX locale model uses the environment variables ‘LC_COLLATE’,
- ‘LC_CTYPE’, ‘LC_MESSAGES’, ‘LC_MONETARY’, ‘LC_NUMERIC’, and ‘LC_TIME’ to
- select the locale which is to be used. This way the user can influence
- lots of functions. As we mentioned above, the ‘gettext’ functions also
- take advantage of this.
- To understand how this happens it is necessary to take a look at the
- various components of the filename which gets computed to locate a
- message catalog. It is composed as follows:
- DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
- The default value for DIR_NAME is system specific. It is computed
- from the value given as the prefix while configuring the C library.
- This value normally is ‘/usr’ or ‘/’. For the former the complete
- DIR_NAME is:
- /usr/share/locale
- We can use ‘/usr/share’ since the ‘.mo’ files containing the message
- catalogs are system independent, so all systems can use the same files.
- If the program executed the ‘bindtextdomain’ function for the message
- domain that is currently handled, the ‘dir_name’ component is exactly
- the value which was given to the function as the second parameter.
- I.e., ‘bindtextdomain’ allows overwriting the only system dependent and
- fixed value to make it possible to address files anywhere in the
- filesystem.
- The CATEGORY is the name of the locale category which was selected in
- the program code. For ‘gettext’ and ‘dgettext’ this is always
- ‘LC_MESSAGES’, for ‘dcgettext’ this is selected by the value of the
- third parameter. As said above it should be avoided to ever use a
- category other than ‘LC_MESSAGES’.
- The LOCALE component is computed based on the category used. Just
- like for the ‘setlocale’ function here comes the user selection into the
- play. Some environment variables are examined in a fixed order and the
- first environment variable set determines the return value of the lookup
- process. In detail, for the category ‘LC_xxx’ the following variables
- in this order are examined:
- ‘LANGUAGE’
- ‘LC_ALL’
- ‘LC_xxx’
- ‘LANG’
- This looks very familiar. With the exception of the ‘LANGUAGE’
- environment variable this is exactly the lookup order the ‘setlocale’
- function uses. But why introduce the ‘LANGUAGE’ variable?
- The reason is that the syntax of the values these variables can have
- is different to what is expected by the ‘setlocale’ function. If we
- would set ‘LC_ALL’ to a value following the extended syntax that would
- mean the ‘setlocale’ function will never be able to use the value of
- this variable as well. An additional variable removes this problem plus
- we can select the language independently of the locale setting which
- sometimes is useful.
- While for the ‘LC_xxx’ variables the value should consist of exactly
- one specification of a locale the ‘LANGUAGE’ variable’s value can
- consist of a colon separated list of locale names. The attentive reader
- will realize that this is the way we manage to implement one of our
- additional demands above: we want to be able to specify an ordered list
- of languages.
- Back to the constructed filename we have only one component missing.
- The DOMAIN_NAME part is the name which was either registered using the
- ‘textdomain’ function or which was given to ‘dgettext’ or ‘dcgettext’ as
- the first parameter. Now it becomes obvious that a good choice for the
- domain name in the program code is a string which is closely related to
- the program/package name. E.g., for the GNU C Library the domain name
- is ‘libc’.
- A limited piece of example code should show how the program is supposed
- to work:
- {
- setlocale (LC_ALL, "");
- textdomain ("test-package");
- bindtextdomain ("test-package", "/usr/local/share/locale");
- puts (gettext ("Hello, world!"));
- }
- At the program start the default domain is ‘messages’, and the
- default locale is "C". The ‘setlocale’ call sets the locale according to
- the user’s environment variables; remember that correct functioning of
- ‘gettext’ relies on the correct setting of the ‘LC_MESSAGES’ locale (for
- looking up the message catalog) and of the ‘LC_CTYPE’ locale (for the
- character set conversion). The ‘textdomain’ call changes the default
- domain to ‘test-package’. The ‘bindtextdomain’ call specifies that the
- message catalogs for the domain ‘test-package’ can be found below the
- directory ‘/usr/local/share/locale’.
- If the user sets in her/his environment the variable ‘LANGUAGE’ to
- ‘de’ the ‘gettext’ function will try to use the translations from the
- file
- /usr/local/share/locale/de/LC_MESSAGES/test-package.mo
- From the above descriptions it should be clear which component of
- this filename is determined by which source.
- In the above example we assumed the ‘LANGUAGE’ environment variable
- to be ‘de’. This might be an appropriate selection but what happens if
- the user wants to use ‘LC_ALL’ because of the wider usability and here
- the required value is ‘de_DE.ISO-8859-1’? We already mentioned above
- that a situation like this is not infrequent. E.g., a person might
- prefer reading a dialect and if this is not available fall back on the
- standard language.
- The ‘gettext’ functions know about situations like this and can
- handle them gracefully. The functions recognize the format of the value
- of the environment variable. It can split the value is different pieces
- and by leaving out the only or the other part it can construct new
- values. This happens of course in a predictable way. To understand
- this one must know the format of the environment variable value. There
- is one more or less standardized form, originally from the X/Open
- specification:
- ‘language[_territory[.codeset]][@modifier]’
- Less specific locale names will be stripped in the order of the
- following list:
- 1. ‘codeset’
- 2. ‘normalized codeset’
- 3. ‘territory’
- 4. ‘modifier’
- The ‘language’ field will never be dropped for obvious reasons.
- The only new thing is the ‘normalized codeset’ entry. This is
- another goodie which is introduced to help reduce the chaos which
- derives from the inability of people to standardize the names of
- character sets. Instead of ISO-8859-1 one can often see 8859-1, 88591,
- iso8859-1, or iso_8859-1. The ‘normalized codeset’ value is generated
- from the user-provided character set name by applying the following
- rules:
- 1. Remove all characters besides numbers and letters.
- 2. Fold letters to lowercase.
- 3. If the same only contains digits prepend the string ‘"iso"’.
- So all of the above names will be normalized to ‘iso88591’. This allows
- the program user much more freedom in choosing the locale name.
- Even this extended functionality still does not help to solve the
- problem that completely different names can be used to denote the same
- locale (e.g., ‘de’ and ‘german’). To be of help in this situation the
- locale implementation and also the ‘gettext’ functions know about
- aliases.
- The file ‘/usr/share/locale/locale.alias’ (replace ‘/usr’ with
- whatever prefix you used for configuring the C library) contains a
- mapping of alternative names to more regular names. The system manager
- is free to add new entries to fill her/his own needs. The selected
- locale from the environment is compared with the entries in the first
- column of this file ignoring the case. If they match, the value of the
- second column is used instead for the further handling.
- In the description of the format of the environment variables we
- already mentioned the character set as a factor in the selection of the
- message catalog. In fact, only catalogs which contain text written
- using the character set of the system/program can be used (directly;
- there will come a solution for this some day). This means for the user
- that s/he will always have to take care of this. If in the collection
- of the message catalogs there are files for the same language but coded
- using different character sets the user has to be careful.
- File: libc.info, Node: Helper programs for gettext, Prev: Message catalogs with gettext, Up: The Uniforum approach
- 8.2.2 Programs to handle message catalogs for ‘gettext’
- -------------------------------------------------------
- The GNU C Library does not contain the source code for the programs to
- handle message catalogs for the ‘gettext’ functions. As part of the GNU
- project the GNU gettext package contains everything the developer needs.
- The functionality provided by the tools in this package by far exceeds
- the abilities of the ‘gencat’ program described above for the ‘catgets’
- functions.
- There is a program ‘msgfmt’ which is the equivalent program to the
- ‘gencat’ program. It generates from the human-readable and -editable
- form of the message catalog a binary file which can be used by the
- ‘gettext’ functions. But there are several more programs available.
- The ‘xgettext’ program can be used to automatically extract the
- translatable messages from a source file. I.e., the programmer need not
- take care of the translations and the list of messages which have to be
- translated. S/He will simply wrap the translatable string in calls to
- ‘gettext’ et.al and the rest will be done by ‘xgettext’. This program
- has a lot of options which help to customize the output or help to
- understand the input better.
- Other programs help to manage the development cycle when new messages
- appear in the source files or when a new translation of the messages
- appears. Here it should only be noted that using all the tools in GNU
- gettext it is possible to _completely_ automate the handling of message
- catalogs. Besides marking the translatable strings in the source code
- and generating the translations the developers do not have anything to
- do themselves.
|